APIdia Launch Partner
Top Description Fields Constructors Methods
com.badlogic.gdx.physics.box2d

public final Class World

extends Object
implements Disposable
Class Inheritance
All Implemented Interfaces
com.badlogic.gdx.utils.Disposable
Imports
java.util.Iterator, com.badlogic.gdx.math.Vector2, com.badlogic.gdx.physics.box2d.JointDef.JointType, com.badlogic.gdx.physics.box2d.joints.DistanceJoint, .DistanceJointDef, .FrictionJoint, .FrictionJointDef, .GearJoint, .GearJointDef, .MotorJoint, .MotorJointDef, .MouseJoint, .MouseJointDef, .PrismaticJoint, .PrismaticJointDef, .PulleyJoint, .PulleyJointDef, .RevoluteJoint, .RevoluteJointDef, .RopeJoint, .RopeJointDef, .WeldJoint, .WeldJointDef, .WheelJoint, .WheelJointDef, com.badlogic.gdx.utils.Array, .Disposable, .GdxRuntimeException, .LongMap, .Pool, .SharedLibraryLoader

The world class manages all physics entities, dynamic simulation, and asynchronous queries. The world also contains efficient memory management facilities.
Author
mzechner

Field Summary

Modifier and TypeField and Description
protected final long
addr

the address of the world instance

protected final LongMap<Body>
bodies

all known bodies

private final Contact
private long[]
protected ContactFilter
contactFilter

Contact filter

protected ContactListener
contactListener

Contact listener

private final Array<Contact>
protected final LongMap<Fixture>
fixtures

all known fixtures

protected final Pool<Body>
freeBodies

pool for bodies

private final Array<Contact>
protected final Pool<Fixture>
freeFixtures

pool for fixtures

pack-priv final Vector2
private final ContactImpulse
protected final LongMap<Joint>
joints

all known joints

private final Manifold
private QueryCallback
private RayCastCallback
private Vector2
private Vector2
pack-priv final float[]
tmpGravity

Get the global gravity vector.

private boolean

Constructor Summary

AccessConstructor and Description
public
World(Vector2
the world gravity vector.
gravity
,
boolean
improve performance by not simulating inactive bodies.
doSleep
)

Construct a world object.

Method Summary

Modifier and TypeMethod and Description
private void
beginContact(long contactAddr)

public void
clearForces()

Manually clear the force buffer on all bodies.

private boolean

Returns:

whether the things collided
contactFilter
(long fixtureA, long fixtureB)

Internal method called from JNI in case a contact happens

public Body
createBody(BodyDef def)

Create a rigid body given a definition.

public Joint
createJoint(JointDef def)

Create a joint to constrain bodies together.

private long
pack-priv void
deactivateBody(Body body)

Internal method for body deactivation with notifying custom contact listener

public void
destroyBody(Body body)

Destroy a rigid body given a definition.

pack-priv void
destroyFixture(Body body, Fixture fixture)

Internal method for fixture destruction with notifying custom contact listener

public void
destroyJoint(Joint joint)

Destroy a joint.

public void
dispose()

Implements com.badlogic.gdx.utils.Disposable.dispose.

Releases all resources of this object.

private void
endContact(long contactAddr)

public boolean
getAutoClearForces()

Get the flag that controls automatic clearing of forces after each time step.

public void
getBodies(Array<Body>
an Array in which to place all bodies currently in the simulation
bodies
)

public int
getBodyCount()

Get the number of bodies.

public int
getContactCount()

Get the number of contacts (each may have 0 or more contact points).

public Array<Contact>

Returns:

the contact list
getContactList
()

Returns the list of Contact instances produced by the last call to step(float, int, int).

public int
getFixtureCount()

Get the number of fixtures.

public void
getFixtures(Array<Fixture>
an Array in which to place all fixtures currently in the simulation
fixtures
)

public Vector2
public int
getJointCount()

Get the number of joints.

public void
getJoints(Array<Joint>
an Array in which to place all joints currently in the simulation
joints
)

public int
getProxyCount()

Get the number of broad-phase proxies.

private boolean

Returns:

whether the native default ContactFilter should be used
getUseDefaultContactFilter
()

Internal method called from JNI

public static native float
getVelocityThreshold()

Returns: the global box2d velocity threshold.

public boolean
isLocked()

Is the world locked (in the middle of a time step).

private native void
jniClearForces(long addr)

private native long
jniCreateBody(long addr, int type, float positionX, float positionY, float angle, float linearVelocityX, float linearVelocityY, float angularVelocity, float linearDamping, float angularDamping, boolean allowSleep, boolean awake, boolean fixedRotation, boolean bullet, boolean active, float inertiaScale)

