RigidBodyComponent

Defined in: physics/src/RigidBodyComponent.ts:38

Wraps a Rapier rigid body. All public API values are in pixels.

Component ordering: Transform must be added before RigidBodyComponent.

Extends

• Component

Constructors

Constructor

new RigidBodyComponent(config): RigidBodyComponent

Defined in: physics/src/RigidBodyComponent.ts:85

Parameters

config

RigidBodyConfig

Returns

RigidBodyComponent

Overrides

Component.constructor

Properties

_bodyHandle

_bodyHandle: number = -1

Defined in: physics/src/RigidBodyComponent.ts:48

Internal

Rapier body handle, set during onAdd.

---

_currPositionX

_currPositionX: number = 0

Defined in: physics/src/RigidBodyComponent.ts:57

Internal

Current authoritative position (post physics step).

---

_currPositionY

_currPositionY: number = 0

Defined in: physics/src/RigidBodyComponent.ts:59

Internal

---

_currRotation

_currRotation: number = 0

Defined in: physics/src/RigidBodyComponent.ts:61

Internal

Current authoritative rotation (post physics step).

---

_kinematicTargetPositionX

_kinematicTargetPositionX: number = 0

Defined in: physics/src/RigidBodyComponent.ts:63

Internal

Position the next step drives a kinematic body toward.

---

_kinematicTargetPositionY

_kinematicTargetPositionY: number = 0

Defined in: physics/src/RigidBodyComponent.ts:65

Internal

---

_kinematicTargetRotation

_kinematicTargetRotation: number = 0

Defined in: physics/src/RigidBodyComponent.ts:67

Internal

Rotation the next step drives a kinematic body toward.

---

_lastWrittenPositionX

_lastWrittenPositionX: number = 0

Defined in: physics/src/RigidBodyComponent.ts:74

Internal

Position physics last wrote to the Transform. A Transform that still holds it carries no game write to capture. Kept per frame for kinematic bodies; for dynamic and static bodies it is seeded on disable, so a Transform write while dormant reads as pending on enable.

---

_lastWrittenPositionY

_lastWrittenPositionY: number = 0

Defined in: physics/src/RigidBodyComponent.ts:76

Internal

---

_lastWrittenRotation

_lastWrittenRotation: number = 0

Defined in: physics/src/RigidBodyComponent.ts:78

Internal

Rotation physics last wrote to the Transform.

---

_prevPositionX

_prevPositionX: number = 0

Defined in: physics/src/RigidBodyComponent.ts:51

Internal

Previous position for interpolation.

---

_prevPositionY

_prevPositionY: number = 0

Defined in: physics/src/RigidBodyComponent.ts:53

Internal

---

_prevRotation

_prevRotation: number = 0

Defined in: physics/src/RigidBodyComponent.ts:55

Internal

Previous rotation for interpolation.

---

entity

entity: Entity

Defined in: core/dist/index.d.ts:4116

Back-reference to the owning entity. Set by the engine when the component is added to an entity. Do not set manually.

Inherited from

Component.entity

---

syncRotation

syncRotation: boolean

Defined in: physics/src/RigidBodyComponent.ts:45

If false, physics will not write rotation back to Transform.

---

inspectExclude?

static optional inspectExclude?: readonly string[]

Defined in: core/dist/index.d.ts:4338

Own fields and getters the Inspector leaves out of this component’s reflected state. Use it for bulk data that is not worth a diagnostic copy — a parsed tilemap, a large lookup table. Lists merge down the class chain, so a subclass adds to its base class’s exclusions.

class TilemapComponent extends VisualComponent {
  static inspectExclude = ["data"];
}

Inherited from

Component.inspectExclude

---

updatePriority?

static optional updatePriority?: number

Defined in: core/dist/index.d.ts:4325

Class-level default for updatePriority: every instance runs at this priority unless its own updatePriority is written. Undeclared = 0. Subclasses inherit their base class’s value unless they declare their own. Declare it on a component whose behavior depends on running after (or before) a sibling, so the entity that adds it does not have to control the add order.

class BoundsClamp extends Component {
  static updatePriority = 10; // after the follow that moves the camera
}

Inherited from

Component.updatePriority

Accessors

context

Get Signature

get context(): EngineContext

Defined in: core/dist/index.d.ts:4171

Access the EngineContext from the entity’s scene. Throws if the entity is not in a scene.

Returns

EngineContext

Inherited from

Component.context

---

effectiveEnabled

Get Signature

get effectiveEnabled(): boolean

Defined in: core/dist/index.d.ts:4141

Whether the component is actually running: enabled, on an active entity, and past onAdd. This is the state onEnable and onDisable track — read it when a method has to behave one way live and another way dormant.

