The World is responsible for creating, managing, colliding and updating all of the bodies within it. More...

#include <World.h>

Inheritance diagram for ime::World:

Classes
struct	DebugDrawerFilter
	Controls the filter flags of the debug drawer. More...

Public Types
using	Ptr = std::shared_ptr< World >
	Shared World pointer. More...

using	GameObjectPtr = std::shared_ptr< GameObject >
	Shared GameObject pointer. More...

using	AABBCallback = std::function< bool(Collider::Ptr)>
	Callback function passed to queryAABB function. More...

using	RayCastCallback = std::function< float(Collider::Ptr, Vector2f, Vector2f, float)>
	Callback function passed to rayCast Function. More...

Public Member Functions
	World (const World &)=delete
	Copy constructor. More...

World &	operator= (const World &)=delete
	Copy assignment operator. More...

void	setGravity (Vector2f gravity)
	Change the gravity of the world. More...

Vector2f	getGravity () const
	Get the gravity of the world. More...

void	setTimescale (float timescale)
	Set the simulation timescale. More...

float	getTimescale () const
	Get the timescale. More...

void	enableContinuousPhysics (bool enable)
	Enable or disable continuous physics. More...

bool	isContinuousPhysicsEnabled () const
	Check whether continuous physics is enabled or not. More...

void	setFixedStep (bool fixed)
	Set whether or not the world is updated in fixed times steps. More...

bool	isFixedStep () const
	Check if the world is updated in fixed or variable time steps. More...

Body::Ptr	createBody (Body::Type type=Body::Type::Static)
	Create a rigid body. More...

void	createBody (const GameObjectPtr &gameObject, Body::Type type=Body::Type::Static)
	Create a body and attach it to a game object. More...

Body::Ptr	getBodyById (unsigned int id)
	Get the body by its unique identifier. More...

bool	destroyBody (const Body::Ptr &body)
	Destroy a rigid body. More...

Joint::Ptr	createJoint (const JointDefinition &definition)
	Create a joint. More...

bool	destroyJoint (const Joint::Ptr &joint)
	Destroy a joint. More...

void	destroyAllBodies ()
	Destroy all the bodies in the world. More...

void	destroyAllJoints ()
	Destroy all the joints in the world. More...

void	update (Time timeStep, unsigned int velocityIterations, unsigned int positionIterations)
	Update the physics world. More...

void	autoClearForceBuffer (bool autoClear)
	Enable or disable automatic force buffer clearance after an update. More...

bool	isForceBufferAutoCleared () const
	Check whether or not the force buffer on all bodies is cleared after each update. More...

void	clearForces ()
	Manually clear the force buffer on all bodies. More...

void	allowSleep (bool sleep)
	Set whether or not the world isSleepingAllowed. More...

bool	isSleepingAllowed () const
	Check if the world can sleep or not. More...

void	enableSubStepping (bool subStep)
	Enable or disable sub-stepping. More...

bool	isSubSteppingEnabled () const
	Check if sub-stepping is enabled or not. More...

void	forEachBody (Callback< Body::Ptr & > callback)
	Execute a callback for each body in the world. More...

void	forEachJoint (Callback< Joint::Ptr & > callback)
	Execute a callback for each joint in the world. More...

std::size_t	getBodyCount () const
	Get the number of bodies in the world. More...

std::size_t	getJointCount () const
	Get the number of joints in the world. More...

bool	isLocked () const
	Check if the world is in the middle of a time step or not. More...

void	rayCast (const RayCastCallback &callback, Vector2f startPoint, Vector2f endPoint)
	Ray-cast the world for all the colliders in the path of the ray. More...

void	queryAABB (const AABBCallback &callback, const AABB &aabb)
	Query the world for all colliders that overlap the given AABB. More...

ContactListener &	getContactListener ()
	Get the contact listener. More...

Scene &	getScene ()
	Get the scene the simulation belongs to. More...

void	enableDebugDraw (bool enable)
	Enable or disable debug drawing. More...

bool	isDebugDrawEnabled () const
	Check if debug draw is enabled or not. More...

DebugDrawerFilter &	getDebugDrawerFilter ()
	Get the debug drawer filter data. More...