private native long
jniCreateDistanceJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float length, float frequencyHz, float dampingRatio)

private native long
jniCreateFrictionJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float maxForce, float maxTorque)

private native long
jniCreateGearJoint(long addr, long bodyA, long bodyB, boolean collideConnected, long joint1, long joint2, float ratio)

private native long
jniCreateMotorJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float linearOffsetX, float linearOffsetY, float angularOffset, float maxForce, float maxTorque, float correctionFactor)

private native long
jniCreateMouseJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float targetX, float targetY, float maxForce, float frequencyHz, float dampingRatio)

private native long
jniCreatePrismaticJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float localAxisAX, float localAxisAY, float referenceAngle, boolean enableLimit, float lowerTranslation, float upperTranslation, boolean enableMotor, float maxMotorForce, float motorSpeed)

private native long
jniCreatePulleyJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float groundAnchorAX, float groundAnchorAY, float groundAnchorBX, float groundAnchorBY, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float lengthA, float lengthB, float ratio)

private native long
jniCreateRevoluteJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float referenceAngle, boolean enableLimit, float lowerAngle, float upperAngle, boolean enableMotor, float motorSpeed, float maxMotorTorque)

private native long
jniCreateRopeJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float maxLength)

private native long
jniCreateWeldJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float referenceAngle, float frequencyHz, float dampingRatio)

private native long
jniCreateWheelJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float localAxisAX, float localAxisAY, boolean enableMotor, float maxMotorTorque, float motorSpeed, float frequencyHz, float dampingRatio)

private native void
jniDeactivateBody(long addr, long bodyAddr)

private native void
jniDestroyBody(long addr, long bodyAddr)

private native void
jniDestroyFixture(long addr, long bodyAddr, long fixtureAddr)

private native void
jniDestroyJoint(long addr, long jointAddr)

private native void
jniDispose(long addr)

private native boolean
private native int
jniGetBodyCount(long addr)

private native int
jniGetContactCount(long addr)

private native void
jniGetContactList(long addr, long[] contacts)

private native void
jniGetGravity(long addr, float[] gravity)

private native int
jniGetJointcount(long addr)

private native int
jniGetProxyCount(long addr)

private native boolean
jniIsLocked(long addr)

private native void
jniQueryAABB(long addr, float lowX, float lowY, float upX, float upY)

private native void
jniRayCast(long addr, float aX, float aY, float bX, float bY)

private native void
jniSetAutoClearForces(long addr, boolean flag)

private native void
jniSetContiousPhysics(long addr, boolean flag)

private native void
jniSetGravity(long addr, float gravityX, float gravityY)

private native void
jniSetWarmStarting(long addr, boolean flag)

private native void
jniStep(long addr, float timeStep, int velocityIterations, int positionIterations)

private native long
newWorld(float gravityX, float gravityY, boolean doSleep)

private void
postSolve(long contactAddr, long impulseAddr)

private void
preSolve(long contactAddr, long manifoldAddr)

public void
QueryAABB(QueryCallback
a user implemented callback class.
callback
,
float
the x coordinate of the lower left corner
lowerX
,
float
the y coordinate of the lower left corner
lowerY
,
float
the x coordinate of the upper right corner
upperX
,
float
the y coordinate of the upper right corner
upperY
)

Query the world for all fixtures that potentially overlap the provided AABB.

public void
rayCast(RayCastCallback
a user implemented callback class.
callback
,
Vector2
the ray starting point
point1
,
Vector2
the ray ending point
point2
)

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

public void
rayCast(RayCastCallback
a user implemented callback class.
callback
,
float
the ray starting point X
point1X
,
float
the ray starting point Y
point1Y
,
float
the ray ending point X
point2X
,
float
the ray ending point Y
point2Y
)

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

private boolean
reportFixture(long addr)

private float
reportRayFixture(long addr, float pX, float pY, float nX, float nY, float fraction)

public void
setAutoClearForces(boolean flag)

Set flag to control automatic clearing of forces after each time step.

public void
setContactFilter(ContactFilter filter)

Register a contact filter to provide specific control over collision.

public void
setContactListener(ContactListener listener)

Register a contact event listener.

public void
setContinuousPhysics(boolean flag)

Enable/disable continuous physics.

public void
setDestructionListener(DestructionListener listener)

Register a destruction listener.

public void
setGravity(Vector2 gravity)

Change the global gravity vector.

