ColliderComponent

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

Wraps a Rapier collider. Attach after RigidBodyComponent.

Component ordering: Transform → RigidBodyComponent → ColliderComponent.

Extends

• Component

Constructors

Constructor

new ColliderComponent(config): ColliderComponent

Defined in: physics/src/ColliderComponent.ts:91

Parameters

config

ColliderConfig

Returns

ColliderComponent

Overrides

Component.constructor

Properties

_colliderHandles

readonly _colliderHandles: number[] = []

Defined in: physics/src/ColliderComponent.ts:50

Internal

Ordered Rapier collider handles, set during onAdd.

---

_contactFilter

_contactFilter: ContactFilter | null = null

Defined in: physics/src/ColliderComponent.ts:58

Internal

Active contact filter, read by PhysicsWorld’s pair hook.

---

_oneWayLanded

_oneWayLanded: Set<string> | null = null

Defined in: physics/src/ColliderComponent.ts:69

Internal

Directed Rapier-handle pairs whose contact with this one-way platform has started and not yet ended. While a pair is in here the platform stays solid for it regardless of the position rule — a deep first-impact penetration must not flip an established landing back to passable while the solver is still pushing the rider out. Maintained by PhysicsWorld from collision start/end events and collider removal; null unless the collider is configured oneWay.

---

config

readonly config: ColliderConfig

Defined in: physics/src/ColliderComponent.ts:47

Collider configuration (shape, sensor, etc.).

---

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

---

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

_colliderHandle

Get Signature

get _colliderHandle(): number

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

Internal

First Rapier handle for single-shape access.

Returns

number

---

_oneWayFilterActive

Get Signature

get _oneWayFilterActive(): boolean

Defined in: physics/src/ColliderComponent.ts:172

Internal

True while the collider’s active filter is still the one config.oneWay installed — the debug overlay draws one-way visuals only then, so a custom filter set over the preset isn’t shown as one-way.

Returns

boolean

---

colliderCount

Get Signature

get colliderCount(): number

Defined in: physics/src/ColliderComponent.ts:138

Number of collider shapes attached to this component’s rigid body.

Returns

number

---

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

---

isDroppingThrough

Get Signature

get isDroppingThrough(): boolean

Defined in: physics/src/ColliderComponent.ts:640

True while a dropThrough window is active for this collider.

Returns

boolean

---

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

---

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

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

---

_detachColliderHandle()

_detachColliderHandle(handle): void

Defined in: physics/src/ColliderComponent.ts:161

Internal

Forget one handle after PhysicsWorld removes its body.

Parameters

handle

number

Returns

void

---

_dispatchCollision()

_dispatchCollision(event): void

Defined in: physics/src/ColliderComponent.ts:799

Internal

Called by PhysicsWorld during event dispatch.

Parameters

event

CollisionEvent

Returns

void

---

_dispatchTrigger()

_dispatchTrigger(event): void

Defined in: physics/src/ColliderComponent.ts:810

Internal

Called by PhysicsWorld during event dispatch.

Parameters

event

TriggerEvent

Returns

void

---

_effectivePart()

_effectivePart(index): ColliderPartConfig

Defined in: physics/src/ColliderComponent.ts:148

Internal

Scaled geometry and placement for one ordered shape.

Parameters

index

number

Returns

ColliderPartConfig

---

_evaluateContactFilter()

_evaluateContactFilter(contact): boolean

Defined in: physics/src/ColliderComponent.ts:778

Internal

Run the contact filter for a candidate pair.

Deliberate exception to the report-and-rethrow rule for developer callbacks: this is called from inside Rapier’s WASM step, and a throw unwinding through WASM mid-step leaves the physics world in an undefined state. The error is caught, reported through the boundary, and the pair falls back to solid — the conservative default.

Reported once per installed filter, not per throw: the filter runs for every candidate pair every step, and a persistently throwing one would otherwise log at frame rate and evict everything else from the error snapshot. setContactFilter re-arms the report.

Parameters

contact

ContactCandidate

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

---

_part()

_part(index): ColliderPartConfig

Defined in: physics/src/ColliderComponent.ts:143