Returns

boolean

Inherited from

Component.effectiveEnabled

---

enabled

Get Signature

get enabled(): boolean

Defined in: core/dist/index.d.ts:4133

Whether this component runs. Disabled components are skipped by ComponentUpdateSystem.

Writing this fires onEnable / onDisable when the effective state changes — enabled && entity.isActive. A component disabled here stays disabled through a setActive(false) / setActive(true) cycle on its entity.

Returns

boolean

Set Signature

set enabled(value): void

Defined in: core/dist/index.d.ts:4134

Parameters

value

boolean

Returns

void

Inherited from

Component.enabled

---

gravityScale

Get Signature

get gravityScale(): number

Defined in: physics/src/RigidBodyComponent.ts:403

Gravity multiplier for this body. 1 unless set.

Returns

number

---

position

Get Signature

get position(): Vec2

Defined in: physics/src/RigidBodyComponent.ts:526

Body position in pixels — the exact simulated pose. A dynamic or kinematic body’s Transform holds the interpolated pose that gets drawn: smooth, and at most one fixed step behind this value.

Falls back to the entity’s world position when no Rapier body exists (e.g. after teardown has destroyed it).

Returns

Vec2

---

positionX

Get Signature

get positionX(): number

Defined in: physics/src/RigidBodyComponent.ts:552

X component of the exact simulated position in pixels. Avoids the Vec2 allocation of position — prefer this and positionY on a per-frame read path.

Returns

number

---

positionY

Get Signature

get positionY(): number

Defined in: physics/src/RigidBodyComponent.ts:563

Y component of the exact simulated position in pixels. Avoids the Vec2 allocation of position.

Returns

number

---

rotation

Get Signature

get rotation(): number

Defined in: physics/src/RigidBodyComponent.ts:577

Body rotation in radians — the exact simulated pose. A dynamic or kinematic body’s Transform holds the interpolated rotation that gets drawn: smooth, and at most one fixed step behind this value.

Falls back to the entity’s world rotation when no Rapier body exists.

Returns

number

---

scene

Get Signature

get scene(): Scene

Defined in: core/dist/index.d.ts:4166

Access the entity’s scene. Throws if the entity is not in a scene. Prefer this over threading through this.entity.scene in component code.

Returns

Scene

Inherited from

Component.scene

---

speed

Get Signature

get speed(): number

Defined in: physics/src/RigidBodyComponent.ts:326

Speed (velocity magnitude) in pixels/s. No Vec2 allocation.

Returns

number

---

speedSquared

Get Signature

get speedSquared(): number

Defined in: physics/src/RigidBodyComponent.ts:334

Squared speed in (pixels/s)². Cheaper than speed when only comparing magnitudes (e.g. against a threshold).

Returns

number

---

type

Get Signature

get type(): BodyType

Defined in: physics/src/RigidBodyComponent.ts:40

Body type (dynamic, static, kinematic). setType changes it.

Returns

BodyType

---

updatePriority

Get Signature

get updatePriority(): number

Defined in: core/dist/index.d.ts:4159

Where this component runs among its siblings. ComponentUpdateSystem calls update / fixedUpdate on an entity’s components in ascending priority; equal priorities run in add order. Undeclared = 0, so a negative value runs before siblings that keep the default and a positive value runs after them. Writable at any time, before or after add(). Defaults to the class’s static updatePriority.

class Player extends Entity {
  setup() {
    this.add(new Mover());
    this.add(new Brain()).updatePriority = -1; // decides before Mover moves
  }
}

Returns

number

Set Signature

set updatePriority(value): void

Defined in: core/dist/index.d.ts:4160

Parameters

value

number

Returns

void

Inherited from

Component.updatePriority

---

velocityX

Get Signature

get velocityX(): number

Defined in: physics/src/RigidBodyComponent.ts:309

X component of linear velocity in pixels/s. Avoids the Vec2 allocation of getVelocity() — prefer this and velocityY on a per-frame read path. Reading both components calls into Rapier twice; use getVelocityInto() to copy both coordinates with one read.

Returns

number

---

velocityY

Get Signature

get velocityY(): number

Defined in: physics/src/RigidBodyComponent.ts:319

Y component of linear velocity in pixels/s. Avoids the Vec2 allocation of getVelocity().

Returns

number

Methods

_applyEnabled()

_applyEnabled(effective): void

Defined in: core/dist/index.d.ts:4273

Internal

Force an effective-enabled transition, firing the hook on a flip. Used by Entity for teardown, where enabled and the entity’s activeness both still read true.

Parameters

