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 packages/nape-js/src/space/Space.ts:44

Accessors

arbiters

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

Returns ArbiterList
- Defined in packages/nape-js/src/space/Space.ts:295

bodies

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

Returns BodyList
- Defined in packages/nape-js/src/space/Space.ts:270

broadphase

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

Returns Broadphase
- Defined in packages/nape-js/src/space/Space.ts:126

compounds

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

Returns CompoundList
- Defined in packages/nape-js/src/space/Space.ts:265

constraints

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

Returns ConstraintList
- Defined in packages/nape-js/src/space/Space.ts:280

deterministic

get deterministic(): boolean
If true, the simulation produces identical results across runs on the same platform given the same inputs (same-platform "soft" determinism).

When enabled, all internal iteration orders (bodies, constraints, arbiters, islands) are sorted by stable IDs before processing. sortContacts is also forced to true.

Performance: adds ~1-5% overhead to step() due to sorting. Default: false.

Returns boolean
- Defined in packages/nape-js/src/space/Space.ts:169
set deterministic(value: boolean): void
Parameters
- value: boolean
Returns void
- Defined in packages/nape-js/src/space/Space.ts:172

elapsedTime

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

Returns number
- Defined in packages/nape-js/src/space/Space.ts:315

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 packages/nape-js/src/space/Space.ts:102
set gravity(value: Vec2): void
Parameters
- value: Vec2
Returns void
- Defined in packages/nape-js/src/space/Space.ts:109

listeners

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

Returns ListenerList
- Defined in packages/nape-js/src/space/Space.ts:305

liveBodies

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

Returns BodyList
- Defined in packages/nape-js/src/space/Space.ts:275

liveConstraints

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

Returns ConstraintList
- Defined in packages/nape-js/src/space/Space.ts:285

metrics

get metrics(): PhysicsMetricsData
Read-only snapshot of the last step() metrics. Returns a reused object (no allocation per call). Only populated when profilerEnabled is true; all values are zero otherwise.

Call metrics.toJSON() for a plain-object copy suitable for logging.

Returns PhysicsMetricsData
- Defined in packages/nape-js/src/space/Space.ts:202

profilerEnabled

get profilerEnabled(): boolean
Enable the built-in performance profiler. When true, each step() call measures per-phase timings (broadphase, narrowphase, velocity solver, position solver, CCD, sleep) and collects entity counters (body, contact, constraint counts). Read results via metrics.

Performance: adds ~14 performance.now() calls per step (~1 microsecond total). Default: false.

Returns boolean
- Defined in packages/nape-js/src/space/Space.ts:188
set profilerEnabled(value: boolean): void
Parameters
- value: boolean
Returns void
- Defined in packages/nape-js/src/space/Space.ts:191

sortContacts

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

Returns boolean
- Defined in packages/nape-js/src/space/Space.ts:152
set sortContacts(value: boolean): void
Parameters
- value: boolean
Returns void
- Defined in packages/nape-js/src/space/Space.ts:155

subSteps

get subSteps(): number
Number of sub-steps performed per step() call. Each sub-step uses deltaTime / subSteps and the same velocity/position iteration counts.

Higher values improve simulation stability (stacking, fast objects, joint stiffness) at the cost of proportionally more CPU time.
- 1 (default) — standard single-step behaviour, zero overhead.
- 4 — good balance between quality and performance for most games.
- 8+ — high-precision, useful for stiff constraints or very fast objects.
Performance: cost scales linearly — subSteps = 4 ≈ 4× solver work. Tip: you can lower velocityIterations to compensate (e.g. 10 iter × 1 step → 3 iter × 4 sub-steps ≈ similar quality at ~1.2× cost).
Returns number
Throws
If set to a value less than 1 or NaN.
- Defined in packages/nape-js/src/space/Space.ts:223
set subSteps(value: number): void
Parameters
- value: number
Returns void
- Defined in packages/nape-js/src/space/Space.ts:226

timeStamp

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

Returns number
- Defined in packages/nape-js/src/space/Space.ts:310

userData

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

Returns Record<string, unknown>
- Defined in packages/nape-js/src/space/Space.ts:91

world

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

Returns Body
- Defined in packages/nape-js/src/space/Space.ts:290

worldAngularDrag

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

Returns number
Throws
If set to NaN.
- Defined in packages/nape-js/src/space/Space.ts:240
set worldAngularDrag(value: number): void
Parameters
- value: number
Returns void
- Defined in packages/nape-js/src/space/Space.ts:243

worldLinearDrag

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

Returns number
Throws
If set to NaN.
- Defined in packages/nape-js/src/space/Space.ts:254
set worldLinearDrag(value: number): void
Parameters
- value: number
Returns void
- Defined in packages/nape-js/src/space/Space.ts:257

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 packages/nape-js/src/space/Space.ts:752

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 packages/nape-js/src/space/Space.ts:969

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 packages/nape-js/src/space/Space.ts:816

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 packages/nape-js/src/space/Space.ts:887

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 packages/nape-js/src/space/Space.ts:691

clear

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

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

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 packages/nape-js/src/space/Space.ts:1010

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 packages/nape-js/src/space/Space.ts:1039

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 packages/nape-js/src/space/Space.ts:1115

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 packages/nape-js/src/space/Space.ts:527

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 packages/nape-js/src/space/Space.ts:1067

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 packages/nape-js/src/space/Space.ts:1083

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 packages/nape-js/src/space/Space.ts:723

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 packages/nape-js/src/space/Space.ts:924

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 packages/nape-js/src/space/Space.ts:781

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 packages/nape-js/src/space/Space.ts:850

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 packages/nape-js/src/space/Space.ts:661

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 packages/nape-js/src/space/Space.ts:331

toString

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

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

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 packages/nape-js/src/space/Space.ts:367

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 packages/nape-js/src/space/Space.ts:485

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 packages/nape-js/src/space/Space.ts:426

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

deterministic

Returns boolean

Parameters

Returns void

elapsedTime

Returns number

gravity

Returns Vec2

Throws

Parameters

Returns void

listeners

Returns ListenerList

liveBodies

Returns BodyList

liveConstraints

Returns ConstraintList

metrics

Returns PhysicsMetricsData

profilerEnabled

Returns boolean

Parameters

Returns void

sortContacts

Returns boolean

Parameters

Returns void

subSteps

Returns number

Throws

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