Class Space

The physics world. Add bodies, shapes, and constraints, then call step() each frame to advance the simulation.

Constructors

constructor

new Space(gravity?: Vec2, broadphase?: Broadphase): Space
Parameters
- Optionalgravity: Vec2
  Initial gravity vector (default (0, 0)).
- Optionalbroadphase: Broadphase
  Broadphase algorithm to use.
Returns Space
- Defined in src/space/Space.ts:43

Accessors

arbiters

get arbiters(): ArbiterList
Read-only list of all active collision/fluid arbiters.

Returns ArbiterList
- Defined in src/space/Space.ts:210

bodies

get bodies(): BodyList
Read-only list of all Body objects directly in this space.

Returns BodyList
- Defined in src/space/Space.ts:185

broadphase

get broadphase(): Broadphase
The broadphase algorithm currently in use (SWEEP_AND_PRUNE or DYNAMIC_AABB_TREE).

Returns Broadphase
- Defined in src/space/Space.ts:125

compounds

get compounds(): CompoundList
Read-only list of all Compound objects in this space.

Returns CompoundList
- Defined in src/space/Space.ts:180

constraints

get constraints(): ConstraintList
Read-only list of all Constraint objects in this space.

Returns ConstraintList
- Defined in src/space/Space.ts:195

elapsedTime

get elapsedTime(): number
Cumulative time simulated (sum of all deltaTime values passed to step()).

Returns number
- Defined in src/space/Space.ts:230

gravity

get gravity(): Vec2
World gravity applied to all dynamic bodies each step. Live Vec2.

Returns Vec2
Throws
If set to null or a disposed Vec2.
- Defined in src/space/Space.ts:101
set gravity(value: Vec2): void
Parameters
- value: Vec2
Returns void
- Defined in src/space/Space.ts:108

listeners

get listeners(): ListenerList
Read-only list of all event listeners registered to this space.

Returns ListenerList
- Defined in src/space/Space.ts:220

liveBodies

get liveBodies(): BodyList
Read-only list of bodies that are awake and actively simulated.

Returns BodyList
- Defined in src/space/Space.ts:190

liveConstraints

get liveConstraints(): ConstraintList
Read-only list of active (awake) constraints.

Returns ConstraintList
- Defined in src/space/Space.ts:200

sortContacts

get sortContacts(): boolean
If true, contact points are sorted for determinism. Default: true.

Returns boolean
- Defined in src/space/Space.ts:144
set sortContacts(value: boolean): void
Parameters
- value: boolean
Returns void
- Defined in src/space/Space.ts:147

timeStamp

get timeStamp(): number
Number of step() calls made so far.

Returns number
- Defined in src/space/Space.ts:225

userData

get userData(): Record<string, unknown>
Arbitrary user data attached to this Space.

Returns Record<string, unknown>
- Defined in src/space/Space.ts:90

world

get world(): Body
The static world body that acts as an immovable anchor for constraints.

Returns Body
- Defined in src/space/Space.ts:205

worldAngularDrag

get worldAngularDrag(): number
Global angular drag coefficient applied to all bodies.

Returns number
Throws
If set to NaN.
- Defined in src/space/Space.ts:155
set worldAngularDrag(value: number): void
Parameters
- value: number
Returns void
- Defined in src/space/Space.ts:158

worldLinearDrag

get worldLinearDrag(): number
Global linear drag coefficient applied to all bodies.

Returns number
Throws
If set to NaN.
- Defined in src/space/Space.ts:169
set worldLinearDrag(value: number): void
Parameters
- value: number
Returns void
- Defined in src/space/Space.ts:172

Methods

bodiesInAABB

bodiesInAABB(
    aabb: AABB,
    containment?: boolean,
    strict?: boolean,
    filter?: InteractionFilter | null,
    output?: BodyList | null,
): BodyList
Return all bodies that have at least one shape overlapping the given AABB.
Parameters
- aabb: AABB
  The axis-aligned bounding box to test against.
- containment: boolean = false
  If true, only shapes fully contained within the AABB count.
- strict: boolean = true
  If true, exact shape geometry is tested; otherwise only AABBs are compared.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: BodyList | null
  Optional existing BodyList to accumulate results into.