Internal

Geometry and placement for one ordered collider shape.

Parameters

index

number

Returns

ColliderPartConfig

---

_previousPose()

_previousPose(index): Readonly<ColliderStepPose> | undefined

Defined in: physics/src/ColliderComponent.ts:153

Internal

This part’s start pose before its last simulated movement.

Parameters

index

number

Returns

Readonly<ColliderStepPose> | undefined

---

_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

---

_scaleDirection()

_scaleDirection(direction): object

Defined in: physics/src/ColliderComponent.ts:696

Internal

Apply signed world scale to a body-local direction.

Parameters

direction

x

number

y

number

Returns

object

x

x: number

y

y: number

---

_syncScale()

_syncScale(): void

Defined in: physics/src/ColliderComponent.ts:648

Internal

Apply the Transform’s world scale before a physics step.

Returns

void

---

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

---

contactWith()

contactWith(other, options?): ColliderContact | undefined

Defined in: physics/src/ColliderComponent.ts:388

The closest points between this collider and other at their current poses, or undefined when they are further apart than prediction (pixels, default 0: touching or overlapping only) or either component has no live collider. A geometric query on the shapes, so it answers for sensors, which never get contact data on their events, and for a pair that never collided.

With selfShapeIndex / otherShapeIndex it measures that one shape pair; pass the indices from a TriggerEvent or CollisionEvent to measure the pair that fired it. Without them, compound colliders report the closest pair among all their parts. An index outside the component’s parts throws, as does other from a different scene’s physics world.

collider.onTrigger((ev) => {
  const contact = collider.contactWith(ev.otherCollider, ev);
  if (contact) spawnSparks(contact.otherPoint, contact.normal);
});

Parameters

other

ColliderComponent

options?

otherShapeIndex?

number

prediction?

number

selfShapeIndex?

number

Returns

ColliderContact | undefined

---

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

---

dropThrough()

dropThrough(seconds): void

Defined in: physics/src/ColliderComponent.ts:628

Let this body fall through one-way platforms for the next seconds seconds of simulated time — the standard down-jump. Only this body is affected; other bodies standing on the same platform stay supported. When the window expires mid-platform, the body keeps falling until it is clear and lands on the next solid side it reaches from above.

Callable before the component is added; the window then starts when the collider is created.

Parameters

seconds

number

Returns

void

---

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

---

getOverlapping()

Call Signature

getOverlapping<T>(filter): Entity & T[]

Defined in: physics/src/ColliderComponent.ts:342

Return all entities whose colliders currently overlap this one, optionally filtered.

Type Parameters

T

T

Parameters

filter

EntityFilter & object

Returns

Entity & T[]

Call Signature

getOverlapping(filter?): Entity[]

Defined in: physics/src/ColliderComponent.ts:345

Return all entities whose colliders currently overlap this one, optionally filtered.

Parameters

filter?

EntityFilter

Returns

Entity[]

---

getOverlappingComponents()

getOverlappingComponents<C>(cls): C[]

Defined in: physics/src/ColliderComponent.ts:358

Return components of type C from all overlapping entities that have one.

Type Parameters

C

C extends Component

Parameters

cls

ComponentClass<C>

Returns

C[]

---

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

---

onAdd()

onAdd(): void

Defined in: physics/src/ColliderComponent.ts:178

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

---

onCollision()

onCollision(handler): () => void

Defined in: physics/src/ColliderComponent.ts:281

Subscribe to collision events. Returns an unsubscribe function.

Parameters

handler

(e) => void

Returns

() => void

---

onDestroy()

onDestroy(): void

Defined in: physics/src/ColliderComponent.ts:271

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

Returns

void

Overrides

Component.onDestroy

---

onDisable()

onDisable(): void

Defined in: physics/src/ColliderComponent.ts:232

Take the collider out of the simulation, keeping its Rapier allocation. Rapier does not re-emit a collision-start for a collider disabled and re-enabled while still overlapping something — a reused entity dropped onto an existing contact gets no onCollision for it.

Returns

void

Overrides

Component.onDisable

---

onEnable()

