World Class
The dynamics world, where all bodies and constraints live.
Constructor
World
-
[options]
Parameters:
-
[options]Object optional-
[solver]Solver optionalDefaults to GSSolver.
-
[gravity]Array optionalDefaults to y=-9.78.
-
[broadphase]Broadphase optionalDefaults to SAPBroadphase
-
[islandSplit=true]Boolean optional
-
Example:
var world = new World({
gravity: [0, -10],
broadphase: new SAPBroadphase()
});
world.addBody(new Body());
Item Index
Methods
Properties
- applyDamping
- applyGravity
- applySpringForces
- bodies
- bodiesToBeRemoved
- BODY_SLEEPING static
- broadphase
- constraints
- contactMaterials
- defaultContactMaterial
- defaultMaterial
- disabledBodyCollisionPairs
- emitImpactEvent
- frictionGravity
- gravity
- ISLAND_SLEEPING static
- islandManager
- islandSplit
- lastTimeStep
- narrowphase
- NO_SLEEPING static
- overlapKeeper
- sleepMode
- solveConstraints
- solver
- springs
- stepping
- time
- useFrictionGravityOnZeroGravity
- useWorldGravityAsFrictionGravity
Methods
addBody
-
body
Add a body to the simulation
Parameters:
-
bodyBody
Example:
var world = new World(),
body = new Body();
world.addBody(body);
addConstraint
-
constraint
Add a constraint to the simulation.
Parameters:
-
constraintConstraint
Example:
var constraint = new LockConstraint(bodyA, bodyB);
world.addConstraint(constraint);
addContactMaterial
-
contactMaterial
Add a ContactMaterial to the simulation.
Parameters:
-
contactMaterialContactMaterial
clear
()
Resets the World, removes all bodies, constraints and springs.
disableBodyCollision
-
bodyA -
bodyB
Disable collision between two bodies
emit
-
event
Emit an event.
Parameters:
-
eventObject-
typeString
-
Returns:
The self object, for chainability.
enableBodyCollision
-
bodyA -
bodyB
Enable collisions between the given two bodies
getBodyById
-
id
Get a body by its id.
Parameters:
-
idNumber
Returns:
The body, or false if it was not found.
getContactMaterial
-
materialA -
materialB
Get a contact material given two materials
Returns:
The matching ContactMaterial, or false on fail.
has
-
type -
listener
Check if an event listener is added
Parameters:
-
typeString -
listenerFunction
Returns:
hitTest
-
worldPoint -
bodies -
precision
Test if a world point overlaps bodies
Parameters:
-
worldPointArrayPoint to use for intersection tests
-
bodiesArrayA list of objects to check for intersection
-
precisionNumberUsed for matching against particles and lines. Adds some margin to these infinitesimal objects.
Returns:
Array of bodies that overlap the point
internalStep
-
dt
Make a fixed step.
Parameters:
-
dtNumber
off
-
type -
listener
Remove an event listener
Parameters:
-
typeString -
listenerFunction
Returns:
The self object, for chainability.
on
-
type -
listener
Add an event listener
Parameters:
-
typeString -
listenerFunction
Returns:
The self object, for chainability.
raycast
-
result -
ray
Ray cast against all bodies in the world.
Parameters:
-
resultRaycastResult -
rayRay
Returns:
True if any body was hit.
Example:
var ray = new Ray({
mode: Ray.CLOSEST, // or ANY
from: [0, 0],
to: [10, 0],
});
var result = new RaycastResult();
world.raycast(result, ray);
// Get the hit point
var hitPoint = vec2.create();
result.getHitPoint(hitPoint, ray);
console.log('Hit point: ', hitPoint[0], hitPoint[1], ' at distance ' + result.getHitDistance(ray));
var ray = new Ray({
mode: Ray.ALL,
from: [0, 0],
to: [10, 0],
callback: function(result){
// Print some info about the hit
console.log('Hit body and shape: ', result.body, result.shape);
// Get the hit point
var hitPoint = vec2.create();
result.getHitPoint(hitPoint, ray);
console.log('Hit point: ', hitPoint[0], hitPoint[1], ' at distance ' + result.getHitDistance(ray));
// If you are happy with the hits you got this far, you can stop the traversal here:
result.stop();
}
});
var result = new RaycastResult();
world.raycast(result, ray);
removeBody
-
body
Remove a body from the simulation. If this method is called during step(), the body removal is scheduled to after the step.
Parameters:
-
bodyBody
runNarrowphase
-
np -
bi -
si -
xi -
ai -
bj -
sj -
xj -
aj -
mu
Runs narrowphase for the shape pair i and j.
Parameters:
-
npNarrowphase -
biBody -
siShape -
xiArray -
aiNumber -
bjBody -
sjShape -
xjArray -
ajNumber -
muNumber
setGlobalRelaxation
-
relaxation
Set the relaxation for all equations and contact materials.
Parameters:
-
relaxationNumber
setGlobalStiffness
-
stiffness
Set the stiffness for all equations and contact materials.
Parameters:
-
stiffnessNumber
step
-
dt -
[timeSinceLastCalled=0] -
[maxSubSteps=10]
Step the physics world forward in time.
There are two modes. The simple mode is fixed timestepping without interpolation. In this case you only use the first argument. The second case uses interpolation. In that you also provide the time since the function was last used, as well as the maximum fixed timesteps to take.
Parameters:
-
dtNumberThe fixed time step size to use.
-
[timeSinceLastCalled=0]Number optionalThe time elapsed since the function was last called.
-
[maxSubSteps=10]Number optionalMaximum number of fixed steps to take per function call.
Example:
// Simple fixed timestepping without interpolation
var fixedTimeStep = 1 / 60;
var world = new World();
var body = new Body({ mass: 1 });
world.addBody(body);
function animate(){
requestAnimationFrame(animate);
world.step(fixedTimeStep);
renderBody(body.position, body.angle);
}
// Start animation loop
requestAnimationFrame(animate);
// Fixed timestepping with interpolation
var maxSubSteps = 10;
var lastTimeSeconds;
function animate(t){
requestAnimationFrame(animate);
timeSeconds = t / 1000;
lastTimeSeconds = lastTimeSeconds || timeSeconds;
deltaTime = timeSeconds - lastTimeSeconds;
world.step(fixedTimeStep, deltaTime, maxSubSteps);
renderBody(body.interpolatedPosition, body.interpolatedAngle);
}
// Start animation loop
requestAnimationFrame(animate);
Properties
applyDamping
Boolean
Enable to automatically apply body damping each step.
Default: true
applyGravity
Boolean
Enable to automatically apply gravity each step.
Default: true
applySpringForces
Boolean
Enable to automatically apply spring forces each step.
Default: true
bodiesToBeRemoved
Array
private
Bodies that are scheduled to be removed at the end of the step.
BODY_SLEEPING
Number
static
Deactivate individual bodies if they are sleepy.
constraints
Array
User-added constraints.
contactMaterials
Array
The ContactMaterials added to the World.
defaultContactMaterial
ContactMaterial
The default contact material to use, if no contact material was set for the colliding materials.
disabledBodyCollisionPairs
Array
private
Disabled body collision pairs. See {{#crossLink "World/disableBodyCollision:method"}}.
emitImpactEvent
Boolean
Set to true if you want to the world to emit the "impact" event. Turning this off could improve performance.
Default: true
frictionGravity
Number
Gravity to use when approximating the friction max force (mumassgravity).
gravity
Array
Gravity in the world. This is applied on all bodies in the beginning of each step().
ISLAND_SLEEPING
Number
static
Deactivates bodies that are in contact, if all of them are sleepy. Note that you must enable .islandSplit for this to work.
islandSplit
Boolean
Whether to enable island splitting. Island splitting can be an advantage for both precision and performance. See IslandManager.
Default: true
lastTimeStep
Number
For keeping track of what time step size we used last step
NO_SLEEPING
Number
static
Never deactivate bodies.
sleepMode
Number
How to deactivate bodies during simulation. Possible modes are: World.NO_SLEEPING, World.BODY_SLEEPING and World.ISLAND_SLEEPING. If sleeping is enabled, you might need to wake up the bodies if they fall asleep when they shouldn't. If you want to enable sleeping in the world, but want to disable it for a particular body, see Body.allowSleep.
Default: World.NO_SLEEPING
solveConstraints
Boolean
Enable/disable constraint solving in each step.
Default: true
stepping
Boolean
Is true during step().
time
Number
World time.
useFrictionGravityOnZeroGravity
Boolean
If the length of .gravity is zero, and .useWorldGravityAsFrictionGravity=true, then switch to using .frictionGravity for friction instead. This fallback is useful for gravityless games.
Default: true
useWorldGravityAsFrictionGravity
Boolean
Set to true if you want .frictionGravity to be automatically set to the length of .gravity.
Default: true
Events
impact
Fired when a first contact is created between two bodies. This event is fired after the step has been done.
postBroadphase
Fired after the Broadphase has collected collision pairs in the world. Inside the event handler, you can modify the pairs array as you like, to prevent collisions between objects that you don't want.
Event Payload:
-
pairsArrayAn array of collision pairs. If this array is [body1,body2,body3,body4], then the body pairs 1,2 and 3,4 would advance to narrowphase.