Returns BodyList
A BodyList of matching bodies.

Throws
If aabb is null or degenerate (zero width or height).
- Defined in src/space/Space.ts:667

bodiesInBody

bodiesInBody(
    body: Body,
    filter?: InteractionFilter | null,
    output?: BodyList | null,
): BodyList
Return all bodies in the space that overlap with any shape attached to body. Equivalent to calling bodiesInShape for each of body's shapes and merging results.
Parameters
- body: Body
  The body whose shapes are used as the query region.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: BodyList | null
  Optional existing BodyList to accumulate results into.
Returns BodyList
A BodyList of overlapping bodies.

Throws
If body is null.
- Defined in src/space/Space.ts:884

bodiesInCircle

bodiesInCircle(
    position: Vec2,
    radius: number,
    containment?: boolean,
    filter?: InteractionFilter | null,
    output?: BodyList | null,
): BodyList
Return all bodies that have at least one shape overlapping a query circle.
Parameters
- position: Vec2
  World-space centre of the query circle.
- radius: number
  Radius of the query circle; must be strictly positive and not NaN.
- containment: boolean = false
  If true, only shapes fully contained within the circle count.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: BodyList | null
  Optional existing BodyList to accumulate results into.
Returns BodyList
A BodyList of matching bodies.

Throws
If position is null/disposed, or radius is NaN or non-positive.
- Defined in src/space/Space.ts:731

bodiesInShape

bodiesInShape(
    shape: Shape,
    containment?: boolean,
    filter?: InteractionFilter | null,
    output?: BodyList | null,
): BodyList
Return all bodies in the space that have at least one shape overlapping shape.
Parameters
- shape: Shape
  The query shape; must be attached to a Body.
- containment: boolean = false
  If true, only shapes fully contained within shape count.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: BodyList | null
  Optional existing BodyList to accumulate results into.
Returns BodyList
A BodyList of overlapping bodies.

Throws
If shape is null, not attached to a Body, or is an invalid polygon.
- Defined in src/space/Space.ts:802

bodiesUnderPoint

bodiesUnderPoint(
    point: Vec2,
    filter?: InteractionFilter | null,
    output?: BodyList | null,
): BodyList
Return all bodies that have at least one shape containing the given world-space point.
Parameters
- point: Vec2
  The world-space point to test.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: BodyList | null
  Optional existing BodyList to accumulate results into.
Returns BodyList
A BodyList of matching bodies.

Throws
If point is null or disposed.
- Defined in src/space/Space.ts:606

clear

clear(): void
Remove all bodies, constraints, and compounds from this space.

Returns void
Throws
If called during a step().
- Defined in src/space/Space.ts:266

convexCast

convexCast(
    shape: Shape,
    deltaTime: number,
    liveSweep?: boolean,
    filter?: InteractionFilter | null,
): ConvexResult | null
Sweep shape along its current velocity for deltaTime seconds and return the first hit.
Parameters
- shape: Shape
  The shape to sweep; must belong to a Body.
- deltaTime: number
  Duration of the sweep; must be non-negative.
- liveSweep: boolean = false
  If true, other body velocities are considered during the sweep.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
Returns ConvexResult | null
The first RayResult hit, or null if nothing was struck.

Throws
If shape is null, not attached to a Body, or deltaTime is negative/NaN.
- Defined in src/space/Space.ts:925

convexMultiCast

convexMultiCast(
    shape: Shape,
    deltaTime: number,
    liveSweep?: boolean,
    filter?: InteractionFilter | null,
    output?: ConvexResultList | null,
): ConvexResultList
Sweep shape along its current velocity for deltaTime seconds and return all hits.
Parameters
- shape: Shape
  The shape to sweep; must belong to a Body.
- deltaTime: number
  Duration of the sweep; must be non-negative.
- liveSweep: boolean = false
  If true, other body velocities are considered during the sweep.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ConvexResultList | null
  Optional existing RayResultList to accumulate results into.
Returns ConvexResultList
A RayResultList of all hits encountered during the sweep.

Throws
If shape is null, not attached to a Body, or deltaTime is negative/NaN.
- Defined in src/space/Space.ts:954

debugDraw

debugDraw(drawer: DebugDraw, flags?: number): void
Draw the current state of the physics world using a user-supplied renderer.