effective

boolean

Returns

void

Inherited from

Component._applyEnabled

---

_capturePendingTarget()

_capturePendingTarget(): void

Defined in: physics/src/RigidBodyComponent.ts:675

Internal

Adopt any pose the game wrote to the Transform as the kinematic step target. Runs before each physics step and before the interpolation lerp overwrites the Transform, so targets stay fresh even on frames that run several steps.

Returns

void

---

_hasPendingTargetPosition()

_hasPendingTargetPosition(): boolean

Defined in: physics/src/RigidBodyComponent.ts:644

Internal

True when the Transform’s world position no longer holds what physics last wrote — i.e. the game (or a moved parent) repositioned it, and the write is waiting to become the kinematic step target.

Returns

boolean

---

_hasPendingTargetRotation()

_hasPendingTargetRotation(): boolean

Defined in: physics/src/RigidBodyComponent.ts:658

Internal

Rotation counterpart of _hasPendingTargetPosition. Compares along the shortest arc: a game that normalizes its own accumulated rotation writes a numerically different, visually identical angle, which is not a new target.

Returns

boolean

---

_isTornDown()

_isTornDown(): boolean

Defined in: core/dist/index.d.ts:4254

Internal

Internal: true once this component has been removed or its entity destroyed. Components are terminal — Entity.add uses this to reject re-attaching an instance whose cleanups and onDestroy already ran.

Returns

boolean

Inherited from

Component._isTornDown

---

_markTornDown()

_markTornDown(): void

Defined in: core/dist/index.d.ts:4260

Internal

Internal: mark this component torn down. Called by Entity.remove() and Entity._performDestroy() after onDestroy runs.

Returns

void

Inherited from

Component._markTornDown

---

_refreshEnabled()

_refreshEnabled(): void

Defined in: core/dist/index.d.ts:4266

Internal

Recompute effective enabled-ness from enabled and the entity’s activeness, firing the hook on a flip.

Returns

void

Inherited from

Component._refreshEnabled

---

_runCleanups()

_runCleanups(onError?): void

Defined in: core/dist/index.d.ts:4241

Internal

Run and clear all registered cleanups. Called by Entity.remove() and Entity._performDestroy() before onDestroy.

Parameters

onError?

(error) => void

Returns

void

Inherited from

Component._runCleanups

---

addCleanup()

protected addCleanup(fn): void

Defined in: core/dist/index.d.ts:4229

Register a cleanup function to run when this component is removed or destroyed, before onDestroy. Use it for what listen, listenScene and listenBus do not cover, such as an unsubscribe from a custom emitter.

Parameters

fn

() => void

Returns

void

Inherited from

Component.addCleanup

---

applyForce()

applyForce(force): void

Defined in: physics/src/RigidBodyComponent.ts:224

Apply a force (in pixels) at the center of mass.

Parameters

force

Vec2Like

Returns

void

---

applyImpulse()

applyImpulse(impulse): void

Defined in: physics/src/RigidBodyComponent.ts:237

Apply an impulse (in pixels) at the center of mass.

Parameters

impulse

Vec2Like

Returns

void

---

applyTorque()

applyTorque(torque): void

Defined in: physics/src/RigidBodyComponent.ts:349

Apply torque, in Rapier’s native units: the value is not converted from pixels, and angular inertia scales with pixelsPerMeter⁻⁴, so the same torque spins a body 16× faster at 100 px/m than at 50. Retune after changing the scale, as with spring stiffness.

Parameters

torque

number

Returns

void

---

destroy()

destroy(): void

Defined in: core/dist/index.d.ts:4247

End this component’s life on its own — the same as entity.remove(SomeClass), without having to name its own class from inside itself, which breaks under subclassing.

Returns

void

Inherited from

Component.destroy

---

fixedUpdate()?

optional fixedUpdate(dt): void

Defined in: core/dist/index.d.ts:4310

Called every fixed timestep by the built-in ComponentUpdateSystem.

Parameters

dt

number

Fixed timestep in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

Component.fixedUpdate

---

getAngularVelocity()

getAngularVelocity(): number

Defined in: physics/src/RigidBodyComponent.ts:366

Get angular velocity in radians/s.

Returns

number

---

getMass()

getMass(): number

Defined in: physics/src/RigidBodyComponent.ts:376

Mass derived from the attached colliders (density × shape size). applyImpulse(dv.scale(getMass())) changes velocity by exactly dv px/s.

Returns

number

---

getPositionInto()

getPositionInto(out): Vec2Buffer

Defined in: physics/src/RigidBodyComponent.ts:537

Copy the exact simulated position in pixels into caller-owned scratch.

