@ignifx/3d · ignifx

@ignifx/3d public barrel: the 3D toolkit — character and camera rigs, the Animator state machine, navigation, and the environment helpers (docs/architecture/12-3d-toolkit.md).

Explicit named re-exports only — no export * (coding standards §4). Everything the adapter owns (src/lite/**) stays internal apart from the type aliases the .lite escape hatches name in their signatures.

Classes#

Animator#

An animation state machine bound to the Model on its entity.

Example#

typescript

const animator = hero.addComponent(Animator);animator.animator = app.assets.load<AnimatorAsset>("3d/hero.animator.json").retain();animator.onEvent.connect((name) => { if (name === "landed") thud(); }, { owner: animator });animator.setFloat("speed", 4.5);animator.setTrigger("jump");

Extends#

Component

Implements#

ComponentHooks

Constructors#

Constructor#

new Animator(): Animator

Applies the schema defaults, exactly as Component.define would.

Returns#

Animator

Overrides#

Component.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One animator per entity: a second state machine on one model would fight over the clips.

animator#

animator: AssetHandle<AnimatorAsset> | null

The document holding the state machine.

applyOnAwake#

applyOnAwake: boolean

Whether the first pose is written before the first update.

defaultLayer#

defaultLayer: string

The layer play and currentState default to; empty means the document's base layer.

schema#

static schema: Schema

The declarative fields (ADR-0004).

speed#

speed: number

A multiplier on every state's own rate.

typeId#

static typeId: string = "ignifx/Animator"

The registration id the serializer writes into scene files.

updateWhenPaused#

updateWhenPaused: boolean

Whether the animator keeps advancing while app.pause() holds.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

enabled#

Get Signature#

get enabled(): boolean

The component's own enabled flag; true by default. Setting it runs the enable or disable transition (docs/architecture/01-lifecycle-and-time.md §6): onDisable runs immediately, awake/onEnable run in the next lifecycle flush — or immediately and nested when the change happens inside a callback.

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

isReady#

Get Signature#

get isReady(): boolean

Whether the document has loaded and the state machine is running.

Returns#

boolean

Whether the document has loaded and the state machine is running.

lite#

Get Signature#

get lite(): object

The Babylon Lite objects this animator owns. Unstable escape hatch (docs/architecture/00-overview.md §3).

Returns#

object

The animation manager, or null under a headless app or before the model loaded.

manager#

readonly manager: AnimationManager | null

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

onEvent#

Get Signature#

get onEvent(): Signal<string>

Fires with the name of every animation event the playing states cross.

Returns#

Signal<string>

Fires with the name of every animation event the playing states cross.

onStateEntered#

Get Signature#

get onStateEntered(): Signal<string>

Fires with a state's name each time a layer enters it.

Returns#

Signal<string>

Fires with a state's name each time a layer enters it.

onStateExited#

Get Signature#

get onStateExited(): Signal<string>

Fires with a state's name each time a layer leaves it, after any crossfade has finished.

Returns#

Signal<string>

Fires with a state's name each time a layer leaves it, after any crossfade has finished.

stateMachine#

Get Signature#

get stateMachine(): AnimatorStateMachine | null

The state machine, for a game that wants to inspect it. null until the document loads.

Returns#

AnimatorStateMachine | null

The machine.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

crossFade()#

crossFade(state, seconds, layer?): void

Crossfades into a state.

Parameters#

state#

string

The state's name.

seconds#

number

How long the fade takes.

layer?#

string

Which layer to play on.

Returns#

void

Throws#

IgnifxError with code IGX-1202 when the state is not declared.

currentState()#

currentState(layer?): string

The state a layer is currently in.

Parameters#

layer?#

string

The layer's name; defaultLayer or the base layer when omitted.

Returns#

string

The state's name, or the empty string before the document loads.

define()#

static define<S>(schema): ComponentDefinition<S>

Declares a component's serialized fields and returns the base class to extend (ADR-0004, docs/architecture/03-scripting-and-components.md §3). The returned class exposes every field as a typed instance property, applies the defaults in its constructor, and carries the schema for the serializer, the inspector, and the docs harness.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Queues this component for destruction. It stays usable until the destroy flush of the current frame, but reports isDestroyed === true immediately (docs/architecture/01-lifecycle-and-time.md §6). Calling it twice is a no-op.

Returns#

void

Inherited from#

Component.destroy

getBool()#

getBool(name): boolean

Reads a bool parameter.

Parameters#

name#

string

The parameter's name.

Returns#

boolean

Whether it is set.

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

getFloat()#

getFloat(name): number

Reads a numeric parameter.

Parameters#

name#

string

The parameter's name.

Returns#

number

The value, or 0 before the document loads.

normalizedTime()#

normalizedTime(layer?): number

How far into its state a layer is, in [0, 1].

Parameters#

layer?#

string

The layer's name; defaultLayer or the base layer when omitted.

Returns#

number

The normalized time.

onAttach()#

onAttach(): void

Finds the Model this animator poses.

Returns#

void

Implementation of#

ComponentHooks.onAttach

onDetach()#

onDetach(): void

Hands the clips back so another animator, or a reload, can claim them.

Returns#

void

Implementation of#

ComponentHooks.onDetach

play()#

play(state, options?): void

Plays a state, cutting to it unless transitionSeconds says otherwise.

Parameters#

state#

string

The state's name.

options?#

AnimatorPlayOptions

The layer and the crossfade length.

Returns#

void

Throws#

IgnifxError with code IGX-1202 when the state is not declared.

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

setBool()#

setBool(name, value): void

Writes a bool parameter.

Parameters#

name#

string

The parameter's name.

value#

boolean

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

setFloat()#

setFloat(name, value): void

Writes a float parameter.

Parameters#

name#

string

The parameter's name.

value#

number

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

setInt()#

setInt(name, value): void

Writes an int parameter.

Parameters#

name#

string

The parameter's name.

value#

number

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

setTrigger()#

setTrigger(name): void

Sets a trigger parameter; the next transition that reads it consumes it.

Parameters#

name#

string

The parameter's name.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

AnimatorAsset#

A parsed animator document.

Example#

typescript

const handle = app.assets.load<AnimatorAsset>("3d/hero.animator.json").retain();await handle.promise;handle.value?.stateNames; // ["idle", "locomotion", "jump"]

Constructors#

Constructor#

new AnimatorAsset(address, definition): AnimatorAsset

Wraps a parsed document.

Parameters#

address#

string

Where it came from.

definition#

AnimatorDefinition

The parsed document.

Returns#

AnimatorAsset

Properties#

address#

readonly address: string

Where the document was loaded from.

assetType#

static assetType: string = ANIMATOR_ASSET_TYPE

The asset type name, so assetRef and the inspector can round-trip a reference.

definition#

readonly definition: AnimatorDefinition

The parsed document.

Accessors#

layerNames#

Get Signature#

get layerNames(): readonly string[]

Every layer name the document declares, base first.

Returns#

readonly string[]

Every layer name the document declares, base first.

stateNames#

Get Signature#

get stateNames(): readonly string[]

Every state name the document declares, in declaration order.

Returns#

readonly string[]

Every state name the document declares, in declaration order.

Methods#

clipNames()#

clipNames(): readonly string[]

Every animation-group name the document plays, across every state and blend tree.

Returns#

readonly string[]

The clip names, without duplicates.

layer()#

layer(name): AnimatorLayerDefinition | null

Finds a layer by name.

Parameters#

name#

string

The layer's name.

Returns#

AnimatorLayerDefinition | null

The declaration, or null.

state()#

state(name): AnimatorStateDefinition | null

Finds a state by name.

Parameters#

name#

string

The state's name.

Returns#

AnimatorStateDefinition | null

The declaration, or null.

AnimatorStateMachine#

The headless half of Animator: parameters in, clip weights out.

Example#

typescript

const machine = new AnimatorStateMachine(definition);machine.setFloat("speed", 4);machine.advance(1 / 60);for (const clip of machine.clips) {  applyWeight(clip.clip, clip.weight);}

Constructors#

Constructor#

new AnimatorStateMachine(definition): AnimatorStateMachine

Builds a machine and puts every layer in its default state.

Parameters#

definition#

AnimatorDefinition

The parsed .animator.json document.

Returns#

AnimatorStateMachine

Properties#

speed#

speed: number = 1

A multiplier applied to every layer's rate; Animator.speed writes it.

Accessors#

clips#

Get Signature#

get clips(): readonly ClipWeight[]

The clip contributions of the last advance, rebuilt in place each frame.

Returns#

readonly ClipWeight[]

The clip contributions of the last advance, rebuilt in place each frame.

definition#

Get Signature#

get definition(): AnimatorDefinition

The document this machine runs.

Returns#

AnimatorDefinition

The document this machine runs.

Methods#

advance()#

advance(deltaSeconds): void

Advances every layer by one frame and recomputes the clip weights.

Parameters#

deltaSeconds#

number

The frame delta, already scaled by whatever clock the caller uses.

Returns#

void

crossFade()#

crossFade(state, seconds, layer?): void

Crossfades into a state.

Parameters#

state#

string

The state's name.

seconds#

number

How long the fade takes.

layer?#

string

Which layer to play on; the state's own layer when omitted.

Returns#

void

Throws#

IgnifxError with code IGX-1202 when the state is not declared.

currentState()#

currentState(layer?): string

The state a layer is currently in.

Parameters#

layer?#

string

The layer's name; the base layer when omitted.

Returns#

string

The state's name.

drainEvents()#

drainEvents(out): void

Hands over the animation events that fired since the last call and clears the queue.

Parameters#

out#

string[]

The array to append names to.

Returns#

void

drainStateChanges()#

drainStateChanges(out): void

Hands over the state entries and exits since the last call and clears the queue.

Parameters#

out#

StateChange[]

The array to append changes to.

Returns#

void

getBool()#

getBool(name): boolean

Reads a bool parameter.

Parameters#

name#

string

The parameter's name.

Returns#

boolean

Whether it is set.

Throws#

IgnifxError with code IGX-1203 when the parameter is not declared.

getFloat()#

getFloat(name): number

Reads a numeric parameter.

Parameters#

name#

string

The parameter's name.

Returns#

number

The value; 0 for a set trigger's companion float, 1/0 for a bool.

Throws#

IgnifxError with code IGX-1203 when the parameter is not declared.

isInTransition()#

isInTransition(layer?): boolean

Whether a layer is mid-crossfade.

Parameters#

layer?#

string

The layer's name; the base layer when omitted.

Returns#

boolean

true while a previous state still contributes.

isTriggerSet()#

isTriggerSet(name): boolean

Whether a trigger is currently set.

Parameters#

name#

string

The parameter's name.

Returns#

boolean

true while the trigger waits to be consumed.

normalizedTime()#

normalizedTime(layer?): number

How far into its state a layer is, in [0, 1].

Parameters#

layer?#

string

The layer's name; the base layer when omitted.

Returns#

number

The normalized time.

Remarks#

A looping state wraps; a one-shot state clamps at 1.

play()#

play(state, options?): void

Plays a state, optionally crossfading into it.

Parameters#

state#

string

The state's name.

options?#

PlayStateOptions

The layer and the crossfade length.

Returns#

void

Throws#

IgnifxError with code IGX-1202 when the state is not declared.

resetTrigger()#

resetTrigger(name): void

Clears a trigger parameter without taking a transition.

Parameters#

name#

string

The parameter's name.

Returns#

void

setBool()#

setBool(name, value): void

Writes a bool parameter.

Parameters#

name#

string

The parameter's name.

value#

boolean

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

setClipLength()#

setClipLength(clip, seconds): void

Declares how long a clip is, in seconds. The adapter calls it once per animation group.

Parameters#

clip#

string

The animation-group name.

seconds#

number

Its length; values at or below zero are ignored.

Returns#

void

setFloat()#

setFloat(name, value): void

Writes a float parameter.

Parameters#

name#

string

The parameter's name.

value#

number

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 when the parameter is not declared, or IGX-1204 when it is not a float.

setInt()#

setInt(name, value): void

Writes an int parameter, truncating towards zero.

Parameters#

name#

string

The parameter's name.

value#

number

The value.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

setTrigger()#

setTrigger(name): void

Sets a trigger parameter. The next transition that consumes it clears it.

Parameters#

name#

string

The parameter's name.

Returns#

void

Throws#

IgnifxError with code IGX-1203 or IGX-1204.

Billboard#

An entity that faces the camera.

Example#

typescript

nameplate.addComponent(Billboard, { mode: "yAxis" });

Extends#

Component

Constructors#

Constructor#

new Billboard(): Billboard

Applies the schema defaults, exactly as Component.define would.

Returns#

Billboard

Overrides#

Component.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One billboard per entity.

faceCameraPlane#

faceCameraPlane: boolean

Whether to align with the view plane rather than aim at the eye.

mode#

mode: "full" | "yAxis"

Whether the billboard is free or locked upright.

schema#

static schema: Schema

The declarative fields (ADR-0004).

typeId#

static typeId: string = "ignifx/Billboard"

The registration id the serializer writes into scene files.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

define()#

static define<S>(schema): ComponentDefinition<S>

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Component.destroy

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

BillboardSystem#

Turns every enabled Billboard towards the main camera.

Implements#

System

Constructors#

Constructor#

new BillboardSystem(): BillboardSystem

Returns#

BillboardSystem

Properties#

name#

readonly name: "ignifx/3d-billboard" = "ignifx/3d-billboard"

The name diagnostics and error reports use.

Implementation of#

System.name

Methods#

update()#

update(ctx): void

Faces every billboard.

Parameters#

ctx#

SystemContext

The world, clock, phase, and delta.

Returns#

void

Implementation of#

System.update

FirstPersonController#

A first-person character.

Example#

typescript

const player = app.world.createEntity("Player");player.addComponent(CharacterController, { height: 1.8, radius: 0.35 });const head = app.world.createEntity("Head", { parent: player, position: { x: 0, y: 1.6, z: 0 } });head.addComponent(Camera);player.addComponent(FirstPersonController, { cameraPivot: head });

Extends#

Script

Constructors#

Constructor#

new FirstPersonController(): FirstPersonController

Applies the schema defaults, exactly as Component.define would.

Returns#

FirstPersonController

Overrides#

Script.constructor

Properties#

airControl#

airControl: number

How much of the ground speed applies mid-air.

allowMultiple#

static allowMultiple: boolean = false

One controller per entity.

cameraPivot#

cameraPivot: Entity | null

The child entity that pitches; usually the camera's entity.

coyoteTime#

coyoteTime: number

How long a jump stays legal after leaving the ground.

crouchAction#

crouchAction: string

The button action that crouches.

crouchHeight#

crouchHeight: number

The controller height while crouched.

crouchSpeed#

crouchSpeed: number

Ground speed while crouched.

gravity#

gravity: number

Downward acceleration.

headBobAmplitude#

headBobAmplitude: number

How far the head bobs while walking, in metres.

headBobFrequency#

headBobFrequency: number

Head bobs per metre travelled.

invertY#

invertY: boolean

Whether looking up needs the stick pushed down.

jumpAction#

jumpAction: string

The button action that jumps.

jumpBufferTime#

jumpBufferTime: number

How long an early jump press is remembered.

jumpHeight#

jumpHeight: number

How high a jump reaches.

lockPointerOnClick#

lockPointerOnClick: boolean

Whether the first click requests pointer lock.

lookAction#

lookAction: string

The vector2 action that looks around.

moveAction#

moveAction: string

The vector2 action that walks.

requires#

static requires: readonly [typeof CharacterController]

The CharacterController this drives.

schema#

static schema: Schema

The declarative fields (ADR-0004).

sensitivity#

sensitivity: number

Degrees of rotation per unit of look input.

sprintAction#

sprintAction: string

The button action that sprints.

sprintFovKick#

sprintFovKick: number

Extra vertical FOV while sprinting, in degrees.

sprintSpeed#

sprintSpeed: number

Ground speed while sprinting.

standHeight#

standHeight: number

The controller height while standing.

typeId#

static typeId: string = "ignifx/FirstPersonController"

The registration id the serializer writes into scene files.

walkSpeed#

walkSpeed: number

Ground speed, in metres per second.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isCrouched#

Get Signature#

get isCrouched(): boolean

Whether the character is crouched.

Returns#

boolean

Whether the character is crouched.

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

isGrounded#

Get Signature#

get isGrounded(): boolean

Whether the character is standing on something.

Returns#

boolean

Whether the character is standing on something.

isSprinting#

Get Signature#

get isSprinting(): boolean

Whether the sprint action is held and the character is moving.

Returns#

boolean

Whether the sprint action is held and the character is moving.

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

pitch#

Get Signature#

get pitch(): number

Where the head is looking, in degrees; negative is up.

Returns#

number

Where the head is looking, in degrees; negative is up.

speed#

Get Signature#

get speed(): number

The character's horizontal speed this step.

Returns#

number

The character's horizontal speed this step.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

verticalVelocity#

Get Signature#

get verticalVelocity(): number

The character's vertical speed, positive upwards.

Returns#

number

The character's vertical speed, positive upwards.

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

yaw#

Get Signature#

get yaw(): number

Where the body is facing, in degrees.

Returns#

number

Where the body is facing, in degrees.

Methods#

awake()#

awake(): void

Finds the character controller and takes the entity's current facing as the starting yaw.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

fixedUpdate()#

fixedUpdate(dt): void

Walks, crouches, and jumps.

Parameters#

dt#

number

The fixed step, in seconds.

Returns#

void

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

onDisable()#

onDisable(): void

Puts the controller back to standing height.

Returns#

void

rebind()#

rebind(): void

Re-resolves the action names, after a rebind or an action-set reload.

Returns#

void

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

update()#

update(dt): void

Looks around, bobs the head, and asks for pointer lock the first time the player clicks.

Parameters#

dt#

number

The frame delta, in seconds.

Returns#

void

JumpTimers#

The two forgiving timers every good jump has (12-3d-toolkit.md §1.1).

Remarks#

Coyote time* keeps a jump legal for a moment after walking off a ledge; jump buffering keeps a jump pressed a moment early from being thrown away. Both are counters, and both are the sort of thing that is either right or infuriating, so both are testable on a stepped clock with no physics world in sight.

Example#

typescript

const jumps = new JumpTimers();jumps.step(dt, controller.isGrounded, jumpAction.wasPressedThisFrame, 0.12, 0.12);if (jumps.consume()) {  verticalVelocity = jumpVelocity(1.2, 20);}

Constructors#

Constructor#

new JumpTimers(): JumpTimers

Returns#

JumpTimers

Accessors#

bufferRemaining#

Get Signature#

get bufferRemaining(): number

How much longer a jump pressed early is still remembered, in seconds.

Returns#

number

How much longer a jump pressed early is still remembered, in seconds.

coyoteRemaining#

Get Signature#

get coyoteRemaining(): number

How much longer a jump started off the ground would still be legal, in seconds.

Returns#

number

How much longer a jump started off the ground would still be legal, in seconds.

Methods#

consume()#

consume(): boolean

Takes a jump if one is owed, clearing both timers.

Returns#

boolean

true when the character should leave the ground.

reset()#

reset(): void

Forgets both timers, for a teleport or a cutscene.

Returns#

void

step()#

step(deltaSeconds, isGrounded, jumpPressed, coyoteSeconds, bufferSeconds): void

Advances both timers by one step.

Parameters#

deltaSeconds#

number

The step.

isGrounded#

boolean

Whether the character is standing on something.

jumpPressed#

boolean

Whether the jump button went down this step.

coyoteSeconds#

number

How long a jump stays legal after leaving the ground.

bufferSeconds#

number

How long an early jump press is remembered.

Returns#

void

LodGroup#

A distance-based renderer switch.

Example#

typescript

const group = tree.addComponent(LodGroup, {  levels: [    { distance: 20, renderer: highDetail },    { distance: 60, renderer: lowDetail },  ],});group.onLevelChanged.connect((level) => app.log.debug("LOD {level}", level), { owner: group });

Extends#

Component

Implements#

ComponentHooks

Constructors#

Constructor#

new LodGroup(): LodGroup

Applies the schema defaults, exactly as Component.define would.

Returns#

LodGroup

Overrides#

Component.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One group per entity.

hysteresis#

hysteresis: number

How far past a threshold a switch waits, as a fraction of the threshold.

levels#

levels: LodLevel[]

The levels, nearest first.

schema#

static schema: Schema

The declarative fields (ADR-0004).

typeId#

static typeId: string = "ignifx/LodGroup"

The registration id the serializer writes into scene files.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

level#

Get Signature#

get level(): number

Which level is showing, or -1 when the group is past its last threshold.

Returns#

number

Which level is showing, or -1 when the group is past its last threshold.

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

onLevelChanged#

Get Signature#

get onLevelChanged(): Signal<number>

Fires with the new level index each time the group switches; -1 means culled.

Returns#

Signal<number>

Fires with the new level index each time the group switches; -1 means culled.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

define()#

static define<S>(schema): ComponentDefinition<S>

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Component.destroy

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

onDetach()#

onDetach(): void

Turns every level off, so a disabled group leaves nothing drawn.

Returns#

void

Implementation of#

ComponentHooks.onDetach

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

LodSystem#

Evaluates every LodGroup against the main camera.

Implements#

System

Constructors#

Constructor#

new LodSystem(): LodSystem

Returns#

LodSystem

Properties#

name#

readonly name: "ignifx/3d-lod" = "ignifx/3d-lod"

The name diagnostics and error reports use.

Implementation of#

System.name

Methods#

update()#

update(ctx): void

Measures each group's distance from the camera and switches it.

Parameters#

ctx#

SystemContext

The world, clock, phase, and delta.

Returns#

void

Implementation of#

System.update

NavigationService#

The app.navigation service.

Example#

typescript

const corners = app.navigation.findPath(guard.transform.position, player.transform.position);if (corners.length > 0) {  agent.setDestination(corners[corners.length - 1]);}

Accessors#

isLoaded#

Get Signature#

get isLoaded(): boolean

Whether Recast has finished loading.

Returns#

boolean

Whether Recast has finished loading.

onReady#

Get Signature#

get onReady(): Signal<NavigationService>

Fires the first time Recast has finished loading.

Returns#

Signal<NavigationService>

Fires the first time Recast has finished loading.

primarySurface#

Get Signature#

get primarySurface(): NavMeshSurface | null

The first surface with a navmesh on it.

Returns#

NavMeshSurface | null

The surface, or null when nothing has baked yet.

surfaces#

Get Signature#

get surfaces(): readonly NavMeshSurface[]

Every NavMeshSurface in the world, in component order.

Returns#

readonly NavMeshSurface[]

Every NavMeshSurface in the world, in component order.

Methods#

closestPoint()#

closestPoint(point, out?): MutableVec3 | null

Snaps a point onto the primary surface.

Parameters#

point#

Vec3Like

The point, in world space.

out?#

MutableVec3 = ...

Where to write the snapped point; a fresh Vec3 when omitted.

Returns#

MutableVec3 | null

The snapped point, or null when nothing is baked.

dispose()#

dispose(): void

Stops handing out plugins; the surfaces dispose the ones they hold.

Returns#

void

findPath()#

findPath(from, to): readonly Vec3[]

Computes a path across the primary surface.

Parameters#

from#

Vec3Like

The start, in world space.

to#

Vec3Like

The end, in world space.

Returns#

readonly Vec3[]

The corner points, start first. Empty when nothing is baked or no path exists.

raycast()#

raycast(from, to, out?): MutableVec3 | null

Casts a walkability ray across the primary surface.

Parameters#

from#

Vec3Like

The start, in world space.

to#

Vec3Like

The end, in world space.

out?#

MutableVec3 = ...

Where to write the hit point; a fresh Vec3 when omitted.

Returns#

MutableVec3 | null

The point where the walkable surface ends, or null when the segment is clear.

NavigationSystem#

Advances Recast crowds on the fixed step.

Implements#

System

Constructors#

Constructor#

new NavigationSystem(service): NavigationSystem

Builds the system.

Parameters#

service#

NavigationService

The service that owns the Recast plugin.

Returns#

NavigationSystem

Properties#

name#

readonly name: "ignifx/3d-navigation" = "ignifx/3d-navigation"

The name diagnostics and error reports use.

Implementation of#

System.name

Methods#

update()#

update(ctx): void

Bakes what has to be baked, steps every crowd, and writes the agents back.

Parameters#

ctx#

SystemContext

The world, clock, phase, and delta.

Returns#

void

Implementation of#

System.update

NavMeshAgent#

A crowd agent.

Example#

typescript

const agent = companion.addComponent(NavMeshAgent, { speed: 4, stoppingDistance: 0.5 });agent.onArrived.connect(() => animator.play("idle"), { owner: agent });agent.setDestination(player.transform.position);

Extends#

Component

Implements#

ComponentHooks

Constructors#

Constructor#

new NavMeshAgent(): NavMeshAgent

Applies the schema defaults, exactly as Component.define would.

Returns#

NavMeshAgent

Overrides#

Component.constructor

Properties#

acceleration#

acceleration: number

How hard the agent accelerates.

allowMultiple#

static allowMultiple: boolean = false

One agent per entity.

height#

height: number

The agent's height, in metres.

radius#

radius: number

The agent's radius, in metres.

schema#

static schema: Schema

The declarative fields (ADR-0004).

separationWeight#

separationWeight: number

How hard agents push apart.

speed#

speed: number

The agent's top speed, in metres per second.

stoppingDistance#

stoppingDistance: number

How close counts as arrived, in metres.

surface#

surface: Entity | null

The entity carrying the surface to join; the first baked surface when unset.

typeId#

static typeId: string = "ignifx/NavMeshAgent"

The registration id the serializer writes into scene files.

updatePosition#

updatePosition: boolean

Whether the crowd's position is written onto the transform.

updateRotation#

updateRotation: boolean

Whether the agent turns the entity to face the way it is moving.

Accessors#

agentIndex#

Get Signature#

get agentIndex(): number

The agent's index in its crowd, or -1.

Returns#

number

The agent's index in its crowd, or -1.

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

destination#

Get Signature#

get destination(): Vec3Like

Where the agent was last told to go. Reused each frame.

Returns#

Vec3Like

Where the agent was last told to go. Reused each frame.

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

Component.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

isOnNavMesh#

Get Signature#

get isOnNavMesh(): boolean

Whether the agent has joined a crowd and is being simulated.

Returns#

boolean

Whether the agent has joined a crowd and is being simulated.

isStopped#

Get Signature#

get isStopped(): boolean

Whether the agent is holding still rather than heading somewhere.

Returns#

boolean

Whether the agent is holding still rather than heading somewhere.

onArrived#

Get Signature#

get onArrived(): Signal<NavMeshAgent>

Fires once each time the agent reaches its destination.

Returns#

Signal<NavMeshAgent>

Fires once each time the agent reaches its destination.

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

remainingDistance#

Get Signature#

get remainingDistance(): number

How far the agent still has to travel, straight-line.

Remarks#

Recast's crowd exposes no remaining path length, so this is the distance from the agent to its destination rather than the length of the corridor — the same approximation Unity's remainingDistance makes for a partial path.

Returns#

number

The distance in metres; Infinity when the agent is not on a navmesh.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

velocity#

Get Signature#

get velocity(): Vec3Like

The agent's current world velocity, as the crowd reports it. Reused each frame.

Returns#

Vec3Like

The agent's current world velocity, as the crowd reports it. Reused each frame.

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

define()#

static define<S>(schema): ComponentDefinition<S>

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Component.destroy

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

onDetach()#

onDetach(): void

Forgets the crowd slot, which Lite cannot free.

Returns#

void

Implementation of#

ComponentHooks.onDetach

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

setDestination()#

setDestination(point): boolean

Sends the agent to a point.

Parameters#

point#

Vec3Like

Where to go, in world space. It is snapped onto the navmesh first.

Returns#

boolean

true when the agent is on a navmesh and took the order.

Example#

typescript

agent.setDestination({ x: 8, y: 0, z: -2 });

stop()#

stop(): void

Holds the agent where it is; setDestination starts it again.

Returns#

void

NavMeshObstacle#

A runtime hole in a navmesh.

Example#

typescript

crate.addComponent(NavMeshObstacle, { shape: "box", size: { x: 1, y: 1, z: 1 } });

Extends#

Component

Implements#

ComponentHooks

Constructors#

Constructor#

new NavMeshObstacle(): NavMeshObstacle

Applies the schema defaults, exactly as Component.define would.

Returns#

NavMeshObstacle

Overrides#

Component.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One obstacle per entity.

height#

height: number

The cylinder's height, in metres.

radius#

radius: number

The cylinder's radius, in metres.

schema#

static schema: Schema

The declarative fields (ADR-0004).

shape#

shape: "box" | "cylinder"

Whether the hole is a box or a cylinder.

size#

size: Vec3Like

The box's full size, in metres.

surface#

surface: Entity | null

The entity carrying the surface to cut; the first baked surface when unset.

typeId#

static typeId: string = "ignifx/NavMeshObstacle"

The registration id the serializer writes into scene files.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

Component.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isCarved#

Get Signature#

get isCarved(): boolean

Whether the hole is currently cut into a navmesh.

Returns#

boolean

Whether the hole is currently cut into a navmesh.

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

define()#

static define<S>(schema): ComponentDefinition<S>

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Component.destroy

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

onDetach()#

onDetach(): void

Fills the hole back in.

Returns#

void

Implementation of#

ComponentHooks.onDetach

remove()#

remove(): void

Fills the hole back in and flushes the tile cache.

Returns#

void

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

NavMeshSurface#

One baked navmesh.

Example#

typescript

const surface = level.addComponent(NavMeshSurface, { agentRadius: 0.4, maxObstacles: 8 });surface.onBaked.connect(() => app.log.info("navmesh ready"), { owner: surface });await surface.bake();

Extends#

Component

Implements#

ComponentHooks

Constructors#

Constructor#

new NavMeshSurface(): NavMeshSurface

Applies the schema defaults, exactly as Component.define would.

Returns#

NavMeshSurface

Overrides#

Component.constructor

Properties#

agentClimb#

agentClimb: number

The tallest step an agent walks up, in metres.

agentHeight#

agentHeight: number

The headroom an agent needs, in metres.

agentRadius#

agentRadius: number

How far agents stay from a wall, in metres.

allowMultiple#

static allowMultiple: boolean = false

One surface per entity; a second navmesh wants its own.

bakeOnAwake#

bakeOnAwake: boolean

Whether the surface bakes itself as soon as it is enabled.

cellHeight#

cellHeight: number

Recast voxel height, in metres.

cellSize#

cellSize: number

Recast voxel width, in metres.

detailSampleDistance#

detailSampleDistance: number

Detail-mesh sampling distance, in voxels.

detailSampleMaxError#

detailSampleMaxError: number

Detail-mesh vertical error, in voxels.

layers#

layers: readonly string[]

Which layers' MeshRenderers are baked; an empty list means every layer.

maxAgentRadius#

maxAgentRadius: number

The largest agent radius the crowd will see.

maxAgents#

maxAgents: number

How many agents this surface's crowd holds.

maxEdgeLength#

maxEdgeLength: number

The longest contour edge, in voxels.

maxObstacles#

maxObstacles: number

How many obstacles fit; above zero builds a tile cache.

maxSimplificationError#

maxSimplificationError: number

How far a simplified edge may stray, in voxels.

maxVertsPerPoly#

maxVertsPerPoly: number

The largest navmesh polygon, in vertices.

mergeRegionArea#

mergeRegionArea: number

Regions smaller than this are merged.

minRegionArea#

minRegionArea: number

Regions smaller than this are discarded.

prebaked#

prebaked: string

A .navmesh.bin address; unsupported by the pinned Babylon Lite.

randomSeed#

randomSeed: number

The seed Recast's randomized queries use.

schema#

static schema: Schema

The declarative fields (ADR-0004).

tileSize#

tileSize: number

Tile size in voxels.

typeId#

static typeId: string = "ignifx/NavMeshSurface"

The registration id the serializer writes into scene files.

walkableSlopeAngle#

walkableSlopeAngle: number

The steepest walkable slope, in degrees.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Component.app

crowd#

Get Signature#

get crowd(): NavCrowd | null

The crowd agents join, or null before the bake.

Returns#

NavCrowd | null

The crowd agents join, or null before the bake.

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Component.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Component.handle

isBaked#

Get Signature#

get isBaked(): boolean

Whether a navmesh exists and queries will answer.

Returns#

boolean

Whether a navmesh exists and queries will answer.

isBaking#

Get Signature#

get isBaking(): boolean

Whether a bake is in flight.

Returns#

boolean

Whether a bake is in flight.

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Component.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Component.isEnabledInHierarchy

lite#

Get Signature#

get lite(): object

The Babylon Lite objects this surface owns. Unstable escape hatch (docs/architecture/00-overview.md §3).

Returns#

object

The Recast plugin and the crowd, or null before the bake.

crowd#

readonly crowd: NavCrowd | null

plugin#

readonly plugin: NavigationPlugin | null

onBaked#

Get Signature#

get onBaked(): Signal<NavMeshSurface>

Fires once each time the surface finishes baking.

Returns#

Signal<NavMeshSurface>

Fires once each time the surface finishes baking.

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Component.onDestroyed

plugin#

Get Signature#

get plugin(): NavigationPlugin | null

The plugin obstacles are added to, or null before the bake.

Returns#

NavigationPlugin | null

The plugin obstacles are added to, or null before the bake.

scratch#

Get Signature#

get scratch(): MutableVec3

Scratch the agent system borrows, so a fixed step allocates nothing.

Returns#

MutableVec3

Scratch the agent system borrows, so a fixed step allocates nothing.

sourceCount#

Get Signature#

get sourceCount(): number

How many geometry sources have been added by hand.

Returns#

number

How many geometry sources have been added by hand.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Component.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Component.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Component.world

Methods#

addSource()#

addSource(positions, indices, worldMatrix): void

Adds a piece of geometry to bake from.

Parameters#

positions#

ArrayLike<number>

Three floats per vertex.

indices#

ArrayLike<number>

Three indices per triangle.

worldMatrix#

ArrayLike<number> | null

A column-major 4x4 to transform the positions by, or null when they are already in world space.

Returns#

void

Remarks#

This is the headless path: Lite's createNavMeshFromSources takes plain arrays, so a level built in code — or a test's floor and wall — can be baked with no GPU anywhere in sight.

Example#

typescript

surface.addSource(floorPositions, floorIndices, null);

bake()#

bake(): Promise<boolean>

Loads Recast if it is not loaded yet, then bakes the navmesh and creates the crowd.

Returns#

Promise<boolean>

true when a navmesh was built.

Remarks#

Baking replaces whatever the surface had: agents that had already joined the old crowd are asked to rejoin on their next fixed step.

Throws#

IgnifxError with code IGX-1206 when Recast cannot be loaded.

Example#

typescript

await surface.bake();

clearSources()#

clearSources(): void

Drops every hand-added source, so the next bake starts clean.

Returns#

void

closestPoint()#

closestPoint(point, out?): MutableVec3 | null

Snaps a point onto this surface.

Parameters#

point#

Vec3Like

The point, in world space.

out?#

MutableVec3 = ...

Where to write the snapped point; a fresh Vec3 when omitted.

Returns#

MutableVec3 | null

The snapped point, or null when there is no navmesh.

define()#

static define<S>(schema): ComponentDefinition<S>

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ComponentDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Spinner extends Component.define({  degreesPerSecond: f32(90, { min: -360, max: 360 }),  axis: vec3({ x: 0, y: 1, z: 0 }),}) {  static typeId = "mygame/Spinner";}

Inherited from#

Component.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Component.destroy

findPath()#

findPath(from, to): readonly Vec3[]

Computes a path across this surface.

Parameters#

from#

Vec3Like

The start, in world space.

to#

Vec3Like

The end, in world space.

Returns#

readonly Vec3[]

The corner points, start first. Empty when there is no navmesh or no path.

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Component.getComponent

onDetach()#

onDetach(): void

Releases the plugin's navmesh, tile cache, and query.

Returns#

void

Implementation of#

ComponentHooks.onDetach

raycast()#

raycast(from, to, out?): MutableVec3 | null

Casts a walkability ray across this surface.

Parameters#

from#

Vec3Like

The start, in world space.

to#

Vec3Like

The end, in world space.

out?#

MutableVec3 = ...

Where to write the hit point; a fresh Vec3 when omitted.

Returns#

MutableVec3 | null

The point where the walkable surface ends, or null when the segment is clear.

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Component.requireComponent

PlatformMover#

A kinematic platform that carries what stands on it (docs/architecture/12-3d-toolkit.md §1.3).

Remarks#

Riders are found with a short downward app.physics.raycast from each character's feet (09-physics.md §5): a character standing on this platform is handed the platform's own delta in the same fixed step, which is what stops it sliding off a moving lift. A ground probe is used rather than CharacterController.onCollided because the contact stream reports a character's collisions*, and a character resting on a surface it never pushes into produces none.

Example#

typescript

lift.addComponent(Rigidbody, { bodyType: "kinematic" });lift.addComponent(BoxCollider, { size: { x: 4, y: 0.4, z: 4 } });lift.addComponent(PlatformMover, { offset: { x: 0, y: 6, z: 0 }, duration: 3 });

Extends#

Script

Constructors#

Constructor#

new PlatformMover(): PlatformMover

Applies the schema defaults, exactly as Component.define would.

Returns#

PlatformMover

Overrides#

Script.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One mover per entity.

carryRiders#

carryRiders: boolean

Whether characters standing on the platform ride it.

duration#

duration: number

How long one leg of the trip takes, in seconds.

offset#

offset: Vec3Like

How far the platform travels from where it started.

requires#

static requires: readonly [typeof Rigidbody]

The kinematic Rigidbody this drives.

schema#

static schema: Schema

The declarative fields (ADR-0004).

typeId#

static typeId: string = "ignifx/PlatformMover"

The registration id the serializer writes into scene files.

waitSeconds#

waitSeconds: number

How long the platform pauses at each end.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

deltaThisStep#

Get Signature#

get deltaThisStep(): Vec3Like

The platform's movement last step, which riders are handed. Reused each step.

Returns#

Vec3Like

The platform's movement last step, which riders are handed. Reused each step.

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

riderCount#

Get Signature#

get riderCount(): number

How many characters are currently riding.

Returns#

number

How many characters are currently riding.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

Methods#

awake()#

awake(): void

Records the starting position and subscribes to every character's contacts.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

fixedUpdate()#

fixedUpdate(dt): void

Moves the platform and its riders.

Parameters#

dt#

number

The fixed step, in seconds.

Returns#

void

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

Projectile#

A fire-and-forget projectile (docs/architecture/12-3d-toolkit.md §1.3).

Example#

typescript

const bullet = app.world.createEntity("Bullet", { position: muzzle.transform.position });bullet.addComponent(SphereCollider, { radius: 0.05 });bullet.addComponent(Rigidbody, { mass: 0.02 });bullet.addComponent(Projectile, { speed: 60, owner: player });

Extends#

Script

Constructors#

Constructor#

new Projectile(): Projectile

Applies the schema defaults, exactly as Component.define would.

Returns#

Projectile

Overrides#

Script.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One projectile per entity.

destroyOnHit#

destroyOnHit: boolean

Whether the projectile destroys itself on its first contact.

gravityScale#

gravityScale: number

How much gravity the projectile feels.

lifetimeSeconds#

lifetimeSeconds: number

How long the projectile lives before destroying itself.

owner#

owner: Entity | null

The entity that fired it.

requires#

static requires: readonly [typeof Rigidbody]

The Rigidbody that carries it.

schema#

static schema: Schema

The declarative fields (ADR-0004).

speed#

speed: number

How fast the projectile leaves the muzzle.

typeId#

static typeId: string = "ignifx/Projectile"

The registration id the serializer writes into scene files.

Accessors#

age#

Get Signature#

get age(): number

How long the projectile has been alive, in seconds.

Returns#

number

How long the projectile has been alive, in seconds.

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

Methods#

awake()#

awake(): void

Finds the body; the launch itself waits for the first fixed step.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

fixedUpdate()#

fixedUpdate(dt): void

Ages the projectile and applies its gravity scale.

Parameters#

dt#

number

The fixed step, in seconds.

Returns#

void

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

onCollisionEnter()#

onCollisionEnter(collision): void

Destroys the projectile on its first contact with anything but its owner.

Parameters#

collision#

unknown

The contact, as physics reports it.

Returns#

void

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

RigidbodyMover#

A physics-driven character or vehicle: forces in, momentum out (docs/architecture/12-3d-toolkit.md §1.3).

Example#

typescript

const ball = app.world.createEntity("Ball");ball.addComponent(SphereCollider, { radius: 0.5 });ball.addComponent(Rigidbody, { mass: 2 });ball.addComponent(RigidbodyMover, { force: 30, maxSpeed: 10 });

Extends#

Script

Constructors#

Constructor#

new RigidbodyMover(): RigidbodyMover

Applies the schema defaults, exactly as Component.define would.

Returns#

RigidbodyMover

Overrides#

Script.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One mover per entity.

cameraRelative#

cameraRelative: boolean

Whether the stick is read relative to the main camera.

force#

force: number

How hard the body is pushed, in newtons.

maxSpeed#

maxSpeed: number

The horizontal speed the mover stops adding force at.

moveAction#

moveAction: string

The vector2 action that steers.

requires#

static requires: readonly [typeof Rigidbody]

The Rigidbody this pushes.

schema#

static schema: Schema

The declarative fields (ADR-0004).

torqueSteering#

torqueSteering: boolean

Whether the stick's X steers by torque rather than by force.

typeId#

static typeId: string = "ignifx/RigidbodyMover"

The registration id the serializer writes into scene files.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

Methods#

awake()#

awake(): void

Finds the body and binds the action name.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

fixedUpdate()#

fixedUpdate(dt): void

Pushes the body.

Parameters#

dt#

number

The fixed step, in seconds.

Returns#

void

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

ThirdPersonCamera#

An orbiting third-person camera rig.

Example#

typescript

const camera = app.world.createEntity("Camera");camera.addComponent(Camera);camera.addComponent(ThirdPersonCamera, { target: hero, distance: 5 });

Extends#

Script

Constructors#

Constructor#

new ThirdPersonCamera(): ThirdPersonCamera

Applies the schema defaults, exactly as Component.define would.

Returns#

ThirdPersonCamera

Overrides#

Script.constructor

Properties#

allowMultiple#

static allowMultiple: boolean = false

One rig per entity.

collisionEnabled#

collisionEnabled: boolean

Whether the boom is shortened by geometry in the way.

collisionLayers#

collisionLayers: readonly string[]

Which layers block the camera; an empty list means every layer.

collisionRadius#

collisionRadius: number

The radius of the sphere swept along the boom.

collisionRecoverySpeed#

collisionRecoverySpeed: number

How fast the boom eases back out, in metres per second.

damping#

damping: number

The follow time constant, in seconds.

distance#

distance: number

How far behind the target the camera sits, in metres.

invertY#

invertY: boolean

Whether looking up needs the stick pushed down.

lookAction#

lookAction: string

The vector2 action that orbits the camera.

maxPitch#

maxPitch: number

The highest pitch, in degrees.

minPitch#

minPitch: number

The lowest pitch, in degrees.

schema#

static schema: Schema

The declarative fields (ADR-0004).

sensitivity#

sensitivity: number

Degrees of orbit per unit of look input.

shoulderOffset#

shoulderOffset: Vec3Like

The pivot offset from the target, in the target's own space.

target#

target: Entity | null

The entity the camera orbits.

typeId#

static typeId: string = "ignifx/ThirdPersonCamera"

The registration id the serializer writes into scene files.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

currentDistance#

Get Signature#

get currentDistance(): number

Where the boom currently ends, after collision. Never longer than distance.

Returns#

number

Where the boom currently ends, after collision. Never longer than distance.

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

pitch#

Get Signature#

get pitch(): number

The camera's orbit pitch, in degrees.

Returns#

number

The camera's orbit pitch, in degrees.

pivot#

Get Signature#

get pivot(): Vec3Like

The point the camera is orbiting, in world space. Reused each frame.

Returns#

Vec3Like

The point the camera is orbiting, in world space. Reused each frame.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

yaw#

Get Signature#

get yaw(): number

The camera's orbit yaw, in degrees.

Returns#

number

The camera's orbit yaw, in degrees.

Methods#

awake()#

awake(): void

Takes the entity's current facing as the starting orbit and binds the action name.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

lateUpdate()#

lateUpdate(dt): void

Orbits, follows, and pulls in.

Parameters#

dt#

number

The frame delta, in seconds.

Returns#

void

rebind()#

rebind(): void

Re-resolves the action name, after a rebind or an action-set reload.

Returns#

void

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

snap()#

snap(): void

Snaps the rig to its target without damping — after a teleport or a scene load.

Returns#

void

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

ThirdPersonController#

A camera-relative third-person character.

Example#

typescript

const hero = app.world.createEntity("Hero");hero.addComponent(CharacterController, { height: 1.8, radius: 0.35 });hero.addComponent(ThirdPersonController, { walkSpeed: 4, sprintSpeed: 7, stepHeight: 0.3 });

Extends#

Script

Constructors#

Constructor#

new ThirdPersonController(): ThirdPersonController

Applies the schema defaults, exactly as Component.define would.

Returns#

ThirdPersonController

Overrides#

Script.constructor

Properties#

airControl#

airControl: number

How much of the ground speed applies mid-air, in [0, 1].

allowMultiple#

static allowMultiple: boolean = false

One controller per entity.

coyoteTime#

coyoteTime: number

How long a jump stays legal after leaving the ground.

gravity#

gravity: number

Downward acceleration, in metres per second squared.

jumpAction#

jumpAction: string

The button action that jumps.

jumpBufferTime#

jumpBufferTime: number

How long an early jump press is remembered.

jumpHeight#

jumpHeight: number

How high a jump reaches, in metres.

moveAction#

moveAction: string

The vector2 action that steers the character.

requires#

static requires: readonly [typeof CharacterController]

The CharacterController this drives (CONSTITUTION.md §3, ADR-0004).

rotateToMovement#

rotateToMovement: boolean

Whether the entity turns to face the way it is moving.

schema#

static schema: Schema

The declarative fields (ADR-0004).

slideSpeed#

slideSpeed: number

How fast the character slides down a slope steeper than the controller's limit.

sprintAction#

sprintAction: string

The button action that sprints.

sprintSpeed#

sprintSpeed: number

Ground speed while sprinting, in metres per second.

stepHeight#

stepHeight: number

The tallest step the probe lifts over; 0 disables the probe.

turnSpeed#

turnSpeed: number

How fast the character turns to face its direction, in degrees per second.

typeId#

static typeId: string = "ignifx/ThirdPersonController"

The registration id the serializer writes into scene files.

walkSpeed#

walkSpeed: number

Ground speed with the stick fully pressed, in metres per second.

Accessors#

app#

Get Signature#

get app(): App

The app that owns the world.

Returns#

App

The app.

Inherited from#

Script.app

enabled#

Get Signature#

get enabled(): boolean

Returns#

boolean

true when the component's own flag is set.

Set Signature#

set enabled(value): void

Parameters#

value#

boolean

Returns#

void

Inherited from#

NavMeshAgent.enabled

entity#

Get Signature#

get entity(): Entity

The entity this component is attached to.

Returns#

Entity

The owning entity.

Inherited from#

Script.entity

handle#

Get Signature#

get handle(): ComponentHandle

The dense runtime handle; invalid after destruction.

Returns#

ComponentHandle

The handle.

Inherited from#

Script.handle

isDestroyed#

Get Signature#

get isDestroyed(): boolean

true from the moment destroy() is called, long before the destroy flush runs.

Returns#

boolean

true once the component has been queued for destruction.

Inherited from#

Script.isDestroyed

isEnabledInHierarchy#

Get Signature#

get isEnabledInHierarchy(): boolean

true when the component's own flag is set and its entity is active in the hierarchy.

Returns#

boolean

true when the component is effectively enabled.

Inherited from#

Script.isEnabledInHierarchy

isGrounded#

Get Signature#

get isGrounded(): boolean

Whether the character is standing on something.

Returns#

boolean

Whether the character is standing on something.

isSprinting#

Get Signature#

get isSprinting(): boolean

Whether the sprint action is held and the character is moving.

Returns#

boolean

Whether the sprint action is held and the character is moving.

moveDirection#

Get Signature#

get moveDirection(): Vec3Like

The direction the character is being pushed this step, normalized. Reused each step.

Returns#

Vec3Like

The direction the character is being pushed this step, normalized. Reused each step.

onDestroyed#

Get Signature#

get onDestroyed(): Signal<Component>

Emitted once when the component is destroyed, in the destroy flush. Connecting with { owner: this } elsewhere uses it to detach handlers automatically (docs/architecture/02-scene-graph.md §8).

Returns#

Signal<Component>

The signal. It is created on first access, so a component nobody listens to allocates nothing.

Inherited from#

Script.onDestroyed

speed#

Get Signature#

get speed(): number

The character's horizontal speed this step, in metres per second.

Returns#

number

The character's horizontal speed this step, in metres per second.

transform#

Get Signature#

get transform(): Transform

The entity's transform — sugar for this.entity.transform, the most-used lookup there is.

Returns#

Transform

The entity's transform.

Inherited from#

Script.transform

uid#

Get Signature#

get uid(): string

The stable ULID; the key files use to reference this component.

Returns#

string

The identifier.

Inherited from#

Script.uid

verticalVelocity#

Get Signature#

get verticalVelocity(): number

The character's vertical speed, positive upwards.

Returns#

number

The character's vertical speed, positive upwards.

world#

Get Signature#

get world(): World

The world the entity belongs to.

Returns#

World

The world.

Inherited from#

Script.world

Methods#

awake()#

awake(): void

Finds the character controller and binds the action names.

Returns#

void

define()#

static define<S>(schema): ScriptDefinition<S>

Declares a script's serialized fields and returns the base class to extend — the Script counterpart of Component.define.

Type Parameters#

S#

S extends Readonly<Record<string, FieldDefinition<unknown>>>

The schema being declared.

Parameters#

schema#

S

The field definitions, keyed by the property name they become.

Returns#

ScriptDefinition<S>

An abstract class to extend.

Throws#

IgnifxError with code IGX-0607 when a field name is not identifier-like or collides with a Component/Script member.

Example#

typescript

class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {  static typeId = "mygame/Patrol";}

Inherited from#

Script.define

destroy()#

destroy(): void

Returns#

void

Inherited from#

Script.destroy

fixedUpdate()#

fixedUpdate(dt): void

Moves the character.

Parameters#

dt#

number

The fixed step, in seconds.

Returns#

void

getComponent()#

getComponent<T>(type): T | null

Finds another component on the same entity — sugar for this.entity.getComponent.

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class; matching is by class identity and inheritance.

Returns#

T | null

The first match in attach order, or null.

Inherited from#

Script.getComponent

rebind()#

rebind(): void

Re-resolves the action names, for a game that changed them at runtime or reloaded its maps.

Returns#

void

requireComponent()#

requireComponent<T>(type): T

Finds another component on the same entity, requiring it to be there — the supported way to link components (docs/architecture/03-scripting-and-components.md §8).

Type Parameters#

T#

T extends Component

The component type to look for.

Parameters#

type#

ComponentType<T>

The component class.

Returns#

T

The first match in attach order.

Throws#

IgnifxError with code IGX-0201 when the entity has no such component.

Inherited from#

Script.requireComponent

resetMomentum()#

resetMomentum(): void

Cancels the character's vertical momentum — after a teleport, or when a cutscene takes over.

Returns#

void

startCoroutine()#

startCoroutine(routine): CoroutineHandle

Starts a coroutine owned by this script (docs/architecture/01-lifecycle-and-time.md §5). The coroutine is paused while the script is not effectively enabled and cancelled when it is destroyed.

Parameters#

routine#

Coroutine

The generator to drive. Call the generator function: this.spawnLoop().

Returns#

CoroutineHandle

A handle for stopping it or waiting on it.

Example#

typescript

blink() {  while (true) {    this.renderer.enabled = !this.renderer.enabled;    yield waitSeconds(0.2);  }}onEnable(): void {  this.startCoroutine(this.blink());}

Inherited from#

Script.startCoroutine

stopAllCoroutines()#

stopAllCoroutines(): void

Stops every coroutine this script started.

Returns#

void

Inherited from#

Script.stopAllCoroutines

stopCoroutine()#

stopCoroutine(handle): void

Stops one coroutine this script started. Stopping a finished coroutine is a no-op.

Parameters#

handle#

CoroutineHandle

The handle Script.startCoroutine returned.

Returns#

void

Inherited from#

Script.stopCoroutine

ThreeDAnimationSystem#

Advances skeletal animation on ignifx's clock.

Implements#

System

Constructors#

Constructor#

new ThreeDAnimationSystem(): ThreeDAnimationSystem

Returns#

ThreeDAnimationSystem

Properties#

name#

readonly name: "ignifx/3d-animation" = "ignifx/3d-animation"

The name diagnostics and error reports use.

Implementation of#

System.name

Methods#

update()#

update(ctx): void

Advances every enabled animator.

Parameters#

ctx#

SystemContext

The world, clock, phase, and delta.

Returns#

void

Remarks#

ctx.dt is time.deltaTime, already scaled by time.timeScale. It is not zero while the app is paused — TimeImpl.beginFrame scales by timeScale only — so the pause check is made here, per animator, which is also what makes updateWhenPaused mean something.

Implementation of#

System.update

Interfaces#

AnimatorBlendChildDefinition#

One child of a 1D blend tree.

Properties#

clip#

readonly clip: string

The animation-group name this child plays.

threshold#

readonly threshold: number

The parameter value at which this child reaches full weight.

AnimatorBlendTreeDefinition#

A 1D blend tree: a run of clips laid out along one parameter.

Properties#

children#

readonly children: readonly AnimatorBlendChildDefinition[]

The children, sorted ascending by threshold.

name#

readonly name: string

The tree's name; what a state's blendTree takes.

param#

readonly param: string

The parameter the tree reads.

AnimatorConditionDefinition#

One condition of one transition.

Properties#

op#

readonly op: "trigger" | "gt" | "gte" | "lt" | "lte" | "eq" | "neq"

The comparison.

param#

readonly param: string

The parameter to test.

value#

readonly value: number

What to compare against. Booleans are 1 and 0; ignored by trigger.

AnimatorDefinition#

The parsed .animator.json document.

Properties#

blendTrees1D#

readonly blendTrees1D: readonly AnimatorBlendTreeDefinition[]

Every 1D blend tree.

format#

readonly format: "ignifx.animator"

Always "ignifx.animator".

formatVersion#

readonly formatVersion: number

Always 1 in this build.

layers#

readonly layers: readonly AnimatorLayerDefinition[]

Every layer, in blend order: the first is the base.

parameters#

readonly parameters: readonly AnimatorParameterDefinition[]

Every parameter, in declaration order.

states#

readonly states: readonly AnimatorStateDefinition[]

Every state, in declaration order.

transitions#

readonly transitions: readonly AnimatorTransitionDefinition[]

Every transition, in declaration order — which is also priority order.

AnimatorEventDefinition#

An animation event: a name emitted on Animator.onEvent when the clip passes a point.

Properties#

name#

readonly name: string

The name emitted on Animator.onEvent.

time#

readonly time: number

Where in the clip the event sits, as a fraction of the clip's length in [0, 1].

AnimatorInput#

What defineAnimator accepts: the document as authored, with every optional key omitted.

Properties#

blendTrees1D?#

readonly optional blendTrees1D?: readonly unknown[]

The 1D blend trees.

format?#

readonly optional format?: string

Always "ignifx.animator" when present.

formatVersion?#

readonly optional formatVersion?: number

The document version.

layers?#

readonly optional layers?: readonly unknown[]

The layers; a document that declares none gets one base layer.

parameters?#

readonly optional parameters?: readonly unknown[]

The parameters.

states?#

readonly optional states?: readonly unknown[]

The states.

transitions?#

readonly optional transitions?: readonly unknown[]

The transitions.

AnimatorLayerDefinition#

One layer: an independent state machine whose pose is blended over the layers below it.

Properties#

additive#

readonly additive: boolean

Whether the layer adds to the pose beneath it rather than replacing it.

defaultState#

readonly defaultState: string

The state the layer starts in; the layer's first state when the document omits it.

mask#

readonly mask: readonly string[]

The bone names the layer's mask lists. Empty means "no mask".

maskMode#

readonly maskMode: "include" | "exclude"

Whether mask lists the bones that animate or the bones that do not.

name#

readonly name: string

The layer's name; what play({ layer }) and currentState(layer) take.

weight#

readonly weight: number

How much of this layer's pose reaches the result, in [0, 1].

AnimatorParameterDefinition#

One declared parameter.

Properties#

kind#

readonly kind: "bool" | "float" | "int" | "trigger"

What kind of value it holds.

name#

readonly name: string

The name setFloat and a condition's param use.

value#

readonly value: number

The value it starts at. Ignored for trigger, which always starts clear.

AnimatorPlayOptions#

What Animator.play accepts.

Properties#

layer?#

readonly optional layer?: string

Which layer to play on; the state's own layer when omitted.

transitionSeconds?#

readonly optional transitionSeconds?: number

How long to crossfade for, in seconds. 0 — the default — cuts.

AnimatorStateDefinition#

One state of one layer.

Properties#

blendTree#

readonly blendTree: string

The 1D blend tree this state plays. Empty when clip names a single clip.

clip#

readonly clip: string

The animation-group name this state plays. Empty when blendTree names one instead.

events#

readonly events: readonly AnimatorEventDefinition[]

The events fired as the state plays.

layer#

readonly layer: string

The layer the state belongs to; the first layer when the document omits it.

loop#

readonly loop: boolean

Whether the state restarts at its end.

name#

readonly name: string

The state's name, unique in the document; what play and a transition's to take.

speed#

readonly speed: number

A multiplier on the clip's own rate. Negative values play the state backwards.

AnimatorTransitionDefinition#

One transition.

Properties#

conditions#

readonly conditions: readonly AnimatorConditionDefinition[]

Every condition, all of which must pass. An empty list passes.

duration#

readonly duration: number

How long the crossfade takes, in seconds. 0 cuts.

exitTime#

readonly exitTime: number | null

The earliest normalized time the source state may be left at, in [0, 1], or null for "any time". A looping state's normalized time wraps, so an exit time fires once per loop.

from#

readonly from: string

The state this leaves, or ANY_STATE.

interruptible#

readonly interruptible: boolean

Whether the transition may start while another transition is already in flight.

to#

readonly to: string

The state this enters.

ClipWeight#

One clip's contribution to the pose this frame.

Properties#

additive#

readonly additive: boolean

Whether the clip belongs to an additive layer.

clip#

readonly clip: string

The animation-group name.

layer#

readonly layer: string

The layer the clip came from, so the adapter can find the mask.

speed#

readonly speed: number

The playback rate to set on the group.

weight#

readonly weight: number

How much of the pose it contributes, before Lite normalizes anything.

LodLevel#

One level of detail.

Properties#

distance#

readonly distance: number

The distance from the camera, in metres, beyond which this level takes over.

renderer#

readonly renderer: MeshRenderer | null

The renderer this level draws.

PlayStateOptions#

What AnimatorStateMachine.play accepts.

Properties#

layer?#

readonly optional layer?: string

Which layer to play on; the base layer when omitted.

transitionSeconds?#

readonly optional transitionSeconds?: number

How long to crossfade for, in seconds. 0 — the default — cuts.

StateChange#

A state change, as AnimatorStateMachine.drainStateChanges reports it.

Properties#

entered#

readonly entered: boolean

Whether the state was entered or left.

layer#

readonly layer: string

The layer the change happened on.

state#

readonly state: string

The state's name.

ThreeDErrorOptions#

Options accepted by threeDError: the same subset of IgnifxErrorOptions this package uses.

Properties#

cause?#

readonly optional cause?: unknown

The failure being wrapped, when there is one.

context?#

readonly optional context?: Readonly<Record<string, string | number | boolean | null>>

Identifiers that locate the failure.

hint?#

readonly optional hint?: string

One sentence telling the developer what to do about it.

ThreeDOptions#

What threeD() accepts. Every field overrides the matching threeD settings section value.

Properties#

autoBakeNavMesh?#

readonly optional autoBakeNavMesh?: boolean

Whether a NavMeshSurface bakes itself when the world loads.

navigationSeed?#

readonly optional navigationSeed?: number

The seed Recast's randomized queries start from.

navigationWasmUrl?#

readonly optional navigationWasmUrl?: string

Where the Recast .wasm is served from. Omit it to use the copy Babylon Lite inlines as a data: URL, which needs no build configuration at all (docs/adr/0017-navigation-wasm.md).

ThreeDSettings#

The resolved threeD settings section.

Example#

typescript

// ignifx.config.tsexport default defineConfig({  threeD: { navigationSeed: 42, navigationWasmUrl: "/recast-navigation.wasm" },});

Properties#

autoBakeNavMesh#

readonly autoBakeNavMesh: boolean

Whether a NavMeshSurface bakes itself when the world loads, without being asked.

navigationSeed#

readonly navigationSeed: number

The seed Recast's randomized queries start from. One seed for the whole project is what makes two runs of a level produce the same paths.

navigationWasmUrl#

readonly navigationWasmUrl: string

Where the Recast .wasm is served from, or the empty string to use the copy Babylon Lite inlines as a data: URL. See docs/adr/0017-navigation-wasm.md.

Type Aliases#

AnimatorConditionOp#

AnimatorConditionOp = typeof ANIMATOR_CONDITION_OPS[number]

The union of ANIMATOR_CONDITION_OPS.

AnimatorMaskMode#

AnimatorMaskMode = typeof ANIMATOR_MASK_MODES[number]

The union of ANIMATOR_MASK_MODES.

AnimatorParameterKind#

AnimatorParameterKind = typeof ANIMATOR_PARAMETER_KINDS[number]

The union of ANIMATOR_PARAMETER_KINDS.

BillboardMode#

BillboardMode = typeof BILLBOARD_MODES[number]

The union of BILLBOARD_MODES.

Remarks#

"full" faces the camera exactly. "yAxis" — the lockY of 12-3d-toolkit.md §6 — turns only around the world up axis, which is what a tree impostor or a name plate wants: it stays upright however far the camera looks down.

LiteAnimationGroup#

LiteAnimationGroup = AnimationGroup

Beta

A Babylon Lite animation group, the clip an Animator weights (index.d.ts 345).

Remarks#

Unstable escape-hatch type.

LiteAnimationManager#

LiteAnimationManager = AnimationManager

Beta

A Babylon Lite animation manager — one per Animator (index.d.ts 430).

Remarks#

Unstable escape-hatch type.

LiteNavCrowd#

LiteNavCrowd = NavCrowd

Beta

A Babylon Lite crowd (index.d.ts 7307).

Remarks#

Unstable escape-hatch type.

LiteNavigationPlugin#

LiteNavigationPlugin = NavigationPlugin

Beta

A Babylon Lite navigation plugin: the Recast module plus one baked navmesh (index.d.ts 7310).

Remarks#

Unstable escape-hatch type.

LiteObstacleHandle#

LiteObstacleHandle = ObstacleHandle

Beta

A Babylon Lite tile-cache obstacle handle (index.d.ts 7706).

Remarks#

Unstable escape-hatch type.

NavObstacleShape#

NavObstacleShape = typeof NAV_OBSTACLE_SHAPES[number]

The union of NAV_OBSTACLE_SHAPES.

ThreeDErrorCode#

ThreeDErrorCode = typeof ThreeDErrorCode[keyof typeof ThreeDErrorCode]

The union of the codes the ThreeDErrorCode table declares.

Variables#

ANIMATOR_ASSET_TYPE#

const ANIMATOR_ASSET_TYPE: "animator" = "animator"

The asset type name the loader registers.

ANIMATOR_CONDITION_OPS#

const ANIMATOR_CONDITION_OPS: readonly ["gt", "gte", "lt", "lte", "eq", "neq", "trigger"]

Every comparison a transition condition can make.

Remarks#

trigger is the odd one out: it has no value, it passes while the named trigger is set, and taking the transition consumes it — which is what makes setTrigger("jump") fire exactly once.

ANIMATOR_FILE_EXTENSIONS#

const ANIMATOR_FILE_EXTENSIONS: readonly string[]

The address suffixes that select the animator loader.

ANIMATOR_FORMAT#

const ANIMATOR_FORMAT: "ignifx.animator" = "ignifx.animator"

The format discriminator every .animator.json document carries.

ANIMATOR_FORMAT_VERSION#

const ANIMATOR_FORMAT_VERSION: 1 = 1

The document version this build reads and writes.

ANIMATOR_MASK_MODES#

const ANIMATOR_MASK_MODES: readonly ["include", "exclude"]

How a layer's pose combines with the layers under it.

ANIMATOR_PARAMETER_KINDS#

const ANIMATOR_PARAMETER_KINDS: readonly ["float", "int", "bool", "trigger"]

Every parameter kind a document can declare, in the order an inspector should list them.

ANY_STATE#

const ANY_STATE: "any" = "any"

The name from takes for a transition that can fire from any state on its layer.

BILLBOARD_MODES#

const BILLBOARD_MODES: readonly ["full", "yAxis"]

Every way a billboard can be constrained.

BILLBOARD_ORDER#

const BILLBOARD_ORDER: 20 = 20

The PostUpdate order the billboard system runs at.

Remarks#

20 is after the 3D animation system at 10, so a billboard parented under an animated bone faces the camera from the pose this frame rather than last frame's — which is the same reason ThirdPersonCamera is a lateUpdate script.

DEFAULT_CLIP_LENGTH#

const DEFAULT_CLIP_LENGTH: 1 = 1

How long a clip whose length nobody has declared is assumed to be, in seconds.

LOD_CULLED#

const LOD_CULLED: -1 = -1

The level index meaning "past the last level; draw nothing".

LOD_ORDER#

const LOD_ORDER: -10 = -10

The PreRender order the LOD system runs at.

Remarks#

-10 puts it before @ignifx/core's render sync at 0, so a renderer switched on this frame is reconciled with the Lite scene in the same frame rather than the next one.

NAV_OBSTACLE_SHAPES#

const NAV_OBSTACLE_SHAPES: readonly ["box", "cylinder"]

Every obstacle shape Lite's tile cache supports.

NAVIGATION_ORDER#

const NAVIGATION_ORDER: 200 = 200

The FixedUpdate order the navigation system runs at.

Remarks#

@ignifx/physics steps the world from its own FixedUpdate system inside the [1001, 9999] extension band; 200 is deliberately outside it and above the [-1000, 1000] core band's midpoint, so navigation lands after fixedUpdate scripts and after the physics step. An agent that also carries a CharacterController therefore sees this step's ground contact.

THREE_D_ANIMATION_ORDER#

const THREE_D_ANIMATION_ORDER: 10 = 10

The PostUpdate order the 3D animation system runs at.

Remarks#

10 puts it after @ignifx/2d's animation system, which registers at 0, and after the core tween system at -100. A project with both toolkits therefore advances tweens, then sprite clips, then skeletal clips — so a tween driving an Animator parameter is read in the same frame it is written, and a single Animator document driving both a SpriteAnimator and a skeleton stays one frame consistent.

THREE_D_ERROR_MESSAGES#

const THREE_D_ERROR_MESSAGES: Readonly<Record<string, string>>

The one-line message template of every code, as ExtensionContext.registerErrorCodes wants it. Context keys appear in braces, matching the core table's convention.

THREE_D_SETTINGS_SECTION#

const THREE_D_SETTINGS_SECTION: "threeD" = "threeD"

The section name as it appears in ignifx.config.ts.

threeD#

const threeD: (options?) => Extension

The @ignifx/3d extension factory.

Parameters#

options?#

ThreeDOptions

Overrides for the threeD settings section.

Returns#

Extension

The extension descriptor to pass to createApp.

Example#

typescript

const app = await createApp({  canvas,  extensions: [physics(), input(), threeD({ navigationSeed: 42 })],});

ThreeDErrorCode#

const ThreeDErrorCode: object

Every diagnostic code @ignifx/3d can throw or log, keyed by an intention-revealing name so call sites read as prose and the compiler catches typos (coding standards §5.2).

Type Declaration#

crowdFull#

readonly crowdFull: "IGX-1207" = "IGX-1207"

A NavMeshAgent could not join its crowd because the surface's maxAgents is full.

duplicateExtension#

readonly duplicateExtension: "IGX-1213" = "IGX-1213"

A second threeD() extension was registered on one app.

emptyNavMesh#

readonly emptyNavMesh: "IGX-1209" = "IGX-1209"

A NavMeshSurface was baked with no source geometry, so every query fails.

invalidAnimatorFile#

readonly invalidAnimatorFile: "IGX-1201" = "IGX-1201"

A .animator.json file is not an ignifx.animator document this build can read.

invalidLodLevel#

readonly invalidLodLevel: "IGX-1214" = "IGX-1214"

A LodGroup level names a renderer that is not under the group's entity.

navigationNotReady#

readonly navigationNotReady: "IGX-1205" = "IGX-1205"

A navigation query ran before the Recast plugin had finished loading, or before a bake.

navigationUnavailable#

readonly navigationUnavailable: "IGX-1206" = "IGX-1206"

The Recast WebAssembly module could not be loaded at all.

noMainCamera#

readonly noMainCamera: "IGX-1211" = "IGX-1211"

A rig needs the main camera and the world has none enabled.

obstaclesNotEnabled#

readonly obstaclesNotEnabled: "IGX-1208" = "IGX-1208"

A NavMeshObstacle needs a surface baked with maxObstacles greater than zero.

parameterKindMismatch#

readonly parameterKindMismatch: "IGX-1204" = "IGX-1204"

A parameter was written with a value of the wrong kind for its declaration.

prebakedNavMeshUnsupported#

readonly prebakedNavMeshUnsupported: "IGX-1210" = "IGX-1210"

A pre-baked .navmesh.bin was named; Babylon Lite 1.27.0 cannot deserialize one.

unknownInputAction#

readonly unknownInputAction: "IGX-1212" = "IGX-1212"

A controller named an input action the loaded action maps do not declare.

unknownParameter#

readonly unknownParameter: "IGX-1203" = "IGX-1203"

setFloat/setInt/setBool/setTrigger named a parameter the document does not declare.

unknownState#

readonly unknownState: "IGX-1202" = "IGX-1202"

Animator.play or a transition named a state the document does not declare.

Example#

typescript

throw threeDError(ThreeDErrorCode.unknownState, "hero.animator.json declares no state named jump.", {  context: { asset: "hero.animator.json", state: "jump" },});

VERSION#

const VERSION: "0.0.0" = "0.0.0"

The @ignifx/3d version this build was cut from.

WORLD_FORWARD#

const WORLD_FORWARD: Vec3Like

Where something faces when the world has no enabled camera at all.

Functions#

animatorFileSchema()#

animatorFileSchema(): Schema

The ignifx.animator document schema.

Returns#

Schema

The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).

cameraRelativeToRef()#

cameraRelativeToRef<TOut>(inputX, inputY, cameraForward, out): TOut

Turns a stick reading into a world-space direction relative to a camera's facing.

Type Parameters#

TOut#

TOut extends MutableVec3

Parameters#

inputX#

number

The stick's X, where +1 is right.

inputY#

number

The stick's Y, where +1 is forward.

cameraForward#

Vec3Like

The camera's forward vector; its Y component is discarded.

out#

TOut

Where to write the direction.

Returns#

TOut

out, for chaining.

Remarks#

Only the camera's yaw is used: a third-person camera looking down at a character should still send "forward on the stick" along the ground, not into it. The result is normalized, or left at zero when the stick is centred.

Example#

typescript

cameraRelativeToRef(move.x, move.y, camera.transform.forward, direction);

createAnimatorLoader()#

createAnimatorLoader(): AssetLoader<AnimatorAsset>

Builds the loader for .animator.json addresses.

Returns#

AssetLoader<AnimatorAsset>

The loader to register with ctx.registerAssetLoader.

Example#

typescript

ctx.registerAssetLoader(createAnimatorLoader());

defaultStateOf()#

defaultStateOf(definition, layer): string

The state a layer starts in.

Parameters#

definition#

AnimatorDefinition

The document.

layer#

AnimatorLayerDefinition

The layer.

Returns#

string

The state's name.

defaultThreeDSettings()#

defaultThreeDSettings(): ThreeDSettings

The values used for everything a project omits.

Returns#

ThreeDSettings

The default threeD section.

defineAnimator()#

defineAnimator(input, address?): AnimatorDefinition

Fills in the defaults of an animator document and checks every invariant the state machine relies on: unique names, resolvable layers, states that name exactly one source of clips, transitions between declared states, and conditions on declared parameters.

Parameters#

input#

AnimatorInput

The document, as authored.

address?#

string = "<inline>"

What to name in an error; defaults to "<inline>".

Returns#

AnimatorDefinition

The complete document.

Throws#

IgnifxError with code IGX-1201 when the document is not readable.

Example#

typescript

const definition = defineAnimator(JSON.parse(text) as AnimatorInput, "3d/hero.animator.json");

describeAnimatorFormat()#

describeAnimatorFormat(): SchemaDescription

Describes the ignifx.animator file format.

Returns#

SchemaDescription

The record pnpm docs:schemas renders.

describeSchemas()#

describeSchemas(): Readonly<Record<string, SchemaDescription>>

Describes every component and settings section this package registers.

Returns#

Readonly<Record<string, SchemaDescription>>

The record pnpm docs:schemas renders, keyed by schema id.

jumpVelocity()#

jumpVelocity(height, gravity): number

The upward speed that reaches a given jump height under a given gravity.

Parameters#

height#

number

The apex height above the take-off point, in metres.

gravity#

number

The downward acceleration, as a positive number.

Returns#

number

The initial vertical speed, in metres per second.

mainCamera()#

mainCamera(world): Camera | null

The camera the player is looking through.

Parameters#

world#

World

The world to look in.

Returns#

Camera | null

The highest-priority enabled camera, or null when the world has none.

Example#

typescript

const camera = mainCamera(this.world);

mainCameraForward()#

mainCameraForward(world): Vec3Like

The main camera's forward vector.

Parameters#

world#

World

The world to look in.

Returns#

Vec3Like

The forward vector, or WORLD_FORWARD when there is no camera.

projectOnSlopeToRef()#

projectOnSlopeToRef<TOut>(direction, normal, out): TOut

Projects a movement vector onto a slope so a character slides along it rather than into it.

Type Parameters#

TOut#

TOut extends MutableVec3

Parameters#

direction#

Vec3Like

The desired direction.

normal#

Vec3Like

The ground normal.

out#

TOut

Where to write the projected direction.

Returns#

TOut

out, for chaining.

slopeAngleDegrees()#

slopeAngleDegrees(normal): number

The angle between a ground normal and straight up, in degrees.

Parameters#

normal#

Vec3Like

The ground normal.

Returns#

number

The slope angle in degrees; 0 for flat ground.

threeDError()#

threeDError(code, message, options?): IgnifxError

Builds an IgnifxError carrying one of this package's codes.

Parameters#

code#

ThreeDErrorCode

The code from the ThreeDErrorCode table.

message#

string

The actionable development sentence.

options?#

ThreeDErrorOptions

Context identifiers, a remedy hint, and the wrapped cause.

Returns#

IgnifxError

The error to throw or to reject with.

Example#

typescript

throw threeDError(ThreeDErrorCode.unknownParameter, "hero.animator.json declares no speed.", {  context: { asset: "hero.animator.json", parameter: "speed" },});

threeDSettingsSchema()#

threeDSettingsSchema(): Schema

The schema the threeD section is validated against.

Returns#

Schema

The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).

turnTowardsDegrees()#

turnTowardsDegrees(currentDegrees, targetDegrees, degreesPerSecond, deltaSeconds): number

Rotates one yaw towards another at a bounded rate, the short way round.

Parameters#

currentDegrees#

number

Where the character faces now.

targetDegrees#

number

Where it should face.

degreesPerSecond#

number

The turn rate; 0 or less snaps.

deltaSeconds#

number

The step.

Returns#

number

The new yaw, in degrees.

Example#

typescript

const yaw = turnTowardsDegrees(current, target, 720, dt);

yawFromDirection()#

yawFromDirection(x, z): number | null

The yaw, in degrees, that faces a horizontal direction.

Parameters#

x#

number

The direction's X.

z#

number

The direction's Z.

Returns#

number | null

The yaw in degrees, or null when the direction is degenerate.