private void
setUseDefaultContactFilter(boolean use)

Sets flag to tell the native code not to call the Java World class if use is true

public static native void
setVelocityThreshold(float
the threshold, default 1.0f
threshold
)

Sets the box2d velocity threshold globally, for all World instances.

public void
setWarmStarting(boolean flag)

Enable/disable warm starting.

public void
step(float
the amount of time to simulate, this should not vary.
timeStep
,
int
for the velocity constraint solver.
velocityIterations
,
int
for the position constraint solver.
positionIterations
)

Take a time step.

Inherited from java.lang.Object:
cloneequalsfinalizegetClasshashCodenotifynotifyAlltoStringwaitwaitwait

Field Detail

addrback to summary
protected final long addr

the address of the world instance

bodiesback to summary
protected final LongMap<Body> bodies

all known bodies

contactback to summary
private final Contact contact
contactAddrsback to summary
private long[] contactAddrs
contactFilterback to summary
protected ContactFilter contactFilter

Contact filter

contactListenerback to summary
protected ContactListener contactListener

Contact listener

contactsback to summary
private final Array<Contact> contacts
fixturesback to summary
protected final LongMap<Fixture> fixtures

all known fixtures

freeBodiesback to summary
protected final Pool<Body> freeBodies

pool for bodies

freeContactsback to summary
private final Array<Contact> freeContacts
freeFixturesback to summary
protected final Pool<Fixture> freeFixtures

pool for fixtures

gravityback to summary
pack-priv final Vector2 gravity
impulseback to summary
private final ContactImpulse impulse
jointsback to summary
protected final LongMap<Joint> joints

all known joints

manifoldback to summary
private final Manifold manifold
queryCallbackback to summary
private QueryCallback queryCallback
rayCastCallbackback to summary
private RayCastCallback rayCastCallback
rayNormalback to summary
private Vector2 rayNormal
rayPointback to summary
private Vector2 rayPoint
tmpGravityback to summary
pack-priv final float[] tmpGravity

Get the global gravity vector.

useDefaultContactFilterback to summary
private boolean useDefaultContactFilter

Constructor Detail

Worldback to summary
public World(Vector2 gravity, boolean doSleep)

Construct a world object.

Parameters
gravity:Vector2

the world gravity vector.

doSleep:boolean

improve performance by not simulating inactive bodies.

Method Detail

beginContactback to summary
private void beginContact(long contactAddr)
clearForcesback to summary
public void clearForces()

Manually clear the force buffer on all bodies. By default, forces are cleared automatically after each call to Step. The default behavior is modified by calling SetAutoClearForces. 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. setAutoClearForces(boolean)

contactFilterback to summary
private boolean contactFilter(long fixtureA, long fixtureB)

Internal method called from JNI in case a contact happens

Returns:boolean

whether the things collided

createBodyback to summary
public Body createBody(BodyDef def)

Create a rigid body given a definition. No reference to the definition is retained. Bodies created by this method are pooled internally by the World object. They will be freed upon calling World#destroyBody(Body)

See Also
Pool
createJointback to summary
public Joint createJoint(JointDef def)

Create a joint to constrain bodies together. No reference to the definition is retained. This may cause the connected bodies to cease colliding.

createProperJointback to summary
private long createProperJoint(JointDef def)
deactivateBodyback to summary
pack-priv void deactivateBody(Body body)

Internal method for body deactivation with notifying custom contact listener

destroyBodyback to summary
public void destroyBody(Body body)

Destroy a rigid body given a definition. No reference to the definition is retained. This function is locked during callbacks.

destroyFixtureback to summary
pack-priv void destroyFixture(Body body, Fixture fixture)

Internal method for fixture destruction with notifying custom contact listener

destroyJointback to summary
public void destroyJoint(Joint joint)

Destroy a joint. This may cause the connected bodies to begin colliding.

disposeback to summary
public void dispose()

Implements com.badlogic.gdx.utils.Disposable.dispose.

Doc from com.badlogic.gdx.utils.Disposable.dispose.

Releases all resources of this object.

endContactback to summary
private void endContact(long contactAddr)
getAutoClearForcesback to summary
public boolean getAutoClearForces()

Get the flag that controls automatic clearing of forces after each time step.

getBodiesback to summary
public void getBodies(Array<Body> bodies)
Parameters
bodies:Array<Body>

an Array in which to place all bodies currently in the simulation

getBodyCountback to summary
public int getBodyCount()

Get the number of bodies.

getContactCountback to summary
public int getContactCount()

Get the number of contacts (each may have 0 or more contact points).