const DebugDrawerFilter &	getDebugDrawerFilter () const

std::unique_ptr< b2World > &	getInternalWorld ()

bool	removeBodyById (unsigned int id)

void	createDebugDrawer (Window &renderWindow)

	~World ()
	Destructor. More...

Static Public Member Functions
static World::Ptr	create (Scene &scene, Vector2f gravity)
	Create the physics simulation. More...

Detailed Description

The World is responsible for creating, managing, colliding and updating all of the bodies within it.

Definition at line 53 of file World.h.

Member Typedef Documentation

◆ AABBCallback

using ime::World::AABBCallback = std::function<bool(Collider::Ptr)>

Callback function passed to queryAABB function.

The callback is called for every collider that overlaps the query AABB. The callback must return false to terminate the query early or true to continue with the query until all colliders have been processed

Definition at line 66 of file World.h.

◆ GameObjectPtr

using ime::World::GameObjectPtr = std::shared_ptr<GameObject>

Shared GameObject pointer.

Definition at line 56 of file World.h.

◆ Ptr

using ime::World::Ptr = std::shared_ptr<World>

Shared World pointer.

Definition at line 55 of file World.h.

◆ RayCastCallback

using ime::World::RayCastCallback = std::function<float(Collider::Ptr, Vector2f, Vector2f, float)>

Callback function passed to rayCast Function.

The callback is called for every collider that the ray collides with. The callback controls how the ray proceeds by the value it returns:

i) -1: Ignore the current collider and continue with the ray casting. The collider will be filtered. That is, the ray cast will proceed as if the collider does not exist

ii) 0: Terminate the ray cast immediately

iii) 1: Don't clip the ray and continue. By default the ray is clipped if it collides with a collider. When 1 is returned the ray will continue as if it did not hit anything

iv) fraction : The fraction is provided to the callback when it is called. If it is returned, then the ray will be clipped to the current point of intersection.

The value returned by the callback function allow you to ray cast any shape, ray cast all shapes, or ray cast the closest shape.

The argument list of the callback is as follows:

first arg: The collider that is currently colliding with the ray second arg: The point of initial intersection (There may be more than one intersection depending on the value returned by the callback) third arg: The normal vector (rotation) at the point of intersection forth arg: The distance from the rays starting point to the current point of intersection (fraction)

Definition at line 102 of file World.h.

Constructor & Destructor Documentation

◆ World()

ime::World::World ( const World & )

delete

Copy constructor.

◆ ~World()

ime::World::~World ( )

Destructor.

Member Function Documentation

◆ allowSleep()

void ime::World::allowSleep ( bool sleep )

Set whether or not the world isSleepingAllowed.

Parameters

sleep True to enable sleeping or false to disable

◆ autoClearForceBuffer()

void ime::World::autoClearForceBuffer ( bool autoClear )

Enable or disable automatic force buffer clearance after an update.

Parameters

autoClear True to enable or false to disable

By default, the force buffer on all bodies is cleared after each call to update. You can disable automatic force buffer clearance if you want to use subStepping

See also: enableSubStepping and clearForces

◆ clearForces()

void ime::World::clearForces ( )

Manually clear the force buffer on all bodies.

By default, forces are cleared automatically after each update. The default behavior is modified by calling autoClearForces. The purpose of this function is to support sub-stepping. Sub-stepping is often used to maintain a fixed sized time step under a variable frame-rate. When you perform sub-stepping you will disable auto clearing of forces and instead call clearForces after all sub-steps are complete in one pass of your game loop.

See also: enableSubStepping and autoClearForceBuffer

◆ create()

static World::Ptr ime::World::create	(	Scene &	scene,
		Vector2f	gravity
	)

static

Create the physics simulation.

Parameters

scene	The scene this world belongs to
gravity	The acceleration of bodies due to gravity

Returns: The created physics world

Note: This class does not keep a reference to the created object

◆ createBody() [1/2]

Body::Ptr ime::World::createBody ( Body::Type type = Body::Type::Static )

Create a rigid body.

Parameters

type	The type of the body to be created

Returns: The created body or a nullptr if this function is called inside a world callback

