PhysicsWorld
Defined in: physics/src/PhysicsWorld.ts:112
Central Rapier2D wrapper. All public API values are in pixels. Pixel-to-meter conversion is handled internally.
Constructors
Section titled “Constructors”Constructor
Section titled “Constructor”new PhysicsWorld(
config?):PhysicsWorld
Defined in: physics/src/PhysicsWorld.ts:174
Parameters
Section titled “Parameters”config?
Section titled “config?”Returns
Section titled “Returns”PhysicsWorld
Properties
Section titled “Properties”_colliderComponents
Section titled “_colliderComponents”
readonly_colliderComponents:Map<number,ColliderComponent>
Defined in: physics/src/PhysicsWorld.ts:122
Internal
Map from collider handle to ColliderComponent.
_colliderShapeIndices
Section titled “_colliderShapeIndices”
readonly_colliderShapeIndices:Map<number,number>
Defined in: physics/src/PhysicsWorld.ts:124
Internal
Map from collider handle to its component shape index.
_jointsByBody
Section titled “_jointsByBody”
readonly_jointsByBody:Map<number,Set<JointRecord>>
Defined in: physics/src/PhysicsWorld.ts:126
Internal
Joint records indexed by each attached body handle.
bodyMap
Section titled “bodyMap”
readonlybodyMap:Map<number,Entity>
Defined in: physics/src/PhysicsWorld.ts:117
Map from Rapier body handle to Entity.
colliderMap
Section titled “colliderMap”
readonlycolliderMap:Map<number,Entity>
Defined in: physics/src/PhysicsWorld.ts:119
Map from Rapier collider handle to Entity.
pixelsPerMeter
Section titled “pixelsPerMeter”
readonlypixelsPerMeter:number
Defined in: physics/src/PhysicsWorld.ts:114
Pixels per meter conversion factor.
Accessors
Section titled “Accessors”elapsed
Section titled “elapsed”Get Signature
Section titled “Get Signature”get elapsed():
number
Defined in: physics/src/PhysicsWorld.ts:205
Total simulated time in seconds — the sum of every step’s dt. Tracks the simulation, not the wall clock, so it respects pause and timeScale.
Returns
Section titled “Returns”number
Methods
Section titled “Methods”_detachJointsForBody()
Section titled “_detachJointsForBody()”_detachJointsForBody(
handle):void
Defined in: physics/src/PhysicsWorld.ts:1732
Internal
Detach every joint touching this body. Called when the body is disabled: a dormant entity may be reused as something else, and a joint is cross-life state the same way momentum and landed contacts are — the next life must not wake up tethered to the old partner. Unlike removal, disabling leaves the body in Rapier, so the joints are freed here.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”void
_forgetColliderContacts()
Section titled “_forgetColliderContacts()”_forgetColliderContacts(
handle):void
Defined in: physics/src/PhysicsWorld.ts:1048
Internal
Forget this collider’s arrival pose and landed-rider pairs. Teleports and shape changes must not count as simulated arrival. Rapier reuses collider handles, so a handle leaving the simulation (removed or disabled) must not stay remembered as “landed” on a one-way platform — the next collider with the same handle would inherit it.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”void
_markQueriesStale()
Section titled “_markQueriesStale()”_markQueriesStale(
bodyHandle?):void
Defined in: physics/src/PhysicsWorld.ts:1143
Internal
Note that a live collider moved without a step (a teleport, or a re-enable), so the next query rebuilds Rapier’s index first. A repositioned body also loses its arrival history and landed pairs.
Parameters
Section titled “Parameters”bodyHandle?
Section titled “bodyHandle?”number
Returns
Section titled “Returns”void
_previousColliderPose()
Section titled “_previousColliderPose()”_previousColliderPose(
handle):Readonly<ColliderStepPose> |undefined
Defined in: physics/src/PhysicsWorld.ts:290
Internal
Last advancing step’s start pose, unless invalidated since.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”Readonly<ColliderStepPose> | undefined
_removeJoint()
Section titled “_removeJoint()”_removeJoint(
record):void
Defined in: physics/src/PhysicsWorld.ts:1717
Internal
Remove a live joint and unlink its record.
Parameters
Section titled “Parameters”record
Section titled “record”JointRecord
Returns
Section titled “Returns”void
_replaceCollider()
Section titled “_replaceCollider()”_replaceCollider(
handle,entity,bodyHandle,config,component,shapeIndex,enabled):number
Defined in: physics/src/PhysicsWorld.ts:1000
Internal
Replace a live collider with one built from config, keeping
the body’s mass and the collider’s enabled state, and return the new
handle. Rapier applies a sensor-flag change only to pairs formed after
it — an awake body’s existing pairs keep their old kind — so a flip has
to be a new collider. Its current pairs end with a stop at the next
step, which _resolveSide still routes to component through the
retired handle, and re-form in the new kind.
The handle changes, so nothing outside this class may cache one; the component’s ordered handle list is the only place it lives.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
entity
Section titled “entity”Entity
bodyHandle
Section titled “bodyHandle”number
config
Section titled “config”component
Section titled “component”shapeIndex
Section titled “shapeIndex”number
enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”number
_setContactFilterEnabled()
Section titled “_setContactFilterEnabled()”_setContactFilterEnabled(
handle,enabled):void
Defined in: physics/src/PhysicsWorld.ts:355
Internal
Toggle contact filtering for a live collider — flips Rapier’s
hook flag and the set that decides whether step passes hooks at all.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
enabled
Section titled “enabled”boolean
Returns
Section titled “Returns”void
_setJointMotor()
Section titled “_setJointMotor()”_setJointMotor(
record,motor):void
Defined in: physics/src/PhysicsWorld.ts:1617
Internal
Reconfigure an attached joint’s motor.
Parameters
Section titled “Parameters”record
Section titled “record”JointRecord
Returns
Section titled “Returns”void
addJoint()
Section titled “addJoint()”addJoint(
bodyA,bodyB,config):JointHandle
Defined in: physics/src/PhysicsWorld.ts:656
Connect two live, active rigid bodies with a joint. All lengths and anchors are in pixels; every number must be finite, and lengths, stiffness and damping at least 0.
Parameters
Section titled “Parameters”config
Section titled “config”Returns
Section titled “Returns”castShape()
Section titled “castShape()”castShape(
shape,origin,direction,maxDistance,options?):RaycastHit|null
Defined in: physics/src/PhysicsWorld.ts:1278
Sweep shape from origin along direction and return the first thing
it would hit, or null if nothing is struck within maxDistance. All
values in pixels.
This is the swept counterpart to queryShape, which only reports what a
shape overlaps where it already stands. Use it to test a move before
committing to it: carrying a rider on a moving platform, spotting a
closing platform before it traps the player, or checking clearance for a
fast fall.
distance is how far the shape travelled, point the world contact
point, and normal the surface normal on the entity that was hit. A
shape already overlapping something at origin reports that hit at
distance: 0 by default. Set stopAtPenetration: false to allow movement
out of an initial overlap while still detecting obstacles along the route.
Movement deeper into the overlap still reports a hit.
The direction is normalized internally, so any non-zero
vector works; a zero-length direction throws, and so does a shape with
a dimension that is not finite and above 0. excludeEntity skips every
collider of that entity — pass the mover when the sweep starts inside its
own collider. Sensors are skipped unless sensors says otherwise.
Reports every live collider at its current pose, running a zero-duration step first when colliders changed since the last step.
Parameters
Section titled “Parameters”origin
Section titled “origin”Vec2Like
direction
Section titled “direction”Vec2Like
maxDistance
Section titled “maxDistance”number
options?
Section titled “options?”excludeEntity?
Section titled “excludeEntity?”Entity
filterGroups?
Section titled “filterGroups?”number
rotation?
Section titled “rotation?”number
sensors?
Section titled “sensors?”stopAtPenetration?
Section titled “stopAtPenetration?”boolean
Stop at an initial overlap (default true). False allows escape.
Returns
Section titled “Returns”RaycastHit | null
contactBetween()
Section titled “contactBetween()”contactBetween(
handle,otherHandle,prediction?):ColliderContact|undefined
Defined in: physics/src/PhysicsWorld.ts:1374
The closest points between two colliders at their current poses, or
undefined when either handle is unknown or the shapes are further apart
than prediction (pixels, default 0: touching or overlapping only). A
geometric query, so it answers for sensors and for pairs that never
formed a contact, and needs no step first. prediction must be finite
and at least 0. normal points from the first collider toward the
second. Colliders whose shapes coincide exactly report an arbitrary
direction. Takes internal Rapier collider handles; game code calls
ColliderComponent.contactWith() instead.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
otherHandle
Section titled “otherHandle”number
prediction?
Section titled “prediction?”number = 0
Returns
Section titled “Returns”ColliderContact | undefined
createBody()
Section titled “createBody()”createBody(
entity,config):number
Defined in: physics/src/PhysicsWorld.ts:610
Create a rigid body and register it. Returns the Rapier handle.
Parameters
Section titled “Parameters”entity
Section titled “entity”Entity
config
Section titled “config”Returns
Section titled “Returns”number
createCollider()
Section titled “createCollider()”createCollider(
entity,bodyHandle,config,component,shapeIndex?,effectivePart?):number
Defined in: physics/src/PhysicsWorld.ts:754
Create a collider attached to a body. Returns the Rapier collider handle.
Parameters
Section titled “Parameters”entity
Section titled “entity”Entity
bodyHandle
Section titled “bodyHandle”number
config
Section titled “config”component
Section titled “component”shapeIndex?
Section titled “shapeIndex?”number = 0
effectivePart?
Section titled “effectivePart?”Returns
Section titled “Returns”number
destroy()
Section titled “destroy()”destroy():
void
Defined in: physics/src/PhysicsWorld.ts:1565
Destroy the physics world and free resources.
Returns
Section titled “Returns”void
getBody()
Section titled “getBody()”getBody(
handle):RigidBody|undefined
Defined in: physics/src/PhysicsWorld.ts:1123
Get a Rapier rigid body by handle. A handle this world did not issue,
or has freed since — including the -1 a RigidBodyComponent holds
before add and after destroy — resolves to undefined. Rapier itself
decodes such a handle to whichever body now sits at that index.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”RigidBody | undefined
getCollider()
Section titled “getCollider()”getCollider(
handle):Collider|undefined
Defined in: physics/src/PhysicsWorld.ts:1133
Get a Rapier collider by handle. A handle this world did not issue, or
has freed since — including the -1 a ColliderComponent holds before
add and after removal — resolves to undefined.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”Collider | undefined
processCollisionEvents()
Section titled “processCollisionEvents()”processCollisionEvents():
void
Defined in: physics/src/PhysicsWorld.ts:387
Deliver the collision events step() queued, plus anything still in
Rapier’s queue, to their ColliderComponents. Every step’s events are
delivered, in order, each with the contact data of its own step.
Collecting and dispatching are separate passes. A handler can retire an entity, and a pooled one goes straight back out of its pool as something else, so both sides of every pair are captured with the life they were queued for before any handler runs. Each side is re-checked immediately before its own callback: the first handler can retire the second side’s receiver. A pair naming a life that has ended, or a collider that was removed mid-drain, is dropped rather than delivered against the changed state.
Returns
Section titled “Returns”void
queryOverlapping()
Section titled “queryOverlapping()”queryOverlapping(
colliderHandle):Entity[]
Defined in: physics/src/PhysicsWorld.ts:1460
Return all entities whose colliders currently overlap the given
collider. Reports Rapier’s intersection pairs, which exist only when
one side is a sensor. Reflects every live collider at its current pose,
running a zero-duration step first when colliders changed since the
last step. Takes an internal Rapier collider handle; game code calls
ColliderComponent.getOverlapping() instead.
Parameters
Section titled “Parameters”colliderHandle
Section titled “colliderHandle”number
Returns
Section titled “Returns”Entity[]
queryRadius()
Section titled “queryRadius()”queryRadius(
center,radius,options?):Entity[]
Defined in: physics/src/PhysicsWorld.ts:1350
Return all entities with a collider overlapping the circle around
center (pixels). Sugar over queryShape with a circle; radius must
be finite and above 0.
Parameters
Section titled “Parameters”center
Section titled “center”Vec2Like
radius
Section titled “radius”number
options?
Section titled “options?”excludeEntity?
Section titled “excludeEntity?”Entity
filterGroups?
Section titled “filterGroups?”number
sensors?
Section titled “sensors?”Returns
Section titled “Returns”Entity[]
queryShape()
Section titled “queryShape()”queryShape(
shape,position,options?):Entity[]
Defined in: physics/src/PhysicsWorld.ts:1415
Return all entities with a collider overlapping shape placed at
position (pixels, rotation in radians). excludeEntity skips every
collider of that entity — pass the querying entity for “what’s around
me” queries. Sensors are skipped unless sensors says otherwise. A
shape with a dimension that is not finite and above 0 throws.
Reports every live collider at its current pose, running a zero-duration step first when colliders changed since the last step — a collider spawned this frame is already seen.
Parameters
Section titled “Parameters”position
Section titled “position”Vec2Like
options?
Section titled “options?”excludeEntity?
Section titled “excludeEntity?”Entity
filterGroups?
Section titled “filterGroups?”number
rotation?
Section titled “rotation?”number
sensors?
Section titled “sensors?”Returns
Section titled “Returns”Entity[]
raycast()
Section titled “raycast()”raycast(
origin,direction,maxDistance,options?):RaycastHit|null
Defined in: physics/src/PhysicsWorld.ts:1203
Cast a ray and return the first hit. All values in pixels.
The direction is normalized internally, so any non-zero vector works —
e.g. target.sub(origin). Throws on a zero-length direction.
excludeEntity skips every collider of that entity — pass the caster
when the ray starts inside its own collider. Sensors are skipped unless
sensors says otherwise.
Reports every live collider at its current pose, including one created,
re-shaped, enabled, disabled or teleported since the last step, at the
cost of a zero-duration step before the query (see step).
Parameters
Section titled “Parameters”origin
Section titled “origin”Vec2Like
direction
Section titled “direction”Vec2Like
maxDistance
Section titled “maxDistance”number
options?
Section titled “options?”excludeEntity?
Section titled “excludeEntity?”Entity
filterGroups?
Section titled “filterGroups?”number
sensors?
Section titled “sensors?”Returns
Section titled “Returns”RaycastHit | null
removeBody()
Section titled “removeBody()”removeBody(
handle):void
Defined in: physics/src/PhysicsWorld.ts:934
Remove a rigid body and all its colliders from the world. Each
collider’s ColliderComponent is left holding no handle, so its own
teardown and every later call on it are inert; a handle Rapier reuses
for the next collider cannot be reached through the stale component.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”void
removeCollider()
Section titled “removeCollider()”removeCollider(
handle):void
Defined in: physics/src/PhysicsWorld.ts:973
Remove a single collider from the world, leaving its body (if any) intact. No-ops if the handle is already gone — removing a body already tears down its colliders, so this covers the case where that ran first.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
Returns
Section titled “Returns”void
setColliderShape()
Section titled “setColliderShape()”setColliderShape(
handle,config,options?,shapeIndex?,effectivePart?):void
Defined in: physics/src/PhysicsWorld.ts:1075
Replace a live collider’s shape, keeping its handle, body attachment,
collision groups, and event subscriptions. config is the owning
component’s config, already carrying the new shape.
The body keeps its mass unless recomputeMass asks for it back from
density × the new shape.
Parameters
Section titled “Parameters”handle
Section titled “handle”number
config
Section titled “config”options?
Section titled “options?”recomputeMass?
Section titled “recomputeMass?”boolean
shapeIndex?
Section titled “shapeIndex?”number = 0
effectivePart?
Section titled “effectivePart?”Returns
Section titled “Returns”void
setGravity()
Section titled “setGravity()”setGravity(
x,y):void
Defined in: physics/src/PhysicsWorld.ts:605
Set gravity in pixels/s².
Parameters
Section titled “Parameters”number
number
Returns
Section titled “Returns”void
snapshot()
Section titled “snapshot()”snapshot():
object
Defined in: physics/src/PhysicsWorld.ts:1483
Inspector-facing snapshot of the current rigid bodies and active contacts.
Returns
Section titled “Returns”object
bodies
Section titled “bodies”bodies:
object[]
contacts
Section titled “contacts”contacts:
object[]
elapsed
Section titled “elapsed”elapsed:
number
step()
Section titled “step()”step(
dt):void
Defined in: physics/src/PhysicsWorld.ts:219
Step the physics simulation by dt seconds and queue the step’s
collision events, each captured with that step’s contact data.
processCollisionEvents() delivers them; a caller that steps directly
must call it, or the queued pairs accumulate.
dt must be finite and >= 0. A zero-duration step moves nothing and
advances no simulated time; it rebuilds Rapier’s query index, which is
what the spatial queries use it for.
Parameters
Section titled “Parameters”number
Returns
Section titled “Returns”void
toMeters()
Section titled “toMeters()”toMeters(
pixels):number
Defined in: physics/src/PhysicsWorld.ts:192
Convert pixels to meters.
Parameters
Section titled “Parameters”pixels
Section titled “pixels”number
Returns
Section titled “Returns”number
toPixels()
Section titled “toPixels()”toPixels(
meters):number
Defined in: physics/src/PhysicsWorld.ts:197
Convert meters to pixels.
Parameters
Section titled “Parameters”meters
Section titled “meters”number
Returns
Section titled “Returns”number
Coding agents: fetch https://yage.dev/llms.txt first and prefer the Markdown references it links over these HTML pages. This page's Markdown counterpart is /llms/packages/physics.md.