getContactListback to summary
public Array<Contact> getContactList()

Returns the list of Contact instances produced by the last call to step(float, int, int). Note that the returned list will have O(1) access times when using indexing. contacts are created and destroyed in the middle of a time step. Use ContactListener to avoid missing contacts

Returns:Array<Contact>

the contact list

getFixtureCountback to summary
public int getFixtureCount()

Get the number of fixtures.

getFixturesback to summary
public void getFixtures(Array<Fixture> fixtures)
Parameters
fixtures:Array<Fixture>

an Array in which to place all fixtures currently in the simulation

getGravityback to summary
public Vector2 getGravity()
getJointCountback to summary
public int getJointCount()

Get the number of joints.

getJointsback to summary
public void getJoints(Array<Joint> joints)
Parameters
joints:Array<Joint>

an Array in which to place all joints currently in the simulation

getProxyCountback to summary
public int getProxyCount()

Get the number of broad-phase proxies.

getUseDefaultContactFilterback to summary
private boolean getUseDefaultContactFilter()

Internal method called from JNI

Returns:boolean

whether the native default ContactFilter should be used

getVelocityThresholdback to summary
public static native float getVelocityThreshold()
Returns:float

the global box2d velocity threshold.

isLockedback to summary
public boolean isLocked()

Is the world locked (in the middle of a time step).

jniClearForcesback to summary
private native void jniClearForces(long addr)
jniCreateBodyback to summary
private native long jniCreateBody(long addr, int type, float positionX, float positionY, float angle, float linearVelocityX, float linearVelocityY, float angularVelocity, float linearDamping, float angularDamping, boolean allowSleep, boolean awake, boolean fixedRotation, boolean bullet, boolean active, float inertiaScale)
jniCreateDistanceJointback to summary
private native long jniCreateDistanceJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float length, float frequencyHz, float dampingRatio)
jniCreateFrictionJointback to summary
private native long jniCreateFrictionJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float maxForce, float maxTorque)
jniCreateGearJointback to summary
private native long jniCreateGearJoint(long addr, long bodyA, long bodyB, boolean collideConnected, long joint1, long joint2, float ratio)
jniCreateMotorJointback to summary
private native long jniCreateMotorJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float linearOffsetX, float linearOffsetY, float angularOffset, float maxForce, float maxTorque, float correctionFactor)
jniCreateMouseJointback to summary
private native long jniCreateMouseJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float targetX, float targetY, float maxForce, float frequencyHz, float dampingRatio)
jniCreatePrismaticJointback to summary
private native long jniCreatePrismaticJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float localAxisAX, float localAxisAY, float referenceAngle, boolean enableLimit, float lowerTranslation, float upperTranslation, boolean enableMotor, float maxMotorForce, float motorSpeed)
jniCreatePulleyJointback to summary
private native long jniCreatePulleyJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float groundAnchorAX, float groundAnchorAY, float groundAnchorBX, float groundAnchorBY, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float lengthA, float lengthB, float ratio)
jniCreateRevoluteJointback to summary
private native long jniCreateRevoluteJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float referenceAngle, boolean enableLimit, float lowerAngle, float upperAngle, boolean enableMotor, float motorSpeed, float maxMotorTorque)
jniCreateRopeJointback to summary
private native long jniCreateRopeJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float maxLength)
jniCreateWeldJointback to summary
private native long jniCreateWeldJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float referenceAngle, float frequencyHz, float dampingRatio)
jniCreateWheelJointback to summary
private native long jniCreateWheelJoint(long addr, long bodyA, long bodyB, boolean collideConnected, float localAnchorAX, float localAnchorAY, float localAnchorBX, float localAnchorBY, float localAxisAX, float localAxisAY, boolean enableMotor, float maxMotorTorque, float motorSpeed, float frequencyHz, float dampingRatio)
jniDeactivateBodyback to summary
private native void jniDeactivateBody(long addr, long bodyAddr)
jniDestroyBodyback to summary
private native void jniDestroyBody(long addr, long bodyAddr)
jniDestroyFixtureback to summary
private native void jniDestroyFixture(long addr, long bodyAddr, long fixtureAddr)
jniDestroyJointback to summary
private native void jniDestroyJoint(long addr, long jointAddr)
jniDisposeback to summary
private native void jniDispose(long addr)
jniGetAutoClearForcesback to summary
private native boolean jniGetAutoClearForces(long addr)
jniGetBodyCountback to summary
private native int jniGetBodyCount(long addr)
jniGetContactCountback to summary
private native int jniGetContactCount(long addr)
jniGetContactListback to summary
private native void jniGetContactList(long addr, long[] contacts)
jniGetGravityback to summary
private native void jniGetGravity(long addr, float[] gravity)
jniGetJointcountback to summary
private native int jniGetJointcount(long addr)
jniGetProxyCountback to summary
private native int jniGetProxyCount(long addr)
jniIsLockedback to summary
private native boolean jniIsLocked(long addr)
jniQueryAABBback to summary
private native void jniQueryAABB(long addr, float lowX, float lowY, float upX, float upY)
jniRayCastback to summary
private native void jniRayCast(long addr, float aX, float aY, float bX, float bY)
jniSetAutoClearForcesback to summary
private native void jniSetAutoClearForces(long addr, boolean flag)
jniSetContiousPhysicsback to summary
private native void jniSetContiousPhysics(long addr, boolean flag)
jniSetGravityback to summary
private native void jniSetGravity(long addr, float gravityX, float gravityY)
jniSetWarmStartingback to summary
private native void jniSetWarmStarting(long addr, boolean flag)
jniStepback to summary
private native void jniStep(long addr, float timeStep, int velocityIterations, int positionIterations)
newWorldback to summary
private native long newWorld(float gravityX, float gravityY, boolean doSleep)
postSolveback to summary
private void postSolve(long contactAddr, long impulseAddr)
preSolveback to summary
private void preSolve(long contactAddr, long manifoldAddr)
QueryAABBback to summary
public void QueryAABB(QueryCallback callback, float lowerX, float lowerY, float upperX, float upperY)