By default, this function creates a static body

Warning: This function is locked during callbacks. This usually means you should not attempt to create a body inside a callback dispatched by the world (Callbacks are dispatched during a step)

◆ createBody() [2/2]

void ime::World::createBody	(	const GameObjectPtr &	gameObject,
		Body::Type	type = `Body::Type::Static`
	)

Create a body and attach it to a game object.

Parameters

gameObject	The game object to attach the body to
type	The type of the body to be created

By default, this function creates a static body

Note: If the world is in the middle of a step, the body will not be created. This usually means you should not attempt to create a body inside a callback dispatched by the world (Callbacks are dispatched during a step)

◆ createJoint()

Joint::Ptr ime::World::createJoint ( const JointDefinition & definition )

Create a joint.

Parameters

definition Definition to create a joint from

Returns: The created joint or a nullptr if this function is called inside a world callback

Note: If the joined bodies are set to not collide, they will stop colliding after the joint is created

Warning: This function is locked during callbacks. This usually means you should not attempt to create a joint inside a callback dispatched by the world (Callbacks are dispatched during a step)

◆ destroyAllBodies()

void ime::World::destroyAllBodies ( )

Destroy all the bodies in the world.

Warning: This function is locked during callbacks. This usually means you should not attempt to create a body inside a callback dispatched by the world (Callbacks are dispatched during a step)

◆ destroyAllJoints()

void ime::World::destroyAllJoints ( )

Destroy all the joints in the world.

Warning: This function is locked during callbacks. This usually means you should not attempt to create a joint inside a callback dispatched by the world (Callbacks are dispatched during a step)

◆ destroyBody()

bool ime::World::destroyBody ( const Body::Ptr & body )

Destroy a rigid body.

Parameters

body	The rigid body to be destroyed

Returns: True if the body was destroyed or false if the world is in the middle of a step or the body does not exist

This function destroys all associated shapes and joints

Warning: This function is locked during callbacks. This usually means you should not attempt to destroy a joint inside a callback dispatched by the world (Callbacks are dispatched during a step)

See also: createBody(const BodyDefinition&)

◆ destroyJoint()

bool ime::World::destroyJoint ( const Joint::Ptr & joint )

Destroy a joint.

Parameters

joint Joint to be destroyed

Returns: True if the joint was destroyed or false if the joint does not exist or if this function is called inside a world callback

Note: If the joined bodies were set to not collide, they may start colliding after the joint is destroyed

Warning: This function is locked during callbacks. This usually means you should not attempt to destroy a joint inside a callback dispatched by the world (Callbacks are dispatched during a step)

See also: createJoint

◆ enableContinuousPhysics()

void ime::World::enableContinuousPhysics ( bool enable )

Enable or disable continuous physics.

Parameters

enable True to enable otherwise false

By default the physics engine uses continues physics

◆ enableDebugDraw()

void ime::World::enableDebugDraw ( bool enable )

Enable or disable debug drawing.

Parameters

enable True to enable debug drawing or false to disable it

Debug drawing allows you to see what the rigid bodies are doing and where they are in the world. When enabled, the physics simulation will render all the bodies it contains using geometric shapes such as circles and rectangles (Depending on the type of colliders on the bodies). By default, the simulation will only render the shapes of the rigid bodies, however you can use the getDebugDrawFilter to control what gets rendered by the debug drawer.

Debug drawing is useful in many different ways. For instance say you have a rigid body attached to a game object and when the game object collides with a wall, the game object sprite always enters the wall by half of its size due to a origin mismatched between the sprite and the rigid body. In this case enabling debug draw and drawing the sprite will point out the problem immediately, saving you a lot of debugging time.

Be default, debug drawing is disabled

Note: Debug drawing is only available when IME is linked to in debug mode, calling this function when IME is linked to in release mode has no effect

◆ enableSubStepping()

void ime::World::enableSubStepping ( bool subStep )

Enable or disable sub-stepping.

Parameters

subStep True to enable sub-stepping, otherwise false

◆ forEachBody()

void ime::World::forEachBody ( Callback< Body::Ptr & > callback )

Execute a callback for each body in the world.

Parameters