Walks all bodies, shapes, constraints, contacts, AABBs, and velocity vectors and calls the appropriate draw primitives on drawer. Only the layers selected by flags are rendered.

Performance note: this method allocates temporary vertex arrays for polygon shapes on every call. It is intended for development/debug use only — do not call it in a performance-critical production loop.
Parameters
- drawer: DebugDraw
  The renderer to use. Must not be null.
- flags: number = DebugDrawFlags.ALL
  Bitmask of DebugDrawFlags layers to render. Defaults to DebugDrawFlags.ALL.
Returns void
Example
```
space.debugDraw(myDrawer, DebugDrawFlags.SHAPES | DebugDrawFlags.JOINTS);
```
- Defined in src/space/Space.ts:1030

interactionType

interactionType(shape1: Shape, shape2: Shape): InteractionType | null
Determine the type of interaction between two shapes (COLLISION, FLUID, SENSOR, or null if they don't interact).
Parameters
- shape1: Shape
  The first shape; must belong to a Body.
- shape2: Shape
  The second shape; must belong to a Body.
Returns InteractionType | null
The InteractionType, or null if the shapes would not interact.

Throws
If either shape is null or not attached to a Body.
- Defined in src/space/Space.ts:442

rayCast

rayCast(
    ray: Ray,
    inner?: boolean,
    filter?: InteractionFilter | null,
): RayResult | null
Cast a ray into the space and return the closest hit.
Parameters
- ray: Ray
  The ray to cast.
- inner: boolean = false
  If true, shapes are tested from the inside as well (useful for concave queries).
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
Returns RayResult | null
The closest RayResult, or null if nothing was hit.

Throws
If ray is null.
- Defined in src/space/Space.ts:982

rayMultiCast

rayMultiCast(
    ray: Ray,
    inner?: boolean,
    filter?: InteractionFilter | null,
    output?: RayResultList | null,
): RayResultList
Cast a ray into the space and return all hits.
Parameters
- ray: Ray
  The ray to cast.
- inner: boolean = false
  If true, shapes are tested from the inside as well.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: RayResultList | null
  Optional existing RayResultList to accumulate results into.
Returns RayResultList
A RayResultList of all shapes the ray intersected.

Throws
If ray is null.
- Defined in src/space/Space.ts:998

shapesInAABB

shapesInAABB(
    aabb: AABB,
    containment?: boolean,
    strict?: boolean,
    filter?: InteractionFilter | null,
    output?: ShapeList | null,
): ShapeList
Return all shapes that overlap with the given AABB.
Parameters
- aabb: AABB
  The axis-aligned bounding box to test against.
- containment: boolean = false
  If true, only shapes fully contained within the AABB are returned.
- strict: boolean = true
  If true, exact shape geometry is tested; otherwise only AABBs are compared.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ShapeList | null
  Optional existing ShapeList to accumulate results into.
Returns ShapeList
A ShapeList of matching shapes.

Throws
If aabb is null or degenerate (zero width or height).
- Defined in src/space/Space.ts:638

shapesInBody

shapesInBody(
    body: Body,
    filter?: InteractionFilter | null,
    output?: ShapeList | null,
): ShapeList
Return all shapes in the space that overlap with any shape attached to body. Equivalent to calling shapesInShape for each of body's shapes and merging results.
Parameters
- body: Body
  The body whose shapes are used as the query region.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ShapeList | null
  Optional existing ShapeList to accumulate results into.
Returns ShapeList
A ShapeList of overlapping shapes.

Throws
If body is null.
- Defined in src/space/Space.ts:839

shapesInCircle

shapesInCircle(
    position: Vec2,
    radius: number,
    containment?: boolean,
    filter?: InteractionFilter | null,
    output?: ShapeList | null,
): ShapeList
Return all shapes that overlap with a circle defined by position and radius.
Parameters
- position: Vec2
  World-space centre of the query circle.
- radius: number
  Radius of the query circle; must be strictly positive and not NaN.
- containment: boolean = false
  If true, only shapes fully contained within the circle are returned.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ShapeList | null
  Optional existing ShapeList to accumulate results into.
Returns ShapeList
A ShapeList of matching shapes.

Throws
If position is null/disposed, or radius is NaN or non-positive.
- Defined in src/space/Space.ts:696

shapesInShape

shapesInShape(
    shape: Shape,
    containment?: boolean,
    filter?: InteractionFilter | null,
    output?: ShapeList | null,
): ShapeList
Return all shapes in the space that overlap with shape.
Parameters
- shape: Shape
  The query shape; must be attached to a Body.
- containment: boolean = false
  If true, only shapes fully contained within shape are returned.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ShapeList | null
  Optional existing ShapeList to accumulate results into.
Returns ShapeList
A ShapeList of overlapping shapes.

Throws
If shape is null, not attached to a Body, or is an invalid polygon.
- Defined in src/space/Space.ts:765

shapesUnderPoint

shapesUnderPoint(
    point: Vec2,
    filter?: InteractionFilter | null,
    output?: ShapeList | null,
): ShapeList
Return all shapes whose geometry contains the given world-space point.
Parameters
- point: Vec2
  The world-space point to test.
- Optionalfilter: InteractionFilter | null
  Optional interaction filter to restrict results.
- Optionaloutput: ShapeList | null
  Optional existing ShapeList to accumulate results into.
Returns ShapeList
A ShapeList of matching shapes.

Throws
If point is null or disposed.
- Defined in src/space/Space.ts:576

step

step(
    deltaTime: number,
    velocityIterations?: number,
    positionIterations?: number,
): void
Advance the simulation by deltaTime seconds. velocityIterations and positionIterations control solver accuracy (default 10 each).
Parameters
- deltaTime: number
  Time step in seconds; must be strictly positive and not NaN.
- velocityIterations: number = 10
  Number of velocity solver iterations (minimum 1).
- positionIterations: number = 10
  Number of position solver iterations (minimum 1).
Returns void
Throws
If deltaTime is NaN, non-positive, or any iteration count is less than 1.
- Defined in src/space/Space.ts:246

toString

toString(): string
Returns a brief string summary of this space.

Returns string
A string in the form Space(bodies=N).
- Defined in src/space/Space.ts:1200

visitBodies

visitBodies(lambda: (body: Body) => void): void
Call lambda for every body in the space, including those inside compounds.
Parameters
- lambda: (body: Body) => void
  Callback invoked with each Body.
Returns void
Throws
If lambda is null.
- Defined in src/space/Space.ts:282

visitCompounds

visitCompounds(lambda: (compound: Compound) => void): void
Call lambda for every compound in the space (recursively).
Parameters
- lambda: (compound: Compound) => void
  Callback invoked with each Compound.
Returns void
Throws
If lambda is null.
- Defined in src/space/Space.ts:400

visitConstraints

visitConstraints(lambda: (constraint: Constraint) => void): void
Call lambda for every constraint in the space, including those inside compounds.
Parameters
- lambda: (constraint: Constraint) => void
  Callback invoked with each Constraint.
Returns void
Throws
If lambda is null.
- Defined in src/space/Space.ts:341

Class Space

Index

Constructors

Accessors

Methods

Constructors

constructor

Parameters

Returns Space

Accessors

arbiters

Returns ArbiterList

bodies

Returns BodyList

broadphase

Returns Broadphase

compounds

Returns CompoundList

constraints

Returns ConstraintList

elapsedTime

Returns number

gravity

Returns Vec2

Throws

Parameters

Returns void

listeners

Returns ListenerList

liveBodies

Returns BodyList

liveConstraints

Returns ConstraintList

sortContacts

Returns boolean

Parameters

Returns void

timeStamp

Returns number

userData

Returns Record<string, unknown>

world

Returns Body

worldAngularDrag

Returns number

Throws

Parameters

Returns void

worldLinearDrag

Returns number

Throws

Parameters

Returns void

Methods

bodiesInAABB

Parameters

Returns BodyList

Throws

bodiesInBody

Parameters

Returns BodyList

Throws

bodiesInCircle

Parameters

Returns BodyList

Throws

bodiesInShape

Parameters

Returns BodyList

Throws

bodiesUnderPoint

Parameters

Returns BodyList

Throws

clear

Returns void

Throws

convexCast

Parameters

Returns ConvexResult | null