Query the world for all fixtures that potentially overlap the provided AABB.

Parameters
callback:QueryCallback

a user implemented callback class.

lowerX:float

the x coordinate of the lower left corner

lowerY:float

the y coordinate of the lower left corner

upperX:float

the x coordinate of the upper right corner

upperY:float

the y coordinate of the upper right corner

rayCastback to summary
public void rayCast(RayCastCallback callback, Vector2 point1, Vector2 point2)

Ray-cast the world for all fixtures in the path of the ray. The ray-cast ignores shapes that contain the starting point.

Parameters
callback:RayCastCallback

a user implemented callback class.

point1:Vector2

the ray starting point

point2:Vector2

the ray ending point

rayCastback to summary
public void rayCast(RayCastCallback callback, float point1X, float point1Y, float point2X, float point2Y)

Ray-cast the world for all fixtures in the path of the ray. The ray-cast ignores shapes that contain the starting point.

Parameters
callback:RayCastCallback

a user implemented callback class.

point1X:float

the ray starting point X

point1Y:float

the ray starting point Y

point2X:float

the ray ending point X

point2Y:float

the ray ending point Y

reportFixtureback to summary
private boolean reportFixture(long addr)
reportRayFixtureback to summary
private float reportRayFixture(long addr, float pX, float pY, float nX, float nY, float fraction)
setAutoClearForcesback to summary
public void setAutoClearForces(boolean flag)

Set flag to control automatic clearing of forces after each time step.

setContactFilterback to summary
public void setContactFilter(ContactFilter filter)

Register a contact filter to provide specific control over collision. Otherwise the default filter is used (b2_defaultFilter). The listener is owned by you and must remain in scope.

setContactListenerback to summary
public void setContactListener(ContactListener listener)

Register a contact event listener. The listener is owned by you and must remain in scope.

setContinuousPhysicsback to summary
public void setContinuousPhysics(boolean flag)

Enable/disable continuous physics. For testing.

setDestructionListenerback to summary
public void setDestructionListener(DestructionListener listener)

Register a destruction listener. The listener is owned by you and must remain in scope.

setGravityback to summary
public void setGravity(Vector2 gravity)

Change the global gravity vector.

setUseDefaultContactFilterback to summary
private void setUseDefaultContactFilter(boolean use)

Sets flag to tell the native code not to call the Java World class if use is true

setVelocityThresholdback to summary
public static native void setVelocityThreshold(float threshold)

Sets the box2d velocity threshold globally, for all World instances.

Parameters
threshold:float

the threshold, default 1.0f

setWarmStartingback to summary
public void setWarmStarting(boolean flag)

Enable/disable warm starting. For testing.

stepback to summary
public void step(float timeStep, int velocityIterations, int positionIterations)

Take a time step. This performs collision detection, integration, and constraint solution.

Parameters
timeStep:float

the amount of time to simulate, this should not vary.

velocityIterations:int

for the velocity constraint solver.

positionIterations:int

for the position constraint solver.