onEnable(): void

Defined in: physics/src/ColliderComponent.ts:251

Called when the component becomes effectively enabled — enabled is true and the entity is active. Fires right after onAdd() for a component added to an active entity, and again on every later flip. Bring live resources back online here (unpause a sound, show a display object, re-enable a physics body). Game-state reset does not belong here: the hook sees whatever state the component held while dormant.

Returns

void

Overrides

Component.onEnable

---

onTrigger()

onTrigger(handler): () => void

Defined in: physics/src/ColliderComponent.ts:291

Subscribe to trigger events (sensor). Returns an unsubscribe function.

Parameters

handler

(e) => void

Returns

() => void

---

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

---

setContactFilter()

setContactFilter(filter): void

Defined in: physics/src/ColliderComponent.ts:610

Set (or clear, with null) this collider’s contact filter — a per-pair veto that decides each physics step whether a candidate contact with another collider is solid (true) or passes through (false). Replaces the built-in filter a oneWay config installed. Callable before the component is added — the filter is armed at collider creation.

The filter runs inside the physics step, so no contact normal exists yet; the ContactCandidate exposes the two sides’ positions and velocities instead. The candidate is a single reused instance — read what you need inside the filter and copy it; a stored reference shows other pairs’ values after the call returns. A filter that throws is reported through the error boundary once (per installed filter) and the pair stays solid.

The component does not own a custom filter’s lifetime. Reinstall it when game code reconstructs the collider.

Parameters

filter

ContactFilter | null

Returns

void

---

setFriction()

setFriction(friction): void

Defined in: physics/src/ColliderComponent.ts:499

Set this component’s friction on every collider part. Values must be finite and at least 0. Callable before the component is added; the value is also kept when setSensor recreates the Rapier colliders.

Parameters

friction

number

Returns

void

---

setRestitution()

setRestitution(restitution): void

Defined in: physics/src/ColliderComponent.ts:481

Set this component’s restitution on every collider part. Values must be finite and at least 0. Callable before the component is added; the value is also kept when setSensor recreates the Rapier colliders.

Parameters

restitution

number

Returns

void

---

setSensor()

setSensor(sensor): void

Defined in: physics/src/ColliderComponent.ts:452

Make this collider a sensor, or solid again. Callable before the component is added — the updated config is applied at collider creation.

On a live collider the Rapier collider is recreated with the new flag: every pair it is currently in ends with a stop (or exit) at the next step and re-forms as the new kind, so a solid box flipped to a sensor falls through what it was resting on. The body’s getMass() is unchanged, the contact filter and every subscription survive, and the collider handle changes. A call that does not change the flag does nothing. Dev builds warn when the flip leaves handlers of the silenced kind (onCollision on a sensor, onTrigger on a solid) registered.

Parameters

sensor

boolean

Returns

void

---

setShape()

setShape(shape, options?): void

Defined in: physics/src/ColliderComponent.ts:540

Replace one collider shape in place, optionally changing its body-local offset in the same operation. Shape dimensions and offset coordinates use authored pixels like ColliderConfig; the current Transform scale applies to both. Omitting offset preserves the selected part’s current offset. The Rapier collider, its body attachment, and every onCollision/onTrigger subscription survive the swap.

The body keeps the mass it already had. A collider is a collision proxy, not a measure of how much matter is there, so a character that crouches takes the same knockback from applyImpulse as one standing up. Pass recomputeMass: true when the new shape means genuinely more or less matter, and the body’s mass should come back from density × the new shape.

Shape or offset changes can leave the collider overlapping other geometry. Check the region the target collider will newly occupy before applying the change. For a feet-origin character standing from a crouch, that region is the headroom between the crouched and standing top edges.

Callable before the component is added — the updated config is applied at collider creation. A pre-add call cannot recompute mass: the body takes its mass from the new shape at creation anyway.

A bad shape, index, offset coordinate, or scaled result throws before anything is stored. Supplied offset coordinates are copied, so later caller mutation cannot change the selected part.

Parameters

shape

ColliderShape

options?

index?

number

offset?

Vec2Like

recomputeMass?

boolean

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