Parameters

out

Vec2Buffer

Returns

Vec2Buffer

---

getVelocity()

getVelocity(): Vec2

Defined in: physics/src/RigidBodyComponent.ts:282

Get linear velocity in pixels/s.

Returns

Vec2

---

getVelocityInto()

getVelocityInto(out): Vec2Buffer

Defined in: physics/src/RigidBodyComponent.ts:293

Copy linear velocity in pixels/s into caller-owned scratch.

Parameters

out

Vec2Buffer

Returns

Vec2Buffer

---

listen()

protected listen<T>(source, token, handler): void

Defined in: core/dist/index.d.ts:4211

Subscribe to events from an entity or a state machine, auto-unsubscribe on removal.

this.listen(this.entity, Hurt, ({ dir }) => this.knockback(dir));
this.listen(brain.mode, brain.mode.events.entered, ({ state }) =>
  this.anim.play(state),
);

Type Parameters

T

T

Parameters

source

EventSource

token

EventToken<T>

handler

(data) => void

Returns

void

Inherited from

Component.listen

---

listenBus()

protected listenBus<K>(event, handler): void

Defined in: core/dist/index.d.ts:4222

Subscribe to an engine EventBus event, auto-unsubscribe on removal. Throws when the entity is not in a scene, like listenScene.

Type Parameters

K

K extends keyof EngineEvents

Parameters

event

K

handler

(data) => void

Returns

void

Inherited from

Component.listenBus

---

listenScene()

protected listenScene<T>(token, handler): void

Defined in: core/dist/index.d.ts:4217

Subscribe to scene-level events, auto-unsubscribe on removal. Handlers fire for bubbled entity events (entity = source) and scene.emit events (entity = undefined).

Type Parameters

T

T

Parameters

token

EventToken<T>

handler

(data, entity?) => void

Returns

void

Inherited from

Component.listenScene

---

lockRotations()

lockRotations(locked): void

Defined in: physics/src/RigidBodyComponent.ts:461

Lock or unlock rotation. A locked body ignores torques and contact spin; setAngularVelocity still turns it. Callable before the component is added — the lock is applied when the Rapier body is created.

Parameters

locked

boolean

Returns

void

---

onAdd()

onAdd(): void

Defined in: physics/src/RigidBodyComponent.ts:97

Called when the component is added to an entity. Validate dependencies here — a service, a sibling component, a render layer — and throw when one is missing. The throw is attributed to this component, recorded in Inspector.getErrors().callbackErrors, and rethrown, so it reaches the caller of entity.add() unchanged.

Returns

void

Overrides

Component.onAdd

---

onDestroy()

onDestroy(): void

Defined in: physics/src/RigidBodyComponent.ts:216

Called when the component is destroyed (entity destroyed or component removed).

Returns

void

Overrides

Component.onDestroy

---

onDisable()

onDisable(): void

Defined in: physics/src/RigidBodyComponent.ts:150

Put the Rapier body to sleep without freeing it — the allocation is exactly what a reused entity gets to keep. Momentum and queued forces/torques are cleared and joints are detached, so waking the body cannot resume a motion — or a tether — that started a life ago.

Record dynamic and static Transforms so only dormant writes count on enable. Kinematic bodies keep pending targets written while active.

Returns

void

Overrides

Component.onDisable

---

onEnable()

onEnable(): void

Defined in: physics/src/RigidBodyComponent.ts:173

Bring the body back and snap interpolation to its current pose, so the first frame after reuse renders where the body is rather than lerping from where it slept.

Returns

void

Overrides

Component.onEnable

---

service()

protected service<T>(key): T

Defined in: core/dist/index.d.ts:4188

Lazy proxy-based service resolution. Can be used at field-declaration time:

readonly input = this.service(InputManagerKey);

The actual resolution is deferred until first property access.

Type Parameters

T

T extends object

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

Component.service

---

setAngularDamping()

setAngularDamping(damping): void

Defined in: physics/src/RigidBodyComponent.ts:428

Set angular velocity damping. Values must be finite and at least 0. Callable before the component is added; the value applies at creation.

Parameters

damping

number

Returns

void

---

setAngularVelocity()

setAngularVelocity(v): void

Defined in: physics/src/RigidBodyComponent.ts:359

Set angular velocity in radians/s (Rapier’s native unit, not scaled by pixelsPerMeter). Rapier caps rotation at 45° per physics step.

Parameters

v

number

Returns

void

---

setEnabledTranslations()

setEnabledTranslations(enableX, enableY): void

Defined in: physics/src/RigidBodyComponent.ts:446