callback The function to be executed on each body

The callback is passed a reference to a pointer to the body on invocation

◆ forEachJoint()

void ime::World::forEachJoint ( Callback< Joint::Ptr & > callback )

Execute a callback for each joint in the world.

Parameters

callback The function to be executed on each joint

The callback is passed a reference to a pointer to the joint on invocation

◆ getBodyById()

Body::Ptr ime::World::getBodyById ( unsigned int id )

Get the body by its unique identifier.

Parameters

id	The id of the body to retrieve

Returns: The body with the given id or a nullptr if there is no body with the given id in the world

◆ getBodyCount()

std::size_t ime::World::getBodyCount ( ) const

Get the number of bodies in the world.

Returns: The number of bodies in th world

◆ getContactListener()

ContactListener& ime::World::getContactListener ( )

Get the contact listener.

Returns: The contact listener

◆ getDebugDrawerFilter()

DebugDrawerFilter& ime::World::getDebugDrawerFilter ( )

Get the debug drawer filter data.

Returns: A reference to the debug drawer filter data

The returned data may be manipulated to set what is rendered by the debug drawer

See also: enableDebugDraw

◆ getGravity()

Vector2f ime::World::getGravity ( ) const

Get the gravity of the world.

Returns: The gravity of the world

◆ getJointCount()

std::size_t ime::World::getJointCount ( ) const

Get the number of joints in the world.

Returns: The number of joints in the world

◆ getScene()

Scene& ime::World::getScene ( )

Get the scene the simulation belongs to.

Returns: The scene this simulation belongs to

◆ getTimescale()

float ime::World::getTimescale ( ) const

Get the timescale.

Returns: The timescale

See also: setTimescale

◆ isContinuousPhysicsEnabled()

bool ime::World::isContinuousPhysicsEnabled ( ) const

Check whether continuous physics is enabled or not.

Returns: True if enabled, otherwise false

See also: enableContinuousPhysics

◆ isDebugDrawEnabled()

bool ime::World::isDebugDrawEnabled ( ) const

Check if debug draw is enabled or not.

Returns: True if debug draw is enabled, otherwise false

See also: enableDebugDraw

◆ isFixedStep()

bool ime::World::isFixedStep ( ) const

Check if the world is updated in fixed or variable time steps.

Returns: True if world is updated in fixed time steps otherwise false

See also: setFixedUpdate

◆ isForceBufferAutoCleared()

bool ime::World::isForceBufferAutoCleared ( ) const

Check whether or not the force buffer on all bodies is cleared after each update.

Returns: True if the force buffer is automatically cleared, otherwise false

See also: autoClearForceBuffer

◆ isLocked()

bool ime::World::isLocked ( ) const

Check if the world is in the middle of a time step or not.

Returns: True if the world is in the middle of a time step, otherwise false

Note: Some functions are locked while the world is in a time step. This means that any request to execute them will be denied

◆ isSleepingAllowed()

bool ime::World::isSleepingAllowed ( ) const

Check if the world can sleep or not.

Returns: True if the world can sleep, otherwise false

◆ isSubSteppingEnabled()

bool ime::World::isSubSteppingEnabled ( ) const

Check if sub-stepping is enabled or not.

Returns: True if enabled, or false if disabled

◆ operator=()

World& ime::World::operator= ( const World & )

delete

Copy assignment operator.

◆ queryAABB()

void ime::World::queryAABB	(	const AABBCallback &	callback,
		const AABB &	aabb
	)

Query the world for all colliders that overlap the given AABB.

Parameters

callback	The function to be executed for every Collider that overlaps the given AABB
aabb	The AABB to query

The callback is executed for every collider that overlaps aabb. The callback must, on every invocation return true to continue with the query or false to terminate the query. When true is returned, the query will continue until all overlapping colliders are processed

◆ rayCast()

void ime::World::rayCast	(	const RayCastCallback &	callback,
		Vector2f	startPoint,
		Vector2f	endPoint
	)

Ray-cast the world for all the colliders in the path of the ray.

Parameters

callback	The function to be executed when the ray collides with a collider
startPoint	The starting point of the ray
endPoint	The ending point of the ray

