CameraComponent

Defined in: renderer/src/CameraComponent.ts:104

Core camera state component. Added by CameraEntity; holds position, zoom, rotation, and layer bindings. Provides convenience methods that delegate to sibling behavior components (CameraFollow, CameraShake, etc.).

Added by CameraEntity; access via direct reference from spawn() or by querying entities with this component.

Extends

• Component

Constructors

Constructor

new CameraComponent(options?): CameraComponent

Defined in: renderer/src/CameraComponent.ts:118

Parameters

options?

CameraComponentOptions

Returns

CameraComponent

Overrides

Component.constructor

Properties

autoBind

readonly autoBind: boolean

Defined in: renderer/src/CameraComponent.ts:114

Bind every world-space layer before applying bindings. Default: true.

---

bindings

readonly bindings: CameraBinding[] | null

Defined in: renderer/src/CameraComponent.ts:112

---

cameraName

readonly cameraName: string | undefined

Defined in: renderer/src/CameraComponent.ts:116

---

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

---

modifiers

readonly modifiers: CameraModifierHost

Defined in: renderer/src/CameraComponent.ts:110

Transient position, rotation, and zoom contributions.

---

position

position: Vec2

Defined in: renderer/src/CameraComponent.ts:106

---

priority

readonly priority: number

Defined in: renderer/src/CameraComponent.ts:115

---

rotation

rotation: number

Defined in: renderer/src/CameraComponent.ts:108

---

zoom

zoom: number

Defined in: renderer/src/CameraComponent.ts:107

---

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

bounds

Get Signature

get bounds(): CameraBounds | undefined

Defined in: renderer/src/CameraComponent.ts:192

Get or set camera bounds.

Returns

CameraBounds | undefined

Set Signature

set bounds(value): void

Defined in: renderer/src/CameraComponent.ts:196

Parameters

value

CameraBounds | undefined

Returns

void

---

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

---

effectivePosition

Get Signature

get effectivePosition(): Vec2

Defined in: renderer/src/CameraComponent.ts:138

Effective position including every active camera modifier.

Returns

Vec2

---

effectiveRotation

Get Signature

get effectiveRotation(): number

Defined in: renderer/src/CameraComponent.ts:149

Effective rotation including every active camera modifier.

Returns

number

---

effectiveZoom

Get Signature

get effectiveZoom(): number

Defined in: renderer/src/CameraComponent.ts:154

Effective zoom including every active camera modifier.

Returns

number

---

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

SpriteComponent.enabled

---

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

---

viewportHeight

Get Signature

get viewportHeight(): number

Defined in: renderer/src/CameraComponent.ts:133

Returns

number

---

viewportWidth

Get Signature

get viewportWidth(): number

Defined in: renderer/src/CameraComponent.ts:129

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

---

_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

---

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

---

follow()

follow(target, options?): void

Defined in: renderer/src/CameraComponent.ts:159

Start following a target.

Parameters

target

FollowTarget

options?

CameraFollowOptions

Returns

void

---

getEffectivePositionInto()

getEffectivePositionInto(out): Vec2Buffer

Defined in: renderer/src/CameraComponent.ts:144

Copy the position including active modifiers into caller-owned scratch.

Parameters

out

Vec2Buffer

Returns

Vec2Buffer

---

getResolvedBindings()

getResolvedBindings(tree): readonly CameraBinding[]

Defined in: renderer/src/CameraComponent.ts:288

Resolve bindings for this camera against the given render tree.

Every world-space layer (LayerDef.space === "world", the default) is bound at full strength. Screen-space layers — declared with space: "screen" or auto-provisioned by plugins via ensureLayer(def, { space: "screen" }), e.g. the UI layer — are skipped so they stay fixed to the viewport.

An entry in bindings replaces the binding for the layer it names; an entry naming a screen-space layer, or a layer the tree does not hold, is added. With autoBind: false the camera binds exactly the entries in bindings and nothing else — the only way to leave a world-space layer untransformed, since a binding with all three ratios at 0 centres the layer on the viewport instead.

Called once per camera per frame, so a layer created after the camera spawned is bound on the next frame.

Parameters

tree

SceneRenderTree

Returns

readonly CameraBinding[]

---

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()?

optional onAdd(): void

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

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

Inherited from

Component.onAdd

---

onDestroy()

onDestroy(): void

Defined in: renderer/src/CameraComponent.ts:309

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

Returns

void

Overrides

Component.onDestroy

---

onDisable()?

optional onDisable(): void

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

Called when the component stops being effectively enabled — enabled went false, the entity (or an ancestor) was deactivated, or the component is being removed or destroyed. Put live resources to sleep here; the component is reused afterwards, so do not free anything onEnable cannot rebuild.

Returns

void

Inherited from

Component.onDisable

---

onEnable()?

optional onEnable(): void

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

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

Inherited from

Component.onEnable

---

screenToWorld()

screenToWorld(screenX, screenY): Vec2

Defined in: renderer/src/CameraComponent.ts:209

Convert screen coordinates to world coordinates.

The conversion uses the camera’s own transform, not any layer’s. A layer bound with a ratio below 1 (parallax, dampened zoom) renders under a different transform, so this result does not name a point on that layer.

The result is undefined for a zoom of 0 or a non-finite camera value.

Parameters

screenX

number

screenY

number

Returns

Vec2

---

screenToWorldInto()

screenToWorldInto(out, screenX, screenY): Vec2Buffer

Defined in: renderer/src/CameraComponent.ts:219

Copy a screen-to-world projection into caller-owned scratch.

Parameters

out

Vec2Buffer

screenX

number

screenY

number

Returns

Vec2Buffer

---

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

---

shake()

shake(intensity, duration, options?): void

Defined in: renderer/src/CameraComponent.ts:178

Start a screen shake effect. intensity is the maximum displacement per axis in world pixels, so what the player sees scales with zoom — the same intensity moves twice as far on screen at zoom 2.

Parameters

intensity

number

duration

number

options?

CameraShakeOptions

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

---

snapToTarget()

snapToTarget(): void

Defined in: renderer/src/CameraComponent.ts:169

Cut to the current follow target, skipping the smoothing ease.

Returns

void

---

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

---

unfollow()

unfollow(): void

Defined in: renderer/src/CameraComponent.ts:164

Stop following any target.

Returns

void

---

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

---

worldToScreen()

worldToScreen(worldX, worldY): Vec2

Defined in: renderer/src/CameraComponent.ts:241

Convert world coordinates to screen coordinates.

The conversion uses the camera’s own transform, not any layer’s. Content on a layer bound with a ratio below 1 (parallax, dampened zoom) is drawn somewhere else on screen than this result says.

Parameters

worldX

number

worldY

number

Returns

Vec2

---

worldToScreenInto()

worldToScreenInto(out, worldX, worldY): Vec2Buffer

Defined in: renderer/src/CameraComponent.ts:251

Copy a world-to-screen projection into caller-owned scratch.

Parameters

out

Vec2Buffer

worldX

number

worldY

number

Returns

Vec2Buffer

---

zoomTo()

zoomTo(target, duration, easing?): void

Defined in: renderer/src/CameraComponent.ts:187

Animate zoom to a target value over a duration.

Parameters

target

number

duration

number

easing?

EasingFunction

Returns

void