Set which translation axes are enabled. A locked axis ignores forces, impulses and contacts; a velocity written with setVelocity still moves the body along it. Callable before the component is added — the locks are applied when the Rapier body is created.

Parameters

enableX

boolean

enableY

boolean

Returns

void

---

setGravityScale()

setGravityScale(scale): void

Defined in: physics/src/RigidBodyComponent.ts:393

Multiply gravity for this body: 1 is the scene’s gravity, 0 removes it, larger values fall faster. This is the per-body control a platformer needs for variable jump height and fast-fall, without moving scene gravity for every other body. scale must be finite; a NaN would write NaN into the body’s position at the next step and nothing recovers it.

Callable before the component is added — the value is applied when the Rapier body is created.

Parameters

scale

number

Returns

void

---

setLinearDamping()

setLinearDamping(damping): void

Defined in: physics/src/RigidBodyComponent.ts:412

Set linear velocity damping. Values must be finite and at least 0. Callable before the component is added; the value applies at creation.

Parameters

damping

number

Returns

void

---

setPosition()

setPosition(x, y): void

Defined in: physics/src/RigidBodyComponent.ts:589

Teleport to a position in pixels — no interpolation, no smoothing, for any body type. On a kinematic body, transform.setPosition() instead moves it there smoothly over one step. A static body’s Transform moves with it (no system writes one otherwise).

Parameters

x

number

y

number

Returns

void

---

setRotation()

setRotation(radians): void

Defined in: physics/src/RigidBodyComponent.ts:624

Teleport to a rotation in radians — no interpolation, no smoothing, for any body type. The rotation counterpart of setPosition; a static body’s Transform rotates with it when syncRotation is on.

Parameters

radians

number

Returns

void

---

setType()

setType(type): void

Defined in: physics/src/RigidBodyComponent.ts:475

Switch the body type at runtime — a dead enemy becomes "static" so nothing pushes it and it pushes nothing; a carried crate becomes "kinematic" while held. Linear and angular velocity are cleared by the switch; locks, gravity scale, damping, colliders and mass are kept. The drawn pose is the exact pose at the switch. Callable before entity.add(); the body is created as the new type.

Parameters

type

BodyType

Returns

void

---

setVelocity()

setVelocity(velocity): void

Defined in: physics/src/RigidBodyComponent.ts:253

Set linear velocity in pixels/s. Rapier caps speed at 400 m/s, 400 × pixelsPerMeter px/s.

Parameters

velocity

Vec2Like

Returns

void

---

setVelocityX()

setVelocityX(vx): void

Defined in: physics/src/RigidBodyComponent.ts:266

Set only the X component of velocity (px/s), preserving Y.

Parameters

vx

number

Returns

void

---

setVelocityY()

setVelocityY(vy): void

Defined in: physics/src/RigidBodyComponent.ts:274

Set only the Y component of velocity (px/s), preserving X.

Parameters

vy

number

Returns

void

---

sibling()

protected sibling<C>(cls): C

Defined in: core/dist/index.d.ts:4199

Lazy proxy-based sibling component resolution. Can be used at field-declaration time:

readonly anim = this.sibling(AnimatedSpriteComponent);

The actual resolution is deferred until first property access. The reference passes instanceof cls before it resolves, so an engine API that checks the type of what it is handed (camera.follow(this.transform)) accepts it.

Type Parameters

C

C extends Component

Parameters

cls

ComponentClass<C>

Returns

C

Inherited from

Component.sibling

---

stateMachine()

protected stateMachine<S>(states, initial, options?): StateMachine<S>

Defined in: core/dist/index.d.ts:4235

Create a state machine whose hooks and event handlers are attributed to this component when they throw. The machine can be declared as a field because service lookup waits until a hook runs.

Type Parameters

S

S extends string

Parameters

states

StateDefinitions<S>

initial

NoInfer<S>

options?

StateMachineOptions

Returns

StateMachine<S>

Inherited from

Component.stateMachine

---

update()?

optional update(dt): void

Defined in: core/dist/index.d.ts:4305

Called every frame by the built-in ComponentUpdateSystem.

Parameters

dt

number

Frame delta in seconds, scaled by scene and entity timeScale.

Returns

void

Inherited from

Component.update

---

use()

protected use<T>(key): T

Defined in: core/dist/index.d.ts:4179

Resolve a service by key, cached after first lookup. Scene-scoped values (registered via scene._registerScoped) take precedence over engine scope. A key declared with scope: "scene" that falls back to engine scope emits a one-shot dev warning — almost always signals a missed beforeEnter hook.

Type Parameters

T

T

Parameters

key

ServiceKey<T>

Returns

T

Inherited from

Component.use