You can use ray casts to do line-of-sight checks, fire guns, etc. The callback will be called for every collider hit by the ray and the value it returns determines how the ray proceeds. Returning a value of zero indicates the ray cast should be terminated. A value of one indicates the ray cast should continue as if no hit occurred. A value of -1 filters the collider (The the ray cast will proceed as if the collider does not exist). If you return the fraction from the argument list, the ray will be clipped to the current intersection point. So you can ray cast any shape, ray cast all shapes, or ray cast the closest shape by returning the appropriate value.

Warning: Due to round-off errors, ray casts can sneak through small cracks between polygons in your static environment. If this is not acceptable in your game, trying slightly overlapping your polygons

◆ setFixedStep()

void ime::World::setFixedStep ( bool fixed )

Set whether or not the world is updated in fixed times steps.

Parameters

fixed True to update world in fixed time steps otherwise false

When set to false, the physics update is synced with the render fps which may vary from time to time. It is advised to use fixed time steps for consistent physics

By default, the world is updated using a fixed time step

◆ setGravity()

void ime::World::setGravity ( Vector2f gravity )

Change the gravity of the world.

Parameters

gravity The new gravity

◆ setTimescale()

void ime::World::setTimescale ( float timescale )

Set the simulation timescale.

Parameters

timescale The new timescale

The timescale can be used to speed up or slow down the simulation without changing the FPS limit. Values above 1.0f speed up the simulation whilst values below 1.0f slow it down A timescale of zero freezes the simulation (Dynamic bodies stop moving).

By default the timescale is 1.0f (real-time)

Note: The simulation timescale will be multiplied by the timescale of the scene this simulation belongs to. If the scenes timescale is set to 2.0f and the simulation timescale is 2.0f, then the simulation will run 4 times as fast

◆ update()

void ime::World::update	(	Time	timeStep,
		unsigned int	velocityIterations,
		unsigned int	positionIterations
	)

Update the physics world.

Parameters

timeStep	The amount o time to simulate
velocityIterations	Iteration for the velocity solver
positionIterations	Iteration for the constraint solver

This function performs integration, collision detection and constraint solution. The iteration count controls how many times the constraint solver sweeps over all the contacts and joints in the world. More iteration always yields a better simulation. But don't trade a small time step for a large iteration count. 60Hz and 10 iterations is far better than 30Hz and 20 iterations.

Note: There is a trade-off between performance and accuracy when selecting velocity and position iterations. Using fewer iterations increases performance but accuracy suffers. Likewise, using more iterations decreases performance but improves the quality of your simulation. The recommended velocity and position iterations are 8 and 3 respectively. All iterations take place in a single step/update; This function is called automatically by the scene and does not need to be invoked directly

The documentation for this class was generated from the following file:

World.h

Classes

Public Types

Public Member Functions

Static Public Member Functions

Detailed Description

Member Typedef Documentation

◆ AABBCallback

◆ GameObjectPtr

◆ Ptr

◆ RayCastCallback

Constructor & Destructor Documentation

◆ World()

◆ ~World()

Member Function Documentation

◆ allowSleep()

◆ autoClearForceBuffer()

◆ clearForces()

◆ create()

◆ createBody() [1/2]

◆ createBody() [2/2]

◆ createJoint()

◆ destroyAllBodies()

◆ destroyAllJoints()

◆ destroyBody()

◆ destroyJoint()

◆ enableContinuousPhysics()

◆ enableDebugDraw()

◆ enableSubStepping()

◆ forEachBody()

◆ forEachJoint()

◆ getBodyById()

◆ getBodyCount()

◆ getContactListener()

◆ getDebugDrawerFilter()

◆ getGravity()

◆ getJointCount()

◆ getScene()

◆ getTimescale()

◆ isContinuousPhysicsEnabled()

◆ isDebugDrawEnabled()

◆ isFixedStep()

◆ isForceBufferAutoCleared()

◆ isLocked()

◆ isSleepingAllowed()

◆ isSubSteppingEnabled()

◆ operator=()

◆ queryAABB()

◆ rayCast()

◆ setFixedStep()

◆ setGravity()

◆ setTimescale()

◆ update()