API reference·skills/ignifx/references/api/ignifx.md
ignifx
This is a generated API reference for a whole package barrel, and it is a large page — several megabytes of HTML. Code blocks on it are not syntax-coloured and headings carry no permalink anchor. The contents rail and the search dialog are the fast way in.
ignifx public barrel: the umbrella entry point that re-exports @ignifx/core and, as each
phase lands, the standard extensions (docs/architecture/00-overview.md §2). Every symbol is
re-exported by name — no export * (coding standards §4).
Phase 2 added the render components, the GPU asset loaders, and the scene serialization surface;
Phase 3 adds the whole of @ignifx/input. The physics, physics-2d, audio, 2d, 3d, and ui
re-exports and the one-call createGame() arrive with the phases of
docs/plan/engineering-plan.md that populate those packages.
Two @ignifx/input exports are deliberately not re-exported, because @ignifx/core already
owns the name: VERSION (the umbrella reports the core version) and describeSchemas (the
documentation harness reads each package's own entry point, so nothing is lost). Reach them as
@ignifx/input's own exports when a tool needs them.
Classes
ActionMap
A named group of actions.
Example
app.input.actions.map("UI").enabled = true;
app.input.actions.map("Player").enabled = false;Constructors
Constructor
new ActionMap(
definition,resolver,onHandlerError):ActionMap
Builds a map and its actions.
Parameters
definition
The map as it appears in an ignifx.inputactions document.
resolver
How binding paths become controls.
onHandlerError
(error) => void
Where an action signal handler's exception is reported.
Returns
Throws
IgnifxError with code IGX-0810 when two actions share a name, or with a binding code
when one of the bindings cannot be resolved.
Properties
enabled
enabled:
boolean
Whether the map's actions resolve. Actions in a disabled map read as released.
name
readonlyname:string
The map name.
Accessors
actions
Get Signature
get actions():
ReadonlyMap<string,InputAction>
The map's actions, keyed by name.
Returns
ReadonlyMap<string, InputAction>
The action table.
Methods
get()
get(
name):InputAction
Looks one action up.
Parameters
name
string
The action name.
Returns
The action.
Throws
IgnifxError with code IGX-0801 when the map declares no such action.
ActionVector
A live, allocation-free view of an action's vector2 value.
Implements
Constructors
Constructor
new ActionVector(
values):ActionVector
Wraps the two slots an action keeps its value in.
Parameters
values
Float32Array
The action's value array.
Returns
Accessors
x
Get Signature
get x():
number
The x component, read from the action's live value.
Returns
number
The current x.
The x component.
Implementation of
y
Get Signature
get y():
number
The y component, read from the action's live value.
Returns
number
The current y.
The y component.
Implementation of
Animator
An animation state machine bound to the Model on its entity.
Example
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
Implements
Constructors
Constructor
new Animator():
Animator
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticschema:Schema
The declarative fields (ADR-0004).
speed
speed:
number
A multiplier on every state's own rate.
typeId
statictypeId:string
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
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
readonlymanager:AnimationManager|null
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
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()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
onDetach()
onDetach():
void
Hands the clips back so another animator, or a reload, can claim them.
Returns
void
Implementation of
play()
play(
state,options?):void
Plays a state, cutting to it unless transitionSeconds says otherwise.
Parameters
state
string
The state's name.
options?
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
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
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
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
The parsed document.
Returns
Properties
address
readonlyaddress:string
Where the document was loaded from.
assetType
staticassetType:string
The asset type name, so assetRef and the inspector can round-trip a reference.
definition
readonlydefinition: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
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
The parsed .animator.json document.
Returns
Properties
speed
speed:
number
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
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
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?
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.
AssetLoadError
The failure an AssetHandle.promise rejects with
(docs/architecture/05-assets-and-loading.md §9). Its code is one of IGX-0502 (aborted),
IGX-0503 (the app was disposed), IGX-0504 (no loader), or IGX-0505 (the load failed after
every retry, with the last failure as cause).
Example
try {
await app.assets.loadAsync("levels/1.scene.json");
} catch (error) {
if (error instanceof AssetLoadError) {
app.log.error("{address} failed from {url}", error.address, error.url);
}
}Extends
Constructors
Constructor
new AssetLoadError(
code,message,options):AssetLoadError
Creates an asset failure.
Parameters
code
`IGX-${number}`
The IGX-05xx code.
message
string
The actionable development sentence.
options
The address and URL, plus the standard context, hint, and cause.
Returns
Overrides
Properties
address
readonlyaddress:string
The address that failed.
cause?
optionalcause?:unknown
Inherited from
code
readonlycode:`IGX-${number}`
The stable diagnostic code for this failure.
Inherited from
context
readonlycontext:ErrorContext
Identifiers that locate the failure (entity uid, component type id, asset key, …).
Inherited from
hint
readonlyhint:string|null
One sentence telling the developer how to fix it, or null when there is nothing to add.
Inherited from
message
message:
string
Inherited from
name
name:
string
Inherited from
stack?
optionalstack?:string
Inherited from
url
readonlyurl:string
The URL it resolved to.
AudioBusesAsset
A parsed .audio.json (docs/architecture/10-audio.md §1).
Example
const tree = await app.assets.loadAsync<AudioBusesAsset>("audio/buses.audio.json");
tree.value.buses[0].name; // "Master"Properties
address
readonlyaddress:string
The address the tree was loaded from.
assetType
staticassetType:string
The type name the asset service registers bus files under.
buses
readonlybuses: readonlyAudioBusDefinition[]
The buses, parents before children.
AudioClip
One loaded sound file (docs/architecture/10-audio.md §2).
Example
const step = await app.assets.loadAsync<AudioClip>("audio/footstep.wav");
step.value.duration; // 0.42
app.audio.playOneShot(step.value);Properties
address
readonlyaddress:string
The address the clip was loaded from.
assetType
staticassetType:string
The type name the asset service registers audio clips under.
isStreaming
readonlyisStreaming:boolean
Whether the clip is played by a media element rather than from a decoded buffer.
url
readonlyurl:string
The URL the address resolved to.
Accessors
byteLength
Get Signature
get byteLength():
number
How many bytes the file held, for diagnostics. Stays at its loaded value after the bytes have been decoded and released.
Returns
number
The file size in bytes, or 0 for a streaming clip, which is never fetched.
channels
Get Signature
get channels():
number|null
How many interleaved channels the clip holds.
Returns
number | null
The channel count, or null when unknown.
duration
Get Signature
get duration():
number|null
How long the clip plays, in seconds.
Returns
number | null
The duration, or null when this build has not been able to determine it.
isDecoded
Get Signature
get isDecoded():
boolean
true once a backend has decoded this clip into a playable buffer.
Returns
boolean
Whether AudioClip.lite carries a buffer.
lite
Get Signature
get lite():
AudioClipLiteHandles
The Babylon Lite objects the clip owns. Unstable escape hatch.
Returns
The decoded buffer, or null.
sampleRate
Get Signature
get sampleRate():
number|null
The clip's sample rate.
Returns
number | null
Samples per second, or null when unknown.
AudioListener
The listener spatial audio is heard from.
Example
const camera = world.createEntity("Main Camera");
camera.addComponent(Camera);
camera.addComponent(AudioListener);Extends
Implements
Constructors
Constructor
new AudioListener():
AudioListener
Creates a component. The engine constructs components; game code never calls new.
Returns
Inherited from
Properties
allowMultiple
staticallowMultiple:boolean
One pair of ears per entity.
schema
staticschema:Schema
The serialized field declarations (ADR-0004). A listener has none: which listener is active is decided by which one is enabled, and a scene file records that on the component itself.
typeId
statictypeId:string
The registration id the serializer and the inspector know this class by.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
spatialTarget
Get Signature
get spatialTarget():
SpatialTarget
The world transform Lite's spatial listener follows: this entity's node
(setSpatialListener(engine, { attachedTo }), index.d.ts 11008).
Returns
SpatialTarget
The entity's Lite node, which exposes the worldMatrix a SpatialTarget needs.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDisable()
onDisable():
void
Hands the ears back to whichever listener was active before this one.
Returns
void
Implementation of
onEnable()
onEnable():
void
Becomes the active listener.
Returns
void
Implementation of
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
AudioService
The service behind app.audio.
Example
app.audio.bus("Music").setVolume(0.3, 2);
app.audio.playOneShot(coin.value, { volume: 0.8, pitch: 1.2 });
await app.audio.unlock(); // from a click handler, for an explicit "tap to start"Implements
Constructors
Constructor
new AudioService(
options):AudioService
Creates the service. The extension does this in onStart, once a backend exists.
Parameters
options
The app, the logger, the backend, and the resolved settings.
Returns
Properties
backend
readonlybackend:AudioBackend
The backend every call is forwarded to; "headless" under Node.
Implementation of
Accessors
buses
Get Signature
get buses():
ReadonlyMap<string,AudioBus>
The mixer tree, keyed by bus name, in declaration order.
Returns
ReadonlyMap<string, AudioBus>
The buses. Empty until the tree has been built, which is before the first frame unless
the project loads its tree from a .audio.json.
isLocked
Get Signature
get isLocked():
boolean
true before the first unlock — the predicate voices queue on.
Returns
boolean
Whether plays are being held.
true before the first unlock, when a browser would refuse to make a sound.
Implementation of
isTreeReady
Get Signature
get isTreeReady():
boolean
true once the mixer tree exists and sounds can be routed.
Returns
boolean
Whether the tree has been built.
isUnlocked
Get Signature
get isUnlocked():
boolean
true once the audio context has run at least once, so plays are no longer queued.
Returns
boolean
Whether the engine has been unlocked.
listener
Get Signature
get listener():
AudioListener|null
The listener spatial audio is heard from (docs/architecture/10-audio.md §4).
Returns
AudioListener | null
The most recently enabled AudioListener, or null when none is enabled.
lite
Get Signature
get lite():
AudioServiceLiteHandles
The Babylon Lite objects behind the service. Unstable escape hatch.
Returns
The engine, or null under the headless backend.
masterVolume
Get Signature
get masterVolume():
number
The master output gain, applied after every bus.
Returns
number
The linear gain, where 1 is unity.
Set Signature
set masterVolume(
value):void
Parameters
value
number
Returns
void
onStateChanged
Get Signature
get onStateChanged():
SignalLike<AudioServiceState>
Emitted whenever AudioService.state changes.
Returns
The signal.
queueWhileLocked
Get Signature
get queueWhileLocked():
boolean
Whether plays made while locked are held rather than dropped.
Returns
boolean
The audio.queueWhileLocked setting.
Whether plays made while locked are held rather than dropped.
Implementation of
state
Get Signature
get state():
AudioServiceState
Where the audio engine is (docs/architecture/10-audio.md §1).
Returns
"locked" until the first unlock, and the audio context's own state after it.
unlockedAtMs
Get Signature
get unlockedAtMs():
number|null
When the engine was unlocked, on the app's realtime clock.
Returns
number | null
Milliseconds since the app was created, or null while still locked.
Methods
buildBuses()
buildBuses(
definitions):Promise<void>
Builds the mixer tree, releasing whatever tree was there before.
Parameters
definitions
readonly AudioBusDefinition[]
The buses, parents before children.
Returns
Promise<void>
Throws
IgnifxError with code IGX-1006 when a definition names a parent that is not declared
before it.
bus()
bus(
name):AudioBus
Looks a bus up by name.
Parameters
name
string
The bus name, for example "Music".
Returns
The bus.
Throws
IgnifxError with code IGX-1001 when the tree holds no such bus.
Example
app.audio.bus("SFX").volume = 0.5;createBus()
createBus(
name,options?):Promise<AudioBus>
Adds a bus to the tree at run time.
Parameters
name
string
The new bus's name.
options?
Its parent, gain, and pause behaviour.
Returns
Promise<AudioBus>
The bus, once the backend has built it.
Throws
IgnifxError with code IGX-1001 when options.parent names a bus that does not exist,
or IGX-1005 when the name is already taken.
Example
const ambience = await app.audio.createBus("Ambience", { parent: "Master", volume: 0.4 });createVoice()
createVoice(
request):SoundVoice
Builds a voice: one clip routed to one bus, with the options an AudioSource carries.
Parameters
request
The clip, the bus name, and the per-sound options.
Returns
The voice.
Remarks
The backend sound is created as soon as the mixer tree exists, which is normally before the first frame; a voice built earlier holds its plays until then, the same way it holds them behind the unlock.
Example
const voice = app.audio.createVoice({
clip, bus: "SFX", volume: 1, playbackRate: 1, loop: false, maxInstances: 8, pan: 0, spatial: null,
});defaultBusTree()
staticdefaultBusTree(names): readonlyAudioBusDefinition[]
Turns a list of bus names into the default tree: the first name is the root and every other
name routes into it (docs/architecture/10-audio.md §1).
Parameters
names
readonly string[]
The bus names, root first.
Returns
readonly AudioBusDefinition[]
The definitions to hand AudioService.buildBuses.
dispose()
dispose():
void
Releases every voice, every bus, and the backend itself.
Returns
void
playOneShot()
playOneShot(
clip,options?):SoundInstance
Plays a clip once, with no component and nothing to keep hold of — a coin pickup, a UI click
(docs/architecture/10-audio.md §1).
Parameters
clip
The clip to play.
options?
Per-play overrides, and the bus to route through.
Returns
The sound, so a caller that wants to can stop or fade it.
Remarks
One voice is kept per clip-and-bus pair and reused, so a hundred coins in a second cost one
Web Audio sub-graph and a hundred instances, with the oldest stolen past sixteen. The clip must
already be loaded; an asset() field hands you exactly that.
Example
class Coin extends Script {
pickup: AssetHandle<AudioClip> | null = null;
onTriggerEnter(): void {
if (this.pickup !== null) {
this.app.audio.playOneShot(this.pickup.value, { pitch: 1 + Math.random() * 0.1 });
}
}
}pump()
pump(
deltaSeconds):void
Advances everything time-based by one frame: fades, pending stops, the app-pause transition,
simulated playback, and onEnded (docs/architecture/01-lifecycle-and-time.md §3 step 10).
Parameters
deltaSeconds
number
The frame delta in seconds.
Returns
void
registerListener()
registerListener(
listener):void
Adds a listener to the selection (docs/architecture/10-audio.md §4). The most recently
registered enabled listener wins, which during a scene load is the one with the highest
creation serial.
Parameters
listener
The listener that just became enabled.
Returns
void
releaseVoice()
releaseVoice(
voice):void
Releases a voice and its backend sound.
Parameters
voice
The voice to release.
Returns
void
reportError()
reportError(
error):void
Reports a failure that has no caller to throw at, through app.onError.
Parameters
error
unknown
What went wrong.
Returns
void
Implementation of
setDiagnostics()
setDiagnostics(
group):void
Attaches the diagnostics group the extension registered.
Parameters
group
The audio counter group.
Returns
void
tryBus()
tryBus(
name):AudioBus|null
Looks a bus up, tolerating its absence — the pattern for code that must work with or without a particular bus (coding standards §5.5).
Parameters
name
string
The bus name.
Returns
AudioBus | null
The bus, or null.
unlock()
unlock():
Promise<void>
Resumes the audio context — what a "tap to start" button calls
(docs/architecture/10-audio.md §1).
Returns
Promise<void>
A promise that settles once the context is running.
Remarks
Every play() made while locked is started as this settles, in the order it was requested.
Calling it when already unlocked is a no-op. Call it from inside a real user-gesture handler:
browsers ignore a resume that does not come from one.
Example
button.addEventListener("click", () => void app.audio.unlock());unregisterListener()
unregisterListener(
listener):void
Removes a listener from the selection.
Parameters
listener
The listener that was disabled or destroyed.
Returns
void
AudioSource
A sound attached to an entity.
Example
class Footsteps extends Script {
#source: AudioSource | null = null;
awake(): void {
this.#source = this.requireComponent(AudioSource);
}
step(): void {
this.#source?.play({ pitch: 0.9 + Math.random() * 0.2 });
}
}Extends
Implements
Constructors
Constructor
new AudioSource():
AudioSource
Applies the schema defaults, exactly as Script.define would.
Returns
Overrides
Properties
bus
bus:
string
Which mixer bus this source routes into.
clip
clip:
AssetHandle<AudioClip> |null
The sound to play.
cone
cone:
AudioConeSettings
The source's directionality, in degrees.
distanceModel
distanceModel:
"linear"|"inverse"|"exponential"
Which attenuation curve distance follows.
loop
loop:
boolean
Whether instances repeat instead of ending.
maxDistance
maxDistance:
number
Maximum distance, in metres; used by the "linear" model.
maxInstances
maxInstances:
number
How many instances may sound at once; the oldest is stolen above it.
minDistance
minDistance:
number
Distance below which no attenuation is applied, in metres.
pan
pan:
number
Stereo pan of a non-spatial source, in [-1, 1].
pitch
pitch:
number
Playback rate; Lite's own pitch is in cents and is not exposed.
playOnAwake
playOnAwake:
boolean
Whether to play once as soon as the entity comes alive.
rolloff
rolloff:
number
How steeply the sound falls off with distance.
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
spatial
spatial:
boolean
Whether the sound is positioned in 3D instead of in the stereo field.
typeId
statictypeId:string
The registration id the serializer and the inspector know this class by.
volume
volume:
number
The sound's own linear gain, in [0, 1].
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
instance
Get Signature
get instance():
SoundInstance|null
The sound this source is playing, once it has played at least once.
Returns
SoundInstance | null
The instance, or null.
instanceCount
Get Signature
get instanceCount():
number
How many instances of this source are live.
Returns
number
The instance count, 0 when nothing is playing.
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.
Whether the owner has already been destroyed.
Inherited from
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
isPlaying
Get Signature
get isPlaying():
boolean
true while at least one instance is sounding, or waiting behind the unlock.
Returns
boolean
Whether the source is making a sound.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
onEnded
Get Signature
get onEnded():
SignalLike
Emitted in PreRender on the frame the last instance stops sounding, whether it ran out or was
stopped (docs/architecture/10-audio.md §3).
Returns
The signal.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Starts the source when playOnAwake is set, after the scene's props have been decoded.
Returns
void
Implementation of
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDestroy()
onDestroy():
void
Releases the voice and its backend sound.
Returns
void
Implementation of
onDisable()
onDisable():
void
Stops everything this source is playing; a disabled source makes no sound.
Returns
void
Implementation of
pause()
pause():
void
Pauses every instance, keeping its position.
Returns
void
play()
play(
options?):SoundInstance|null
Starts one more instance of this source's clip.
Parameters
options?
Per-play overrides for volume, pitch, loop, delay, start offset, and duration.
Returns
SoundInstance | null
The sound, so a caller can fade or stop it; null when the source has no clip.
Throws
IgnifxError with code IGX-1001 when bus names a bus the tree does not hold.
Example
this.source.play({ volume: 0.6, delay: 0.25 });playOneShot()
playOneShot(
clip,options?):SoundInstance
Plays another clip once through this source's bus, without disturbing what this source is
playing (docs/architecture/10-audio.md §3).
Parameters
clip
The clip to play.
options?
The gain for this one play.
Returns
The sound.
Example
this.source.playOneShot(this.impact.value, { volume: 0.5 });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
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
resume()
resume():
void
Resumes every paused instance.
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stop()
stop(
fadeSeconds?):void
Stops every instance, optionally fading out first.
Parameters
fadeSeconds?
number
Seconds of frame time to fade over; omitted or 0 stops now.
Returns
void
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
update()
update():
void
Pushes the field changes a running sound can accept and rebuilds the voice when one it cannot accept changed.
Returns
void
Implementation of
Billboard
An entity that faces the camera.
Example
nameplate.addComponent(Billboard, { mode: "yAxis" });Extends
Constructors
Constructor
new Billboard():
Billboard
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
BillboardSystem
Turns every enabled Billboard towards the main camera.
Implements
Constructors
Constructor
new BillboardSystem():
BillboardSystem
Returns
Properties
name
readonlyname:"ignifx/3d-billboard"="ignifx/3d-billboard"
The name diagnostics and error reports use.
Implementation of
Methods
update()
update(
ctx):void
Faces every billboard.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
Binding
One binding of one action.
Remarks
A binding tagged with a control scheme still resolves when another scheme is active. Unity's
schemes filter device pairing and UI glyphs, not resolution, and a game that binds jump to both
the space bar and the south button expects both to work whichever scheme the player used last.
Set input.strictSchemes to make the tag a filter instead.
Example
const jump = app.input.actions.get("jump");
jump.bindings[0].overridePath = "<Keyboard>/enter";Constructors
Constructor
new Binding(
definition,resolver):Binding
Builds a binding from its document form.
Parameters
definition
The binding as it appears in an ignifx.inputactions document.
resolver
How paths become controls, and how the owner is told they changed.
Returns
Throws
IgnifxError with code IGX-0802, IGX-0803, or IGX-0806 when the definition names
an unknown processor, an unresolvable path, or an unknown composite.
Properties
composite
readonlycomposite:CompositeKind|null
The composite this binding uses, or null for a simple path binding.
partNames
readonlypartNames: readonlystring[]
The composite part names, in evaluation order; empty for a simple binding.
partPaths
readonlypartPaths: readonlystring[]
The path each composite part was declared with, in Binding.partNames order.
path
readonlypath:string
The path the binding was declared with; "" for a composite.
processors
readonlyprocessors: readonlystring[]
The processor strings the binding declared, in application order.
scheme
readonlyscheme:string
The control scheme this binding is tagged with; "" when it belongs to every scheme.
Accessors
effectivePath
Get Signature
get effectivePath():
string
The path the binding actually reads: the override when there is one, otherwise the declared path.
Returns
string
The effective path; "" for a composite with no override.
overridePath
Get Signature
get overridePath():
string|null
The path that replaces Binding.path at run time, or null when the binding is not
overridden (docs/architecture/08-input.md §6).
Remarks
Assigning re-resolves the binding: a path that does not resolve throws IGX-0803 and the
previous override is kept. A composite binding cannot be overridden as a whole; override the
action's simple bindings instead.
Returns
string | null
The override, or null. Assign null to return to the declared path.
Set Signature
set overridePath(
path):void
Parameters
path
string | null
Returns
void
BoxCollider
A box collider, sized in local units (09-physics.md §2.2).
Example
const floor = world.createEntity("Floor");
floor.addComponent(BoxCollider, { size: { x: 20, y: 1, z: 20 } });Extends
Constructors
Constructor
new BoxCollider():
BoxCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
size
size:
Vec3Like
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,scale):PhysicsShape
Builds this collider's Havok shape.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
scale
The entity's lossy scale, applied to the authored dimensions.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
scale,out):void
Writes half the size of this collider's local bounding box, scale applied.
Parameters
scale
The entity's lossy scale.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
BoxCollider2D
An axis-aligned box collider, sized in local metres.
Example
const floor = world.createEntity("Floor");
floor.addComponent(BoxCollider2D, { size: { x: 20, y: 1 } });Extends
Constructors
Constructor
new BoxCollider2D():
BoxCollider2D
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
TilemapCollider2D.inlineMaterial
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
size
size:
Vec2Like
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
Camera
The camera an entity renders the world through (docs/architecture/07-rendering.md §2.1).
Remarks
A world renders through the enabled camera with the highest priority; ties break on creation
order. A world with no enabled camera draws nothing and logs IGX-0706 once.
Example
const eye = world.createEntity("Main Camera", { position: { x: 0, y: 2, z: -6 } });
eye.addComponent(Camera, { fov: 50, near: 0.05 });Extends
Implements
Constructors
Constructor
new Camera():
Camera
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
At most one camera per entity: two views from one transform would be the same view.
clearColor
clearColor:
ColorLike|null
far
far:
number
fov
fov:
number
near
near:
number
orthographicSize
orthographicSize:
number
priority
priority:
number
projection
projection:
"perspective"|"orthographic"
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
typeId
statictypeId:string
The namespaced registration id.
viewport
viewport:
object
height
height:
number
width
width:
number
x
x:
number
y
y:
number
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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 camera this component owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
object
The camera, or null before the component is attached.
camera
readonlycamera:FreeCamera|null
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
getProjectionMatrix()
getProjectionMatrix(
out):Mat4
Copies the camera's projection matrix into out.
Parameters
out
A 4x4 matrix that receives the result, column-major.
Returns
out, for chaining.
getViewMatrix()
getViewMatrix(
out):Mat4
Copies the camera's view matrix — the inverse of its world matrix — into out.
Parameters
out
A 4x4 matrix that receives the result, column-major.
Returns
out, for chaining.
onAttach()
onAttach():
void
Creates the Lite camera and parents it under the entity's node.
Returns
void
Implementation of
onDetach()
onDetach():
void
Drops the Lite camera.
Returns
void
Remarks
A Lite camera holds no GPU resource and is never added to the scene — only assigned to
scene.camera — so breaking the parent link and forgetting it is the whole teardown. The
PreRender system re-picks the main camera on the next frame and clears scene.camera when
this was the last one.
Implementation of
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
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
screenToRay()
screenToRay(
x,y,out?):Ray|null
Builds a world-space ray through a point on the canvas.
Parameters
x
number
The backing-store pixel x, from the canvas's left edge.
y
number
The backing-store pixel y, from the canvas's top edge.
out?
The ray to fill; a fresh one is allocated when omitted.
Returns
Ray | null
out, or null when the view-projection matrix is singular — a zero-sized viewport,
or a camera that is not attached.
Remarks
Coordinates are backing-store pixels — the canvas's width/height, the space
Camera.worldToScreen answers in and @ignifx/input reports <Pointer>/position in — not
CSS pixels; multiply a DOM event's offsetX/offsetY by devicePixelRatio first.
Example
const ray = camera.screenToRay(event.offsetX, event.offsetY);
const hit = ray === null ? null : world.raycastRender(ray);screenToWorldPoint()
screenToWorldPoint(
x,y,distance,out):MutableVec3|null
The world-space point a canvas pixel maps to at a given distance along the view ray.
Parameters
x
number
The backing-store pixel x, from the canvas's left edge (see Camera.screenToRay).
y
number
The backing-store pixel y, from the canvas's top edge.
distance
number
How far along the ray to travel, in metres.
out
Receives the point.
Returns
MutableVec3 | null
out, or null when no ray could be built.
viewportToWorldPoint()
viewportToWorldPoint(
u,v,distance,out):MutableVec3|null
The world-space point a normalized viewport coordinate maps to.
Parameters
u
number
The horizontal coordinate, 0 at the viewport's left edge and 1 at its right.
v
number
The vertical coordinate, 0 at the bottom edge and 1 at the top, matching
Babylon's viewport convention.
distance
number
How far along the ray to travel, in metres.
out
Receives the point.
Returns
MutableVec3 | null
out, or null when no ray could be built.
worldToScreen()
worldToScreen(
point,out):boolean
Projects a world-space point onto the canvas.
Parameters
point
The world-space point.
out
Receives the pixel position in x/y — measured from the viewport's top left —
and the clip depth in z, which is 1 at the near plane and 0 at the far plane because
Lite's projection is reverse-depth.
Returns
boolean
true when the point is in front of the camera; false when it is behind it, in which
case out holds a mirrored projection and should be ignored.
Camera2D
The 2D camera.
Remarks
orthographicSize is a half-height in metres, exactly as Unity's orthographic camera is, so
the zoom it produces is viewportHeightPx / (2 · size · PPU). With pixelPerfect on, that zoom
is snapped to a whole number (or to 1/n when the camera is pulled far out) and the camera's
position is snapped to the pixel grid at sync time — scripts keep their sub-pixel positions, so
movement stays smooth even though drawing does not.
Example
const camera = app.world.createEntity({ name: "camera" }).addComponent(Camera2D);
camera.orthographicSize = 3;
camera.pixelPerfect = true;Extends
Constructors
Constructor
new Camera2D():
Camera2D
Builds a camera with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One camera per entity.
boundsMax
boundsMax:
Vec2Like|null
The upper bound of the camera's travel, in metres, or null for no bound.
boundsMin
boundsMin:
Vec2Like|null
The lower bound of the camera's travel, in metres, or null for no bound.
deadZone
deadZone:
Vec2Like
The half-size of the rectangle the target may move inside before the camera reacts, in metres.
follow
follow:
Entity|null
The entity this camera follows, or null. Read by Camera2DFollow.
followDamping
followDamping:
number
How long the follow takes to catch up, in seconds.
followOffset
followOffset:
Vec2Like
A constant offset added to the followed entity's position, in metres.
orthographicSize
orthographicSize:
number
Half the viewport height, in metres.
pixelPerfect
pixelPerfect:
boolean
Whether zoom snaps to an integer and positions snap to the pixel grid.
priority
priority:
number
Highest wins when a world has several enabled cameras.
referenceResolution
referenceResolution:
Vec2Like
The design resolution a pixel-perfect camera fits an integer zoom to, in pixels.
schema
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
centre
Get Signature
get centre():
Vec2Like
The world point the camera is centred on, after bounds clamping and pixel-perfect snapping.
Returns
A read-only view of the centre, in metres.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
viewportSizePx
Get Signature
get viewportSizePx():
Vec2Like
The viewport the camera last measured, in pixels.
Returns
A read-only view of the size.
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
zoom
Get Signature
get zoom():
number
The zoom the camera last resolved to — Sprite2DView.zoom.
Returns
number
The zoom; 1 before the first sync.
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
screenToWorld()
screenToWorld(
x,y,out?):MutableVec2
Converts a viewport pixel into a world point.
Parameters
x
number
The viewport x, in pixels from the left edge.
y
number
The viewport y, in pixels from the top edge.
out?
The vector to write; omitting it allocates one.
Returns
out, in world metres.
Remarks
x and y are measured from the surface's top-left corner, which is what a PointerEvent
reports and what @ignifx/input's pointer position carries. The result is in metres with +Y
up. Before the first frame has synced, the camera has no viewport and the result is the
camera's own centre.
Example
const world = camera.screenToWorld(pointer.x, pointer.y);worldToScreen()
worldToScreen(
point,out?):MutableVec2
Converts a world point into a viewport pixel.
Parameters
point
The world point, in metres.
out?
The vector to write; omitting it allocates one.
Returns
out, in pixels from the surface's top-left corner.
Camera2DFollow
A damped, dead-zoned camera follow.
Example
const camera = app.world.createEntity({ name: "camera" });
const view = camera.addComponent(Camera2D);
view.follow = player;
view.deadZone = { x: 0.5, y: 0.3 };
camera.addComponent(Camera2DFollow);Extends
Constructors
Constructor
new Camera2DFollow():
Camera2DFollow
Creates a component. The engine constructs components; game code never calls new.
Returns
Inherited from
Properties
allowMultiple
staticallowMultiple:boolean
One follow per entity.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Finds the camera on this entity.
Returns
void
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
lateUpdate()
lateUpdate(
deltaTime):void
Moves the camera toward its target.
Parameters
deltaTime
number
The scaled frame delta.
Returns
void
Remarks
The damping is frame-rate independent: the camera covers the same fraction of the remaining
distance per second, not per frame, so a 30 fps machine and a 144 fps machine see the same
motion. followDamping is the time constant in seconds; 0 snaps.
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
CapsuleCollider
A capsule collider: a cylinder with hemispherical caps, standing along one axis.
Remarks
height is the total tip-to-tip height, so a capsule shorter than 2 * radius degenerates to
a sphere of that radius rather than inverting.
Extends
Constructors
Constructor
new CapsuleCollider():
CapsuleCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
direction
direction:
"x"|"y"|"z"
height
height:
number
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
radius
radius:
number
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,scale):PhysicsShape
Builds this collider's Havok shape.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
scale
The entity's lossy scale, applied to the authored dimensions.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
scale,out):void
Writes half the size of this collider's local bounding box, scale applied.
Parameters
scale
The entity's lossy scale.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
CapsuleCollider2D
A capsule collider: a rectangle with semicircular caps, standing along X or Y.
Remarks
height is the total tip-to-tip height, so a capsule shorter than 2 * radius degenerates to
a circle of that radius rather than inverting. Rapier's capsule always stands along Y, so an
x capsule is expressed by swapping the axes of the half-extents — which means an x capsule
and a rotated y capsule are the same shape.
Extends
Constructors
Constructor
new CapsuleCollider2D():
CapsuleCollider2D
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
direction
direction:
"x"|"y"
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
height
height:
number
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
radius
radius:
number
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
CharacterController
A kinematic capsule that walks, slides, and pushes (09-physics.md §2.3).
Example
class Walk extends Script implements ScriptCallbacks {
static typeId = "mygame/Walk";
fixedUpdate(dt: number): void {
const controller = this.entity.requireComponent(CharacterController);
controller.move({ x: 2 * dt, y: 0, z: 0 });
}
}Extends
Implements
Constructors
Constructor
new CharacterController():
CharacterController
Applies the schema defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One controller per entity.
center
center:
Vec3Like
height
height:
number
interpolation
interpolation:
"none"|"interpolate"
pushStrength
pushStrength:
number
radius
radius:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
skinWidth
skinWidth:
number
slopeLimit
slopeLimit:
number
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
groundNormal
Get Signature
get groundNormal():
Vec3
The averaged normal of the supporting surface.
Returns
A live view; copy it if you keep it.
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
isGrounded
Get Signature
get isGrounded():
boolean
Whether the character is standing on a walkable surface.
Returns
boolean
true when the last step's probe reported supported.
onCollided
Get Signature
get onCollided():
Signal<CharacterCollision>
Emitted once per dynamic body the character pushed during a step.
Returns
The signal, created on first access.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
supportState
Get Signature
get supportState():
"unsupported"|"sliding"|"supported"
How the character was supported at the end of the last step.
Returns
"unsupported" | "sliding" | "supported"
"unsupported", "sliding", or "supported".
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
velocity
Get Signature
get velocity():
Vec3
The controller's current velocity.
Returns
A freshly allocated vector.
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
move()
move(
displacement):void
Requests a displacement for this fixed step. Displacements accumulate until the step runs.
Parameters
displacement
The world-space displacement to attempt.
Returns
void
onAttach()
onAttach():
void
Creates the Lite controller at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Releases the Lite controller.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the capsule at the start of the next fixed step.
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
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
setHeight()
setHeight(
height,preserveFeet?):void
Changes the capsule height without losing the controller's state — the crouch primitive.
Parameters
height
number
The new total height, tip to tip.
preserveFeet?
boolean
Whether the foot position stays fixed; defaults to true.
Returns
void
setVelocity()
setVelocity(
velocity):void
Sets the controller's velocity, which is what integrate advances.
Parameters
velocity
Metres per second, world space.
Returns
void
teleport()
teleport(
position):void
Teleports the character, clearing any swept motion and the interpolation history.
Parameters
position
The new world position of the entity.
Returns
void
CharacterController2D
A kinematic character that walks, slides, climbs slopes, and steps up.
Example
class Walk extends Script implements ScriptCallbacks {
static typeId = "mygame/Walk";
fixedUpdate(dt: number): void {
const controller = this.entity.requireComponent(CharacterController2D);
controller.move({ x: 4 * dt, y: -9.81 * dt });
}
}Extends
Implements
Constructors
Constructor
new CharacterController2D():
CharacterController2D
Applies the schema defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One controller per entity.
height
height:
number
interpolation
interpolation:
"none"|"interpolate"
offset
offset:
Vec2Like
onOneWayPlatforms
onOneWayPlatforms:
boolean
pushBodies
pushBodies:
boolean
radius
radius:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
shape
shape:
"box"|"capsule"
skinWidth
skinWidth:
number
slopeLimit
slopeLimit:
number
snapToGround
snapToGround:
number
stepOffset
stepOffset:
number
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
groundNormal
Get Signature
get groundNormal():
Vec2
The most upward-facing normal of the obstacles the last move touched.
Returns
A live view; copy it if you keep it.
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
isGrounded
Get Signature
get isGrounded():
boolean
Whether the character ended the last step on walkable ground.
Returns
boolean
Rapier's computedGrounded from the last move.
onCollided
Get Signature
get onCollided():
Signal<CharacterCollision2D>
Emitted once per obstacle the character hit during a step.
Returns
The signal, created on first access.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
velocity
Get Signature
get velocity():
Vec2
How fast the character actually moved over the last fixed step, after sliding and blocking.
Returns
A freshly allocated vector in metres per second.
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
move()
move(
displacement):void
Requests a displacement for this fixed step. Displacements accumulate until the step runs.
Parameters
displacement
The world-space displacement to attempt, in metres.
Returns
void
onAttach()
onAttach():
void
Creates the Rapier controller at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Releases the Rapier controller and its collider.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the capsule or box at the start of the next fixed step.
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
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
teleport()
teleport(
position):void
Teleports the character, clearing any pending motion and the interpolation history.
Parameters
position
The new world position of the entity, in metres.
Returns
void
CircleCollider2D
A circle collider. Non-uniform scale is not representable as a circle, so the larger scale axis wins — the same rule Unity applies.
Extends
Constructors
Constructor
new CircleCollider2D():
CircleCollider2D
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
radius
radius:
number
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
abstract Collider
The base class of every collider. It is never registered on its own; entity.getComponents and
world.components accept it because the concrete colliders extend it.
Extends
Extended by
Implements
Constructors
Constructor
new Collider():
Collider
Applies the shared defaults. A concrete collider calls super() and then applies its own.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
abstract Collider2D
The base class of every 2D collider.
Extends
Extended by
Implements
Constructors
Constructor
new Collider2D():
Collider2D
Applies the shared defaults. A concrete collider calls super() and then applies its own.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Color
An RGBA colour whose components are linear and normally in 0-1 (values above 1 are allowed
and mean HDR intensity). Lighting maths only works in linear space, which is why this is the
space ignifx stores; scene files and hex strings are sRGB, and
Color.fromHex/Color.fromSrgb are the doors between the two
(docs/architecture/06-serialization-and-scene-format.md section 3).
Every method says which space it works in. The rule of thumb: if it takes or returns a hex string
or has Srgb in its name, it is sRGB; everything else is linear.
Example
const tint = Color.fromHex("#ff8800") ?? new Color(1, 1, 1, 1); // parsed as sRGB, stored linear
tint.scaleRgb(2); // twice as bright, same alpha
tint.toHex(); // back to sRGB: "#ffbe00"Constructors
Constructor
new Color(
r?,g?,b?,a?):Color
Creates a colour from linear components.
Parameters
r?
number
The linear red component. Defaults to 0.
g?
number
The linear green component. Defaults to 0.
b?
number
The linear blue component. Defaults to 0.
a?
number
The alpha component. Defaults to 1 (opaque).
Returns
Properties
a
a:
number
The alpha component in 0-1. Alpha is always linear, never gamma encoded.
b
b:
number
The linear blue component.
g
g:
number
The linear green component.
r
r:
number
The linear red component.
Methods
black()
staticblack():Color
Opaque black.
Returns
A new linear (0, 0, 0, 1). Allocates.
clone()
clone():
Color
Copies this colour into a new one.
Returns
A new colour. Allocates.
copyFrom()
copyFrom(
c):this
Copies every component from another colour.
Parameters
c
The colour to read.
Returns
this
This colour.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two colours component by component, with a tolerance.
Parameters
a
The first colour.
b
The second colour.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
c,epsilon?):boolean
Compares this colour with another, component by component, with a tolerance.
Parameters
c
The colour to compare against.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
from()
staticfrom(c):Color
Copies any colour-shaped value into a Color.
Parameters
c
The linear colour to copy.
Returns
A new colour. Allocates.
fromHex()
staticfromHex(hex):Color|null
Parses an sRGB hex string into a linear colour.
Parameters
hex
string
#rrggbb or #rrggbbaa, with or without the leading #, in either case.
Returns
Color | null
A new colour, or null when the string is not a hex colour. Colours arrive from files
and user input, so a bad one is expected absence rather than API misuse (coding standards
section 5.5): the caller decides whether to substitute a default or raise a load error.
Allocates.
Example
const tint = Color.fromHex("#ff8800aa") ?? Color.white();fromHexToRef()
staticfromHexToRef(hex,out):boolean
Parses an sRGB hex string into out as linear components.
Parameters
hex
string
#rrggbb or #rrggbbaa, with or without the leading #, in either case.
out
The colour to write; left untouched when parsing fails.
Returns
boolean
true when hex was a valid hex colour.
fromSrgb()
staticfromSrgb(r,g,b,a?):Color
Builds a colour from sRGB components, converting RGB to linear and taking alpha as-is.
Parameters
r
number
The sRGB red component, 0-1.
g
number
The sRGB green component, 0-1.
b
number
The sRGB blue component, 0-1.
a?
number
The alpha component, 0-1. Defaults to 1.
Returns
A new colour holding linear components. Allocates.
fromSrgbToRef()
staticfromSrgbToRef<TOut>(r,g,b,a,out):TOut
Writes a colour built from sRGB components into out.
Type Parameters
TOut
TOut extends Color
Parameters
r
number
The sRGB red component, 0-1.
g
number
The sRGB green component, 0-1.
b
number
The sRGB blue component, 0-1.
a
number
The alpha component, 0-1.
out
TOut
The colour to write; holds linear components afterwards.
Returns
TOut
out.
lerp()
lerp(
target,t):this
Moves this colour towards a target, in linear space (which is where blending belongs; lerping sRGB values darkens midpoints).
Parameters
target
The colour reached at t === 1.
t
number
The interpolant; not clamped.
Returns
this
This colour.
lerpToRef()
staticlerpToRef<TOut>(a,b,t,out):TOut
Writes the linear-space interpolation of a and b into out.
Type Parameters
TOut
TOut extends Color
Parameters
a
The colour written at t === 0.
b
The colour written at t === 1.
t
number
The interpolant; not clamped.
out
TOut
The colour to write; may alias a or b.
Returns
TOut
out.
linearToSrgb()
staticlinearToSrgb(channel):number
Converts one linear channel to sRGB, the inverse of Color.srgbToLinear.
Parameters
channel
number
The linear channel value; clamped into 0-1, so HDR intensity is lost.
Returns
number
The sRGB value.
multiply()
multiply(
c):this
Multiplies this colour by another, component by component including alpha — the usual way a tint is applied.
Parameters
c
The colour to multiply by.
Returns
this
This colour.
multiplyToRef()
staticmultiplyToRef<TOut>(a,b,out):TOut
Writes the component-wise product a * b into out, in linear space.
Type Parameters
TOut
TOut extends Color
Parameters
a
The first colour.
b
The second colour.
out
TOut
The colour to write; may alias a or b.
Returns
TOut
out.
scaleRgb()
scaleRgb(
factor):this
Scales the linear RGB components, leaving alpha alone. This is what "brighter" means: alpha is coverage, not colour.
Parameters
factor
number
The intensity factor.
Returns
this
This colour.
scaleRgbToRef()
staticscaleRgbToRef<TOut>(c,factor,out):TOut
Writes c with its RGB scaled and its alpha untouched into out.
Type Parameters
TOut
TOut extends Color
Parameters
c
The colour to scale.
factor
number
The intensity factor.
out
TOut
The colour to write; may alias c.
Returns
TOut
out.
set()
set(
r,g,b,a):this
Assigns every component at once, in linear space.
Parameters
r
number
The new linear red component.
g
number
The new linear green component.
b
number
The new linear blue component.
a
number
The new alpha component.
Returns
this
This colour.
srgbToLinear()
staticsrgbToLinear(channel):number
Converts one sRGB channel to linear, using the IEC 61966-2-1 curve Babylon Lite uses
(lib/math/color.js).
Parameters
channel
number
The sRGB channel value; clamped into 0-1.
Returns
number
The linear value.
toArray()
toArray(
out,offset?):Float32Array
Writes the linear components into a Float32Array, the form a shader wants. The output
comes first to mirror Babylon Lite's toArray helpers.
Parameters
out
Float32Array
The array to write into.
offset?
number
The index of the red component. Defaults to 0.
Returns
Float32Array
out.
toHex()
toHex():
string
Encodes this colour as an sRGB hex string.
Returns
string
#rrggbb for an opaque colour, #rrggbbaa when alpha is below 1. Allocates a
string.
Example
new Color(1, 1, 1, 1).toHex(); // "#ffffff"toSrgbToRef()
toSrgbToRef<
TOut>(out):TOut
Writes this colour's sRGB-encoded components into out, for display, pickers and files.
Components are clamped into 0-1 by the encoding curve.
Type Parameters
TOut
TOut extends Color
Parameters
out
TOut
The colour to write; may be this colour. Its fields hold sRGB values afterwards, not linear ones.
Returns
TOut
out.
transparent()
statictransparent():Color
Fully transparent black.
Returns
A new linear (0, 0, 0, 0). Allocates.
white()
staticwhite():Color
Opaque white.
Returns
A new linear (1, 1, 1, 1). Allocates.
abstract Component
Typed data and behaviour attached to an entity
(docs/architecture/03-scripting-and-components.md §1). Engine-owned components
(MeshRenderer, Rigidbody, AudioSource) are plain Components driven by systems; game
behaviour extends Script, which adds the frame lifecycle.
Remarks
A component class must have a no-argument constructor: the engine constructs it, then assigns
entity, uid, and handle, then applies schema defaults and the init object, then calls
onAttach. Reading this.entity from a constructor therefore throws IGX-0206; cache lookups
in onAttach or awake instead.
Where the statics are declared. typeId, schema, requires, and allowMultiple are not
members of this class. Declaring them here would make every static typeId = "mygame/Mover" an
override and force the override keyword on it under noImplicitOverride (coding standards §3)
— the same reasoning that keeps the callbacks on ComponentHooks. The shape lives on
ComponentStatics instead, and ComponentRegistry reads it once per class and supplies
the defaults (allowMultiple is true when the class declares nothing).
Example
class Health extends Component.define({ maximum: f32(100) }) {
static typeId = "mygame/Health";
current = 0;
onAttach(): void {
this.current = this.maximum;
}
}Extended by
CameraEnvironmentLightMeshRendererModelPostProcessStackScriptTransformPlayerInputCharacterControllerColliderRigidbodyCharacterController2DCollider2DRigidbody2DCamera2DParallaxLayerSpriteAnimatorSpriteLayerEffectSpriteRendererTilemapTilemapRendererTextComponentWorldAnchorAnimatorBillboardLodGroupNavMeshAgentNavMeshObstacleNavMeshSurface
Implements
Constructors
Constructor
new Component():
Component
Creates a component. The engine constructs components; game code never calls new.
Returns
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The 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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The 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.
Whether the owner has already been destroyed.
Implementation of
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.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Implementation of
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Methods
define()
staticdefine<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
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
class Spinner extends Component.define({
degreesPerSecond: f32(90, { min: -360, max: 360 }),
axis: vec3({ x: 0, y: 1, z: 0 }),
}) {
static typeId = "mygame/Spinner";
}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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
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
The component class.
Returns
T
The first match in attach order.
Throws
IgnifxError with code IGX-0201 when the entity has no such component.
ComponentRegistry
The component-class table of one app. There is one per App, never a module-level one
(CONSTITUTION.md §3.5, §3.6): two apps in one test process must not see each other's types.
Example
const registry = new ComponentRegistry();
registry.register(Mover);
registry.get("mygame/Mover"); // MoverConstructors
Constructor
new ComponentRegistry():
ComponentRegistry
Returns
Accessors
size
Get Signature
get size():
number
How many classes the registry has described, registered explicitly or not.
Returns
number
The class count.
Methods
describe()
describe(
type):ComponentClassInfo
Describes a class, computing and caching its info on first sight. Explicit registration is only
needed for serializable components; a script added from code is described the first time it
is attached (docs/architecture/03-scripting-and-components.md §4).
Parameters
type
The component class.
Returns
The cached class info.
get()
get(
typeId):ComponentType<Component> |null
Looks a class up by its registered id.
Parameters
typeId
string
The namespaced id.
Returns
ComponentType<Component> | null
The class, or null when nothing is registered under the id.
implementsCallback()
implementsCallback(
type,kind):boolean
Reports whether a component class implements a script callback, from the bit mask the registry
computed when it first described the class. Extension authors use it to decide once per class
what a per-frame path would otherwise have to rediscover
(docs/architecture/04-extensions.md §3).
Parameters
type
The component class. A plain (non-Script) class always answers false.
kind
The callback ordinal.
Returns
boolean
true when the class implements the callback.
Example
registry.implementsCallback(Explode, ScriptCallbackKind.onCollisionEnter); // trueisRegistered()
isRegistered(
type):boolean
Reports whether a class was registered explicitly.
Parameters
type
The component class.
Returns
boolean
true when the class was registered under a type id.
register()
register(
type,typeId?):ComponentClassInfo
Registers a component class so that scenes using it can be loaded and saved.
Parameters
type
The component class.
typeId?
string
An explicit id, when the class does not declare one.
Returns
What the registry worked out about the class.
Throws
IgnifxError with code IGX-0203 when the id is already registered by another class, or
when the id is not <namespace>/<Name>.
registerAll()
registerAll(
types):void
Registers several component classes.
Parameters
types
readonly ConcreteComponentType<Component>[]
The component classes.
Returns
void
registrations()
registrations(): readonly readonly [
string,ComponentType<Component>][]
Every class registered under a type id, paired with that id, in registration order.
Returns
readonly readonly [string, ComponentType<Component>][]
A freshly allocated array of [typeId, class] pairs.
Remarks
The scene-file JSON Schema generator
(docs/architecture/06-serialization-and-scene-format.md §8) walks it to narrow
components[].props per typeId. Classes described but never registered are not listed:
only a registered class can appear in a file.
replace()
replace(
type):ComponentReplacement
Swaps the class registered under a typeId for a replacement, for script hot reload
(docs/architecture/15-devtools-and-diagnostics.md §5). The previous class's cached info is
dropped and the replacement inherits its classIndex, so per-class bookkeeping indexed by that
number stays valid across a reload.
Parameters
type
The replacement class. It must declare the typeId it replaces.
Returns
The freshly built info for the replacement, and the class it replaced.
Remarks
Additive and hot-reload-only: nothing on the normal path replaces a registration, and
register still refuses to bind one id to two classes (IGX-0203).
Throws
IgnifxError with code IGX-0204 when the replacement declares no typeId.
Example
const { previous } = registry.replace(NextMover);requireTypeId()
requireTypeId(
type):string
The id a component must carry to be written to a file.
Parameters
type
The component class.
Returns
string
The registered id.
Throws
IgnifxError with code IGX-0204 when the class declares no typeId.
ControlSchemes
The scheme table, with the lookup the frame's device attribution goes through.
Constructors
Constructor
new ControlSchemes():
ControlSchemes
Returns
Accessors
all
Get Signature
get all(): readonly
ControlSchemeDefinition[]
The declared schemes, in document order.
Returns
readonly ControlSchemeDefinition[]
The schemes.
Methods
forDevice()
forDevice(
device):string
Finds the scheme a device family belongs to.
Parameters
device
The device family that produced input.
Returns
string
The scheme name, or "" when no scheme lists the family.
has()
has(
name):boolean
Whether a scheme with that name is declared.
Parameters
name
string
The scheme name.
Returns
boolean
true when the table declares it.
Cursor
The cursor controller, reached as app.input.cursor.
Example
app.input.cursor.visible = false;Constructors
Constructor
new Cursor():
Cursor
Returns
Accessors
visible
Get Signature
get visible():
boolean
Whether the mouse cursor is drawn over the canvas. Assigning false applies cursor: none to
the canvas; a headless app records the value and does nothing else.
Returns
boolean
true unless the cursor has been hidden.
Set Signature
set visible(
value):void
Parameters
value
boolean
Returns
void
CylinderCollider
A cylinder collider standing along Y.
Extends
Constructors
Constructor
new CylinderCollider():
CylinderCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
height
height:
number
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
radius
radius:
number
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,scale):PhysicsShape
Builds this collider's Havok shape.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
scale
The entity's lossy scale, applied to the authored dimensions.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
scale,out):void
Writes half the size of this collider's local bounding box, scale applied.
Parameters
scale
The entity's lossy scale.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
DevtoolsService
The devtools overlay's controller, reached as app.devtools.
Example
app.devtools.open();
app.devtools.panel("inspector").show();
app.devtools.select(app.world.findByName("Player"));Accessors
isOpen
Get Signature
get isOpen():
boolean
Whether the overlay is up.
Returns
boolean
true between DevtoolsService.open and DevtoolsService.close.
isSceneReloadDelegated
Get Signature
get isSceneReloadDelegated():
boolean
Whether app.hotReload is already re-instantiating scene instances, in which case
DevtoolsService.reloadScenes deliberately does nothing rather than reloading twice.
Returns
boolean
true when core's own hotReload.reloadScenes is on.
onClosed
Get Signature
get onClosed():
SignalLike
Emitted after the overlay closed.
Returns
The signal.
onOpened
Get Signature
get onOpened():
SignalLike
Emitted after the overlay opened.
Returns
The signal.
onSelectionChanged
Get Signature
get onSelectionChanged():
SignalLike<Entity|null>
Emitted whenever DevtoolsService.select changes the selection.
Returns
SignalLike<Entity | null>
The signal.
panels
Get Signature
get panels(): readonly
DevtoolsPanelHandle[]
Every panel this build carries, in tab order.
Returns
readonly DevtoolsPanelHandle[]
The handles.
reloadScenes
Get Signature
get reloadScenes():
boolean
Whether a scene file that changes on disk re-instantiates its live scene instances
(docs/architecture/15-devtools-and-diagnostics.md §5).
Returns
boolean
true while scene reload is on.
Set Signature
set reloadScenes(
value):void
Parameters
value
boolean
Returns
void
selected
Get Signature
get selected():
Entity|null
The entity the Inspector panel is showing.
Returns
Entity | null
The entity, or null.
Methods
close()
close():
void
Closes the overlay, disposing its DOM and every subscription it installed.
Returns
void
open()
open():
void
Opens the overlay. On a headless app — or on any app with no DOM canvas — it is a documented
no-op with one debug line (docs/architecture/07-rendering.md §6).
Returns
void
panel()
panel(
name):DevtoolsPanelHandle
Returns a handle to one panel.
Parameters
name
string
The panel name, one of DEVTOOLS_PANEL_NAMES.
Returns
The handle.
Throws
IgnifxError with code IGX-1552 when no panel is registered under the name.
select()
select(
entity):void
Selects an entity for the Inspector panel.
Parameters
entity
Entity | null
The entity, or null to clear the selection.
Returns
void
toggle()
toggle():
void
Opens the overlay when it is closed and closes it when it is open.
Returns
void
Diagnostics
The frame-sampled counters reached as app.diagnostics
(docs/architecture/15-devtools-and-diagnostics.md §3).
Remarks
Nothing on the per-frame path allocates: Diagnostics.frame is one long-lived object the loop writes in place, the history is a preallocated structure-of-arrays ring buffer, and counters are typed arrays addressed by index (coding standards §7).
Example
const diagnostics = new Diagnostics({ development: true });
diagnostics.beginFrame(16.7);
diagnostics.frame.fixedSteps = 1;
diagnostics.endFrame();
diagnostics.readFrame(0, sample).fixedSteps; // 1Constructors
Constructor
new Diagnostics(
options?):Diagnostics
Creates the diagnostics service of one app.
Parameters
options?
Development flag, clock, and history length.
Returns
Properties
frame
readonlyframe:FrameSample
The frame being measured. The frame loop writes its counters in place; everything else reads them. Values are reset by Diagnostics.beginFrame.
historyCapacity
readonlyhistoryCapacity:number
How many frames the history can hold.
isDevelopment
readonlyisDevelopment:boolean
Whether per-phase timings and User Timing entries are being recorded.
Accessors
groups
Get Signature
get groups(): readonly
DiagnosticsGroup[]
Every registered counter group, in registration order.
Returns
readonly DiagnosticsGroup[]
The live list of groups.
historyLength
Get Signature
get historyLength():
number
How many frames of history are currently recorded, never more than the capacity.
Returns
number
The number of retained frames.
Methods
beginFrame()
beginFrame(
rawDeltaMs):void
Starts a new frame: zeroes Diagnostics.frame, assigns the next frame number, and records the raw delta.
Parameters
rawDeltaMs
number
The wall-clock delta handed to the loop, before clamping, in milliseconds.
Returns
void
clearHistory()
clearHistory():
void
Drops every recorded frame and resets the frame counter.
Returns
void
endFrame()
endFrame():
void
Copies Diagnostics.frame into the history ring buffer, overwriting the oldest entry.
Returns
void
group()
group(
name):DiagnosticsGroup|null
Looks a counter group up by name.
Parameters
name
string
The group name.
Returns
DiagnosticsGroup | null
The group, or null when no subsystem registered it — an absent group is expected
absence, not a failure (coding standards §5.5).
profile()
profile(
name):ProfileScope
Opens a timing scope. In development builds it writes a performance.mark/measure pair that
shows up in browser profilers; outside development it is free
(docs/architecture/15-devtools-and-diagnostics.md §6).
Parameters
name
string
The scope name, shown in the profiler.
Returns
A scope to end(); scopes must be ended in the order they were opened.
Example
const scope = app.diagnostics.profile("physics.step");
stepPhysics();
scope.end();readFrame()
readFrame(
offset,out):FrameSample
Reads a recorded frame into a caller-owned sample, so plotting the whole history allocates nothing.
Parameters
offset
number
0 is the most recently ended frame, historyLength - 1 the oldest retained.
out
The sample to fill; build it with createFrameSample().
Returns
The same out sample, zeroed when the offset is out of range.
Example
const sample = createFrameSample();
diagnostics.readFrame(0, sample); // the frame that just endedregisterGroup()
registerGroup(
name,counterNames):DiagnosticsGroup
Registers a subsystem's counter group.
Parameters
name
string
The group name, unique within this app.
counterNames
readonly string[]
The counter names, in the order their indices are assigned.
Returns
The group, whose indices are resolved once with DiagnosticsGroup.index.
Throws
IgnifxError with code IGX-1503 when the name is already registered.
Dialog
A modal panel with a title, a message, and buttons.
Constructors
Constructor
new Dialog(
host,options?):Dialog
Builds the dialog and mounts it hidden.
Parameters
host
The overlay host, normally app.ui.
options?
The title, the message, the buttons, and the layer.
Returns
Accessors
element
Get Signature
get element():
HTMLDivElement|null
The dialog's outermost element, so a template can restyle it or mount more into it.
Returns
HTMLDivElement | null
The element, or null when the app has no DOM overlay.
isVisible
Get Signature
get isVisible():
boolean
Whether the dialog is shown.
Returns
boolean
true while it is on screen.
onChosen
Get Signature
get onChosen():
SignalLike<string>
Emitted with a button's id when it is pressed. The dialog does not hide itself; the game
decides, because "Cancel" and "Delete everything" want different follow-ups.
Returns
SignalLike<string>
The signal.
onDismissed
Get Signature
get onDismissed():
SignalLike
Emitted after Dialog.hide, whatever caused it.
Returns
The signal.
Methods
dispose()
dispose():
void
Removes the dialog and unsubscribes.
Returns
void
hide()
hide():
void
Hides the dialog and emits Dialog.onDismissed.
Returns
void
setMessage()
setMessage(
text):void
Replaces the body text, if the dialog was built with one.
Parameters
text
string
The new message.
Returns
void
setTitle()
setTitle(
text):void
Replaces the heading, if the dialog was built with one.
Parameters
text
string
The new heading.
Returns
void
show()
show():
void
Shows the dialog.
Returns
void
EdgeCollider2D
An open chain of line segments — a platformer's ground contour.
Extends
Constructors
Constructor
new EdgeCollider2D():
EdgeCollider2D
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
points
points:
Vec2Like[]
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
ElectronStorageBackend
app.storage's desktop backend: the preload bridge, wearing core's StorageBackend interface.
Example
const backend = new ElectronStorageBackend(window.ignifxHost);
await backend.set("saves", "slot1", { kind: "json", json: '{"level":3}' });Implements
Constructors
Constructor
new ElectronStorageBackend(
host):ElectronStorageBackend
Builds a backend over a bridge.
Parameters
host
The validated window.ignifxHost.
Returns
Properties
name
readonlyname:string
The identifier that appears in error context.
Implementation of
Methods
clear()
clear(
namespace):Promise<void>
Removes every value of one namespace.
Parameters
namespace
string
The namespace path.
Returns
Promise<void>
A promise that settles once the namespace is empty.
Implementation of
delete()
delete(
namespace,key):Promise<void>
Removes one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside it.
Returns
Promise<void>
A promise that settles once the value is gone.
Implementation of
get()
get(
namespace,key):Promise<StoredValue|null>
Reads one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside it.
Returns
Promise<StoredValue | null>
The stored value, or null when the namespace has no such key.
Implementation of
keys()
keys(
namespace,prefix?):Promise<readonlystring[]>
Lists the keys of one namespace.
Parameters
namespace
string
The namespace path.
prefix?
string
When given, only keys starting with it are returned.
Returns
Promise<readonly string[]>
The matching keys, sorted ascending; [] for an unknown namespace.
Implementation of
set()
set(
namespace,key,value):Promise<void>
Writes one value, replacing whatever was there.
Parameters
namespace
string
The namespace path.
key
string
The key inside it.
value
The JSON text or the octets to persist.
Returns
Promise<void>
A promise that settles once the value is durable.
Implementation of
Entity
A node of the scene tree (docs/architecture/02-scene-graph.md §4). Every entity has a stable
id, a name, tags, a layer, an active flag, an ordered list of components, and exactly one
Transform wrapping its Babylon Lite node.
Remarks
Entities are created by the world, never with new: world.createEntity() allocates the Lite
node, the handle, and the transform together. Destroying one queues its whole subtree for the
current frame's destroy flush; it reports isDestroyed === true immediately and throws
IGX-0101 on any further structural change (addComponent, removeComponent, setParent,
active, layer, name, isStatic, tags.add/delete). Transform writes are deliberately
not* guarded: they are the hottest path in the engine and a write to a doomed node is harmless.
Example
const player = world.createEntity("Player", { position: { x: 0, y: 1, z: 0 } });
player.layer = world.layers.indexOf("Player");
player.tags.add("player");
const mover = player.addComponent(Mover, { speed: 8 });
const gun = world.createEntity("Gun", { parent: player });Accessors
active
Get Signature
get active():
boolean
The entity's own active flag. Setting it to false disables every component in the subtree
(onDisable), hides the Lite subtree, and pauses their coroutines; setting it back reverses
that with onEnable, and start still runs only once ever
(docs/architecture/01-lifecycle-and-time.md §6).
Returns
boolean
The own flag.
Set Signature
set active(
value):void
Parameters
value
boolean
Returns
void
activeInHierarchy
Get Signature
get activeInHierarchy():
boolean
active and every ancestor's active. Materialised on change, never walked per read.
Returns
boolean
true when the entity and every ancestor are active.
children
Get Signature
get children(): readonly
Entity[]
The children, in creation order. The array is live; treat it as read-only.
Returns
readonly Entity[]
The live child list.
components
Get Signature
get components(): readonly
Component[]
The components, in attach order. The transform is always first.
Returns
readonly Component[]
The live component list.
handle
Get Signature
get handle():
EntityHandle
The dense runtime handle; world.getEntityByHandle stops resolving it after destruction.
Returns
The 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 entity has been queued for destruction.
isStatic
Get Signature
get isStatic():
boolean
The immovability hint: true promises that the transform will not change after awake, which
lets the 2D batcher, physics, and navmesh treat the entity as static.
Returns
boolean
true when the entity is marked static.
Set Signature
set isStatic(
value):void
Parameters
value
boolean
Returns
void
layer
Get Signature
get layer():
number
The layer slot, 0..31 (docs/architecture/02-scene-graph.md §7). Layers drive physics
collision matrices and raycast masks. Files store the layer name, so reordering the project
list is safe.
Returns
number
The slot index.
Set Signature
set layer(
value):void
Parameters
value
number
Returns
void
name
Get Signature
get name():
string
The display name. Not unique, and never used for lookup by the engine
(docs/architecture/02-scene-graph.md §4).
Returns
string
The name.
Set Signature
set name(
value):void
Parameters
value
string
Returns
void
onActiveChanged
Get Signature
get onActiveChanged():
Signal<boolean>
Emitted with the new value when the entity's own active flag changes. An ancestor's change
does not emit it; read activeInHierarchy for the effective state.
Returns
Signal<boolean>
The signal, created on first access.
onChildAdded
Get Signature
Emitted after a child is added, whether by creation or by reparenting.
Returns
The signal, created on first access.
onChildRemoved
Get Signature
Emitted after a child is removed.
Returns
The signal, created on first access.
onComponentAdded
Get Signature
Emitted with each component attached to this entity, synchronously at the end of
addComponent, after the component's onAttach has run
(docs/architecture/02-scene-graph.md §8). Extensions that key work off an entity's component
set — the physics extension recomputing Rigidbody.collisionEvents, say — listen here rather
than polling entity.components. Costs nothing until something connects.
Returns
The signal, created on first access.
onComponentRemoved
Get Signature
Emitted with each component the destroy flush removes from this entity, after it has left
entity.components and before its onDetach runs. Removal is deferred, so this fires in the
destroy flush rather than inside removeComponent.
Returns
The signal, created on first access.
onDestroyed
Get Signature
Emitted in the destroy flush, after the entity's components have run onDestroy. Signal's
{ owner } option uses it to detach handlers automatically.
Returns
The signal, created on first access.
onParentChanged
Get Signature
Emitted with the new parent after this entity is reparented.
Returns
The signal, created on first access.
parent
Get Signature
get parent():
Entity|null
The parent entity, or null when the entity is a root of its scene.
Returns
Entity | null
The parent, or null.
prefab
Get Signature
get prefab():
EntityPrefabLink|null
The prefab link for an entity a scene file's instance entry produced
(docs/architecture/02-scene-graph.md §6). It is set on the instance root and on every entity
the instanced scene contributed, so tooling can show where an object came from.
Remarks
The engine keeps no live link back to the prefab after load: editing the instanced scene does
not update loaded instances, and "apply changes to prefab" is editor work, post-1.0. The link
exists so that saving re-emits the subtree as an instance entry with recomputed overrides
(06-serialization-and-scene-format.md §5) rather than as plain entities.
Example
const link = enemy.prefab;
if (link !== null && link.instanceRoot === enemy) {
app.log.info(`${enemy.name} is the root of an instance of ${link.address}`);
}Returns
EntityPrefabLink | null
The link, or null for an entity the scene declared itself or code created.
scene
Get Signature
get scene():
SceneInstance
The scene instance the entity belongs to.
Returns
The owning scene instance.
tags
Get Signature
get tags():
TagSet
The free-form tags the world indexes for world.findByTag.
Returns
The tag set.
transform
Get Signature
get transform():
Transform
The entity's transform. Every entity has one; it can be neither removed nor disabled.
Returns
The transform.
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this entity.
Returns
string
The identifier.
world
Get Signature
get world():
World
The world that owns the entity.
Returns
The world.
Methods
addComponent()
addComponent<
T>(type,init?):T
Attaches a component.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class.
init?
Initial values for the class's schema fields.
Returns
T
The attached component.
Remarks
The engine constructs the class with no arguments, assigns its identity, applies schema
defaults then init, calls onAttach, and finally runs the enable transition — so awake
runs in the next lifecycle flush, or immediately and nested when addComponent is called from
inside a callback (docs/architecture/01-lifecycle-and-time.md §4). Everything a class lists in
static requires is added first if it is missing.
Throws
IgnifxError with code IGX-0202 when the class does not allow multiple instances and
the entity already has one, IGX-0605/IGX-0606/IGX-0607 when init does not match the
schema, and IGX-0101 when the entity has been destroyed.
destroy()
destroy():
void
Queues this entity and its whole subtree for the current frame's destroy flush. isDestroyed
becomes true immediately; onDisable and onDestroy run in the flush, children before
parents (docs/architecture/01-lifecycle-and-time.md §6). Calling it twice is a no-op.
Returns
void
destroyImmediate()
destroyImmediate():
void
Runs the destroy flush for this entity right now, rather than at the end of the frame. It exists for tooling and tests.
Returns
void
Throws
IgnifxError with code IGX-0102 when called from inside a lifecycle callback, where
destroying an object the engine is still iterating would be unsound; use destroy() there.
find()
find(
path):Entity|null
Resolves a path relative to this entity — "Body/Arm.L", "../Sibling", "/Root/Child".
Parameters
path
string
The path. A leading / resolves from the roots of this entity's scene instance;
.. is the parent and . is this entity, as whole segments only, so a name may contain dots.
Returns
Entity | null
The entity, or null when the path resolves to nothing.
Remarks
Deliberately fragile, and allowed only in tests, examples, and tools: the
ignifx/no-entity-find-in-src rule flags it anywhere else. Use entityRef/componentRef
fields or requireComponent to link objects (docs/architecture/02-scene-graph.md §4).
findChild()
findChild(
predicate,deep?):Entity|null
Finds a descendant satisfying a predicate.
Parameters
predicate
(entity) => boolean
Called with each candidate; the first true wins.
deep?
boolean
true (the default) searches the whole subtree depth-first; false searches
direct children only.
Returns
Entity | null
The first match, or null.
getComponent()
getComponent<
T>(type):T|null
The first component matching a class, by identity or inheritance — getComponent(Script)
returns the first script.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class, abstract or concrete.
Returns
T | null
The first match in attach order, or null. Cost is linear in the entity's component
count, so cache the result in awake.
getComponentInChildren()
getComponentInChildren<
T>(type,includeInactive?):T|null
The first matching component on this entity or anywhere below it, depth-first.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class.
includeInactive?
boolean
false (the default) skips entities that are inactive in the
hierarchy.
Returns
T | null
The first match, or null.
getComponentInParent()
getComponentInParent<
T>(type):T|null
The first matching component on this entity or any ancestor.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class.
Returns
T | null
The first match walking up from this entity, or null.
getComponents()
getComponents<
T>(type):T[]
Every component matching a class, by identity or inheritance.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class.
Returns
T[]
A freshly allocated array in attach order; empty when there is no match.
getComponentsInChildren()
getComponentsInChildren<
T>(type,includeInactive?):T[]
Every matching component on this entity and everything below it, depth-first.
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class.
includeInactive?
boolean
false (the default) skips entities that are inactive in the
hierarchy.
Returns
T[]
A freshly allocated array.
hasComponent()
hasComponent(
type):boolean
Reports whether the entity carries a component of a class.
Parameters
type
The component class.
Returns
boolean
true when at least one matches.
isDescendantOf()
isDescendantOf(
other):boolean
Reports whether this entity is anywhere below another in the tree.
Parameters
other
The candidate ancestor.
Returns
boolean
true when other is a strict ancestor of this entity.
removeComponent()
removeComponent(
component):void
Queues one component for destruction. It stays usable until the destroy flush.
Parameters
component
The component to remove; it must be attached to this entity.
Returns
void
Throws
IgnifxError with code IGX-0205 when the component is the entity's transform.
requireComponent()
requireComponent<
T>(type):T
The first component matching a class, 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.
Parameters
type
The component class.
Returns
T
The first match in attach order.
Throws
IgnifxError with code IGX-0201 when the entity has no such component.
root()
root():
Entity
The topmost ancestor.
Returns
The root of this entity's branch, which is this entity when it has no parent.
setParent()
setParent(
parent,options?):void
Moves the entity under a new parent, or to the root of its scene.
Parameters
parent
Entity | null
The new parent, or null to detach to the scene root.
options?
How the entity's transform is treated across the move:
worldPositionStays is true by default and keeps the world transform, while false keeps
the local values.
Returns
void
Throws
IgnifxError with code IGX-0306 when the new parent is inside this entity's own
subtree, and IGX-0101 when either entity has been destroyed.
Example
gun.setParent(hand); // snaps to the hand, keeping world pose
gun.setParent(hand, { worldPositionStays: false }); // keeps its local offset insteadEnvironment
The world's lighting environment (docs/architecture/07-rendering.md §2.5).
Example
const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
world.createEntity("Environment").addComponent(Environment, {
environment: studio.retain(),
imageProcessing: { exposure: 1.2, contrast: 1, toneMapping: "aces" },
});Extends
Implements
Constructors
Constructor
new Environment():
Environment
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One per entity, and effectively one per world: the fields are all scene state.
blur
blur:
number
clearColor
clearColor:
ColorLike
environment
environment:
AssetHandle<EnvironmentAsset> |null
fog
imageProcessing
imageProcessing:
ImageProcessingSettings
rotation
rotation:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
skybox
skybox:
object
enabled
enabled:
boolean
size
size:
number
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
installed
Get Signature
get installed():
EnvironmentAsset|null
The environment asset this component installed, once it has loaded.
Returns
EnvironmentAsset | null
The asset, or null when none is loaded.
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Records that the component exists; the scene is written on the first sync.
Returns
void
Implementation of
onDetach()
onDetach():
void
Leaves the scene as it is.
Returns
void
Remarks
Lite offers no "unload environment": loadEnvironment installs textures and a skybox and has
no inverse. Rather than pretend otherwise, removing an Environment leaves what it installed
in place until another one replaces it — which is also what "the most recently enabled wins"
implies. The PreRender system re-picks the winner on the next frame.
Implementation of
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
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
EnvironmentAsset
A loaded image-based lighting environment (docs/architecture/07-rendering.md §2.5).
Example
const studio = await app.assets.loadAsync<EnvironmentAsset>("environments/studio.env");
world.createEntity("Env").addComponent(Environment, { environment: studio.retain() });Properties
address
readonlyaddress:string
The address the environment was loaded from.
assetType
staticassetType:string
The type name the asset service registers environments under.
brdfUrl
readonlybrdfUrl:string
The URL Lite fetched the BRDF lookup table from, or empty when the load was headless.
definition
readonlydefinition:EnvironmentDefinition
What the file declared, with the defaults filled in.
Accessors
lite
Get Signature
get lite():
EnvironmentAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch.
Returns
The GPU handles, or null under a headless app.
FirstPersonController
A first-person character.
Example
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
Constructors
Constructor
new FirstPersonController():
FirstPersonController
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
airControl
airControl:
number
How much of the ground speed applies mid-air.
allowMultiple
staticallowMultiple:boolean
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
staticrequires: readonly [typeofCharacterController]
The CharacterController this drives.
schema
staticschema: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
statictypeId:string
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
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
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
The world.
Inherited from
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()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
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
FontAsset
A parsed font file (docs/architecture/05-assets-and-loading.md §5).
Example
const inter = await app.assets.loadAsync<FontAsset>("fonts/inter.ttf");
inter.value.address; // "fonts/inter.ttf"Properties
address
readonlyaddress:string
The address the font was loaded from.
assetType
staticassetType:string
The type name the asset service registers fonts under.
byteLength
readonlybyteLength:number
How many bytes the file held, for diagnostics.
Accessors
lite
Get Signature
get lite():
FontAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch.
Returns
The parsed font.
GamepadDevice
A game controller (docs/architecture/08-input.md §4). Values are refreshed once per frame from
navigator.getGamepads(); the Gamepad API has no events for axis motion, so polling is the only
option and it happens in PreUpdate with everything else.
Example
const pad = app.input.gamepads[0];
if (pad.isConnected) {
pad.rumble(0.6, 0.2);
}Extends
Constructors
Constructor
new GamepadDevice(
slot):GamepadDevice
Builds one gamepad slot. Slots exist from app start and report isConnected === false until a
pad appears in them.
Parameters
slot
number
The slot index, 0 through 3.
Returns
Overrides
Properties
deviceIndex
readonlydeviceIndex:number
Which device of its family this is; 0 for every family that has only one.
Inherited from
kind
readonlykind:DeviceKind
The device family this device belongs to.
Inherited from
Accessors
controls
Get Signature
get controls(): readonly
ControlDescriptor[]
The device's controls, in index order.
Returns
readonly ControlDescriptor[]
The control table.
Inherited from
id
Get Signature
get id():
string
The pad's id string, or "" when the slot is empty.
Returns
string
The identifier the browser reports.
isConnected
Get Signature
get isConnected():
boolean
Whether the device is present. Only gamepads ever report false.
Returns
boolean
true when bindings to this device can produce input.
Inherited from
Methods
control()
control(
name):ControlDescriptor|null
Looks a control up by name. Call it at binding time, never per frame.
Parameters
name
string
The control name, for example dpad/up.
Returns
ControlDescriptor | null
The descriptor, or null when the device has no such control.
Inherited from
rumble()
rumble(
intensity,seconds):boolean
Plays a dual-rumble effect, when the pad exposes a haptic actuator
(docs/architecture/08-input.md §4).
Parameters
intensity
number
Motor magnitude in [0, 1]; values outside are clamped.
seconds
number
How long the effect lasts.
Returns
boolean
true when an effect was started, false when the pad has no actuator.
Example
app.input.gamepads[0].rumble(1, 0.15);valueAt()
valueAt(
offset):number
Reads one component of the device's value array.
Parameters
offset
number
The slot, from a ControlDescriptor.
Returns
number
The value, or 0 when the slot is out of range.
Inherited from
HeadlessBackend
The audio backend that runs where there is no Web Audio.
Example
// Exercise the browser's locked-until-a-gesture behaviour in a Node test.
const app = await createApp({
headless: true,
extensions: [audio({ createBackend: () => new HeadlessBackend({ startSuspended: true }) })],
});Implements
Constructors
Constructor
new HeadlessBackend(
options?):HeadlessBackend
Creates the backend.
Parameters
options?
The initial gain, and whether to start suspended.
Returns
Properties
kind
readonlykind:AudioBackendKind
Which implementation this is.
Implementation of
lite
readonlylite:AudioLiteHandles|null
There is no Lite engine behind this backend.
Implementation of
Accessors
buses
Get Signature
get buses(): readonly
HeadlessBus[]
Every bus this backend has made, for tests and diagnostics.
Returns
readonly HeadlessBus[]
The live buses, in creation order.
elapsedMs
Get Signature
get elapsedMs():
number
How many milliseconds of engine time the pump has advanced, for diagnostics.
Returns
number
The elapsed simulated time in milliseconds.
elapsedSeconds
Get Signature
get elapsedSeconds():
number
How many seconds of engine time the pump has advanced.
Returns
number
The elapsed simulated time in seconds.
listener
Get Signature
get listener():
SpatialTarget|null
The world transform the listener follows.
Returns
SpatialTarget | null
The target, or null when the listener sits at the world origin.
onStateChanged
Get Signature
get onStateChanged():
SignalLike<AudioBackendState>
Emitted whenever the state changes.
Returns
The signal.
Emitted whenever AudioBackend.state changes.
Implementation of
sounds
Get Signature
get sounds(): readonly
HeadlessSound[]
Every sound this backend has made and not released, for tests and diagnostics.
Returns
readonly HeadlessSound[]
The live sounds, in creation order.
state
Get Signature
get state():
AudioBackendState
The simulated context's state.
Returns
The state.
The audio context's current state.
Implementation of
Methods
createBus()
createBus(
request):Promise<BackendBus>
Creates a simulated bus.
Parameters
request
The name, gain, and parent bus.
Returns
Promise<BackendBus>
The bus.
Implementation of
createSound()
createSound(
request):BackendSound
Creates a simulated sound. Synchronously, on purpose: it is what makes onEnded timing exact
in a test that never awaits between play() and the frames it steps.
Parameters
request
The clip, routing, and per-sound options.
Returns
The sound.
Implementation of
decode()
decode():
Promise<void>
Nothing is decoded under Node: a clip keeps whatever duration its container header gave it.
Returns
Promise<void>
A settled promise.
Implementation of
dispose()
dispose():
void
Releases every sound and bus and closes the simulated context.
Returns
void
Implementation of
disposeBus()
disposeBus(
bus):void
Releases a bus.
Parameters
bus
The bus.
Returns
void
Implementation of
disposeSound()
disposeSound(
sound):void
Releases a sound.
Parameters
sound
The sound.
Returns
void
Implementation of
getMasterVolume()
getMasterVolume():
number
Reads the master gain.
Returns
number
The gain.
Implementation of
pause()
pause(
sound):void
Pauses every instance.
Parameters
sound
The sound.
Returns
void
Implementation of
play()
play(
sound,request):void
Starts one instance, or resumes the sound when it was paused — Babylon Lite's documented
behaviour (index.d.ts 8955).
Parameters
sound
The sound.
request
The per-play overrides.
Returns
void
Implementation of
resume()
resume(
sound):void
Resumes every paused instance.
Parameters
sound
The sound.
Returns
void
Implementation of
setBusVolume()
setBusVolume(
bus,volume):void
Sets a bus's gain.
Parameters
bus
The bus.
volume
number
The gain to apply now.
Returns
void
Implementation of
setListener()
setListener(
target):void
Records the transform the listener follows. Nothing is audible, so nothing else happens; the value is here so a test can assert that a listener was selected.
Parameters
target
SpatialTarget | null
The transform, or null.
Returns
void
Implementation of
setMasterVolume()
setMasterVolume(
volume):void
Sets the master gain.
Parameters
volume
number
The gain to apply now.
Returns
void
Implementation of
setSoundPan()
setSoundPan(
sound,pan):void
Sets a sound's stereo pan.
Parameters
sound
The sound.
pan
number
The pan in [-1, 1].
Returns
void
Implementation of
setSoundVolume()
setSoundVolume(
sound,volume):void
Sets a sound's gain. Fades are interpolated by the service, so the value arrives already at this frame's position along the ramp.
Parameters
sound
The sound.
volume
number
The gain to apply now.
Returns
void
Implementation of
stop()
stop(
sound):void
Stops every instance.
Parameters
sound
The sound.
Returns
void
Implementation of
unlock()
unlock():
Promise<void>
Moves the simulated context to "running".
Returns
Promise<void>
A promise that settles once the state has changed.
Implementation of
update()
update(
deltaSeconds):void
Advances simulated playback by one frame, dropping every instance whose time ran out.
Parameters
deltaSeconds
number
The frame delta in seconds.
Returns
void
Implementation of
HeadlessBus
A bus of the headless backend: a name, a gain, and its place in the tree.
Implements
Constructors
Constructor
new HeadlessBus(
name,volume,parent):HeadlessBus
Creates a simulated bus.
Parameters
name
string
The bus name.
volume
number
Its own linear gain.
parent
HeadlessBus | null
The bus it routes into, or null.
Returns
Properties
isDisposed
isDisposed:
boolean
true once the tree it belongs to has released it.
lite
readonlylite:null
Lite owns nothing here, so the escape hatch is always null.
Implementation of
name
readonlyname:string
The bus name.
Implementation of
parent
readonlyparent:HeadlessBus|null
The bus it routes into, or null for the root.
volume
volume:
number
The bus's own linear gain, before the parent chain.
Accessors
effectiveVolume
Get Signature
get effectiveVolume():
number
The gain this bus actually contributes: its own, multiplied up the parent chain. A real Web Audio graph gets this for free by chaining gain nodes; the simulation has to multiply.
Returns
number
The product of every gain from this bus to the root.
HeadlessSound
A sound of the headless backend: one clip routed to one bus, carrying simulated instances.
Implements
Constructors
Constructor
new HeadlessSound(
request):HeadlessSound
Creates a simulated sound.
Parameters
request
The clip, routing, and per-sound options.
Returns
Properties
bus
readonlybus:HeadlessBus|null
The bus it routes into, or null for the main bus.
clip
readonlyclip:AudioClip
The clip this sound plays.
isDisposed
isDisposed:
boolean
true once the backend has released it.
maxInstances
readonlymaxInstances:number
How many instances may play at once.
pan
pan:
number
The sound's stereo pan, as the last setSoundPan left it.
spatial
readonlyspatial:BackendSpatialRequest|null
The 3D placement it was created with, or null for a non-spatial sound.
volume
volume:
number
The sound's own linear gain, as the last setSoundVolume left it.
Accessors
effectiveVolume
Get Signature
get effectiveVolume():
number
The gain a listener would hear: the sound's own gain times its bus chain.
Returns
number
The product.
instanceCount
Get Signature
get instanceCount():
number
How many instances are live.
Returns
number
The instance count.
How many instances of this sound are live.
Implementation of
isPaused
Get Signature
get isPaused():
boolean
Whether every live instance is paused.
Returns
boolean
true when there is at least one instance and none of them are running.
true when every instance has been paused.
Implementation of
isPlaying
Get Signature
get isPlaying():
boolean
Whether anything is sounding.
Returns
boolean
true while at least one instance is live and not paused.
true while at least one instance is playing or about to.
Implementation of
Methods
advance()
advance(
deltaSeconds):void
Advances every running instance and drops the ones that finished.
Parameters
deltaSeconds
number
The frame delta in seconds.
Returns
void
dispose()
dispose():
void
Drops every instance; the backend calls it from disposeSound.
Returns
void
pauseAll()
pauseAll():
void
Pauses every instance, keeping its remaining time.
Returns
void
resumeAll()
resumeAll():
void
Resumes every paused instance.
Returns
void
start()
start(
request):void
Starts one instance, stealing the oldest when the sound is already at maxInstances.
Parameters
request
The per-play overrides.
Returns
void
stopAll()
stopAll():
void
Stops every instance at once, without an onEnded: a stop is not an end.
Returns
void
HeightfieldCollider
A heightfield collider: a regular grid of height samples in the XZ plane, which is what a terrain
uses (index.d.ts 2601, 6266).
Remarks
Only Lite's explicit heightfield path is used, because the groundMesh path reads
mesh._cpuPositions and worldMatrix and therefore needs a GPU. heights is row-major with
samplesX * samplesZ entries.
Extends
Constructors
Constructor
new HeightfieldCollider():
HeightfieldCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
heights
heights:
number[]
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
samplesX
samplesX:
number
samplesZ
samplesZ:
number
schema
staticschema:Schema
The serialized field declarations.
size
size:
Vec3Like
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,scale):PhysicsShape
Builds this collider's Havok shape.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
scale
The entity's lossy scale, applied to the authored dimensions.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
scale,out):void
Writes half the size of this collider's local bounding box, scale applied.
Parameters
scale
The entity's lossy scale.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
HostDesktop
The Desktop a desktop build gets: every call forwarded over the preload bridge.
Implements
Constructors
Constructor
new HostDesktop(
host):HostDesktop
Builds a desktop service over a bridge.
Parameters
host
The validated window.ignifxHost.
Returns
Properties
isElectron
readonlyisElectron:boolean
Always true.
Implementation of
onWindowEvent
readonlyonWindowEvent:SignalLike<HostWindowEvent>
The host window's lifecycle events.
Implementation of
versions
readonlyversions:HostVersions|null
What the bridge reported at load time.
Implementation of
Methods
dispose()
dispose():
void
Removes the window-event subscription and clears the signal. Safe to call twice.
Returns
void
isFullscreen()
isFullscreen():
Promise<boolean>
Reports whether the window is full screen.
Returns
Promise<boolean>
true when it is.
Implementation of
openExternal()
openExternal(
url):Promise<void>
Opens a URL in the user's browser or mail client.
Parameters
url
string
The absolute URL to open.
Returns
Promise<void>
A promise that settles once the OS accepted it.
Implementation of
paths()
paths():
Promise<HostPaths>
Resolves the platform directories.
Returns
Promise<HostPaths>
The directories the host reported.
Implementation of
quit()
quit():
Promise<void>
Closes the window and quits the application.
Returns
Promise<void>
A promise that settles once the quit has been requested.
Implementation of
setFullscreen()
setFullscreen(
fullscreen):Promise<void>
Enters or leaves full screen.
Parameters
fullscreen
boolean
true to enter, false to leave.
Returns
Promise<void>
A promise that settles once the host applied it.
Implementation of
setWindowTitle()
setWindowTitle(
title):Promise<void>
Sets the window title.
Parameters
title
string
The new title.
Returns
Promise<void>
A promise that settles once the host applied it.
Implementation of
showOpenDialog()
showOpenDialog(
options?):Promise<HostOpenDialogResult>
Shows a modal open dialog over the game window.
Parameters
options?
What the dialog offers.
Returns
Promise<HostOpenDialogResult>
What the user chose.
Implementation of
watchWindowEvents()
watchWindowEvents(
listener):void
Subscribes to the host's window lifecycle events and re-emits them on HostDesktop.onWindowEvent.
Parameters
listener
(event) => void
Called with each event name before the signal is emitted, so electron()
can map focus and blur onto onApplicationFocus.
Returns
void
HudText
Pixel-space HUD text.
Example
const label = app.world.createEntity("score").addComponent(HudText);
label.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
label.anchor = "topLeft";
label.position = { x: 16, y: 16 };
label.i18nKey = "hud.score";Extends
Implements
Constructors
Constructor
new HudText():
HudText
Builds a HUD label with the schema's defaults.
Returns
Overrides
Properties
align
align:
"left"|"center"|"right"
Which edge the lines align to.
Inherited from
allowMultiple
staticallowMultiple:boolean
One HUD label per entity; a second belongs on a second entity.
anchor
anchor:
"topLeft"|"top"|"topRight"|"left"|"center"|"right"|"bottomLeft"|"bottom"|"bottomRight"
Which point of the render target HudText.position is measured from.
color
color:
ColorLike
The colour every glyph starts with.
Inherited from
font
font:
AssetHandle<FontAsset> |null
The TTF or OTF the glyphs come from.
Inherited from
fontSize
fontSize:
number
The em size, in render-target pixels.
Inherited from
i18nKey
i18nKey:
string
A translation key looked up in app.i18n; wins over TextComponent.text.
Inherited from
lineHeight
lineHeight:
number
The line-height multiplier.
Inherited from
maxWidth
maxWidth:
number
The wrap width, in render-target pixels; 0 does not wrap.
Inherited from
opacity
opacity:
number
The whole-block alpha multiplier.
Inherited from
order
order:
number
The sort order within the text renderer; lower draws first.
position
position:
Vec2Like
The offset from the anchor, in render-target pixels; x grows right, y grows down.
schema
staticschema:Schema
The declarative fields (ADR-0004).
text
text:
string
The literal string to draw; ignored when TextComponent.i18nKey is set.
Inherited from
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
TextComponent.isEnabledInHierarchy
lite
Get Signature
get lite():
object
The Babylon Lite objects the component owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
object
The text layer, or null before the first frame that had a font and a string.
layer
readonlylayer:TextLayer|null
metrics
Get Signature
get metrics():
TextMetrics
The block's laid-out size, in render-target pixels.
Remarks
{ width: 0, height: 0 } until the block exists. This is Lite's only text measurement, and
it is what a caller centring a block on the screen needs — Lite's align aligns lines against
each other, not against the screen.
Example
const label = entity.addComponent(HudText);
label.metrics.width; // 0 until a font and a string are setReturns
The size.
Inherited from
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Drops the layer and the block when the component goes away.
Returns
void
Implementation of
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
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
TextComponent.requireComponent
resolveText()
resolveText(
i18n):string
The string that will actually be drawn: the translated i18nKey, or text.
Parameters
i18n
I18nService | null
The localization service, or null when the app has none.
Returns
string
The resolved string.
Inherited from
I18nService
The localization service, reached as app.i18n.
Example
await app.i18n.load(app.assets.load<LocaleAsset>("ui/strings.i18n.json"));
app.i18n.locale = "fr";
app.i18n.t("hud.lives", { count: 3 });Accessors
availableLocales
Get Signature
get availableLocales(): readonly
string[]
Every locale any loaded document declares, sorted.
Returns
readonly string[]
The BCP 47 tags.
fallbackLocale
Get Signature
get fallbackLocale():
string
The locale a key falls back to when the active locale has no entry for it. Set from the first
document's defaultLocale.
Returns
string
The BCP 47 tag.
Set Signature
set fallbackLocale(
value):void
Parameters
value
string
Returns
void
locale
Get Signature
get locale():
string
The active locale. Writing a locale no loaded document declares throws IGX-1303, because a
silent no-op there is a bug that only shows up as untranslated text much later.
Throws
IgnifxError with code IGX-1303 when no loaded document declares the tag.
Returns
string
The BCP 47 tag.
Set Signature
set locale(
value):void
Parameters
value
string
Returns
void
onLocaleChanged
Get Signature
get onLocaleChanged():
SignalLike<string>
Emitted after I18nService.locale changed. UI that caches rendered strings — HudText
does — redraws from here.
Returns
SignalLike<string>
The signal.
Methods
has()
has(
key):boolean
Whether the active locale, or the fallback, has an entry for a key.
Parameters
key
string
The message key.
Returns
boolean
true when I18nService.t will find a message.
load()
load(
source):Promise<void>
Merges a translation document into the service.
Parameters
source
LocaleAsset | AssetHandle<LocaleAsset>
A loaded document, or its handle.
Returns
Promise<void>
A promise that settles once the document has been merged.
Remarks
Accepts a loaded LocaleAsset or the handle of one, in which case the merge happens when
the handle settles. Later loads win on a repeated key, which is what makes a per-locale
download or a downloadable language pack work. The first document loaded also sets
I18nService.fallbackLocale and, when the app is still on its starting locale and the
document does not declare it, moves the active locale to the document's defaultLocale.
Example
using strings = app.assets.load<LocaleAsset>("ui/strings.i18n.json");
await app.i18n.load(strings);t()
t(
key,params?):string
Renders a message.
Parameters
key
string
The message key.
params?
Readonly<Record<string, string | number>>
The values {name} placeholders and plural selectors read.
Returns
string
The rendered message, or the key itself when no document declares it.
Example
app.i18n.t("hud.lives", { count: 1 }); // "1 life"
app.i18n.t("hud.lives", { count: 4 }); // "4 lives"IgnifxError
The error every ignifx API throws for misuse (CONSTITUTION.md §3.9). It always carries a stable
IGX-#### code and the context identifiers needed to find the offending object,
so a production build can compact the human-readable half without losing meaning.
Example
try {
world.instantiate(scene);
} catch (error) {
if (isIgnifxError(error) && error.code === CoreErrorCode.sceneNotLoaded) {
await scene.load();
}
}Extends
Error
Extended by
Constructors
Constructor
new IgnifxError(
code,message,options?):IgnifxError
Creates an ignifx error.
Parameters
code
`IGX-${number}`
The stable IGX-#### code for the failure.
message
string
An actionable description of what went wrong, used in development mode.
options?
Context, hint, format mode, and the standard cause.
Returns
Overrides
Error.constructor
Properties
cause?
optionalcause?:unknown
Inherited from
Error.cause
code
readonlycode:`IGX-${number}`
The stable diagnostic code for this failure.
context
readonlycontext:ErrorContext
Identifiers that locate the failure (entity uid, component type id, asset key, …).
hint
readonlyhint:string|null
One sentence telling the developer how to fix it, or null when there is nothing to add.
message
message:
string
Inherited from
Error.message
name
name:
string
Inherited from
Error.name
stack?
optionalstack?:string
Inherited from
Error.stack
IndexedDbStorageBackend
A store backed by the browser's IndexedDB.
Example
const app = await createApp({ canvas, storage: new IndexedDbStorageBackend() });Implements
Constructors
Constructor
new IndexedDbStorageBackend():
IndexedDbStorageBackend
Returns
Properties
name
readonlyname:"indexeddb"="indexeddb"
The identifier that appears in error context.
Implementation of
Methods
clear()
clear(
namespace):Promise<void>
Empties one namespace.
Parameters
namespace
string
The namespace path.
Returns
Promise<void>
A promise that settles once the transaction commits.
Implementation of
delete()
delete(
namespace,key):Promise<void>
Removes one value.
Parameters
namespace
string
The namespace path.
key
string
The key.
Returns
Promise<void>
A promise that settles once the transaction commits.
Implementation of
dispose()
dispose():
void
Closes the connection. The next call opens a new one.
Returns
void
Implementation of
get()
get(
namespace,key):Promise<StoredValue|null>
Reads one value.
Parameters
namespace
string
The namespace path.
key
string
The key.
Returns
Promise<StoredValue | null>
The value, or null.
Implementation of
keys()
keys(
namespace,prefix?):Promise<readonlystring[]>
Lists one namespace's keys.
Parameters
namespace
string
The namespace path.
prefix?
string
An optional key prefix.
Returns
Promise<readonly string[]>
The matching keys, in ascending order.
Implementation of
set()
set(
namespace,key,value):Promise<void>
Writes one value.
Parameters
namespace
string
The namespace path.
key
string
The key.
value
The value.
Returns
Promise<void>
A promise that settles once the transaction commits.
Implementation of
InputAction
One input action (docs/architecture/08-input.md §2).
Example
class Player extends Script {
update(dt: number): void {
const move = this.app.input.actions.get("move");
this.transform.translate({ x: move.vector.x * dt, y: 0, z: move.vector.y * dt });
if (this.app.input.actions.get("jump").wasPressedThisFrame) {
this.jump();
}
}
}Constructors
Constructor
new InputAction(
definition,map,resolver,onHandlerError):InputAction
Builds an action from its document form.
Parameters
definition
The action as it appears in an ignifx.inputactions document.
map
The map the action belongs to.
resolver
How binding paths become controls.
onHandlerError
(error) => void
Where a signal handler's exception is reported.
Returns
Throws
IgnifxError with code IGX-0802, IGX-0803, or IGX-0806 for an unusable binding.
Properties
enabled
enabled:
boolean
Whether this action resolves at all. An action in a disabled map reads as released too.
map
readonlymap:ActionMap
The map the action belongs to.
name
readonlyname:string
The action name game code asks for.
onCanceled
readonlyonCanceled:Signal<InputActionEvent>
Emitted the frame the action returns to rest.
onPerformed
readonlyonPerformed:Signal<InputActionEvent>
Emitted when the action is pressed and whenever its value changes while actuated.
onStarted
readonlyonStarted:Signal<InputActionEvent>
Emitted the frame the action is first actuated.
type
readonlytype:InputActionType
What the action produces.
Accessors
axis
Get Signature
get axis():
number
The action's scalar value, for an axis action.
Returns
number
The signed value; for other types, the x component.
bindings
Get Signature
get bindings(): readonly
Binding[]
The bindings that feed this action, in declaration order.
Returns
readonly Binding[]
The bindings.
isPressed
Get Signature
get isPressed():
boolean
Whether the action is actuated past the press point.
Returns
boolean
true while held.
magnitude
Get Signature
get magnitude():
number
How far the action is actuated, in [0, 1] for normalised controls.
Returns
number
The magnitude the press point is compared against.
value
Get Signature
get value():
number|boolean|Vec2Like
The action's value in the shape its type implies.
Returns
number | boolean | Vec2Like
A boolean for button, a number for axis, a live Vec2Like for vector2.
vector
Get Signature
get vector():
Vec2Like
The action's vector value, for a vector2 action. The object is a live view: it always reads
the action's current value and is never reallocated.
Returns
The live vector.
wasPressedThisFrame
Get Signature
get wasPressedThisFrame():
boolean
Whether the action became pressed in this frame. Stable for the whole frame, every fixed step included.
Returns
boolean
true in the one frame the press resolved.
wasReleasedThisFrame
Get Signature
get wasReleasedThisFrame():
boolean
Whether the action was released in this frame. Stable for the whole frame.
Returns
boolean
true in the one frame the release resolved.
InputActionsAsset
A loaded input actions document.
Example
const actions = await app.assets.loadAsync<InputActionsAsset>("input/default.input.json");
app.input.loadActions(actions.value);Constructors
Constructor
new InputActionsAsset(
address,definition):InputActionsAsset
Wraps a validated document. The inputactions loader constructs these.
Parameters
address
string
The address it was loaded from.
definition
The validated document.
Returns
Properties
address
readonlyaddress:string
The address the document was loaded from; "" for one built in code.
assetType
staticassetType:string
The type name the asset service registers input action documents under.
definition
readonlydefinition:InputActionsDefinition
The validated document.
Accessors
mapNames
Get Signature
get mapNames(): readonly
string[]
The names of the maps the document declares, in document order.
Returns
readonly string[]
The map names.
InputActionSet
A private copy of a document's action maps, owned by one PlayerInput or by game code that
asked for one (docs/architecture/08-input.md §7).
Properties
actions
readonlyactions:InputActionsView
The lookups over the set's maps.
maps
readonlymaps:ReadonlyMap<string,ActionMap>
The set's maps, keyed by name.
Accessors
isDisposed
Get Signature
get isDisposed():
boolean
Whether InputActionSet.dispose has run.
Returns
boolean
true once the set has been disposed.
Methods
dispose()
dispose():
void
Unregisters the set so its actions stop resolving. Disposing twice is a no-op.
Returns
void
InputActionsView
The maps installed on one input source, and the two lookups over them.
Example
app.input.actions.get("jump").wasPressedThisFrame;
app.input.actions.map("Player").enabled = false;Constructors
Constructor
new InputActionsView(
maps):InputActionsView
Wraps a map table.
Parameters
maps
Map<string, ActionMap>
The installed maps, keyed by name; the view reads it live.
Returns
Accessors
maps
Get Signature
get maps():
ReadonlyMap<string,ActionMap>
Every installed map, keyed by name.
Returns
ReadonlyMap<string, ActionMap>
The map table.
Methods
find()
find(
name):InputAction|null
Finds an action by name in any map, enabled or not.
Parameters
name
string
The action name.
Returns
InputAction | null
The action, or null when no map declares it — an absent action is not a failure
(coding standards §5.5).
get()
get(
name):InputAction
Finds an action by name in the enabled maps.
Parameters
name
string
The action name.
Returns
The action.
Throws
IgnifxError with code IGX-0801 when no enabled map declares it.
map()
map(
name):ActionMap
Looks a map up by name.
Parameters
name
string
The map name.
Returns
The map.
Throws
IgnifxError with code IGX-0804 when no map is installed under that name.
InputDevice
One input device: a named control table and the values behind it
(docs/architecture/08-input.md §4).
Remarks
Values live in a Float32Array. Reads take the descriptor's offset, never the control's name,
so nothing on the per-frame path allocates or hashes a string (coding standards §7).
Example
const space = app.input.devices.keyboard.control("space");
if (space !== null && app.input.devices.keyboard.valueAt(space.offset) > 0) {
jump();
}Extended by
Constructors
Constructor
new InputDevice(
kind,deviceIndex,specs,isConnected?):InputDevice
Builds a device from its control declarations.
Parameters
kind
The device family.
deviceIndex
number
Which device of the family this is.
specs
readonly ControlSpec[]
The control declarations, in index order.
isConnected?
boolean
Whether the device starts connected. Gamepads start disconnected.
Returns
Properties
deviceIndex
readonlydeviceIndex:number
Which device of its family this is; 0 for every family that has only one.
kind
readonlykind:DeviceKind
The device family this device belongs to.
Accessors
controls
Get Signature
get controls(): readonly
ControlDescriptor[]
The device's controls, in index order.
Returns
readonly ControlDescriptor[]
The control table.
isConnected
Get Signature
get isConnected():
boolean
Whether the device is present. Only gamepads ever report false.
Returns
boolean
true when bindings to this device can produce input.
Methods
control()
control(
name):ControlDescriptor|null
Looks a control up by name. Call it at binding time, never per frame.
Parameters
name
string
The control name, for example dpad/up.
Returns
ControlDescriptor | null
The descriptor, or null when the device has no such control.
valueAt()
valueAt(
offset):number
Reads one component of the device's value array.
Parameters
offset
number
The slot, from a ControlDescriptor.
Returns
number
The value, or 0 when the slot is out of range.
InputDevices
Every input device an app has (docs/architecture/08-input.md §1).
Example
app.input.devices.keyboard.control("space");
app.input.devices.gamepads[0].isConnected;Constructors
Constructor
new InputDevices():
InputDevices
Builds one device of every family plus the four gamepad slots.
Returns
Properties
all
readonlyall: readonlyInputDevice[]
Every device, in a stable order.
gamepads
readonlygamepads: readonlyGamepadDevice[]
The four gamepad slots, connected or not.
keyboard
readonlykeyboard:InputDevice
The physical keyboard.
mouse
readonlymouse:InputDevice
The mouse.
pointer
readonlypointer:InputDevice
The unified primary pointer: mouse, pen, or first touch.
touch
readonlytouch:InputDevice
The touch screen and its ten slots.
virtual
readonlyvirtual:VirtualDevice
The synthetic device on-screen controls feed.
Methods
device()
device(
kind,deviceIndex):InputDevice|null
Looks a device up by family and index.
Parameters
kind
The device family.
deviceIndex
number
Which device of the family; only gamepads have more than one.
Returns
InputDevice | null
The device, or null when the family has no such index.
resolve()
resolve(
path,virtualKind?):ControlRef
Resolves a binding path to the control it names, creating the control when the path names the
virtual device (docs/architecture/08-input.md §8).
Parameters
path
string
The binding path, for example <Gamepad>{1}/leftStick.
virtualKind?
The kind a virtual control is created with when it does not exist yet.
Returns
The device and control the path names.
Throws
IgnifxError with code IGX-0803 when the path is malformed, names an unknown device
index, or names a control the device does not have.
Example
const ref = app.input.devices.resolve("<Mouse>/delta");
ref.device.valueAt(ref.control.offset);InputService
The input service (docs/architecture/08-input.md §1).
Example
const app = await createApp({ headless: true, extensions: [input()] });
app.input.loadActions(
defineInputActions({
maps: [{ name: "Player", actions: [{ name: "jump", bindings: [{ path: "<Keyboard>/space" }] }] }],
}),
);
app.input.simulate({ "<Keyboard>/space": 1 });
app.step(1 / 60);
app.input.actions.get("jump").wasPressedThisFrame; // trueImplements
Constructors
Constructor
new InputService(
options):InputService
Builds the service. The extension constructs exactly one per app.
Parameters
options
The app, the resolved settings, and an optional gamepad reader.
Returns
Properties
cursor
readonlycursor:Cursor
Cursor visibility over the canvas.
devices
readonlydevices:InputDevices
Every input device this app has.
pointerLock
readonlypointerLock:PointerLock
Pointer lock (docs/architecture/08-input.md §4).
pressPoint
pressPoint:
number
The magnitude at which an analog value counts as pressed. Defaults to the input setting.
strictSchemes
strictSchemes:
boolean
Whether a binding tagged with a control scheme resolves only while that scheme is active.
Defaults to the input.strictSchemes setting.
Accessors
actions
Get Signature
get actions():
InputActionsView
The installed action maps and the two lookups over them.
Returns
The action lookup.
actionsHandle
Get Signature
get actionsHandle():
AssetHandle<InputActionsAsset> |null
The handle of the .input.json document the input.actions setting named, or null when the
project named none.
Remarks
The extension starts the load in onStart and installs the maps at delivery, which is the
PreUpdate of the first stepped frame. Awaiting the handle inside onStart would deadlock: a
headless app has not been stepped yet and a canvas app has not started its loop
(05-assets-and-loading.md §4). Game code that must wait awaits this handle's promise.
Returns
AssetHandle<InputActionsAsset> | null
The handle, or null.
controlSchemes
Get Signature
get controlSchemes(): readonly
ControlSchemeDefinition[]
The control schemes the loaded document declared.
Returns
readonly ControlSchemeDefinition[]
The schemes, in document order.
currentScheme
Get Signature
get currentScheme():
string
The control scheme in use, chosen by the device that produced input last.
Returns
string
The scheme name, or "" before any input arrives.
events
Get Signature
get events(): readonly
InputEventRecord[]
The current frame's raw events, in arrival order
(docs/architecture/08-input.md §5). The array and its records are reused each frame.
Returns
readonly InputEventRecord[]
The frame's event list.
gamepads
Get Signature
get gamepads(): readonly
GamepadDevice[]
The gamepad slots, connected or not.
Returns
readonly GamepadDevice[]
The four slots, in slot order.
onControlSchemeChanged
Get Signature
get onControlSchemeChanged():
SignalLike<string>
Emitted with the new scheme name whenever the active control scheme changes.
Returns
SignalLike<string>
The signal.
onDeviceConnected
Get Signature
get onDeviceConnected():
SignalLike<InputDevice>
Emitted when a gamepad appears in a slot.
Returns
The signal.
onDeviceDisconnected
Get Signature
get onDeviceDisconnected():
SignalLike<InputDevice>
Emitted when a gamepad leaves a slot.
Returns
The signal.
uiHasFocus
Get Signature
get uiHasFocus():
boolean
Whether a DOM text field has focus (docs/architecture/08-input.md §5). While it is true,
keyboard actions read as released and keyboard events are still published on
InputService.events; pointer actions keep working.
Returns
boolean
true while the UI owns the keyboard. @ignifx/ui assigns it.
Set Signature
set uiHasFocus(
value):void
Parameters
value
boolean
Returns
void
uiHasPointer
Get Signature
get uiHasPointer():
boolean
Whether a pointer is pressed on the UI overlay (docs/architecture/08-input.md §5). While it is
true, pointing-device actions (<Pointer>, <Mouse>, <Touch>) read as released and their
events are still published on InputService.events; keyboard and gamepad actions keep
working. Pointer moves and releases are read from the window, so without this flag a drag that
began on a UI slider would also drive <Pointer>/delta.
Returns
boolean
true while the UI owns the pointer. @ignifx/ui assigns it.
Set Signature
set uiHasPointer(
value):void
Parameters
value
boolean
Returns
void
Methods
cancelInteractiveRebind()
cancelInteractiveRebind():
void
Cancels the interactive rebind in flight, if there is one.
Returns
void
clearActions()
clearActions():
void
Removes every installed map and control scheme.
Returns
void
clearOverrides()
clearOverrides():
void
Returns every binding to its declared path.
Returns
void
createActionSet()
createActionSet(
source,options?):InputActionSet
Builds a private copy of a document's maps, bound to one gamepad slot
(docs/architecture/08-input.md §7). PlayerInput uses it so that two players can hold the
same action names without sharing state; the copy resolves in the same PreUpdate pass as
app.input.actions.
Parameters
source
InputActionsAsset | InputActionsDefinition | AssetHandle<InputActionsAsset>
A loaded asset, its handle, or a definition built by defineInputActions.
options?
The gamepad slot to pin to and the control scheme to keep.
Returns
The private set. Dispose it when the owner goes away.
Example
const set = app.input.createActionSet(asset, { deviceSlot: 1, scheme: "Gamepad" });
set.actions.get("move").vector.x;invalidateBindings()
invalidateBindings():
void
Marks the control-to-actions index stale, so the next frame rebuilds it.
Returns
void
Implementation of
BindingResolver.invalidateBindings
loadActions()
loadActions(
source):void
Installs the maps and control schemes of a document, merging by map name: a map whose name is
already installed is replaced, and every other installed map is kept
(docs/architecture/08-input.md §3).
Parameters
source
InputActionsAsset | InputActionsDefinition | AssetHandle<InputActionsAsset>
A loaded asset, its handle, or a definition built by defineInputActions.
Returns
void
Throws
IgnifxError with code IGX-0802, IGX-0803, IGX-0806, or IGX-0810 when a binding
or a name in the document cannot be used.
loadOverrides()
loadOverrides(
json):void
Applies a saved override document, clearing whatever was applied before.
Parameters
json
The document from InputService.saveOverrides.
Returns
void
Throws
IgnifxError with code IGX-0808 when the document cannot be applied.
performInteractiveRebind()
performInteractiveRebind(
action,options?):Promise<InteractiveRebindResult>
Listens for the next control the player actuates and writes its path into one of an action's
bindings as an override (docs/architecture/08-input.md §6).
Parameters
action
The action to rebind.
options?
Binding index, exclusions, cancel path, timeout, and threshold.
Returns
Promise<InteractiveRebindResult>
What the player chose, or a cancelled or timed-out result. The promise settles from the
PreUpdate resolution, the same delivery point an asset handle settles at.
Throws
IgnifxError with code IGX-0807 when a rebind is already listening.
Example
const result = await app.input.performInteractiveRebind(app.input.actions.get("jump"), {
cancelPath: "<Keyboard>/escape",
timeoutSeconds: 5,
});releaseAll()
releaseAll():
void
Queues a release of every control, which is what blur and visibilitychange do
(docs/architecture/08-input.md §4). A game that opens a modal outside the canvas can call it
so a key held at that moment does not stay stuck.
Returns
void
Example
app.input.releaseAll();resolveControl()
resolveControl(
path,kind?):ControlRef
Resolves a binding path to a device control, creating a <Virtual> control on demand.
Parameters
path
string
The binding path.
kind?
The kind a new <Virtual> control is created with.
Returns
The resolved control.
Throws
IgnifxError with code IGX-0803 when the path does not resolve.
Implementation of
BindingResolver.resolveControl
saveOverrides()
saveOverrides():
InputOverridesJson
Collects every binding override currently applied.
Returns
The document to persist.
simulate()
simulate(
values):void
Queues synthetic control values, resolved by the same pipeline as real input
(docs/architecture/08-input.md §8). This is how headless tests drive the engine.
Parameters
values
Readonly<Record<string, SimulatedValue>>
Binding paths to the value each control takes, held until changed again.
Returns
void
Throws
IgnifxError with code IGX-0803 when a path does not resolve.
Example
app.input.simulate({ "<Keyboard>/w": 1, "<Gamepad>/leftStick": { x: 0.5, y: 0 } });simulateEvent()
simulateEvent(
event):void
Queues one synthetic raw event, as if the DOM had delivered it.
Parameters
event
The event to queue; code names a control, not a KeyboardEvent.code.
Returns
void
Example
app.input.simulateEvent({ type: "pointerdown", x: 10, y: 20, button: 0 });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
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
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
LayerMask
An immutable set of layer slots.
Remarks
Two ways in, deliberately:
- Scripts use
world.layers.mask("Player", "Enemy")— names, resolved through the project's LayerTable, which is what makes files rename-safe. - LayerMask.of takes slot indices, for code that already resolved names (a system
caching
entity.layeratawake, say) and for tests.
There is no name-taking static, because resolving a name needs the project's table and a static has no access to one; LayerMask.fromNames is the standalone form that takes the table explicitly.
Example
class Hitbox extends Script {
#hostiles = LayerMask.nothing();
awake(): void {
this.#hostiles = this.world.layers.mask("Enemy", "Projectile");
}
onTriggerEnter(other: TriggerEvent): void {
if (this.#hostiles.has(other.entity.layer)) {
this.takeDamage();
}
}
}Constructors
Constructor
new LayerMask(
bits):LayerMask
Wraps a raw bit word. Prefer LayerMask.of, LayerMask.fromNames, or
world.layers.mask(...).
Parameters
bits
number
The bit word; only the low 32 bits are kept.
Returns
Properties
bits
readonlybits:number
The 32 slot bits, read as an unsigned word.
Methods
everything()
staticeverything():LayerMask
The mask with all 32 slots set.
Returns
A full mask.
fromBits()
staticfromBits(bits):LayerMask
Wraps a bit word that was stored or received from another system.
Parameters
bits
number
The bit word.
Returns
The mask.
fromNames()
staticfromNames(table,names):LayerMask
Builds a mask from layer names resolved through a table — the standalone form of
world.layers.mask(...).
Parameters
table
The project's layer table.
names
readonly string[]
The layer names to include.
Returns
The mask.
Throws
IgnifxError with code IGX-0303 when a name is not declared.
has()
has(
layer):boolean
Reports whether a slot is in the mask.
Parameters
layer
number
The slot index.
Returns
boolean
true when the slot's bit is set.
intersects()
intersects(
other):boolean
Reports whether the mask shares at least one slot with another.
Parameters
other
The mask to test against.
Returns
boolean
true when the two masks overlap.
nothing()
staticnothing():LayerMask
The mask with no slots set.
Returns
An empty mask.
of()
staticof(...layers):LayerMask
Builds a mask from layer slot indices.
Parameters
layers
...readonly number[]
The slots to include; values outside [0, 31] are ignored.
Returns
The mask.
Example
LayerMask.of(0, 8).bits; // 0b100000001toNames()
toNames(
table):string[]
The names of every slot in the mask, in slot order — what the serializer writes, because files
store names rather than bits (docs/architecture/06-serialization-and-scene-format.md §3).
Parameters
table
The project's layer table.
Returns
string[]
The names of the set slots that the table declares; unnamed slots are skipped.
with()
with(
layer):LayerMask
Adds a slot.
Parameters
layer
number
The slot index; out-of-range values are ignored.
Returns
A new mask; this one is unchanged.
without()
without(
layer):LayerMask
Removes a slot.
Parameters
layer
number
The slot index; out-of-range values are ignored.
Returns
A new mask; this one is unchanged.
LayerTable
The resolved mapping between layer names and the 32 layer slots.
Remarks
How the project list is interpreted (the settings example in
docs/architecture/04-extensions.md §5 opens with "Default", while
docs/architecture/02-scene-graph.md §7 reserves slots 0–7, so one rule has to reconcile the
two): the eight reserved names always occupy slots 0–7. A project entry that repeats a reserved
name keeps that reserved slot and consumes no user slot; every other entry takes the next free
slot from 8 upwards, in declaration order. A name declared twice is IGX-0304; more names than
slots is IGX-0305.
Example
const table = createLayerTable(["Default", "Ground", "Player"]);
table.indexOf("Ground"); // 8
table.mask("Ground", "Player").bits; // 0b1100000000Accessors
count
Get Signature
get count():
number
How many slots carry a name.
Returns
number
The count, always at least eight.
names
Get Signature
get names(): readonly
string[]
Every slot's name, indexed by slot. Unassigned user slots hold the empty string.
Returns
readonly string[]
The 32 slot names.
Methods
has()
has(
name):boolean
Reports whether a name is declared.
Parameters
name
string
The layer name.
Returns
boolean
true when the name resolves to a slot.
indexOf()
indexOf(
name):number
Resolves a layer name to its slot.
Parameters
name
string
The layer name.
Returns
number
The slot index, or -1 when the project does not declare the name.
mask()
mask(...
names):LayerMask
Builds a mask from layer names — the ergonomic form scripts use, reached as
world.layers.mask("Player", "Enemy").
Parameters
names
...readonly string[]
The layer names to include.
Returns
The mask.
Throws
IgnifxError with code IGX-0303 when a name is not declared.
Example
const hostiles = this.world.layers.mask("Enemy", "Projectile");
if (hostiles.has(other.layer)) {
this.takeDamage();
}nameOf()
nameOf(
index):string|null
The name of a slot.
Parameters
index
number
The slot index.
Returns
string | null
The name, or null when the slot is out of range or unassigned.
requireIndex()
requireIndex(
name):number
Resolves a layer name to its slot, requiring it to exist.
Parameters
name
string
The layer name.
Returns
number
The slot index.
Throws
IgnifxError with code IGX-0303 when the project does not declare the name. Scene
loading* is more forgiving: an unknown name in a file resolves to Default with the same code
reported as a diagnostic (docs/architecture/02-scene-graph.md §7).
Light
A light source (docs/architecture/07-rendering.md §2.2).
Remarks
The entity's transform defines the light: a directional or spot light points along the entity's
local +Z, a point light sits at its origin, and a hemispheric light's sky direction is its local
+Y.
Example
const sun = world.createEntity("Sun");
sun.transform.lookAt({ x: 0, y: 0, z: 0 });
sun.addComponent(Light, { type: "directional", intensity: 3, shadows: { enabled: true } });Extends
Implements
Constructors
Constructor
new Light():
Light
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
At most one light per entity: two lights from one transform want two entities.
color
color:
ColorLike
exclude
exclude: (
Entity|null)[]
groundColor
groundColor:
ColorLike
includeOnly
includeOnly: (
Entity|null)[]
intensity
intensity:
number
range
range:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
shadows
shadows:
LightShadowSettings
spotAngle
spotAngle:
number
spotExponent
spotExponent:
number
type
type:
"directional"|"point"|"spot"|"hemispheric"
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
isCastingShadows
Get Signature
get isCastingShadows():
boolean
Whether this light currently casts shadows — which needs the shadows rendering feature, a
light kind Lite can shadow, and shadows.enabled.
Returns
boolean
true when a shadow generator is attached.
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.
Whether the owner has already been destroyed.
Inherited from
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 light this component owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
object
The light and its shadow generator, either of which may be null.
light
readonlylight:LiteLight|null
shadowGenerator
readonlyshadowGenerator:ShadowGenerator|null
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Records that the component exists; the Lite light is built on the first sync.
Returns
void
Implementation of
onDetach()
onDetach():
void
Removes the light from the scene and releases its shadow generator.
Returns
void
Implementation of
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
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
LoadingScreen
A full-overlay loading panel.
Example
const screen = new LoadingScreen(app.ui, { label: "Loading…" });
screen.bindTo(app.assets);
await app.assets.preloadGroup("boot").promise;
screen.hide();Constructors
Constructor
new LoadingScreen(
host,options?):LoadingScreen
Builds the screen and mounts it.
Parameters
host
The overlay host, normally app.ui.
options?
The layer, the label, and the initial visibility.
Returns
Accessors
element
Get Signature
get element():
HTMLDivElement|null
The screen's outermost element, so a template can restyle it or add a logo.
Returns
HTMLDivElement | null
The element, or null when the app has no DOM overlay.
isVisible
Get Signature
get isVisible():
boolean
Whether the screen is shown.
Returns
boolean
true while it is on screen.
onDismissed
Get Signature
get onDismissed():
SignalLike
Emitted after LoadingScreen.hide, whatever caused it.
Returns
The signal.
progress
Get Signature
get progress():
number
How far along the bar is, in [0, 1]. Writing it moves the bar; values outside the range are
clamped.
Returns
number
The fraction.
Set Signature
set progress(
value):void
Parameters
value
number
Returns
void
Methods
bindTo()
bindTo(
assets):Disconnect
Follows an asset service's aggregate progress until LoadingScreen.dispose or a second call to this method.
Parameters
assets
The asset service, normally app.assets.
Returns
A function that stops following.
dispose()
dispose():
void
Removes the screen and stops following the asset service.
Returns
void
hide()
hide():
void
Hides the screen and emits LoadingScreen.onDismissed.
Returns
void
setLabel()
setLabel(
text):void
Replaces the label.
Parameters
text
string
The new label.
Returns
void
show()
show():
void
Shows the screen.
Returns
void
LocaleAsset
A loaded translation document (docs/architecture/05-assets-and-loading.md §5).
Remarks
Pure data: it loads identically under Node and in a browser and has nothing to release.
Example
const strings = await app.assets.loadAsync<LocaleAsset>("ui/strings.i18n.json");
strings.value.availableLocales; // ["en", "fr"]Properties
address
readonlyaddress:string
The address the document was loaded from.
assetType
staticassetType:string
The type name the asset service registers translation documents under.
document
readonlydocument:LocaleDocument
The parsed document.
Accessors
availableLocales
Get Signature
get availableLocales(): readonly
string[]
Every locale the document declares, sorted.
Returns
readonly string[]
The BCP 47 tags.
LodGroup
A distance-based renderer switch.
Example
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
Implements
Constructors
Constructor
new LodGroup():
LodGroup
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Turns every level off, so a disabled group leaves nothing drawn.
Returns
void
Implementation of
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
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
LodSystem
Evaluates every LodGroup against the main camera.
Implements
Constructors
Constructor
new LodSystem():
LodSystem
Returns
Properties
name
readonlyname:"ignifx/3d-lod"="ignifx/3d-lod"
The name diagnostics and error reports use.
Implementation of
Methods
update()
update(
ctx):void
Measures each group's distance from the camera and switches it.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
Mat4
A 4×4 transformation matrix stored column-major in a Float32Array, byte-compatible with WGSL's
mat4x4<f32> and with Babylon Lite's Mat4 (translation in slots 12/13/14).
ignifx is left-handed, Y up, +Z forward (ADR-0011), so the projection helpers are the LH
family and they use Lite's reverse depth convention: the near plane maps to 1 and the far
plane to 0.
Instance methods mutate the matrix and return this; ToRef statics write into their out
matrix and allocate nothing, and are safe when out aliases an input. The remaining statics
allocate a fresh matrix and say so.
Example
const world = new Mat4();
Mat4.composeToRef(position, rotation, scale, world);
const inverse = new Mat4();
if (Mat4.invertToRef(world, inverse)) {
Mat4.transformPointToRef(inverse, worldPoint, localPoint);
}Constructors
Constructor
new Mat4():
Mat4
Creates an identity matrix.
Returns
Properties
elements
readonlyelements:Mat4Elements
The 16 elements, column-major (elements[column * 4 + row]). This is the object to hand to
anything that wants a Mat4Like — including Babylon Lite — and the buffer to upload to
the GPU. It is never reallocated, so a reference to it stays valid for the matrix's lifetime.
Methods
clone()
clone():
Mat4
Copies this matrix into a new one.
Returns
A new matrix. Allocates.
compose()
staticcompose(position,rotation,scale):Mat4
Builds a translation-rotation-scale matrix, the same composition order Babylon Lite's
mat4Compose uses (translation * rotation * scale).
Parameters
position
The translation, in metres.
rotation
The rotation; assumed to be a unit quaternion.
scale
The per-axis scale.
Returns
A new matrix. Allocates.
composeToRef()
staticcomposeToRef(position,rotation,scale,out):Mat4
Writes a translation-rotation-scale matrix into out.
Parameters
position
The translation, in metres.
rotation
The rotation; assumed to be a unit quaternion.
scale
The per-axis scale.
out
The matrix to write.
Returns
out.
Example
Mat4.composeToRef(transform.localPosition, transform.localRotation, transform.localScale, local);copyFrom()
copyFrom(
m):this
Copies every element from another matrix.
Parameters
m
The matrix to read.
Returns
this
This matrix.
decomposeToRef()
staticdecomposeToRef(m,outPosition,outRotation,outScale):boolean
Splits an affine transformation-rotation-scale matrix back into its parts, using Babylon Lite's
convention (lib/math/mat4-decompose.js): scales are the lengths of the basis columns, and a
mirrored matrix (negative basis determinant) reports a negative Y scale rather than
silently dropping the reflection. Shear is not detected.
Parameters
m
The matrix to split.
outPosition
Receives the translation.
outRotation
Receives the rotation as a unit quaternion.
outScale
Receives the per-axis scale.
Returns
boolean
true on success; false when a basis column has (near) zero length, in which case
the outputs are left untouched.
Example
Mat4.decomposeToRef(node.worldMatrix, position, rotation, scale);determinant()
staticdeterminant(m):number
The full 4×4 determinant.
Parameters
m
The matrix to measure.
Returns
number
The determinant; zero means the matrix cannot be inverted.
determinant()
determinant():
number
The full 4×4 determinant of this matrix.
Returns
number
The determinant; zero means the matrix cannot be inverted.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two matrices element by element, with a tolerance.
Parameters
a
The first matrix.
b
The second matrix.
epsilon?
number
The largest per-element difference still considered equal.
Returns
boolean
true when every element matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
m,epsilon?):boolean
Compares this matrix with another element by element, with a tolerance.
Parameters
m
The matrix to compare against.
epsilon?
number
The largest per-element difference still considered equal.
Returns
boolean
true when every element matches within epsilon.
from()
staticfrom(m):Mat4
Creates a matrix holding a copy of another matrix's elements.
Parameters
m
The matrix to copy.
Returns
A new matrix. Allocates.
fromQuat()
staticfromQuat(q):Mat4
Builds a pure rotation matrix from a quaternion.
Parameters
q
The rotation; assumed to be a unit quaternion.
Returns
A new matrix. Allocates.
fromQuatToRef()
staticfromQuatToRef(q,out):Mat4
Writes a pure rotation matrix into out.
Parameters
q
The rotation; assumed to be a unit quaternion.
out
The matrix to write.
Returns
out.
getRotationToRef()
staticgetRotationToRef<TOut>(m,out):TOut
Reads a matrix's rotation, dividing the scale out of the basis first.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
m
The matrix to read.
out
TOut
The quaternion to write. Left untouched when a basis column has zero length.
Returns
TOut
out.
getScaleToRef()
staticgetScaleToRef<TOut>(m,out):TOut
Reads a matrix's per-axis scale as the lengths of its basis columns, negating Y for a mirrored matrix exactly as Mat4.decomposeToRef does.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
m
The matrix to read.
out
TOut
The vector to write.
Returns
TOut
out.
getTranslationToRef()
staticgetTranslationToRef<TOut>(m,out):TOut
Reads a matrix's translation.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
m
The matrix to read.
out
TOut
The vector to write.
Returns
TOut
out.
identity()
staticidentity():Mat4
Creates an identity matrix.
Returns
A new identity matrix. Allocates.
identity()
identity():
this
Resets this matrix to the identity.
Returns
this
This matrix.
invert()
invert():
boolean
Inverts this matrix in place.
Returns
boolean
true on success. When the matrix is singular this returns false and leaves the
matrix untouched.
invertToRef()
staticinvertToRef(m,out):boolean
Writes the inverse of m into out.
Parameters
m
The matrix to invert.
out
The matrix to write; may alias m. Left untouched when the inverse does not exist.
Returns
boolean
true on success, false when m is singular. Returning a status rather than null
keeps the call allocation-free (coding standards §7).
Example
if (!Mat4.invertToRef(world, worldToLocal)) {
// degenerate scale — skip this entity
}lookAtLH()
staticlookAtLH(eye,target,up):Mat4
Builds a left-handed view matrix that places the camera at eye looking at target.
Parameters
eye
The camera position, in metres.
target
The point to look at, in metres.
up
The camera's up direction.
Returns
A new matrix. Allocates.
lookAtLHToRef()
staticlookAtLHToRef(eye,target,up,out):Mat4
Writes a left-handed view matrix into out. Reproduces Babylon Lite's mat4LookAtLHToRef,
including its degenerate-input behaviour: when eye and target coincide, or when up is
parallel to the view direction, out becomes the identity.
Parameters
eye
The camera position, in metres.
target
The point to look at, in metres.
up
The camera's up direction.
out
The matrix to write.
Returns
out.
multiply()
staticmultiply(a,b):Mat4
Multiplies two matrices.
Parameters
a
The left-hand matrix.
b
The right-hand matrix.
Returns
A new matrix holding a * b. Allocates.
multiply()
multiply(
m):this
Post-multiplies this matrix by another (this = this * m), so m's transform is applied first
when the product acts on a column vector.
Parameters
m
The right-hand matrix.
Returns
this
This matrix.
multiplyToRef()
staticmultiplyToRef(a,b,out):Mat4
Writes a * b into out. Acting on a column vector, b is applied first.
Parameters
a
The left-hand matrix.
b
The right-hand matrix.
out
The matrix to write; may alias a or b.
Returns
out.
orthoLH()
staticorthoLH(width,height,near,far):Mat4
Builds a centred left-handed orthographic projection.
Parameters
width
number
The view width, in metres.
height
number
The view height, in metres.
near
number
The near plane distance, in metres.
far
number
The far plane distance, in metres.
Returns
A new matrix. Allocates.
orthoLHToRef()
staticorthoLHToRef(width,height,near,far,out):Mat4
Writes a centred left-handed orthographic projection into out, with the same reverse-depth
convention as Mat4.perspectiveLHToRef.
Parameters
width
number
The view width, in metres.
height
number
The view height, in metres.
near
number
The near plane distance, in metres.
far
number
The far plane distance, in metres.
out
The matrix to write.
Returns
out.
orthoOffCenterLHToRef()
staticorthoOffCenterLHToRef(left,right,bottom,top,near,far,out):Mat4
Writes an off-centre left-handed orthographic projection into out, reproducing Babylon Lite's
mat4OrthoOffCenterLHToRef (reverse depth).
Parameters
left
number
The left clip plane, in metres.
right
number
The right clip plane, in metres.
bottom
number
The bottom clip plane, in metres.
top
number
The top clip plane, in metres.
near
number
The near plane distance, in metres.
far
number
The far plane distance, in metres.
out
The matrix to write.
Returns
out.
perspectiveLH()
staticperspectiveLH(fovDegrees,aspect,near,far):Mat4
Builds a left-handed perspective projection.
Parameters
fovDegrees
number
The vertical field of view, in degrees.
aspect
number
The viewport's width divided by its height.
near
number
The near plane distance, in metres.
far
number
The far plane distance, in metres.
Returns
A new matrix. Allocates.
perspectiveLHToRef()
staticperspectiveLHToRef(fovDegrees,aspect,near,far,out):Mat4
Writes a left-handed perspective projection into out, matching Babylon Lite's
mat4PerspectiveLHToRef — which is a reverse-depth projection: the near plane maps to
clip-space depth 1 and the far plane to 0, the arrangement that keeps float depth precise.
Parameters
fovDegrees
number
The vertical field of view, in degrees.
aspect
number
The viewport's width divided by its height.
near
number
The near plane distance, in metres.
far
number
The far plane distance, in metres.
out
The matrix to write.
Returns
out.
scaling()
staticscaling(x,y,z):Mat4
Builds a pure scaling matrix.
Parameters
x
number
Scale along X.
y
number
Scale along Y.
z
number
Scale along Z.
Returns
A new matrix. Allocates.
scalingToRef()
staticscalingToRef(x,y,z,out):Mat4
Writes a pure scaling matrix into out.
Parameters
x
number
Scale along X.
y
number
Scale along Y.
z
number
Scale along Z.
out
The matrix to write.
Returns
out.
transformDirectionToRef()
statictransformDirectionToRef<TOut>(m,direction,out):TOut
Transforms a direction by a matrix, ignoring translation. Note that this is the plain basis transform: a non-uniformly scaled matrix needs its inverse-transpose to keep normals correct.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
m
The transformation.
direction
The direction to transform.
out
TOut
The vector to write; may alias direction.
Returns
TOut
out.
transformPointToRef()
statictransformPointToRef<TOut>(m,point,out):TOut
Transforms a point by a matrix, applying translation and the perspective divide.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
m
The transformation.
point
The point to transform, in metres.
out
TOut
The vector to write; may alias point.
Returns
TOut
out.
translation()
statictranslation(x,y,z):Mat4
Builds a pure translation matrix.
Parameters
x
number
Translation along X, in metres.
y
number
Translation along Y, in metres.
z
number
Translation along Z, in metres.
Returns
A new matrix. Allocates.
translationToRef()
statictranslationToRef(x,y,z,out):Mat4
Writes a pure translation matrix into out.
Parameters
x
number
Translation along X, in metres.
y
number
Translation along Y, in metres.
z
number
Translation along Z, in metres.
out
The matrix to write.
Returns
out.
transpose()
transpose():
this
Transposes this matrix in place, swapping rows and columns.
Returns
this
This matrix.
transposeToRef()
statictransposeToRef(m,out):Mat4
Writes the transpose of m into out.
Parameters
m
The matrix to transpose.
out
The matrix to write; may alias m.
Returns
out.
MaterialAsset
A material a MeshRenderer or a Model draws with
(docs/architecture/07-rendering.md §2.6).
Remarks
Materials are shared: many renderers reference one asset, and editing it changes all of them. MaterialAsset.clone is the per-renderer variation escape hatch — it rebuilds the Lite material from the same declaration, so the copy starts identical and drifts on its own.
Example
const gold = await app.assets.loadAsync<MaterialAsset>("materials/gold.material.json");
using warm = gold.value.clone(app);
warm.value.setBaseColor({ r: 1, g: 0.6, b: 0.2, a: 1 });Properties
assetType
staticassetType:string
The type name the asset service registers materials under.
definition
readonlydefinition:MaterialDefinition
The declaration this material was built from; MaterialAsset.clone replays it.
textures
readonlytextures: readonlyAssetHandle<TextureAsset>[]
The texture handles the material samples, in slot order. It does not own them.
Accessors
kind
Get Signature
get kind():
"standard"|"pbr"|"shader"
The material family.
Returns
"standard" | "pbr" | "shader"
"pbr" or "standard".
lite
Get Signature
get lite():
MaterialAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch.
Returns
The Lite material.
name
Get Signature
get name():
string
The material's human-readable name.
Returns
string
The declared name.
Methods
clone()
clone(
app):AssetHandle<MaterialAsset>
Builds an independent copy of this material from the same declaration — the per-renderer
variation path of docs/architecture/07-rendering.md §2.6.
Parameters
app
The app whose asset service publishes the copy.
Returns
The copy's handle, with one holder — the caller.
Remarks
The copy shares the original's textures (they are addressed assets, and the handles are retained by whoever loaded them) and nothing else: it is a second Lite material in the same family, so it costs no extra shader compilation.
setAlpha()
setAlpha(
alpha):void
Replaces the material's overall alpha.
Parameters
alpha
number
The new alpha, 0 to 1.
Returns
void
setBaseColor()
setBaseColor(
color):void
Replaces the base colour — the PBR baseColorFactor, or a Standard material's diffuseColor.
Parameters
color
The new sRGB colour. Alpha is used by PBR and ignored by Standard, which carries
its own alpha.
Returns
void
Remarks
The colour is sRGB, like every colour in ignifx's public API; the linear value the shader reads
is derived here. The change marks the material's uniform block dirty, which is the cheap path:
no pipeline is recompiled (src/lite/material.ts).
setMetallicRoughness()
setMetallicRoughness(
metallic,roughness):void
Replaces the metallic and roughness factors of a "pbr" material. A Standard material has
neither, so the call is ignored.
Parameters
metallic
number
The metallic factor, 0 to 1.
roughness
number
The roughness factor, 0 to 1.
Returns
void
MemoryStorageBackend
A store that lives as long as the app does.
Example
const app = await createApp({ storage: new MemoryStorageBackend() });Implements
Constructors
Constructor
new MemoryStorageBackend():
MemoryStorageBackend
Returns
Properties
name
readonlyname:"memory"="memory"
The identifier that appears in error context.
Implementation of
Methods
clear()
clear(
namespace):Promise<void>
Empties one namespace.
Parameters
namespace
string
The namespace path.
Returns
Promise<void>
A promise that settles once the namespace is empty.
Implementation of
delete()
delete(
namespace,key):Promise<void>
Removes one value.
Parameters
namespace
string
The namespace path.
key
string
The key.
Returns
Promise<void>
A promise that settles once the value is gone.
Implementation of
dispose()
dispose():
void
Drops every namespace.
Returns
void
Implementation of
get()
get(
namespace,key):Promise<StoredValue|null>
Reads one value.
Parameters
namespace
string
The namespace path.
key
string
The key.
Returns
Promise<StoredValue | null>
A copy of the stored value, or null.
Implementation of
keys()
keys(
namespace,prefix?):Promise<readonlystring[]>
Lists one namespace's keys.
Parameters
namespace
string
The namespace path.
prefix?
string
An optional key prefix.
Returns
Promise<readonly string[]>
The matching keys, sorted ascending.
Implementation of
set()
set(
namespace,key,value):Promise<void>
Writes one value.
Parameters
namespace
string
The namespace path, created on demand.
key
string
The key.
value
The value to copy in.
Returns
Promise<void>
A promise that settles once the value is stored.
Implementation of
MeshAsset
A geometry template a MeshRenderer draws (docs/architecture/07-rendering.md §2.3).
Remarks
Build one with a primitive factory or MeshAsset.fromData; each returns the handle the
MeshRenderer.mesh field takes. A mesh that came from a file arrives as part of a ModelAsset
instead — a glTF is a tree of meshes, materials, and animations, not one buffer.
Example
using box = MeshAsset.box(app, { size: 2 });
const cube = app.world.createEntity("Cube");
cube.addComponent(MeshRenderer, { mesh: box.retain() });Properties
assetType
staticassetType:string
The type name the asset service registers meshes under.
name
readonlyname:string
A human-readable name, used in diagnostics and as the Lite mesh's name.
Accessors
isDisposed
Get Signature
get isDisposed():
boolean
Whether the template's GPU buffers have been released.
Returns
boolean
true once MeshAsset.dispose has run.
lite
Get Signature
get lite():
MeshAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
The template mesh, or null under a headless app.
Methods
[dispose]()
[dispose]():
void
Releases the template when the asset leaves a using block.
Returns
void
box()
staticbox(app,options?):AssetHandle<MeshAsset>
Creates a box template and publishes it.
Parameters
app
The app whose engine uploads the geometry and whose asset service holds the handle.
options?
A uniform size, or per-axis dimensions.
Returns
The handle, with one holder — the caller.
Example
const box = MeshAsset.box(app, { width: 2, height: 1, depth: 3 });capsule()
staticcapsule(app,options?):AssetHandle<MeshAsset>
Creates a capsule template standing along Y and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
Total height, radius, and tessellation.
Returns
The handle, with one holder.
cylinder()
staticcylinder(app,options?):AssetHandle<MeshAsset>
Creates a cylinder template standing along Y and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
Height, diameters, and tessellation.
Returns
The handle, with one holder.
dispose()
dispose():
void
Releases the template's GPU buffers.
Returns
void
Remarks
Lite exports no mesh disposer: a mesh's buffers are freed when it leaves its last scene, so the
adapter adds the template to a scene and takes it straight out again
(src/lite/gpu/mesh.ts). Clones still in a scene keep the shared buffers alive; what the
template loses is the ability to be cloned again. Calling it twice is a no-op, and it is a
no-op under a headless app, which has no buffers.
fromData()
staticfromData(app,name,data):AssetHandle<MeshAsset>
Creates a template from raw vertex data and publishes it.
Parameters
app
The app that owns the engine and the asset service.
name
string
A human-readable name.
data
Positions, normals, indices, and optional texture coordinates. Lite keeps references to the arrays; do not mutate them afterwards.
Returns
The handle, with one holder.
Example
const triangle = MeshAsset.fromData(app, "triangle", {
positions: Float32Array.from([0, 0, 0, 1, 0, 0, 0, 1, 0]),
normals: Float32Array.from([0, 0, -1, 0, 0, -1, 0, 0, -1]),
indices: Uint32Array.from([0, 1, 2]),
});ground()
staticground(app,options?):AssetHandle<MeshAsset>
Creates a subdivided grid in the XZ plane and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
Width, depth, subdivisions, and UV scale.
Returns
The handle, with one holder.
plane()
staticplane(app,options?):AssetHandle<MeshAsset>
Creates a quad template in the XY plane and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
A uniform size, or width and height.
Returns
The handle, with one holder.
sphere()
staticsphere(app,options?):AssetHandle<MeshAsset>
Creates a sphere template and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
Diameter and ring count.
Returns
The handle, with one holder.
torus()
statictorus(app,options?):AssetHandle<MeshAsset>
Creates a torus template in the XZ plane and publishes it.
Parameters
app
The app that owns the engine and the asset service.
options?
Diameter, thickness, and tessellation.
Returns
The handle, with one holder.
MeshCollider
A collider built from real geometry: either an explicit MeshAsset or, when mesh is
null, whatever the entity's MeshRenderer/Model put under its node.
Remarks
Headless is not supported. @babylonjs/[email protected] documents mesh and convex-hull colliders
as unavailable on the null engine (index.d.ts 2781), and a headless MeshAsset uploads no
geometry at all (MeshAsset.lite.mesh is null), so building one reports IGX-0906 instead of
producing an empty shape. Use a primitive collider in headless tests.
Extends
Constructors
Constructor
new MeshCollider():
MeshCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
convex
convex:
boolean
includeChildren
includeChildren:
boolean
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
mesh
mesh:
AssetHandle<MeshAsset> |null
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,_scale,node):PhysicsShape
Builds this collider's Havok shape from real geometry.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
_scale
Unused: a mesh shape carries the geometry's own world scale.
node
SceneNode
The entity's node, whose meshes supply the vertices when mesh is null.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
_scale,out):void
Writes half the size of this collider's local bounding box — zero, because measuring a triangle soup means reading its vertices, which is GPU territory.
Parameters
_scale
Unused.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
MeshRenderer
Draws a mesh asset with a material (docs/architecture/07-rendering.md §2.3).
Example
using box = MeshAsset.box(app, { size: 1 });
const cube = world.createEntity("Cube");
cube.addComponent(MeshRenderer, { mesh: box.retain(), castShadows: true });Extends
Implements
Constructors
Constructor
new MeshRenderer():
MeshRenderer
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several renderers on one entity draw several meshes from one transform, which is useful.
castShadows
castShadows:
boolean
materials
materials: (
AssetHandle<MaterialAsset> |null)[]
mesh
mesh:
AssetHandle<MeshAsset> |null
pickable
pickable:
boolean
receiveShadows
receiveShadows:
boolean
renderOrder
renderOrder:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
isVisible
Get Signature
get isVisible():
boolean
Whether the mesh is currently drawn: its own enabled flag and its entity's
activeInHierarchy, materialised onto Lite's visible.
Returns
boolean
true when the clone is visible.
lite
Get Signature
get lite():
object
The Babylon Lite mesh this renderer draws. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
object
The clone, or null when there is nothing to draw.
mesh
readonlymesh:SceneNode|null
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Nothing to do at attach: the clone is built on the first sync, once mesh has been decoded.
Returns
void
Implementation of
onDetach()
onDetach():
void
Removes the clone from the scene, releasing its share of the template's buffers.
Returns
void
Implementation of
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
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
Model
One instance of a loaded model (docs/architecture/07-rendering.md §2.4).
Example
const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
const entity = world.createEntity("Hero");
const model = entity.addComponent(Model, { model: hero.retain() });
model.attachToNode("hand.R", sword);Extends
Implements
Constructors
Constructor
new Model():
Model
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One model per entity: a second instance under the same transform wants its own entity.
castShadows
castShadows:
boolean
materialOverrides
materialOverrides:
Record<string,AssetHandle<MaterialAsset> |null>
model
model:
AssetHandle<ModelAsset> |null
pickable
pickable:
boolean
receiveShadows
receiveShadows:
boolean
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
typeId
statictypeId:string
The namespaced registration id.
Accessors
animations
Get Signature
get animations(): readonly
AnimationGroup[]
Beta
The clips the file declared.
Remarks
Unstable: these are Lite's own animation groups, and ignifx does not advance them in Phase 2
(ADR-0003 — @ignifx/3d's animator owns playback).
Returns
readonly AnimationGroup[]
The clips, in load order.
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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 instance owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
object
The cloned root, or null when there is nothing instantiated.
root
readonlyroot:SceneNode|null
nodes
Get Signature
get nodes():
ReadonlyMap<string,SceneNode>
The glTF nodes of this instance, by their names in the file.
Remarks
The map is the instance's own, so two Models of one asset never hand out each other's nodes.
It is empty until the asset is loaded, and under a headless app.
Returns
ReadonlyMap<string, SceneNode>
The nodes, keyed by glTF node name.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
skeletons
Get Signature
get skeletons(): readonly
Skeleton[]
Beta
The skeletons the file declared. Empty unless the boneControl rendering feature was on before
the asset loaded.
Returns
readonly Skeleton[]
The skeletons.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
attachToNode()
attachToNode(
nodeName,entity):boolean
Parents an entity under one of the model's glTF nodes — the "weapon in hand" case
(docs/architecture/07-rendering.md §2.4).
Parameters
nodeName
string
The glTF node name, as the file spells it.
entity
The entity to attach.
Returns
boolean
true when the node exists and the entity was attached.
Remarks
The entity keeps its local transform, so it lands at the node's origin and then follows it
for free: Lite composes parentWorld × local on every read, so a bone attachment costs no
per-frame work at all. Detach by re-parenting the entity in the ordinary way.
Example
model.attachToNode("hand.R", sword);define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Nothing to do at attach: the instance is built on the first sync, once model is decoded.
Returns
void
Implementation of
onDetach()
onDetach():
void
Removes the instance from the scene and gives back its share of the template's buffers.
Returns
void
Implementation of
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
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
ModelAsset
A loaded glTF or GLB file (docs/architecture/05-assets-and-loading.md §5).
Example
const hero = await app.assets.loadAsync<ModelAsset>("models/hero.glb");
hero.value.animations.map((clip) => clip.name);Properties
address
readonlyaddress:string
The address the model was loaded from.
animations
readonlyanimations: readonlyAnimationGroup[]
Beta
The clips the file declared, stripped from the container so Lite never ticks them.
Remarks
Unstable: these are Lite's own animation groups, handed on to @ignifx/3d's animator, and they
are excluded from the stability guarantees of CONSTITUTION.md Article IV. A Model re-binds
them per instance when the animation system lands; in Phase 2 they are read-only metadata.
assetType
staticassetType:string
The type name the asset service registers models under.
skeletons
readonlyskeletons: readonlySkeleton[]
Beta
The skeletons the file declared. Empty unless the boneControl rendering feature was on before
the load, because Lite builds them only then (index.d.ts 653).
Accessors
instanceCount
Get Signature
get instanceCount():
number
How many Model components currently hold a copy of this template.
Returns
number
The live instance count.
lite
Get Signature
get lite():
ModelAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch.
Returns
The template container, or null under a headless app.
Methods
[dispose]()
[dispose]():
void
Releases the template when the asset leaves a using block.
Returns
void
dispose()
dispose():
void
Releases the template's GPU resources.
Returns
void
Remarks
The container was never added to a scene, so the round trip removeFromScene needs is the same
one MeshAsset.dispose performs: this hands it to the scene and takes it straight back out,
which drops its share of every buffer. Clones still in a scene keep theirs. Calling it twice is
a no-op, and it is a no-op under a headless app.
instantiate()
instantiate(
parent):ModelInstantiation|null
Clones the template under an entity's node.
Parameters
parent
SceneNode | null
The entity's transform node, or null for world space.
Returns
ModelInstantiation | null
The cloned root and its named nodes, or null when there is nothing to clone — a
headless app, or a file that declared only lights.
releaseInstance()
releaseInstance():
void
Records that one fewer Model holds a copy. Releasing below zero is a no-op.
Returns
void
retainInstance()
retainInstance():
void
Records that one more Model holds a copy.
Returns
void
MusicPlayer
A music track player with a playlist and crossfading.
Example
const jukebox = world.createEntity("Music");
const music = jukebox.addComponent(MusicPlayer, { autoAdvance: true, crossfadeSeconds: 3 });
music.play(menuTheme.value, { fadeIn: 1.5 });
// …later…
music.crossfadeTo(battleTheme.value, 2);Extends
Implements
Constructors
Constructor
new MusicPlayer():
MusicPlayer
Applies the schema defaults, exactly as Script.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One music player per entity.
autoAdvance
autoAdvance:
boolean
Whether a track that ends crossfades into the next one.
bus
bus:
string
Which mixer bus the music routes into.
crossfadeSeconds
crossfadeSeconds:
number
How long a crossfade takes, in seconds.
loopPlaylist
loopPlaylist:
boolean
Whether the playlist wraps after its last entry.
loopTrack
loopTrack:
boolean
Whether the current track repeats instead of ending.
playlist
playlist: (
AssetHandle<AudioClip> |null)[]
The tracks, in the order they are played.
playOnAwake
playOnAwake:
boolean
Whether to start the first playlist entry as soon as the entity is alive.
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
typeId
statictypeId:string
The registration id the serializer and the inspector know this class by.
volume
volume:
number
The gain a track fades up to, in [0, 1].
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
current
Get Signature
get current():
SoundInstance|null
The track that is playing.
Returns
SoundInstance | null
The sound, or null when nothing is playing.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
index
Get Signature
get index():
number
Which entry of playlist is playing.
Returns
number
The index, or -1 when the current track did not come from the playlist.
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.
Whether the owner has already been destroyed.
Inherited from
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
isPlaying
Get Signature
get isPlaying():
boolean
Whether music is sounding.
Returns
boolean
true while a track is playing or waiting behind the unlock.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
previous
Get Signature
get previous():
SoundInstance|null
The track that is fading out, while a crossfade is in progress.
Returns
SoundInstance | null
The outgoing sound, or null.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Starts the first playlist entry when playOnAwake is set.
Returns
void
Implementation of
crossfadeTo()
crossfadeTo(
clip,seconds?):SoundInstance
Fades the current track out while fading a new one in.
Parameters
clip
The track to fade in.
seconds?
number
How long both fades take; defaults to crossfadeSeconds.
Returns
The incoming sound.
Example
music.crossfadeTo(battleTheme.value, 3);define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
next()
next():
SoundInstance|null
Crossfades to the next playlist entry, wrapping when loopPlaylist is set.
Returns
SoundInstance | null
The incoming sound, or null when the playlist has nothing left to play.
onDestroy()
onDestroy():
void
Stops the music and releases both voices.
Returns
void
Implementation of
play()
play(
clip,options?):SoundInstance
Plays a track, replacing whatever was playing.
Parameters
clip
The track.
options?
How long to fade the new track up over.
Returns
The sound.
Example
music.play(theme.value, { fadeIn: 2 });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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stop()
stop(
options?):void
Stops the music.
Parameters
options?
How long to fade out over; omitted stops now.
Returns
void
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
NavigationService
The app.navigation service.
Example
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
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
The point, in world space.
out?
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): readonlyVec3[]
Computes a path across the primary surface.
Parameters
from
The start, in world space.
to
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
The start, in world space.
to
The end, in world space.
out?
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
Constructors
Constructor
new NavigationSystem(
service):NavigationSystem
Builds the system.
Parameters
service
The service that owns the Recast plugin.
Returns
Properties
name
readonlyname:"ignifx/3d-navigation"="ignifx/3d-navigation"
The name diagnostics and error reports use.
Implementation of
Methods
update()
update(
ctx):void
Bakes what has to be baked, steps every crowd, and writes the agents back.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
NavMeshAgent
A crowd agent.
Example
const agent = companion.addComponent(NavMeshAgent, { speed: 4, stoppingDistance: 0.5 });
agent.onArrived.connect(() => animator.play("idle"), { owner: agent });
agent.setDestination(player.transform.position);Extends
Implements
Constructors
Constructor
new NavMeshAgent():
NavMeshAgent
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
acceleration
acceleration:
number
How hard the agent accelerates.
allowMultiple
staticallowMultiple:boolean
One agent per entity.
height
height:
number
The agent's height, in metres.
radius
radius:
number
The agent's radius, in metres.
schema
staticschema: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
statictypeId:string
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
The app.
Inherited from
destination
Get Signature
get destination():
Vec3Like
Where the agent was last told to go. Reused each frame.
Returns
Where the agent was last told to go. Reused each frame.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Fires once each time the agent reaches its destination.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
velocity
Get Signature
get velocity():
Vec3Like
The agent's current world velocity, as the crowd reports it. Reused each frame.
Returns
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
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Forgets the crowd slot, which Lite cannot free.
Returns
void
Implementation of
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
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
setDestination()
setDestination(
point):boolean
Sends the agent to a point.
Parameters
point
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
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
crate.addComponent(NavMeshObstacle, { shape: "box", size: { x: 1, y: 1, z: 1 } });Extends
Implements
Constructors
Constructor
new NavMeshObstacle():
NavMeshObstacle
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One obstacle per entity.
height
height:
number
The cylinder's height, in metres.
radius
radius:
number
The cylinder's radius, in metres.
schema
staticschema: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
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Fills the hole back in.
Returns
void
Implementation of
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
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
NavMeshSurface
One baked navmesh.
Example
const surface = level.addComponent(NavMeshSurface, { agentRadius: 0.4, maxObstacles: 8 });
surface.onBaked.connect(() => app.log.info("navmesh ready"), { owner: surface });
await surface.bake();Extends
Implements
Constructors
Constructor
new NavMeshSurface():
NavMeshSurface
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
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
staticallowMultiple:boolean
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
staticschema:Schema
The declarative fields (ADR-0004).
tileSize
tileSize:
number
Tile size in voxels.
typeId
statictypeId:string
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
The app.
Inherited from
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
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
readonlycrowd:NavCrowd|null
plugin
readonlyplugin:NavigationPlugin|null
onBaked
Get Signature
get onBaked():
Signal<NavMeshSurface>
Fires once each time the surface finishes baking.
Returns
Fires once each time the surface finishes baking.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
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
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
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
The point, in world space.
out?
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()
staticdefine<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
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
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
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
findPath()
findPath(
from,to): readonlyVec3[]
Computes a path across this surface.
Parameters
from
The start, in world space.
to
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Releases the plugin's navmesh, tile cache, and query.
Returns
void
Implementation of
raycast()
raycast(
from,to,out?):MutableVec3|null
Casts a walkability ray across this surface.
Parameters
from
The start, in world space.
to
The end, in world space.
out?
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
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
ParallaxLayer
A parallax layer.
Example
const sky = app.world.createEntity({ name: "sky" }).addComponent(ParallaxLayer);
sky.sortingLayer = "Background";
sky.factor = { x: 0.2, y: 0.5 };Extends
Constructors
Constructor
new ParallaxLayer():
ParallaxLayer
Builds a parallax layer with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One parallax setting per entity; several entities may each drive a different sorting layer.
factor
factor:
Vec2Like
How much of the camera's motion the layer follows, per axis; 1 is no parallax.
repeatHeight
repeatHeight:
number
The world height one repetition spans, in metres.
repeatWidth
repeatWidth:
number
The world width one repetition spans, in metres; 0 disables horizontal repetition.
repeatX
repeatX:
boolean
Whether the layer's sprites repeat horizontally across the camera's view.
repeatY
repeatY:
boolean
Whether the layer's sprites repeat vertically.
schema
staticschema:Schema
The declarative fields (ADR-0004).
sortingLayer
sortingLayer:
string
Which sorting layer this component slows down.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
Physics2DService
The service behind app.physics2d.
Example
const hit = app.physics2d.raycast({ x: 0, y: 5 }, { x: 0, y: -1 }, 20);
if (hit !== null) {
app.log.info("ray hit {name} at {y}", hit.entity.name, hit.point.y);
}Accessors
gravity
Get Signature
get gravity():
Vec2
World gravity in metres per second squared.
Returns
A live view; writing to it does nothing, assign the property instead.
Set Signature
set gravity(
value):void
Replaces world gravity, which every body feels from the next fixed step.
Parameters
value
The new acceleration vector.
Returns
void
rapier
Get Signature
get rapier():
Physics2DRapierHandles
The Rapier handles.
Returns
The world.
Methods
overlapBox()
overlapBox(
centre,size,rotation?,options?): readonlyEntity[]
Lists the entities a box overlaps.
Parameters
centre
The box's world position.
size
Its full width and height in metres.
rotation?
number
Its rotation in degrees counter-clockwise; defaults to 0.
options?
Layer mask and trigger behaviour.
Returns
readonly Entity[]
The overlapping entities. The array is reused between calls.
Throws
IgnifxError with code IGX-1153 when no fixed step has run yet.
overlapCircle()
overlapCircle(
centre,radius,options?): readonlyEntity[]
Lists the entities a circle overlaps.
Parameters
centre
The circle's world position.
radius
number
Its radius in metres.
options?
Layer mask and trigger behaviour.
Returns
readonly Entity[]
The overlapping entities, in Rapier's order. The array is reused between calls.
Throws
IgnifxError with code IGX-1153 when no fixed step has run yet.
raycast()
raycast(
origin,direction,maxDistance?,options?):RaycastHit2D|null
Casts a ray and returns the first entity it hits.
Parameters
origin
The world-space origin, in metres.
direction
The direction; it is normalised for you.
maxDistance?
number
How far to travel; defaults to 10 km.
options?
Layer mask and trigger behaviour.
Returns
RaycastHit2D | null
The hit, or null when the ray clears everything.
Throws
IgnifxError with code IGX-1153 when no fixed step has run yet.
raycastAll()
raycastAll(
origin,direction,maxDistance?,options?): readonlyRaycastHit2D[]
Casts a ray and returns every entity along it, nearest first.
Parameters
origin
The world-space origin.
direction
The direction; it is normalised for you.
maxDistance?
number
How far to travel; defaults to 10 km.
options?
Layer mask and trigger behaviour.
Returns
readonly RaycastHit2D[]
The hits, in increasing distance. The array is reused between calls.
Throws
IgnifxError with code IGX-1153 when no fixed step has run yet.
shapeCast()
shapeCast(
centre,radius,direction,maxDistance,options?):ShapeCastHit2D|null
Sweeps a circle and returns the first contact.
Parameters
centre
Where the sweep starts.
radius
number
The circle's radius in metres.
direction
The sweep direction; it is normalised for you.
maxDistance
number
How far to sweep.
options?
Layer mask and trigger behaviour.
Returns
ShapeCastHit2D | null
The hit, or null.
Throws
IgnifxError with code IGX-1153 when no fixed step has run yet.
PhysicsMaterial
A loaded surface material. The values are the ones Havok's setPhysicsShapeMaterial takes
(index.d.ts 10853).
Example
const ice = await app.assets.load<PhysicsMaterial>("materials/ice.physicsmaterial.json");
floor.addComponent(BoxCollider, { size: { x: 10, y: 1, z: 10 }, material: ice });Implements
Constructors
Constructor
new PhysicsMaterial(
name,values):PhysicsMaterial
Wraps parsed values. The loader constructs these; game code uses PhysicsMaterial.fromValues when it wants one in code.
Parameters
name
string
A human-readable name.
values
Friction, static friction, and restitution.
Returns
Properties
assetType
staticassetType:string
The asset type token, so asset(PhysicsMaterial) fields resolve.
friction
readonlyfriction:number
The dynamic friction coefficient.
Implementation of
PhysicsMaterialValues.friction
name
readonlyname:string
A human-readable name, used in diagnostics.
restitution
readonlyrestitution:number
How much of the approach speed is returned, 0 to 1.
Implementation of
PhysicsMaterialValues.restitution
staticFriction
readonlystaticFriction:number
The static friction coefficient.
Implementation of
PhysicsMaterialValues.staticFriction
Methods
fromValues()
staticfromValues(name,values):PhysicsMaterial
Builds a material in code, filling in the fields the caller omitted.
Parameters
name
string
A human-readable name.
values
Partial<PhysicsMaterialValues>
Any subset of the three coefficients.
Returns
The material.
Example
const bouncy = PhysicsMaterial.fromValues("bouncy", { restitution: 0.9 });PhysicsMaterial2D
A loaded 2D surface.
Example
const ice = await app.assets.load<PhysicsMaterial2D>("materials/ice.physicsmaterial.json");
floor.addComponent(BoxCollider2D, { size: { x: 10, y: 1 }, material: ice });Implements
Constructors
Constructor
new PhysicsMaterial2D(
name,values):PhysicsMaterial2D
Wraps parsed values.
Parameters
name
string
A human-readable name.
values
Friction and restitution.
Returns
Properties
assetType
staticassetType:string
The asset type token, so asset(PhysicsMaterial2D) fields resolve.
friction
readonlyfriction:number
The friction coefficient.
Implementation of
Physics2DMaterialValues.friction
name
readonlyname:string
A human-readable name, used in diagnostics.
restitution
readonlyrestitution:number
How much of the approach speed is returned, 0 to 1.
Implementation of
Physics2DMaterialValues.restitution
Methods
fromValues()
staticfromValues(name,values):PhysicsMaterial2D
Builds a material in code, filling in the fields the caller omitted.
Parameters
name
string
A human-readable name.
values
Partial<Physics2DMaterialValues>
Any subset of the two coefficients.
Returns
The material.
Example
const bouncy = PhysicsMaterial2D.fromValues("bouncy", { restitution: 0.9 });PhysicsService
The service behind app.physics.
Example
const hit = app.physics.raycast({ x: 0, y: 10, z: 0 }, { x: 0, y: -1, z: 0 }, 20);
if (hit !== null) {
app.log.info("ray hit {name} at {y}", hit.entity.name, hit.point.y);
}Accessors
debugViewer
Get Signature
get debugViewer():
PhysicsDebugViewer
The wireframe overlay.
Returns
The viewer toggle.
gravity
Get Signature
get gravity():
Vec3
World gravity in metres per second squared.
Returns
A live view; writing to it does nothing, assign the property instead.
Set Signature
set gravity(
value):void
Replaces world gravity, which every body feels from the next fixed step.
Parameters
value
The new acceleration vector, in metres per second squared.
Returns
void
hasStepped
Get Signature
get hasStepped():
boolean
Whether at least one fixed step has completed, which is when Havok has built its broadphase and
queries become legal (09-physics.md §5). A script that queries from lateUpdate or update
checks this on the first frame, where the fixed loop may not have run yet, instead of catching
IGX-0902.
Returns
boolean
true once the first step has run.
lite
Get Signature
get lite():
PhysicsLiteHandles
The Babylon Lite handles.
Returns
The Havok world and the simulation scene.
Methods
dispose()
dispose():
void
Releases the viewer, if one is up. Called from the extension's dispose.
Returns
void
distanceToNearest()
distanceToNearest(
shape,position,maxDistance,options?):number
How far the nearest body is from a positioned shape, which is the one thing Lite's
shapeProximity answers exactly.
Parameters
shape
The query shape.
position
Its world position.
maxDistance
number
How far to search.
options?
Trigger behaviour.
Returns
number
The distance, or Number.POSITIVE_INFINITY when nothing is in range.
Throws
IgnifxError with code IGX-0902 in development when no fixed step has run yet.
isDebugViewerEnabled()
isDebugViewerEnabled():
boolean
Whether the viewer is currently drawing.
Returns
boolean
true when a viewer exists.
overlap()
overlap(
shape,position,rotation?,options?): readonlyEntity[]
Lists the entities a positioned shape overlaps (09-physics.md §5).
Parameters
shape
The query shape.
position
Its world position.
rotation?
Its world rotation; accepted for forward compatibility and currently unused, because the bounds test is axis-aligned.
options?
Layer mask and trigger behaviour.
Returns
readonly Entity[]
The overlapping entities, in body creation order. The array is reused between calls.
Remarks
Lite's shapeProximity reports one hit and no identity (index.d.ts 11540,
lib/physics/havok-queries.js:7), so this is answered from the extension's own bounds index:
every registered body whose world bounding box intersects the query shape's. It is conservative
— a body whose box overlaps but whose shape does not is listed.
Throws
IgnifxError with code IGX-0902 in development when no fixed step has run yet.
raycast()
raycast(
origin,direction,maxDistance?,options?):RaycastHit|null
Casts a ray and returns the first entity it hits (09-physics.md §5).
Parameters
origin
The world-space origin.
direction
The direction; it is normalised for you.
maxDistance?
number
How far to travel; defaults to 10 km.
options?
Layer mask and trigger behaviour.
Returns
RaycastHit | null
The hit, or null when the ray clears everything.
Throws
IgnifxError with code IGX-0902 in development when no fixed step has run yet.
setDebugViewerEnabled()
setDebugViewerEnabled(
enabled):void
Shows or hides Lite's wireframe bodies.
Parameters
enabled
boolean
Whether the viewer draws.
Returns
void
shapeCast()
shapeCast(
shape,from,to,options?):ShapeCastHit|null
Sweeps a shape and returns the first contact (09-physics.md §5).
Parameters
shape
The shape to sweep.
from
The start position.
to
The end position.
options?
Layer mask and trigger behaviour.
Returns
ShapeCastHit | null
The hit, or null.
Remarks
Lite's shapeCast reports no body (index.d.ts 11497), so entity is resolved against the
extension's body-bounds index and is bounds-accurate rather than shape-accurate.
Throws
IgnifxError with code IGX-0902 in development when no fixed step has run yet.
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
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
Constructors
Constructor
new PlatformMover():
PlatformMover
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticrequires: readonly [typeofRigidbody]
The kinematic Rigidbody this drives.
schema
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
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
The app.
Inherited from
deltaThisStep
Get Signature
get deltaThisStep():
Vec3Like
The platform's movement last step, which riders are handed. Reused each step.
Returns
The platform's movement last step, which riders are handed. Reused each step.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Records the starting position and subscribes to every character's contacts.
Returns
void
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
PlayerInput
Binds an entity to an action document and one device slot.
Remarks
The schema field actions holds the asset; the resolved lookup is playerInput.input, which
is the same InputActionsView app.input.actions exposes. 08-input.md §7 spells the
lookup player.input.actions; the two cannot both be called actions on one class, and the
serialized field is the one whose name the file format fixes.
Example
const player = entity.addComponent(PlayerInput, { actions: handle, deviceSlot: 1 });
player.input?.get("move").vector.x;Extends
Implements
Constructors
Constructor
new PlayerInput():
PlayerInput
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
actions
actions:
AssetHandle<InputActionsAsset> |null
The ignifx.inputactions document this player's private maps are built from.
allowMultiple
staticallowMultiple:boolean
One player owns one entity.
deviceSlot
deviceSlot:
number
Which gamepad slot the player's <Gamepad>/… bindings are pinned to.
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
scheme
scheme:
string
The control scheme to keep; "" keeps every binding whatever its tag.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
input
Get Signature
get input():
InputActionsView|null
The player's private action lookup.
Returns
InputActionsView | null
The view over the private maps, or null until the document is available.
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Builds the private maps as soon as the component's fields are assigned.
Returns
void
Implementation of
onDetach()
onDetach():
void
Stops the private maps resolving.
Returns
void
Implementation of
rebuild()
rebuild():
boolean
Rebuilds the private maps from the current actions, deviceSlot, and scheme fields. Call
it after changing any of them; onAttach calls it once for you.
Returns
boolean
true when a set was built, false when the document or the service is absent.
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
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
PointerLock
The pointer-lock controller, reached as app.input.pointerLock.
Example
canvas.addEventListener("click", () => {
void app.input.pointerLock.request();
});
app.input.pointerLock.onChange.connect((locked) => hud.setCrosshair(locked));Constructors
Constructor
new PointerLock():
PointerLock
Returns
Accessors
locked
Get Signature
get locked():
boolean
Whether the canvas currently holds the pointer.
Returns
boolean
true while document.pointerLockElement is this app's canvas.
onChange
Get Signature
get onChange():
SignalLike<boolean>
Emitted whenever the lock is taken or released, with the new state.
Returns
SignalLike<boolean>
The signal.
Methods
exit()
exit():
void
Releases the lock, if this app holds it.
Returns
void
request()
request():
Promise<boolean>
Requests the lock. Must be called from inside a user gesture.
Returns
Promise<boolean>
true once the lock is held, false when the browser refused it.
Throws
IgnifxError with code IGX-0809 when the app has no DOM canvas to lock.
PolygonCollider2D
A convex polygon collider, wound in either direction, in local metres.
Remarks
Rapier builds the convex hull of the points, so a concave outline is silently rounded out.
Model a concave shape as several PolygonCollider2Ds on one entity, or as an
EdgeCollider2D when it is an open contour.
Extends
Constructors
Constructor
new PolygonCollider2D():
PolygonCollider2D
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
points
points:
Vec2Like[]
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
PostProcessStack
One instance of a post-process chain, attached to the main camera's entity
(docs/architecture/07-rendering.md §2.7).
Example
cameraEntity.addComponent(PostProcessStack, {
bloom: { enabled: true, threshold: 0.85, weight: 0.4 },
smaa: { enabled: true },
});Extends
Implements
Constructors
Constructor
new PostProcessStack():
PostProcessStack
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One chain per camera entity; a second would fight the first for the swapchain.
bloom
bloom:
BloomEffectSettings
imageProcessing
imageProcessing:
ImageProcessingEffectSettings
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
smaa
smaa:
SmaaEffectSettings
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
taskCount
Get Signature
get taskCount():
number
How many frame-graph tasks the stack has recorded.
Returns
number
The task count; 0 before the chain is built, under a headless app, and when the
postProcessing rendering feature is off.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Nothing to do at attach: the chain is built on the first sync that wants an effect.
Returns
void
Implementation of
onDetach()
onDetach():
void
Disables and disposes every task the stack recorded.
Returns
void
Implementation of
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
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
Projectile
A fire-and-forget projectile (docs/architecture/12-3d-toolkit.md §1.3).
Example
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
Constructors
Constructor
new Projectile():
Projectile
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticrequires: readonly [typeofRigidbody]
The Rigidbody that carries it.
schema
staticschema:Schema
The declarative fields (ADR-0004).
speed
speed:
number
How fast the projectile leaves the muzzle.
typeId
statictypeId:string
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
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Finds the body; the launch itself waits for the first fixed step.
Returns
void
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
Quat
A rotation, stored as a unit quaternion. Quaternions are how ignifx stores every rotation: they interpolate smoothly, never gimbal-lock, and compose without matrix round-trips. Euler angles exist only at the edges of the API, always in degrees (ADR-0011, coding standards section 5.1).
Conventions, all verified against Babylon Lite 1.27.0's implementation so a Quat and a Lite
quaternion mean the same rotation:
- Euler order is intrinsic XYZ (
lib/math/quat-euler.js), the inverse of Lite'squatToEulerXYZ. a * bis the Hamilton product: applied to a vector it performsbfirst, thena, matching the matrix productMa * Mb.- The space is left-handed with Y up and +Z forward, so rotating
(1, 0, 0)by 90 degrees about +Y gives(0, 0, -1), and Quat.lookRotation maps +Z ontoforward.
Instance methods mutate the receiver and return this; ToRef statics write into a final out
argument and allocate nothing; the remaining statics allocate and say so.
Example
// face the movement direction, then blend into it over time
const target = Quat.lookRotation(velocity);
Quat.slerpToRef(transform.localRotation, target, 0.2, transform.localRotation);Constructors
Constructor
new Quat(
x?,y?,z?,w?):Quat
Creates a quaternion. The defaults are the identity rotation.
Parameters
x?
number
The imaginary X component. Defaults to 0.
y?
number
The imaginary Y component. Defaults to 0.
z?
number
The imaginary Z component. Defaults to 0.
w?
number
The real component. Defaults to 1.
Returns
Properties
w
w:
number
The real (scalar) component.
x
x:
number
The imaginary X component.
y
y:
number
The imaginary Y component.
z
z:
number
The imaginary Z component.
Methods
angleDegrees()
staticangleDegrees(a,b):number
The angle between two rotations, in degrees, along the shortest arc.
Parameters
a
The first rotation; assumed to be a unit quaternion.
b
The second rotation; assumed to be a unit quaternion.
Returns
number
The angle in [0, 180] degrees.
clone()
clone():
Quat
Copies this quaternion into a new one.
Returns
A new quaternion. Allocates.
conjugate()
conjugate():
this
Conjugates this quaternion, negating its imaginary part. For a unit quaternion this is the inverse rotation.
Returns
this
This quaternion.
conjugateToRef()
staticconjugateToRef<TOut>(q,out):TOut
Writes the conjugate of q into out.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
q
The rotation to conjugate.
out
TOut
The quaternion to write; may alias q.
Returns
TOut
out.
copyFrom()
copyFrom(
q):this
Copies every component from another quaternion.
Parameters
q
The quaternion to read.
Returns
this
This quaternion.
dot()
staticdot(a,b):number
The dot product of two rotations.
Parameters
a
The first rotation.
b
The second rotation.
Returns
number
The dot product.
dot()
dot(
q):number
The dot product of this quaternion with another. Its magnitude is the cosine of half the angle between the two rotations.
Parameters
q
The other rotation.
Returns
number
The dot product.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two quaternions component by component, with a tolerance. Note that q and -q are
the same rotation but are not equal by this test; compare with Quat.angleDegrees
when that matters.
Parameters
a
The first quaternion.
b
The second quaternion.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
q,epsilon?):boolean
Compares this quaternion with another, component by component, with a tolerance. Note that q
and -q are the same rotation but are not equal by this test.
Parameters
q
The quaternion to compare against.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
from()
staticfrom(q):Quat
Copies any quaternion-shaped value into a Quat.
Parameters
q
The quaternion to copy.
Returns
A new quaternion. Allocates.
fromAxisAngle()
staticfromAxisAngle(axis,degrees):Quat
Builds a rotation of degrees about an axis.
Parameters
axis
The axis to turn about; normalized internally.
degrees
number
The angle, in degrees.
Returns
A new quaternion. Allocates.
fromAxisAngleToRef()
staticfromAxisAngleToRef<TOut>(axis,degrees,out):TOut
Writes a rotation of degrees about an axis into out.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
axis
The axis to turn about; normalized internally. A zero-length axis writes the identity rotation.
degrees
number
The angle, in degrees.
out
TOut
The quaternion to write.
Returns
TOut
out.
fromEulerDegrees()
staticfromEulerDegrees(xDegrees,yDegrees,zDegrees):Quat
Builds a rotation from Euler angles in degrees, in intrinsic XYZ order.
Parameters
xDegrees
number
Rotation about X (pitch), in degrees.
yDegrees
number
Rotation about Y (yaw), in degrees.
zDegrees
number
Rotation about Z (roll), in degrees.
Returns
A new quaternion. Allocates.
Example
transform.localRotation.copyFrom(Quat.fromEulerDegrees(0, 90, 0)); // face +XfromEulerDegreesToRef()
staticfromEulerDegreesToRef<TOut>(xDegrees,yDegrees,zDegrees,out):TOut
Writes a rotation built from Euler degrees into out.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
xDegrees
number
Rotation about X (pitch), in degrees.
yDegrees
number
Rotation about Y (yaw), in degrees.
zDegrees
number
Rotation about Z (roll), in degrees.
out
TOut
The quaternion to write.
Returns
TOut
out.
fromEulerRadians()
staticfromEulerRadians(xRadians,yRadians,zRadians):Quat
Builds a rotation from Euler angles in radians, in intrinsic XYZ order.
Parameters
xRadians
number
Rotation about X, in radians.
yRadians
number
Rotation about Y, in radians.
zRadians
number
Rotation about Z, in radians.
Returns
A new quaternion. Allocates.
fromEulerRadiansToRef()
staticfromEulerRadiansToRef<TOut>(xRadians,yRadians,zRadians,out):TOut
Writes a rotation built from Euler radians into out. This is Babylon Lite's eulerToQuat
(lib/math/quat-euler.js) element for element, so a rotation built here means the same thing
to Lite's node hierarchy.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
xRadians
number
Rotation about X, in radians.
yRadians
number
Rotation about Y, in radians.
zRadians
number
Rotation about Z, in radians.
out
TOut
The quaternion to write.
Returns
TOut
out.
fromRotationMatrix()
staticfromRotationMatrix(m):Quat
Reads the rotation out of a transformation matrix.
Parameters
m
The matrix to read; scale is divided out first.
Returns
A new quaternion. Allocates.
fromRotationMatrixToRef()
staticfromRotationMatrixToRef<TOut>(m,out):TOut
Writes the rotation of a transformation matrix into out, dividing out the scale exactly as
Mat4.decomposeToRef does.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
m
The matrix to read.
out
TOut
The quaternion to write. Left untouched when a basis column has zero length.
Returns
TOut
out.
identity()
staticidentity():Quat
The identity rotation.
Returns
A new (0, 0, 0, 1). Allocates; see QUAT_IDENTITY.
identity()
identity():
this
Resets this quaternion to the identity rotation.
Returns
this
This quaternion.
invert()
invert():
this
Inverts this rotation. Unlike Quat.conjugate this also divides by the squared length, so it is correct for quaternions that have drifted from unit length.
Returns
this
This quaternion.
invertToRef()
staticinvertToRef<TOut>(q,out):TOut
Writes the inverse of q into out, dividing the conjugate by the squared length.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
q
The rotation to invert.
out
TOut
The quaternion to write; may alias q. A zero-length input writes the identity.
Returns
TOut
out.
length()
length():
number
The length of this quaternion; 1 for a well-formed rotation.
Returns
number
The length.
lengthSquared()
lengthSquared():
number
The squared length of this quaternion.
Returns
number
The squared length.
lookRotation()
staticlookRotation(forward,up?):Quat
Builds the rotation that points local +Z along forward and local +Y as close to up as it
can (left-handed, ADR-0011).
Parameters
forward
The direction to face; normalized internally.
up?
The reference up direction. Defaults to world up, (0, 1, 0).
Returns
A new quaternion. Allocates.
lookRotationToRef()
staticlookRotationToRef<TOut>(forward,up,out):TOut
Writes the rotation that points local +Z along forward into out. The basis is built the way
Babylon Lite builds it in quatFromLookDirectionRH (lib/math/quat-from-look-direction-rh.js):
right = up x forward, up' = forward x right, columns (right, up', forward) — which in
ignifx's left-handed space is exactly the Unity-style look rotation, whatever the Lite function
is named.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
forward
The direction to face; normalized internally.
up
The reference up direction; normalized internally.
out
TOut
The quaternion to write. Degenerate input (a zero-length forward, or an up
parallel to it) writes the identity rotation, where Lite would produce a meaningless basis.
Returns
TOut
out.
multiply()
staticmultiply(a,b):Quat
Composes two rotations.
Parameters
a
The rotation applied second.
b
The rotation applied first.
Returns
A new quaternion holding a * b. Allocates.
multiply()
multiply(
q):this
Post-multiplies this rotation by another (this = this * q): applied to a vector, q happens
first.
Parameters
q
The right-hand rotation.
Returns
this
This quaternion.
multiplyToRef()
staticmultiplyToRef<TOut>(a,b,out):TOut
Writes the Hamilton product a * b into out. Applied to a vector, b is performed first.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
a
The left-hand rotation.
b
The right-hand rotation.
out
TOut
The quaternion to write; may alias a or b.
Returns
TOut
out.
normalize()
normalize():
this
Scales this quaternion to unit length. Compositions drift over time, so normalize rotations you
keep integrating. A zero-length quaternion becomes the identity rather than NaN.
Returns
this
This quaternion.
normalizeToRef()
staticnormalizeToRef<TOut>(q,out):TOut
Writes a unit-length copy of q into out.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
q
The rotation to normalize.
out
TOut
The quaternion to write; may alias q. A zero-length input writes the identity.
Returns
TOut
out.
rotateVectorToRef()
staticrotateVectorToRef<TOut>(q,v,out):TOut
Rotates a vector by a quaternion, writing the result into out. This is the allocation-free
way to turn a local direction into a world direction.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
q
The rotation; assumed to be a unit quaternion.
v
The vector to rotate.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
Example
// world-space forward of an entity
Quat.rotateVectorToRef(transform.localRotation, VEC3_FORWARD, forward);set()
set(
x,y,z,w):this
Assigns every component at once.
Parameters
x
number
The new imaginary X component.
y
number
The new imaginary Y component.
z
number
The new imaginary Z component.
w
number
The new real component.
Returns
this
This quaternion.
slerp()
staticslerp(a,b,t):Quat
Interpolates between two rotations along the shortest arc, at a constant angular rate.
Parameters
a
The rotation returned at t === 0.
b
The rotation returned at t === 1.
t
number
The interpolant; not clamped.
Returns
A new quaternion. Allocates.
slerpToRef()
staticslerpToRef<TOut>(a,b,t,out):TOut
Writes the spherical interpolation of a and b into out, taking the shortest arc: when the
two rotations point away from each other one is negated first, which is the same rotation. Very
close rotations fall back to a normalized linear blend, where slerp is numerically unstable.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
a
The rotation written at t === 0.
b
The rotation written at t === 1.
t
number
The interpolant; not clamped.
out
TOut
The quaternion to write; may alias a or b.
Returns
TOut
out.
toArray()
toArray(
out,offset?):Float32Array
Writes this quaternion into a Float32Array, for GPU upload. The output comes first to mirror
Babylon Lite's ObservableQuat.toArray.
Parameters
out
Float32Array
The array to write into.
offset?
number
The index of the X component. Defaults to 0.
Returns
Float32Array
out.
toEulerDegreesToRef()
statictoEulerDegreesToRef<TOut>(q,out):TOut
Writes a rotation's Euler angles in degrees into out, in intrinsic XYZ order — the inverse of
Quat.fromEulerDegreesToRef.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
q
The rotation to convert; assumed to be a unit quaternion.
out
TOut
The vector to write; x is pitch, y is yaw, z is roll, all in degrees.
Returns
TOut
out.
toEulerRadiansToRef()
statictoEulerRadiansToRef<TOut>(q,out):TOut
Writes a rotation's Euler angles in radians into out, in intrinsic XYZ order. This is Babylon
Lite's quatToEulerXYZ (lib/math/quat-euler.js) line for line, including its behaviour near
the poles: at a Y rotation of plus or minus 90 degrees the X and Z angles are not separable and
the result is one of the infinitely many valid answers.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
q
The rotation to convert; assumed to be a unit quaternion.
out
TOut
The vector to write, in radians.
Returns
TOut
out.
Rigidbody
Makes an entity's colliders a Havok body (09-physics.md §2.1).
Example
const crate = world.createEntity("Crate");
crate.transform.position = { x: 0, y: 5, z: 0 };
crate.addComponent(BoxCollider, { size: { x: 1, y: 1, z: 1 } });
crate.addComponent(Rigidbody, { mass: 2 });Extends
Implements
Constructors
Constructor
new Rigidbody():
Rigidbody
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One body per entity.
bodyType
bodyType:
"static"|"dynamic"|"kinematic"
collisionEvents
collisionEvents:
"auto"|"on"|"off"
freezeRotation
freezeRotation:
FreezeRotation
interpolation
interpolation:
"none"|"interpolate"
kinematicSync
kinematicSync:
"teleport"|"velocity"
mass
mass:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
startAsleep
startAsleep:
boolean
typeId
statictypeId:string
The namespaced registration id.
Accessors
angularVelocity
Get Signature
get angularVelocity():
Vec3
The body's angular velocity in radians per second.
Returns
A freshly allocated vector; use Rigidbody.angularVelocityToRef in hot code.
Set Signature
set angularVelocity(
value):void
Replaces the body's angular velocity.
Parameters
value
Radians per second, world space.
Returns
void
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
linearVelocity
Get Signature
get linearVelocity():
Vec3
The body's linear velocity in metres per second.
Returns
A freshly allocated vector; use Rigidbody.linearVelocityToRef in hot code.
Set Signature
set linearVelocity(
value):void
Replaces the body's linear velocity.
Parameters
value
Metres per second, world space.
Returns
void
lite
Get Signature
get lite():
RigidbodyLiteHandles
The Babylon Lite handles this component owns.
Returns
The Havok body, or null before the first fixed step built it.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
addForce()
addForce(
force,point?):void
Applies a force for one fixed step. Call it from fixedUpdate.
Parameters
force
Newtons, world space.
point?
Where to apply it; defaults to the entity's world position.
Returns
void
Example
fixedUpdate(): void {
this.body.addForce({ x: 0, y: 20, z: 0 });
}addImpulse()
addImpulse(
impulse,point?):void
Applies an instantaneous impulse.
Parameters
impulse
Newton-seconds, world space.
point?
Where to apply it; defaults to the entity's world position.
Returns
void
angularVelocityToRef()
angularVelocityToRef(
out):MutableVec3
Reads the angular velocity without allocating.
Parameters
out
The vector to write.
Returns
out.
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
linearVelocityToRef()
linearVelocityToRef(
out):MutableVec3
Reads the linear velocity without allocating.
Parameters
out
The vector to write.
Returns
out.
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which turns it back into an implicit static body.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the body at the start of the next fixed step. Call it after changing bodyType,
mass, freezeRotation, or the entity's scale.
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
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
teleport()
teleport(
position,rotation?):void
Moves the body without integrating a velocity, and resets the interpolation history so the display pose does not slide across the gap.
Parameters
position
The new world position.
rotation?
The new world rotation; defaults to the current one.
Returns
void
Rigidbody2D
Makes an entity's 2D colliders a Rapier body.
Example
const crate = world.createEntity("Crate");
crate.transform.position2D = new Vec2(0, 5);
crate.addComponent(BoxCollider2D, { size: { x: 1, y: 1 } });
crate.addComponent(Rigidbody2D, { mass: 2 });Extends
Implements
Constructors
Constructor
new Rigidbody2D():
Rigidbody2D
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One body per entity.
angularDamping
angularDamping:
number
bodyType
bodyType:
"static"|"dynamic"|"kinematic"
collisionEvents
collisionEvents:
"auto"|"on"|"off"
freezeRotation
freezeRotation:
boolean
gravityScale
gravityScale:
number
interpolation
interpolation:
"none"|"interpolate"
linearDamping
linearDamping:
number
mass
mass:
number
schema
staticschema:Schema
The serialized field declarations (ADR-0004).
typeId
statictypeId:string
The namespaced registration id.
Accessors
angularVelocity
Get Signature
get angularVelocity():
number
The body's angular velocity.
Returns
number
Degrees per second, counter-clockwise — the same unit as Transform.rotation2D.
Set Signature
set angularVelocity(
value):void
Replaces the body's angular velocity.
Parameters
value
number
Degrees per second, counter-clockwise.
Returns
void
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
computedMass
Get Signature
get computedMass():
number
The mass Rapier computed for the body, in kilograms.
Returns
number
The mass, or 0 before the body exists.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
linearVelocity
Get Signature
get linearVelocity():
Vec2
The body's linear velocity in metres per second.
Returns
A freshly allocated vector; use Rigidbody2D.linearVelocityToRef in hot code.
Set Signature
set linearVelocity(
value):void
Replaces the body's linear velocity.
Parameters
value
Metres per second, world space.
Returns
void
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
rapier
Get Signature
get rapier():
Rigidbody2DRapierHandles
The Rapier handles this component owns.
Returns
The body, or null before the first fixed step built it.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
addForce()
addForce(
force,point?):void
Applies a force for one fixed step. Call it from fixedUpdate.
Parameters
force
Newtons, world space.
point?
Where to apply it; defaults to the centre of mass.
Returns
void
Example
fixedUpdate(): void {
this.body.addForce({ x: 0, y: 20 });
}addImpulse()
addImpulse(
impulse,point?):void
Applies an instantaneous impulse.
Parameters
impulse
Newton-seconds, world space.
point?
Where to apply it; defaults to the centre of mass.
Returns
void
addTorque()
addTorque(
torque):void
Applies a torque for one fixed step.
Parameters
torque
number
Newton-metres, positive counter-clockwise.
Returns
void
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
linearVelocityToRef()
linearVelocityToRef(
out):MutableVec2
Reads the linear velocity without allocating.
Parameters
out
The vector to write.
Returns
out.
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which turns it back into an implicit static body.
Returns
void
Implementation of
rebuild()
rebuild():
void
Rebuilds the body at the start of the next fixed step. Call it after changing bodyType,
mass, freezeRotation, damping, or the entity's scale.
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
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
teleport()
teleport(
position,rotation?):void
Moves the body without integrating a velocity, and resets the interpolation history so the display pose does not slide across the gap.
Parameters
position
The new world position, in metres.
rotation?
number
The new rotation in degrees counter-clockwise; defaults to the current one.
Returns
void
RigidbodyMover
A physics-driven character or vehicle: forces in, momentum out
(docs/architecture/12-3d-toolkit.md §1.3).
Example
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
Constructors
Constructor
new RigidbodyMover():
RigidbodyMover
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticrequires: readonly [typeofRigidbody]
The Rigidbody this pushes.
schema
staticschema:Schema
The declarative fields (ADR-0004).
torqueSteering
torqueSteering:
boolean
Whether the stick's X steers by torque rather than by force.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
awake()
awake():
void
Finds the body and binds the action name.
Returns
void
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
SceneInstance
One loaded scene file, or the implicit default scene
(docs/architecture/02-scene-graph.md §3). An entity belongs to exactly one instance: the scene
it was loaded from, or the world's active scene when it was created in code.
Remarks
The implicit "default" instance every app starts with has no asset and is always loaded.
An instance created by world.loadScene carries the handle it was built from and reports
isLoaded === false only while its entities are being constructed — a window no game code can
observe, because construction is one synchronous block (docs/architecture/02-scene-graph.md §2).
Example
world.activeScene.persistent = true; // survives a "single" load, like DontDestroyOnLoadProperties
name
readonlyname:string
The instance's name; the file's name, or "default" for the implicit scene.
persistent
persistent:
boolean
Whether the instance survives a "single" scene load — Unity's DontDestroyOnLoad, at scene
granularity rather than per object.
uid
readonlyuid:string
The instance id, distinct from the address of the asset it was loaded from.
Accessors
asset
Get Signature
get asset():
AssetHandle<SceneAsset> |null
The asset this instance was loaded from.
Returns
AssetHandle<SceneAsset> | null
The handle world.loadScene retained on the instance's behalf, or null for the
implicit default scene and for instances created in code.
isLoaded
Get Signature
get isLoaded():
boolean
Whether every entity of the instance has been constructed and its references resolved.
Returns
boolean
true once construction has finished; false only during it.
onUnloading
Get Signature
get onUnloading():
Signal
Emitted just before the instance is unloaded, while its entities are still valid.
Returns
The signal.
remap
Get Signature
get remap():
UidRemap|null
The file-local uid to runtime object table of this instance
(docs/architecture/02-scene-graph.md §10). Two instances of one scene have two tables, which
is what keeps their $entity/$component references apart.
Returns
UidRemap | null
The table, or null for an instance that was not built from a file.
roots
Get Signature
get roots(): readonly
Entity[]
The instance's root entities — the ones with no parent — in creation order.
Returns
readonly Entity[]
The live root list. Its identity is stable for the instance's lifetime.
settings
Get Signature
get settings():
JsonObject|null
The scene-level values the file carried — environment, clear colour, 2D mode flags, physics
overrides (docs/architecture/06-serialization-and-scene-format.md §2). The core keeps them as
plain JSON; the systems that understand a key read it from here.
Returns
JsonObject | null
The block, or null for an instance that was not built from a file.
abstract Script
A component that receives the engine lifecycle (docs/architecture/03-scripting-and-components.md
§2). This is the Unity MonoBehaviour role and the primary way game code is written.
Remarks
Where the callbacks are declared. awake, update, onCollisionEnter and the rest are
not* members of this class. Declaring them here would make every implementation an override, and
noImplicitOverride (coding standards §3) would then demand an override modifier on every
update in every game — which the documented examples do not carry, and which would be a tax on
the most-written method in the engine. They live in ScriptCallbacks instead; write
implements ScriptCallbacks to have their signatures checked. The engine detects which callbacks
a class implements once, by inspecting the prototype at registration, so an empty update() {}
costs a call per frame and not defining it costs nothing.
The statics work the same way. typeId, schema, requires, allowMultiple,
executionOrder, and updateWhenPaused are not members of Component or Script either: a
static declared on the base class is an override too, so static typeId = "mygame/Mover" would
have needed an override modifier. Their shape lives on ComponentStatics and
ScriptStatics, which the class-token types intersect, so a plain static on a subclass
satisfies them structurally; ComponentRegistry reads each one once per class and applies the
defaults (executionOrder 0, updateWhenPaused false).
Example
class Mover extends Script.define({ speed: f32(5) }) implements ScriptCallbacks {
static typeId = "mygame/Mover";
static executionOrder = -10;
update(dt: number): void {
this.transform.translate({ x: 0, y: 0, z: this.speed * dt });
}
}Extends
Extended by
AudioListenerAudioSourceMusicPlayerCamera2DFollowFirstPersonControllerPlatformMoverProjectileRigidbodyMoverThirdPersonCameraThirdPersonController
Constructors
Constructor
new Script():
Script
Creates a component. The engine constructs components; game code never calls new.
Returns
Inherited from
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Overrides
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Signal
A typed, synchronous, many-listener event (docs/architecture/02-scene-graph.md §8). Signals are
the "signal up" half of the engine's call down, signal up convention: a parent calls methods on
the children it owns, a child announces what happened and lets interested parties subscribe.
Remarks
Delivery guarantees:
- Handlers run in connection order, synchronously, inside Signal.emit.
- A handler connected during an emit runs on the next emit, never the one in flight.
- A handler disconnected during an emit never runs again, including in the emit in flight.
- One handler throwing does not stop delivery to the others.
- Nothing is allocated per emit on the non-deferred path (coding standards §7).
The payload type T defaults to void, so signal.emit() takes no argument.
Example
class Health extends Script {
readonly onDied = new Signal<Entity>();
damage(amount: number): void {
this.hp -= amount;
if (this.hp <= 0) {
this.onDied.emit(this.entity);
}
}
}
health.onDied.connect((entity) => this.spawnLoot(entity), { owner: this, once: true });Type Parameters
T
T = void
Implements
SignalLike<T>
Constructors
Constructor
new Signal<
T>(options?):Signal<T>
Creates a signal.
Parameters
options?
The deferred-delivery scheduler and the handler-error reporter. Both are supplied by the app for engine signals; a signal a script owns usually needs neither.
Returns
Signal<T>
Accessors
connectionCount
Get Signature
get connectionCount():
number
How many handlers are currently attached.
Returns
number
The live connection count.
How many handlers are currently attached.
Implementation of
Methods
clear()
clear():
void
Detaches every handler, including the auto-disconnect hooks held on owners.
Returns
void
connect()
connect(
handler,options?):Disconnect
Attaches a handler.
Parameters
handler
The listener.
options?
once to detach after the first delivery, deferred to queue delivery on the
signal's DeferredQueue, and owner to detach when the owner is destroyed.
Returns
A function that detaches the handler; calling it twice is a no-op.
Throws
IgnifxError with code IGX-0103 when deferred is requested and the signal was
constructed without a DeferredQueue.
Example
const stop = app.events.onSceneLoaded.connect((scene) => this.spawn(scene), { owner: this });
stop();Implementation of
disconnect()
disconnect(
handler):void
Detaches the first connection made with this handler. Detaching a handler that is not connected is a no-op.
Parameters
handler
The listener to detach.
Returns
void
emit()
emit(
value):void
Delivers a value to every attached handler, in connection order.
Parameters
value
T
The payload. Omitted for Signal<void>.
Returns
void
Throws
IgnifxError with code IGX-0104 wrapping the first handler exception, when the signal
was constructed without an onHandlerError reporter.
SortingLayerTable
Resolves sorting-layer names to draw orders.
Example
const layers = new SortingLayerTable(["Background", "Default", "Foreground"]);
layers.indexOf("Foreground"); // 2Constructors
Constructor
new SortingLayerTable(
names):SortingLayerTable
Builds the table from the project's sortingLayers section.
Parameters
names
readonly string[]
The names, back to front. An empty list falls back to ["Default"].
Returns
Accessors
names
Get Signature
get names(): readonly
string[]
The layer names, back to front.
Returns
readonly string[]
The names.
Methods
indexOf()
indexOf(
name):number
Resolves a name to its index.
Parameters
name
string
The sorting layer name.
Returns
number
The index, or -1 when the project declares no such layer.
orderOf()
orderOf(
name):number
The Lite Sprite2DLayer.order a sorting layer's sub-layers start at.
Parameters
name
string
The sorting layer name.
Returns
number
The base order.
Throws
IgnifxError with code IGX-1107 when the project declares no such layer.
require()
require(
name):number
Resolves a name to its index and refuses to guess.
Parameters
name
string
The sorting layer name.
Returns
number
The index.
Throws
IgnifxError with code IGX-1107 when the project declares no such layer.
SoundVoice
The concrete class behind SoundInstance, as app.audio.createVoice returns it.
Remarks
Hold a SoundInstance rather than this: the interface is the contract, and this class adds only what the components that own a voice need — releasing it, re-panning it, and flushing the plays it held while the engine was locked.
Implements
Constructors
Constructor
new SoundVoice(
host,clip,volume):SoundVoice
Creates a voice. The service does this; game code reaches one through play().
Parameters
host
The backend and the lock state.
clip
The clip to play.
volume
number
Its starting gain.
Returns
Properties
clip
readonlyclip:AudioClip
The clip being played.
Implementation of
Accessors
bus
Get Signature
get bus():
AudioBus|null
The bus this voice routes into.
Returns
AudioBus | null
The bus, or null while the tree is still being built or when the voice goes straight
to the engine's main bus.
The bus it routes into, or null when it goes straight to the engine's main bus.
Implementation of
instanceCount
Get Signature
get instanceCount():
number
How many instances are live.
Returns
number
The backend's instance count plus the plays still queued.
How many instances are live, including ones queued behind the unlock.
Implementation of
isAlive
Get Signature
get isAlive():
boolean
true while the voice holds a live instance or a queued play — which is the predicate
onEnded watches, and which stays true for a paused sound because a pause is not an end.
Returns
boolean
Whether anything is still owed.
isDisposed
Get Signature
get isDisposed():
boolean
true once the voice has been released and can no longer play.
Returns
boolean
Whether the voice is dead.
isPaused
Get Signature
get isPaused():
boolean
Whether every live instance is paused.
Returns
boolean
true when the sound is paused.
true when every live instance is paused.
Implementation of
isPlaying
Get Signature
get isPlaying():
boolean
Whether anything is sounding.
Returns
boolean
true while an instance is running or a play is waiting for the unlock.
true while at least one instance is sounding, or waiting for the unlock.
Implementation of
onEnded
Get Signature
get onEnded():
SignalLike
Emitted when the last instance stops sounding.
Returns
The signal.
Emitted in PreRender on the frame the last instance stops sounding, whether it ran out or was
stopped. Never emitted for a sound that is merely paused.
Implementation of
sound
Get Signature
get sound():
BackendSound|null
The backend's sound, once it exists.
Returns
BackendSound | null
The sound, or null while it is still being created.
volume
Get Signature
get volume():
number
The gain, where a fade in progress has reached.
Returns
number
The linear gain.
The gain, where a fade in progress has reached.
Implementation of
Methods
advance()
advance(
deltaSeconds):void
Advances the fade and the pending stop. Runs before the backend's own update, so a stop that comes due this frame is seen as an end in the same frame.
Parameters
deltaSeconds
number
The frame delta in seconds.
Returns
void
attach()
attach(
sound,bus):void
Adopts the backend sound the service created and releases whatever was queued behind it.
Parameters
sound
The freshly created sound.
bus
AudioBus | null
The bus it was routed to.
Returns
void
dispose()
dispose():
void
Releases the backend sound and every listener.
Returns
void
flush()
flush():
void
Starts every play that was waiting for the sound or for the unlock.
Returns
void
pause()
pause():
void
Pauses every instance.
Returns
void
Implementation of
play()
play(
request):void
Starts one instance, or holds the request until the sound exists and the engine is unlocked.
Parameters
request
The per-play overrides.
Returns
void
resume()
resume():
void
Resumes every paused instance.
Returns
void
Implementation of
setPan()
setPan(
pan):void
Sets the stereo pan of a non-spatial sound.
Parameters
pan
number
The pan in [-1, 1].
Returns
void
settle()
settle():
void
Raises onEnded when the voice stopped being alive since the previous frame. Runs after the
backend's update, so a simulated instance that ran out this frame is already gone.
Returns
void
setVolume()
setVolume(
volume,rampSeconds?):void
Fades the gain.
Parameters
volume
number
The target linear gain.
rampSeconds?
number
How long the fade takes, in frame time.
Returns
void
Implementation of
stop()
stop(
fadeSeconds?):void
Stops every instance, optionally fading first.
Parameters
fadeSeconds?
number
Seconds of frame time to fade over; 0 stops now.
Returns
void
Implementation of
SphereCollider
A sphere collider. Non-uniform scale is not representable as a sphere, so the largest scale axis wins — the same rule Unity applies.
Extends
Constructors
Constructor
new SphereCollider():
SphereCollider
Applies this collider's defaults on top of the shared ones.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity form one compound body (09-physics.md §2.2).
Inherited from
center
center:
Vec3Like
The shape's offset from the entity origin, in local units.
Inherited from
inlineMaterial
inlineMaterial:
PhysicsMaterialValues|null
An inline surface, used when Collider.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial> |null
A .physicsmaterial.json reference; wins over Collider.inlineMaterial.
Inherited from
radius
radius:
number
schema
staticschema:Schema
The serialized field declarations.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
createShape()
createShape(
world,scale):PhysicsShape
Builds this collider's Havok shape.
Parameters
world
PhysicsWorld
The Havok world the shape belongs to.
scale
The entity's lossy scale, applied to the authored dimensions.
Returns
PhysicsShape
The shape handle.
Overrides
Collider.createShape
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
halfExtentsToRef()
halfExtentsToRef(
scale,out):void
Writes half the size of this collider's local bounding box, scale applied.
Parameters
scale
The entity's lossy scale.
out
The vector to write.
Returns
void
Overrides
Collider.halfExtentsToRef
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, a centre, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2, z: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):PhysicsMaterialValues
Resolves the surface this collider presents to Havok.
Parameters
fallback
The world's physics.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
SpriteAnimationAsset
A loaded sprite-animation document.
Remarks
Resolution needs an atlas, and a document may be loaded before, after, or without one. The asset
therefore keeps the parsed clips and resolves them lazily the first time an atlas is offered;
SpriteAnimator offers its renderer's atlas. Under a headless app everything here works
unchanged, which is what makes animation timing testable with app.step.
Example
const clips = await app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json").promise;
clips.clipNames(); // ["idle", "run"]Properties
address
readonlyaddress:string
The address the document was loaded from.
assetType
staticassetType:string
The type name the asset service registers animation documents under.
atlasAddress
readonlyatlasAddress:string
The atlas address the document names, already resolved against its own address.
definition
readonlydefinition:SpriteAnimationDefinition
The parsed document.
Accessors
defaultClipName
Get Signature
get defaultClipName():
string
The name of the clip a component that names none plays.
Returns
string
The first clip's name, or "" when the document is empty.
Methods
clipNames()
clipNames(): readonly
string[]
Every clip name, in declaration order.
Returns
readonly string[]
A freshly allocated array.
requireClip()
requireClip(
name,atlas):SpriteClip
Looks a clip up, resolving against an atlas first.
Parameters
name
string
The clip name.
atlas
The atlas the frame names index into.
Returns
The clip.
Throws
IgnifxError with code IGX-1108 when the document declares no such clip.
resolve()
resolve(
atlas):ReadonlyMap<string,SpriteClip>
Resolves every clip's frame names against an atlas.
Parameters
atlas
The atlas the frame names index into.
Returns
ReadonlyMap<string, SpriteClip>
The clips, keyed by name.
Remarks
The result is cached against the atlas it was resolved with, so playing ten characters off one atlas resolves once. Offering a different atlas re-resolves.
SpriteAnimator
A sprite animator.
Example
const animator = hero.addComponent(SpriteAnimator);
animator.animations = app.assets.load<SpriteAnimationAsset>("2d/hero.spriteanim.json").retain();
animator.onEvent.connect((name) => { if (name === "footstep") playStep(); }, { owner: animator });
animator.play("run");Extends
Implements
Constructors
Constructor
new SpriteAnimator():
SpriteAnimator
Builds an animator with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One animator per entity.
animations
animations:
AssetHandle<SpriteAnimationAsset> |null
The document holding the clips.
defaultClip
defaultClip:
string
Which clip to start on; empty plays the document's first.
playOnAwake
playOnAwake:
boolean
Whether the default clip starts as soon as the document has loaded.
schema
staticschema:Schema
The declarative fields (ADR-0004).
speed
speed:
number
A multiplier on the clip's own frame rate.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
asset
Get Signature
get asset():
SpriteAnimationAsset|null
The loaded animation document, or null while it is still loading.
Returns
SpriteAnimationAsset | null
The document.
clip
Get Signature
get clip():
SpriteClip|null
The clip currently playing, or null.
Returns
SpriteClip | null
The clip.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
frame
Get Signature
get frame():
number
The atlas frame index the animator last wrote.
Returns
number
The frame index, or -1 when no clip is playing.
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
isPlaying
Get Signature
get isPlaying():
boolean
Whether a clip is currently advancing.
Returns
boolean
true while playing.
onClipEnded
Get Signature
get onClipEnded():
Signal<string>
Emitted with a clip's name when a non-looping clip reaches its last frame.
Returns
Signal<string>
The signal.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
onEvent
Get Signature
get onEvent():
Signal<string>
Emitted with an event's name when playback passes the frame that declares it.
Remarks
A looping clip fires each event once per pass. A clip advanced by more than one frame in a
single step — a long frame, or a high speed — fires every event it skipped over, in order,
so a footstep is never silently dropped.
Returns
Signal<string>
The signal.
time
Get Signature
get time():
number
How far into the clip playback is, in seconds.
Returns
number
The elapsed time.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Clears playback state, so a recycled component does not inherit the previous one's.
Returns
void
Implementation of
onDetach()
onDetach():
void
Releases the signals' handlers.
Returns
void
Implementation of
pause()
pause():
void
Suspends playback where it is; SpriteAnimator.resume continues from there.
Returns
void
play()
play(
name,options?):void
Starts a clip.
Parameters
name
string
The clip's name.
options?
Whether to rewind a clip that is already playing.
Returns
void
Throws
IgnifxError with code IGX-1108 when the document declares no such clip.
Example
animator.play("run", { restart: true });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
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
resume()
resume():
void
Continues a paused clip.
Returns
void
stop()
stop():
void
Stops playback and rewinds to the clip's first frame.
Returns
void
SpriteAtlasAsset
A loaded sprite atlas.
Remarks
Under a headless app the document is parsed and every frame is queryable, but lite.atlas is
null — nothing is uploaded (docs/architecture/07-rendering.md §6). That is what lets a
headless test assert frame counts, pivots, and animation timing without a GPU.
Example
const handle = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json");
const atlas = await handle.promise;
atlas.frameIndex("idle_0"); // 0Properties
address
readonlyaddress:string
The address the atlas was loaded from.
assetType
staticassetType:string
The type name the asset service registers sprite atlases under.
definition
readonlydefinition:SpriteAtlasDefinition
The parsed .atlas.json document.
Accessors
frameCount
Get Signature
get frameCount():
number
How many frames the atlas declares.
Returns
number
The frame count.
isReleased
Get Signature
get isReleased():
boolean
Whether the atlas was uploaded to a device at all.
Returns
boolean
true once the GPU texture has been given up, or under a headless app.
lite
Get Signature
get lite():
SpriteAtlasAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch
(CONSTITUTION.md §3.4).
Returns
The Lite atlas, or null under a headless app.
Methods
frame()
frame(
index):SpriteFrameInfo|null
Describes one frame.
Parameters
index
number
The frame index.
Returns
SpriteFrameInfo | null
The frame, or null when the index is out of range.
frameIndex()
frameIndex(
name):number
Looks a frame up by name.
Parameters
name
string
The frame name.
Returns
number
The index, or -1 when the atlas has no such frame.
frameNames()
frameNames(): readonly
string[]
Every frame name, in index order.
Returns
readonly string[]
A freshly allocated array.
requireFrame()
requireFrame(
name):number
Looks a frame up by name and refuses to guess.
Parameters
name
string
The frame name.
Returns
number
The index.
Throws
IgnifxError with code IGX-1106 when the atlas declares no such frame.
SpriteLayerEffect
A per-layer shader effect.
Example
const dusk = app.world.createEntity({ name: "dusk" }).addComponent(SpriteLayerEffect);
dusk.sortingLayer = "Default";
dusk.kind = "tint";
dusk.tint = { r: 0.6, g: 0.6, b: 0.9, a: 1 };Extends
Constructors
Constructor
new SpriteLayerEffect():
SpriteLayerEffect
Builds an effect with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One effect per entity; several entities may each drive a different sorting layer.
kind
kind:
"custom"|"tint"
Which shader to install.
params
params:
Vec4Like
The fx.params vec4 a custom shader reads.
schema
staticschema:Schema
The declarative fields (ADR-0004).
shader
shader:
string
The WGSL fragment body a custom effect installs.
sortingLayer
sortingLayer:
string
Which sorting layer the effect applies to.
tint
tint:
object
The colour the tint effect multiplies by, written into fx.params.
a
readonlya:number
b
readonlyb:number
g
readonlyg:number
r
readonlyr:number
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
source()
source():
string
The WGSL fragment body this effect installs.
Returns
string
The shader source.
Throws
IgnifxError with code IGX-1113 when kind is "custom" and shader is empty.
SpriteLayerRegistry
Owns every Lite sprite layer in one app.
Constructors
Constructor
new SpriteLayerRegistry(
sortingLayers,ySort,onLayerCreated,onLayerRemoved):SpriteLayerRegistry
Builds the registry.
Parameters
sortingLayers
Resolves a sorting-layer name to its draw order.
ySort
Readonly<Record<string, boolean>>
Which sorting layers draw back-to-front by world Y.
onLayerCreated
(layer) => void
Called with each new Lite layer, so the sprite renderer can draw it.
onLayerRemoved
(layer) => void
Called before a layer is dropped.
Returns
Methods
collectLayers()
collectLayers(
worldOnly,out):Sprite2DLayer[]
The Lite layers, in draw order — what picking tests against.
Parameters
worldOnly
boolean
Whether to skip screen-space layers.
out
Sprite2DLayer[]
The array to fill; it is emptied first, so one array serves every frame.
Returns
Sprite2DLayer[]
out.
describe()
describe(): readonly
SpriteLayerEntry[]
Every layer, in draw order.
Returns
readonly SpriteLayerEntry[]
A freshly allocated snapshot, for diagnostics.
SpriteRenderer
A sprite.
Remarks
The sprite field is an atlas handle; the frame inside it comes from the address's #frame:
fragment when there is one, and otherwise from SpriteRenderer.frame, which game code and
SpriteAnimator both write. A sprite whose atlas has not finished loading draws nothing and
costs nothing.
Example
const hero = app.world.createEntity({ name: "hero" });
const sprite = hero.addComponent(SpriteRenderer);
sprite.sprite = app.assets.load<SpriteAtlasAsset>("2d/hero.atlas.json").retain();
sprite.sortingLayer = "Default";Extends
Implements
Constructors
Constructor
new SpriteRenderer():
SpriteRenderer
Builds a sprite with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several sprites may share an entity — a character and its shadow, for instance.
blend
blend:
"opaque"|"premultiplied"|"alpha"|"additive"|"multiply"
How the sprite's colour combines with what is behind it.
color
color:
ColorLike
The tint multiplied into every texel.
flipX
flipX:
boolean
Whether the sprite is mirrored horizontally.
flipY
flipY:
boolean
Whether the sprite is mirrored vertically.
orderInLayer
orderInLayer:
number
The sub-order within the sorting layer; higher draws in front.
pickable
pickable:
boolean
Whether app.twoD.pickAt considers this sprite.
pivotOverride
pivotOverride:
Vec2Like|null
The pivot in [0, 1] of the frame, overriding the frame's own; null uses the frame's.
schema
staticschema:Schema
The declarative fields (ADR-0004).
screenSpace
screenSpace:
boolean
Whether the sprite keeps the identity view instead of following the Camera2D.
sortingLayer
sortingLayer:
string
Which sorting layer the sprite draws on.
sprite
sprite:
AssetHandle<SpriteAtlasAsset> |null
The atlas this sprite draws a frame of.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
atlas
Get Signature
get atlas():
SpriteAtlasAsset|null
The loaded atlas, or null while it is still loading or failed.
Returns
SpriteAtlasAsset | null
The atlas.
bounds
Get Signature
get bounds():
object
The sprite's world-space axis-aligned bounding box, for coarse queries
(docs/architecture/11-2d-toolkit.md §5).
Remarks
The box is the one the last sync computed, so it is a frame behind a sprite that has just moved, and it is the origin-sized empty box until the sprite has been synced once. It ignores rotation: a rotated sprite reports the box of its unrotated quad, which is the cheap conservative answer only for rotations that are multiples of a quarter turn.
Returns
object
A freshly allocated box in world metres.
max
readonlymax:Vec2Like
min
readonlymin:Vec2Like
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
frame
Get Signature
get frame():
number
The atlas frame drawn.
Returns
number
The frame index.
Set Signature
set frame(
value):void
Sets the atlas frame drawn, marking the sprite for the next sync when it changes.
Parameters
value
number
The frame index.
Returns
void
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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 the component uses. Unstable escape hatch
(CONSTITUTION.md §3.4).
Returns
object
The sprite handle, or null when the sprite is not in a layer.
sprite
readonlysprite:Sprite2DHandle|null
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Resets the sync shadow state, so a recycled component does not inherit the previous one's.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks the sprite for removal from its layer. The sync system does the removal, because it owns the layer.
Returns
void
Implementation of
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
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
TagSet
The mutable set of tags on one entity.
Example
entity.tags.add("enemy");
entity.tags.has("enemy"); // true
for (const tag of entity.tags) {
console.log(tag);
}Accessors
size
Get Signature
get size():
number
How many tags the entity carries.
Returns
number
The tag count.
Methods
[iterator]()
[iterator]():
IterableIterator<string>
Every tag, in insertion order, so a tag set can be spread or used in for…of.
Returns
IterableIterator<string>
An iterator over the tags.
add()
add(
tag):this
Adds a tag. Adding a tag the entity already carries is a no-op.
Parameters
tag
string
The tag.
Returns
this
This set, so calls chain.
delete()
delete(
tag):boolean
Removes a tag.
Parameters
tag
string
The tag.
Returns
boolean
true when the tag was present and has been removed.
has()
has(
tag):boolean
Reports whether the entity carries a tag.
Parameters
tag
string
The tag.
Returns
boolean
true when the tag is present.
values()
values():
IterableIterator<string>
Every tag, in insertion order.
Returns
IterableIterator<string>
An iterator over the tags.
abstract TextComponent
The base of HudText, WorldText2D, and WorldText: the schema fields and the shaped block.
Remarks
Abstract, and never registered as a component itself; the three concrete classes are.
Extends
Extended by
Constructors
Constructor
new TextComponent():
TextComponent
Creates a component. The engine constructs components; game code never calls new.
Returns
Inherited from
Properties
align
align:
"left"|"center"|"right"
Which edge the lines align to.
color
color:
ColorLike
The colour every glyph starts with.
font
font:
AssetHandle<FontAsset> |null
The TTF or OTF the glyphs come from.
fontSize
fontSize:
number
The em size, in render-target pixels.
i18nKey
i18nKey:
string
A translation key looked up in app.i18n; wins over TextComponent.text.
lineHeight
lineHeight:
number
The line-height multiplier.
maxWidth
maxWidth:
number
The wrap width, in render-target pixels; 0 does not wrap.
opacity
opacity:
number
The whole-block alpha multiplier.
text
text:
string
The literal string to draw; ignored when TextComponent.i18nKey is set.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
metrics
Get Signature
get metrics():
TextMetrics
The block's laid-out size, in render-target pixels.
Remarks
{ width: 0, height: 0 } until the block exists. This is Lite's only text measurement, and
it is what a caller centring a block on the screen needs — Lite's align aligns lines against
each other, not against the screen.
Example
const label = entity.addComponent(HudText);
label.metrics.width; // 0 until a font and a string are setReturns
The size.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
resolveText()
resolveText(
i18n):string
The string that will actually be drawn: the translated i18nKey, or text.
Parameters
i18n
I18nService | null
The localization service, or null when the app has none.
Returns
string
The resolved string.
TextureAsset
A loaded 2D texture (docs/architecture/05-assets-and-loading.md §5).
Example
const albedo = await app.assets.loadAsync<TextureAsset>("textures/hero-albedo.png");
albedo.value.options.srgb; // what the .meta.json sidecar asked forProperties
address
readonlyaddress:string
The address the texture was loaded from.
assetType
staticassetType:string
The type name the asset service registers textures under.
options
readonlyoptions:TextureImportOptions
The resolved import options, sidecar values merged onto the defaults.
Accessors
isReleased
Get Signature
get isReleased():
boolean
Whether the GPU texture has been given up.
Returns
boolean
true once TextureAsset.releaseGpu has run.
lite
Get Signature
get lite():
TextureAssetLiteHandles
The Babylon Lite objects the asset owns. Unstable escape hatch.
Returns
The GPU texture, or null under a headless app.
Methods
releaseGpu()
releaseGpu():
boolean
Gives up the asset's share of the GPU texture, destroying it when it was the last one. Calling it twice is a no-op, and it is a no-op under a headless app.
Returns
boolean
true when this call destroyed the underlying GPUTexture.
retainGpu()
retainGpu():
void
Claims an extra share of the GPU texture, so releasing the asset does not destroy it.
Returns
void
Remarks
Only needed when a Lite object has to outlive the asset that loaded it. Ordinary sharing goes
through ctx.loadDependency, which counts the asset handle instead.
ThirdPersonCamera
An orbiting third-person camera rig.
Example
const camera = app.world.createEntity("Camera");
camera.addComponent(Camera);
camera.addComponent(ThirdPersonCamera, { target: hero, distance: 5 });Extends
Constructors
Constructor
new ThirdPersonCamera():
ThirdPersonCamera
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
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
staticschema: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
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
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()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
ThirdPersonController
A camera-relative third-person character.
Example
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
Constructors
Constructor
new ThirdPersonController():
ThirdPersonController
Applies the schema defaults, exactly as Component.define would.
Returns
Overrides
Properties
airControl
airControl:
number
How much of the ground speed applies mid-air, in [0, 1].
allowMultiple
staticallowMultiple:boolean
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
staticrequires: readonly [typeofCharacterController]
The CharacterController this drives (CONSTITUTION.md §3, ADR-0004).
rotateToMovement
rotateToMovement:
boolean
Whether the entity turns to face the way it is moving.
schema
staticschema: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
statictypeId:string
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
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The direction the character is being pushed this step, normalized. Reused each step.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
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
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
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
The world.
Inherited from
Methods
awake()
awake():
void
Finds the character controller and binds the action names.
Returns
void
define()
staticdefine<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
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
class Patrol extends Script.define({ waypoints: array(vec3()), speed: f32(3) }) {
static typeId = "mygame/Patrol";
}Inherited from
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
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
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
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
The generator to drive. Call the generator function: this.spawnLoop().
Returns
A handle for stopping it or waiting on it.
Example
blink() {
while (true) {
this.renderer.enabled = !this.renderer.enabled;
yield waitSeconds(0.2);
}
}
onEnable(): void {
this.startCoroutine(this.blink());
}Inherited from
stopAllCoroutines()
stopAllCoroutines():
void
Stops every coroutine this script started.
Returns
void
Inherited from
stopCoroutine()
stopCoroutine(
handle):void
Stops one coroutine this script started. Stopping a finished coroutine is a no-op.
Parameters
handle
The handle Script.startCoroutine returned.
Returns
void
Inherited from
ThreeDAnimationSystem
Advances skeletal animation on ignifx's clock.
Implements
Constructors
Constructor
new ThreeDAnimationSystem():
ThreeDAnimationSystem
Returns
Properties
name
readonlyname:"ignifx/3d-animation"="ignifx/3d-animation"
The name diagnostics and error reports use.
Implementation of
Methods
update()
update(
ctx):void
Advances every enabled animator.
Parameters
ctx
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
Tilemap
A tilemap.
Example
const level = app.world.createEntity({ name: "level" }).addComponent(Tilemap);
level.map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").retain();
level.setTile(0, 3, 2, 0); // carve a hole in the ground layerExtends
Implements
Constructors
Constructor
new Tilemap():
Tilemap
Builds a tilemap with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One tilemap per entity.
cellSizeOverride
cellSizeOverride:
number
The metres one cell spans, overriding the document's own; 0 uses the document's.
chunkSize
chunkSize:
number
How many cells one chunk spans on each axis.
map
map:
AssetHandle<TilemapAsset> |null
The .tilemap.json document.
schema
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
asset
Get Signature
get asset():
TilemapAsset|null
The loaded document, or null while it is still loading.
Returns
TilemapAsset | null
The asset.
cellSize
Get Signature
get cellSize():
number
How many metres one cell spans.
Returns
number
The cell size; 0 when nothing has loaded.
collisionData
Get Signature
get collisionData():
TilemapCollisionData
The merged collision surface, rebuilt if a tile changed since the last read.
Remarks
The shape is the contract @ignifx/physics-2d consumes: chunked, in world metres relative to
the tilemap entity's origin, with adjacent full-cell tiles merged into as few counter-clockwise
rectangles as possible.
Returns
The collision data.
definition
Get Signature
get definition():
TilemapDefinition|null
The parsed document, or null.
Returns
TilemapDefinition | null
The definition.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
layerCount
Get Signature
get layerCount():
number
How many layers the document has.
Returns
number
The layer count.
onCollisionChanged
Get Signature
get onCollisionChanged():
Signal
Emitted after the merged collision surface has been rebuilt.
Remarks
@ignifx/physics-2d connects to this and rebuilds only the chunks whose geometry moved. The
rebuild is lazy: the signal fires on the first read of Tilemap.collisionData after a
change, not on the setTile call itself, so a script that rewrites a thousand tiles in one
frame pays for one merge.
Returns
The signal.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
onTileChanged
Get Signature
get onTileChanged():
Signal<TileChange>
Emitted whenever setTile changes a cell.
Returns
The signal.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
cellToWorld()
cellToWorld<
TOut>(x,y,out):TOut
Converts a cell into the world point at its centre.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
x
number
The cell's column.
y
number
The cell's row, with 0 at the bottom.
out
TOut
The vector to write.
Returns
TOut
out, in world metres.
collisionAt()
collisionAt(
x,y):TileCollisionInfo
The collision footprint of whatever is at a cell, across every collision layer.
Parameters
x
number
The cell's column.
y
number
The cell's row, with 0 at the bottom.
Returns
The topmost non-empty collider, or a "none" shape.
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
getTile()
getTile(
layer,x,y):number
Reads a tile.
Parameters
layer
number
The layer's index in the document.
x
number
The cell's column, with 0 at the left.
y
number
The cell's row, with 0 at the bottom.
Returns
number
The tile id, or 0 for an empty or out-of-range cell.
layerSize()
layerSize(
layer):Vec2Like
A layer's size, in cells.
Parameters
layer
number
The layer's index.
Returns
The size, or a zero size for an unknown layer.
onAttach()
onAttach():
void
Drops the grids, so a recycled component does not inherit the previous one's.
Returns
void
Implementation of
onDetach()
onDetach():
void
Releases the grids.
Returns
void
Implementation of
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
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
setTile()
setTile(
layer,x,y,tileId):void
Writes a tile.
Parameters
layer
number
The layer's index in the document.
x
number
The cell's column, with 0 at the left.
y
number
The cell's row, with 0 at the bottom.
tileId
number
The tile id, or 0 to clear the cell.
Returns
void
Throws
IgnifxError with code IGX-1111 when the cell is outside the layer.
worldToCell()
worldToCell<
TOut>(point,out):TOut
Converts a world point into the cell containing it.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
point
The world point, in metres.
out
TOut
The vector to write.
Returns
TOut
out, holding integer cell coordinates that may be outside the map.
Remarks
The point is in world metres; the map's own origin is the tilemap entity's position, so a moved or scaled tilemap still answers correctly. The result is floored, so a point exactly on a cell boundary belongs to the cell above and to the right of it.
TilemapAsset
A loaded tilemap document.
Example
const map = await app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").promise;
map.definition.layers.length; // 2Properties
address
readonlyaddress:string
The address the document was loaded from.
assetType
staticassetType:string
The type name the asset service registers tilemaps under.
atlasAddresses
readonlyatlasAddresses: readonlystring[]
Each tileset's atlas address, resolved against this document's address.
definition
readonlydefinition:TilemapDefinition
The parsed document, with every tile layer decoded to a dense array.
Methods
atlasFor()
atlasFor(
tilesetIndex):string
The atlas address a tileset's tiles come from.
Parameters
tilesetIndex
number
The tileset's index in the document.
Returns
string
The address, or "" when the index is out of range.
TilemapCollider2D
The collision surface of a tilemap, as one static body's worth of Rapier shapes.
Example
const map = world.createEntity("Map");
const collider = map.addComponent(TilemapCollider2D);
collider.collisionData = tilemap.collisionData;Extends
Constructors
Constructor
new TilemapCollider2D():
TilemapCollider2D
Applies the shared defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
Several colliders on one entity make one compound body.
Inherited from
frictionCombine
frictionCombine:
"average"|"min"|"multiply"|"max"
How this surface's friction combines with the one it touches.
Inherited from
inlineMaterial
inlineMaterial:
Physics2DMaterialValues|null
An inline surface, used when Collider2D.material is null.
Inherited from
isTrigger
isTrigger:
boolean
When true the shape reports overlaps and resolves no contacts.
Inherited from
layerOverride
layerOverride:
string
The name of the layer this collider filters as, or "" to use entity.layer.
Inherited from
material
material:
AssetHandle<PhysicsMaterial2D> |null
A .physicsmaterial.json reference; wins over Collider2D.inlineMaterial.
Inherited from
offset
offset:
Vec2Like
The shape's offset from the entity origin, in local metres.
Inherited from
oneWay
oneWay:
boolean
Whether this is a one-way platform: a CharacterController2D with
onOneWayPlatforms passes up through it and lands on it coming down. Rigid bodies are
unaffected — one-way support is a character-controller feature in the MVP.
Inherited from
restitutionCombine
restitutionCombine:
"average"|"min"|"multiply"|"max"
How this surface's restitution combines with the one it touches.
Inherited from
schema
staticschema:Schema
The serialized field declarations; the geometry itself comes from the tilemap asset.
typeId
statictypeId:string
The namespaced registration id.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
collisionData
Get Signature
get collisionData():
TilemapCollisionData|null
The merged chunk geometry this collider builds shapes from.
Returns
TilemapCollisionData | null
The data, or null when none has been supplied.
Set Signature
set collisionData(
value):void
Replaces the tilemap geometry and schedules a rebuild.
Parameters
value
TilemapCollisionData | null
The merged chunk geometry, or null to drop the shapes.
Returns
void
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
Collider2D.isEnabledInHierarchy
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks the entity's body for a rebuild at the start of the next fixed step.
Returns
void
Inherited from
onDetach()
onDetach():
void
Marks the entity's body for a rebuild, which removes this collider from it.
Returns
void
Inherited from
rebuild()
rebuild():
void
Rebuilds the entity's body and shapes at the start of the next fixed step. Call it after
changing a size, an offset, isTrigger, or the entity's scale.
Returns
void
Example
box.size = { x: 2, y: 2 };
box.rebuild();Inherited from
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
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
resolveMaterial()
resolveMaterial(
fallback):Physics2DMaterialValues
Resolves the surface this collider presents to Rapier.
Parameters
fallback
The world's physics2d.defaultMaterial.
Returns
The asset's values, the inline values, or the fallback.
Inherited from
TilemapRenderer
A tilemap renderer.
Example
const level = app.world.createEntity({ name: "level" });
level.addComponent(Tilemap).map = app.assets.load<TilemapAsset>("2d/level-1.tilemap.json").retain();
const renderer = level.addComponent(TilemapRenderer);
renderer.atlas = app.assets.load<SpriteAtlasAsset>("2d/tiles.atlas.json").retain();Extends
Implements
Constructors
Constructor
new TilemapRenderer():
TilemapRenderer
Builds a renderer with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One renderer per entity.
atlas
atlas:
AssetHandle<SpriteAtlasAsset> |null
The atlas the tile frames come from.
cullChunks
cullChunks:
boolean
Whether chunks outside the camera's visible bounds are dropped.
schema
staticschema:Schema
The declarative fields (ADR-0004).
sortingLayer
sortingLayer:
string
Which sorting layer the tiles draw on, when the document's layers name none.
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
chunkCount
Get Signature
get chunkCount():
number
How many chunks are currently materialised.
Returns
number
The count.
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
loadedAtlas
Get Signature
get loadedAtlas():
SpriteAtlasAsset|null
The loaded atlas, or null.
Returns
SpriteAtlasAsset | null
The atlas.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
spriteCount
Get Signature
get spriteCount():
number
How many sprites the materialised chunks hold in total.
Returns
number
The count.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onAttach()
onAttach():
void
Marks every chunk stale, so a recycled component rebuilds.
Returns
void
Implementation of
onDetach()
onDetach():
void
Marks every chunk stale; the 2D sync system does the removal, because it owns the layers.
Returns
void
Implementation of
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
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
Toast
A stack of transient messages.
Example
const toasts = new Toast(app.ui);
toasts.show("Checkpoint reached");
// in a script's update:
toasts.advance(dt);Constructors
Constructor
new Toast(
host,options?):Toast
Builds the stack and mounts it.
Parameters
host
The overlay host, normally app.ui.
options?
The layer, the default duration, and the stack depth.
Returns
Accessors
element
Get Signature
get element():
HTMLDivElement|null
The stack element, so a template can reposition it.
Returns
HTMLDivElement | null
The element, or null when the app has no DOM overlay.
messages
Get Signature
get messages(): readonly
string[]
The messages currently on screen, oldest first.
Returns
readonly string[]
The texts.
onDismissed
Get Signature
get onDismissed():
SignalLike<string>
Emitted with a message's text when it times out or is pushed off the stack.
Returns
SignalLike<string>
The signal.
Methods
advance()
advance(
deltaSeconds):void
Advances every message's timer.
Parameters
deltaSeconds
number
Seconds elapsed since the previous call; dt from a script's update.
Returns
void
clear()
clear():
void
Removes every message at once.
Returns
void
dispose()
dispose():
void
Removes the stack and unsubscribes.
Returns
void
show()
show(
text,duration?):void
Shows a message.
Parameters
text
string
The message.
duration?
number
How long it stays up, in seconds; defaults to the stack's own duration.
Returns
void
Transform
The view over an entity's Babylon Lite SceneNode
(docs/architecture/02-scene-graph.md §5). Every entity has exactly one; it cannot be removed
and cannot be disabled (IGX-0205).
Remarks
There is no second copy of position, rotation, or scale anywhere in ignifx: physics, animation,
and scripts all read and write the same Lite node. localPosition, localRotation, and
localScale are the node's own live values, so transform.localPosition.x += 1 writes straight
through with no copy and no dirty flag of ignifx's own.
World-space getters (position, rotation, eulerAngles, lossyScale, forward, right,
up) allocate a fresh value; every one of them has a ToRef twin that writes into a caller-owned
object and allocates nothing, and hot code uses those (coding standards §7).
Example
class Follow extends Script implements ScriptCallbacks {
#target = new Vec3();
lateUpdate(dt: number): void {
this.player.transform.positionToRef(this.#target); // no allocation
this.transform.localPosition.copyFrom(this.#target); // straight into the Lite node
}
}Extends
Constructors
Constructor
new Transform():
Transform
Creates an unbound transform. The entity constructor binds it to a Lite node immediately.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
An entity has exactly one transform.
typeId
statictypeId:string
The registration id of the one component every entity carries.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
enabled
Get Signature
get enabled():
boolean
A transform is always enabled: it is the entity's only view of its own position, and the engine, physics, and animation all write through it.
Throws
IgnifxError with code IGX-0205 on any attempt to set it to false. Deactivate the
entity instead (docs/architecture/01-lifecycle-and-time.md §6).
Returns
boolean
Always true.
Set Signature
set enabled(
value):void
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.
Parameters
value
boolean
Returns
void
true when the component's own flag is set.
Overrides
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
eulerAngles
Get Signature
get eulerAngles():
Vec3
The world rotation as intrinsic XYZ Euler angles in degrees.
Returns
A freshly allocated vector. Use Transform.eulerAnglesToRef in hot code.
Set Signature
set eulerAngles(
value):void
Parameters
value
Returns
void
forward
Get Signature
get forward():
Vec3
The world unit vector pointing along the entity's local +Z (ADR-0011: left-handed, Y up, +Z forward).
Returns
A freshly allocated vector. Use Transform.forwardToRef in hot code.
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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():
SceneNode
The Babylon Lite node this transform is a view over. Unstable escape hatch
(docs/architecture/00-overview.md §3); excluded from the stability guarantees of
CONSTITUTION.md Article IV.
Returns
SceneNode
The node.
localEulerAngles
Get Signature
get localEulerAngles():
Vec3
The local rotation as intrinsic XYZ Euler angles in degrees (ADR-0011).
Returns
A freshly allocated vector. Use Transform.localEulerAnglesToRef in hot code.
Set Signature
set localEulerAngles(
value):void
Parameters
value
Returns
void
localMatrix
Get Signature
get localMatrix():
Mat4Like
The matrix that takes local space to the parent's space, composed from the local TRS as
T * R * S.
Returns
The 16 column-major elements. The same storage and staleness rules as
Transform.worldMatrix.
localPosition
Get Signature
get localPosition():
MutableVec3
The position relative to the parent, as a live view over the Lite node: writing to it moves the entity and invalidates the subtree's world matrices.
Returns
The live local position. Never hold it past the entity's lifetime.
localPosition2D
Get Signature
get localPosition2D():
Vec2
The local position in the 2D plane; the Z depth is left alone by the setter, because 2D uses it
only as a sorting fallback (docs/architecture/00-overview.md §4).
Returns
A freshly allocated 2D vector.
Set Signature
set localPosition2D(
value):void
Parameters
value
Returns
void
localRotation
Get Signature
get localRotation():
MutableQuat
The rotation relative to the parent, as a live view over the Lite node.
Returns
The live local rotation.
localScale
Get Signature
get localScale():
MutableVec3
The scale relative to the parent, as a live view over the Lite node. Non-uniform scale is supported; negative scale is allowed but shadows and physics shapes do not support it.
Returns
The live local scale.
localScale2D
Get Signature
get localScale2D():
Vec2
The local scale in the 2D plane.
Returns
A freshly allocated 2D vector.
Set Signature
set localScale2D(
value):void
Parameters
value
Returns
void
lossyScale
Get Signature
get lossyScale():
Vec3
The world scale, read as the lengths of the world matrix's basis columns. It is lossy: a
rotated parent with non-uniform scale has no exact per-axis world scale, so this is the closest
approximation, exactly as Unity's lossyScale is.
Returns
A freshly allocated vector. Use Transform.lossyScaleToRef in hot code.
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
position
Get Signature
get position():
Vec3
The world position.
Returns
A freshly allocated vector. Use Transform.positionToRef in hot code.
Set Signature
set position(
value):void
Parameters
value
Returns
void
position2D
Get Signature
get position2D():
Vec2
The world position, in metres, in the plane 2D games use.
Returns
A freshly allocated 2D vector.
Set Signature
set position2D(
value):void
Parameters
value
Returns
void
right
Get Signature
get right():
Vec3
The world unit vector pointing along the entity's local +X.
Returns
A freshly allocated vector. Use Transform.rightToRef in hot code.
rotation
Get Signature
get rotation():
Quat
The world rotation.
Returns
A freshly allocated quaternion. Use Transform.rotationToRef in hot code.
Set Signature
set rotation(
value):void
Parameters
value
Returns
void
rotation2D
Get Signature
get rotation2D():
number
The local rotation about +Z in degrees, counter-clockwise — the only rotation 2D uses (ADR-0011).
Returns
number
The angle in degrees.
Set Signature
set rotation2D(
degrees):void
Parameters
degrees
number
Returns
void
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
up
Get Signature
get up():
Vec3
The world unit vector pointing along the entity's local +Y.
Returns
A freshly allocated vector. Use Transform.upToRef in hot code.
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
worldMatrix
Get Signature
get worldMatrix():
Mat4Like
The world matrix, copied out of Lite's cache the first time it is read after a change.
Remarks
Lite documents its Mat4 as opaque and recomputes it lazily up the parent chain, so the
adapter copies it element by element rather than handing out Lite's own object (ADR-0003
Validation). The returned view is this transform's own storage: it is read-only, its identity
is stable, and its contents change the next time the matrix is read after the entity moves.
Returns
The 16 column-major elements, translation in slots 12/13/14.
worldMatrixVersion
Get Signature
get worldMatrixVersion():
number
A counter that increases whenever this transform's world matrix is invalidated, by its own TRS
or by any ancestor's. Snapshot it to detect movement without comparing matrices — how
extensions feed spatial acceleration structures (docs/architecture/02-scene-graph.md §9).
Returns
number
The current version.
Methods
define()
staticdefine<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
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
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
destroy()
destroy():
void
A transform cannot be destroyed on its own.
Returns
void
Throws
IgnifxError with code IGX-0205. Destroy the entity instead.
Overrides
eulerAnglesToRef()
eulerAnglesToRef<
TOut>(out):TOut
Writes the world Euler angles in degrees into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out.
forwardToRef()
forwardToRef<
TOut>(out):TOut
Writes the world +Z axis into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out, normalised.
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
inverseTransformDirection()
inverseTransformDirection(
world,out?):MutableVec3
Takes a direction from world space to this entity's local space.
Parameters
world
The direction, in world space.
out?
Where to write the result; a fresh Vec3 is allocated when omitted.
Returns
The local direction; unchanged input when the world matrix is singular.
inverseTransformPoint()
inverseTransformPoint(
world,out?):MutableVec3
Takes a point from world space to this entity's local space.
Parameters
world
The point, in world space.
out?
Where to write the result; a fresh Vec3 is allocated when omitted.
Returns
The local point; unchanged input when the world matrix is singular.
localEulerAnglesToRef()
localEulerAnglesToRef<
TOut>(out):TOut
Writes the local Euler angles in degrees into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out.
lookAt()
lookAt(
target,up?):void
Points the entity's +Z axis at a world-space target.
Parameters
target
Where to look, in world space.
up?
The world up hint; defaults to +Y.
Returns
void
lossyScaleToRef()
lossyScaleToRef<
TOut>(out):TOut
Writes the lossy world scale into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out.
positionToRef()
positionToRef<
TOut>(out):TOut
Writes the world position into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out.
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
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
rightToRef()
rightToRef<
TOut>(out):TOut
Writes the world +X axis into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out, normalised.
rotate()
rotate(
eulerDegrees,space?):void
Rotates the entity by intrinsic XYZ Euler angles in degrees. Allocates nothing.
Parameters
eulerDegrees
The rotation to apply.
space?
"local" | "world"
"local" (the default) applies the rotation in the entity's own space;
"world" applies it in world space.
Returns
void
rotateAround()
rotateAround(
point,axis,degrees):void
Orbits the entity around a world-space point.
Parameters
point
The pivot, in world space.
axis
The axis to rotate about, in world space; need not be normalised.
degrees
number
How far to rotate, counter-clockwise about the axis.
Returns
void
rotationToRef()
rotationToRef<
TOut>(out):TOut
Writes the world rotation into a caller-owned quaternion. Allocates nothing.
Type Parameters
TOut
TOut extends MutableQuat
Parameters
out
TOut
The quaternion to write.
Returns
TOut
out.
setPositionAndRotation()
setPositionAndRotation(
position,rotation):void
Sets world position and rotation together, which is cheaper than setting them one at a time because the parent's world matrix is read once.
Parameters
position
The world position, in metres.
rotation
The world rotation.
Returns
void
transformDirection()
transformDirection(
local,out?):MutableVec3
Takes a direction from this entity's local space to world space; translation is ignored.
Parameters
local
The direction, in the entity's local space.
out?
Where to write the result; a fresh Vec3 is allocated when omitted.
Returns
The world direction.
transformPoint()
transformPoint(
local,out?):MutableVec3
Takes a point from this entity's local space to world space.
Parameters
local
The point, in the entity's local space.
out?
Where to write the result; a fresh Vec3 is allocated when omitted.
Returns
The world point.
translate()
translate(
delta,space?):void
Moves the entity by a delta. Allocates nothing.
Parameters
delta
How far to move, in metres.
space?
"local" | "world"
"local" (the default) rotates the delta by the entity's own rotation first, so
{ z: 1 } means "one metre forward"; "world" adds the delta to the world position.
Returns
void
Example
this.transform.translate({ x: 0, y: 0, z: this.speed * dt }); // forwardupToRef()
upToRef<
TOut>(out):TOut
Writes the world +Y axis into a caller-owned vector. Allocates nothing.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
out
TOut
The vector to write.
Returns
TOut
out, normalised.
Tween
A tween in flight.
Remarks
Endpoints are latched when the delay elapses, not when the tween is created, so two tweens queued on one property in the same frame chain rather than fight.
Example
const tween = app.tweens.to(entity.transform, { position: { x: 5, y: 0, z: 0 } }, {
duration: 1,
ease: "cubicInOut",
});
tween.onComplete.connect(() => app.log.info("arrived"));Properties
onComplete
Fires once when the tween finishes, with the tween itself. Never fires after stop.
updateWhenPaused
readonlyupdateWhenPaused:boolean
Whether the tween runs while the app is paused.
Accessors
isDone
Get Signature
get isDone():
boolean
Whether the tween has finished or been stopped and will never advance again.
Returns
boolean
Whether the tween has finished or been stopped and will never advance again.
isPaused
Get Signature
get isPaused():
boolean
Whether pause is holding the tween.
Returns
boolean
Whether pause is holding the tween.
isPlaying
Get Signature
get isPlaying():
boolean
Whether the tween is still advancing.
Returns
boolean
Whether the tween is still advancing.
progress
Get Signature
get progress():
number
How far through the current cycle the tween is, in [0, 1], after the yoyo reversal and before
the easing curve.
Returns
number
The normalized cycle time.
target
Get Signature
get target():
object
The object being tweened, for stopAllOf.
Returns
object
The object being tweened, for stopAllOf.
Methods
complete()
complete():
void
Jumps the target to the tween's end value, then finishes it. onComplete fires, exactly as it
would have on the last frame.
Returns
void
pause()
pause():
void
Holds the tween where it is; resume picks it back up.
Returns
void
resume()
resume():
void
Releases a pause.
Returns
void
stop()
stop():
void
Ends the tween where it stands, leaving the target at its current value. onComplete does not
fire.
Returns
void
TwoDAnimationSystem
Advances sprite animation on ignifx's clock.
Implements
Constructors
Constructor
new TwoDAnimationSystem(
tilemaps):TwoDAnimationSystem
Builds the system.
Parameters
tilemaps
Advances animated tiles on the same clock.
Returns
Properties
name
readonlyname:"ignifx/2d-animation"="ignifx/2d-animation"
The name diagnostics and error reports use.
Implementation of
Methods
update()
update(
ctx):void
Advances every animator and every animated tile.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
TwoDService
The 2D service.
Example
const hit = app.twoD.pickAt(pointer.x, pointer.y);
if (hit !== null) {
hit.entity.destroy();
}Accessors
layers
Get Signature
get layers(): readonly
SpriteLayerEntry[]
Every Lite sprite layer in draw order, for diagnostics and tests.
Remarks
The snapshot is freshly allocated on each read; it is a debugging surface, not a per-frame one.
Returns
readonly SpriteLayerEntry[]
The layers.
lite
Get Signature
get lite():
TwoDLiteHandles
The Babylon Lite objects the toolkit owns. Unstable escape hatch
(CONSTITUTION.md §3.4).
Returns
The sprite rendering context, or null under a headless app or before the first frame.
mainCamera
Get Signature
get mainCamera():
Camera2D|null
The camera the last frame was drawn through: the highest-priority enabled Camera2D.
Returns
Camera2D | null
The camera, or null when the world has none enabled.
mode
Get Signature
get mode():
"sprite"|"mixed"
Whether sprites are the whole frame or composite over the 3D scene.
Returns
"sprite" | "mixed"
The mode.
pixelsPerUnit
Get Signature
get pixelsPerUnit():
number
How many pixels one world metre spans (docs/architecture/11-2d-toolkit.md §1).
Returns
number
The conversion factor; 100 unless the project or a scene changed it.
settings
Get Signature
get settings():
TwoDSettings
The resolved twoD settings, after any scene-file override.
Returns
The settings.
sortingLayers
Get Signature
get sortingLayers(): readonly
string[]
The project's sorting layers, back to front.
Returns
readonly string[]
The names.
spriteCount
Get Signature
get spriteCount():
number
How many SpriteRenderer components the last frame walked.
Returns
number
The count.
syncedLastFrame
Get Signature
get syncedLastFrame():
number
How many sprites the last frame actually wrote to Lite.
Remarks
This is the number spike S6.1 watches: on a steady frame with a static tilemap it is the count of sprites that genuinely moved, not the count that exist.
Returns
number
The count.
Methods
pickAt()
pickAt(
xPx,yPx):TwoDPick|null
Picks the topmost sprite under a viewport pixel (docs/architecture/11-2d-toolkit.md §5).
Parameters
xPx
number
The viewport x, in pixels from the left edge.
yPx
number
The viewport y, in pixels from the top edge.
Returns
TwoDPick | null
The hit, or null for a miss.
Remarks
Picking is a CPU test against every world layer's instance data, in draw order — no GPU
readback and no frame of latency, which is what makes it usable from a click handler. It
resolves only SpriteRenderer components: a tilemap's tiles have no component, so use
Tilemap.worldToCell for those.
registerTileObjectFactory()
registerTileObjectFactory(
type,factory):void
Registers the factory that turns one kind of tilemap object into an entity
(docs/architecture/11-2d-toolkit.md §2.5).
Parameters
type
string
The object type the map writes.
factory
Builds the entity, or returns null to spawn nothing.
Returns
void
Throws
IgnifxError with code IGX-1110 when a factory for the type is already registered.
Example
app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
const player = world.createEntity({ name: "player" });
player.transform.position2D = new Vec2(position.x, position.y);
return player;
});screenToWorld()
screenToWorld(
xPx,yPx,out?):MutableVec2
Converts a viewport pixel into a world point through the active camera.
Parameters
xPx
number
The viewport x.
yPx
number
The viewport y.
out?
The vector to write; omitting it allocates one.
Returns
out, or the origin when no camera is active.
unregisterTileObjectFactory()
unregisterTileObjectFactory(
type):boolean
Removes a tile-object factory.
Parameters
type
string
The object type.
Returns
boolean
true when a factory was registered.
visibleWorldBounds()
visibleWorldBounds(
out):boolean
The world-space rectangle the camera can currently see.
Parameters
out
The box to write: its min takes the lower corner and its max the upper.
Returns
boolean
true when a camera and a layer existed to measure against.
worldToScreen()
worldToScreen(
point,out?):MutableVec2
Converts a world point into a viewport pixel through the active camera.
Parameters
point
The world point, in metres.
out?
The vector to write; omitting it allocates one.
Returns
out, or the origin when no camera is active.
TwoDSyncSystem
Writes sprites and camera views into Babylon Lite once per frame.
Implements
Properties
name
readonlyname:"ignifx/2d-sync"="ignifx/2d-sync"
The name diagnostics and error reports use.
Implementation of
Methods
onWorldCreated()
onWorldCreated(
world):void
Connects the scene hook to a new world.
Parameters
world
The new world.
Returns
void
Remarks
This is the only hook that fires for every world. register runs before the world exists and
onStart runs only when a game calls app.start(), so a headless tool that loads a scene
without ever starting a loop would otherwise never see its settings.twoD block.
Implementation of
onWorldDisposed()
onWorldDisposed(
_world):void
Drops every layer when the world goes away.
Parameters
_world
The world being disposed.
Returns
void
Implementation of
update()
update(
ctx):void
Runs one frame's synchronisation.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
UidRemap
The per-instance mapping from the uids a scene file carries to the runtime objects built from it
(docs/architecture/02-scene-graph.md §10). Loading the same scene twice produces two remaps, so
two instances of one prefab never resolve each other's references.
Remarks
The "file uid" side of the table is the uid an entity carries in the expanded file — the same
uid for entities declared by the scene itself, and a freshly minted one for each copy an
instance entry expands, because a prefab instanced twice would otherwise contribute the same
uid twice.
Constructors
Constructor
new UidRemap():
UidRemap
Returns
Accessors
size
Get Signature
get size():
number
How many entities the remap holds.
Returns
number
The entity count.
Methods
clear()
clear():
void
Drops every entry; the scene instance calls it on unload.
Returns
void
component()
component(
fileUid):Component|null
Resolves a file uid to its component.
Parameters
fileUid
string
The uid read from the file.
Returns
Component | null
The component, or null when the file declares no such component.
entity()
entity(
fileUid):Entity|null
Resolves a file uid to its entity.
Parameters
fileUid
string
The uid read from the file.
Returns
Entity | null
The entity, or null when the file declares no such entity.
entries()
entries():
IterableIterator<readonly [string,Entity]>
Every entity the remap holds, in the order the file declared them.
Returns
IterableIterator<readonly [string, Entity]>
The live iterator over [fileUid, entity] pairs.
UiHost
The DOM overlay host, reached as app.ui.
Example
const hud = app.ui.layer("hud");
app.ui.scaling = "fit";
app.ui.referenceResolution = [640, 360];Accessors
isActive
Get Signature
get isActive():
boolean
Whether there is a DOM overlay at all. false under a headless app, an OffscreenCanvas, or a
detached canvas — the three cases in which every other member is a no-op.
Returns
boolean
true when UiHost.root is an element.
keyboardHasFocus
Get Signature
get keyboardHasFocus():
boolean
Whether a text field currently owns the keyboard — the same value the host writes into
app.input.uiHasFocus.
Returns
boolean
true while typing must not fire keyboard actions.
layers
Get Signature
get layers(): readonly
UiLayer[]
Every layer, back to front.
Returns
readonly UiLayer[]
The layers, ordered by zIndex.
layout
Get Signature
get layout():
UiLayout
The root's current size, scale, and offset, in the units the scaling mode chose.
Returns
The layout last computed.
onLayoutChanged
Get Signature
get onLayoutChanged():
SignalLike<UiLayout>
Emitted after every recomputation that changed the layout: a canvas resize, a device-pixel-ratio change, or a write to UiHost.scaling or UiHost.referenceResolution.
Returns
The signal.
pixelMapping
Get Signature
get pixelMapping():
UiPixelMapping
The conversion from render-target pixels — the space Camera.worldToScreen, HudText, and
app.renderer.captureScreenshot() work in — to UI units.
Returns
The mapping last computed.
pointerOverUi
Get Signature
get pointerOverUi():
boolean
Whether a pointer is currently pressed on an interactive element of the overlay.
Remarks
A click on a UI element never reaches gameplay in the first place: @ignifx/input reads
pointerdown and wheel from the canvas (packages/input/src/dom/pointer-source.ts), and
the overlay root is the canvas's sibling rather than its child, so a press that lands on a
pointer-events: auto element is not on the canvas and is never queued. This flag covers the
remaining case: pointermove and pointerup are read from the window, so a drag that
started on a slider still moves <Pointer>/delta. A camera script that must ignore that reads
this flag.
Returns
boolean
true while at least one pointer is down on the overlay.
referenceResolution
Get Signature
get referenceResolution(): readonly
number[]
The [width, height] the "fit" mode scales to. Writing it recomputes the layout.
Returns
readonly number[]
A copy of the current reference resolution.
Set Signature
set referenceResolution(
value):void
Parameters
value
readonly number[]
Returns
void
root
Get Signature
get root():
HTMLDivElement|null
The overlay root: an absolutely positioned <div> covering the canvas, pointer-events: none.
Returns
HTMLDivElement | null
The root, or null when the app has no DOM overlay.
scaling
Get Signature
get scaling():
"css"|"fit"|"dpi"
How the overlay's coordinate system relates to the canvas. Writing it recomputes the layout immediately.
Returns
"css" | "fit" | "dpi"
The current mode.
Set Signature
set scaling(
value):void
Parameters
value
"css" | "fit" | "dpi"
Returns
void
visible
Get Signature
get visible():
boolean
Whether the whole overlay is shown. Per-layer visibility is app.ui.layer(name).visible.
Returns
boolean
true while the overlay is shown.
Set Signature
set visible(
value):void
Parameters
value
boolean
Returns
void
Methods
layer()
layer(
name,options?):UiLayer
Returns the named layer, creating it the first time it is asked for.
Parameters
name
string
The layer name.
options?
The stacking order and the initial visibility, used only on creation.
Returns
The layer.
Example
const menu = app.ui.layer("menu", { zIndex: 100 });refresh()
refresh():
void
Re-measures the canvas and rewrites the root's geometry.
Returns
void
Remarks
Called by the ResizeObserver, by the window's resize event — which is what a
device-pixel-ratio change fires — and by every write to a scaling property. Games call it after
changing the canvas's size by hand. A recomputation that produces the same layout writes
nothing and emits nothing.
UiLayer
A named layer of the overlay.
Example
const hud = app.ui.layer("hud");
hud.element?.append(document.createElement("div"));
hud.visible = false;Properties
name
readonlyname:string
The name the layer is addressed by.
Accessors
element
Get Signature
get element():
HTMLDivElement|null
The layer's element, or null when the app has no DOM overlay.
Returns
HTMLDivElement | null
The <div> a game mounts its tree into.
visible
Get Signature
get visible():
boolean
Whether the layer is shown. Hiding a layer hides everything mounted in it without unmounting anything, which is what a pause menu wants.
Returns
boolean
true while the layer is shown.
Set Signature
set visible(
value):void
Parameters
value
boolean
Returns
void
zIndex
Get Signature
get zIndex():
number
The layer's stacking order within the root.
Returns
number
The z-index.
Set Signature
set zIndex(
value):void
Parameters
value
number
Returns
void
Methods
clear()
clear():
void
Removes every child of the layer without removing the layer itself.
Returns
void
Remarks
A no-op under a headless app.
UiSystem
Projects world anchors and re-shapes text once per frame.
Implements
Properties
name
readonlyname:"ignifx/ui-sync"="ignifx/ui-sync"
The name diagnostics and error reports use.
Implementation of
Methods
onWorldCreated()
onWorldCreated(
_world):void
Builds the overlay, now that the engine and its canvas exist.
Parameters
_world
The new world, which the overlay does not need.
Returns
void
Remarks
This is the only hook that fires inside createApp after the Lite engine was created:
register runs before it, and onStart runs only when a game calls app.start(), which a
headless tool never does. @ignifx/2d uses the same hook for the same reason.
Implementation of
update()
update(
ctx):void
Runs one frame's synchronisation.
Parameters
ctx
The world, clock, phase, and delta.
Returns
void
Implementation of
UnavailableDesktop
The Desktop a browser build gets: isElectron === false, and every call refused.
Remarks
A refusing implementation rather than an absent property, because the alternative — leaving
app.desktop undefined outside Electron — turns a portable game's every desktop call into an
optional-chaining exercise and hides the mistake of calling one unconditionally.
Implements
Constructors
Constructor
new UnavailableDesktop():
UnavailableDesktop
Returns
Properties
isElectron
readonlyisElectron:boolean
Always false.
Implementation of
onWindowEvent
readonlyonWindowEvent:SignalLike<HostWindowEvent>
Never emits: a browser build has no host window to report on.
Implementation of
versions
readonlyversions:HostVersions|null
Always null.
Implementation of
Methods
isFullscreen()
isFullscreen():
Promise<boolean>
Refuses.
Returns
Promise<boolean>
Never; the promise rejects with IGX-1462.
Implementation of
openExternal()
openExternal(
_url):Promise<void>
Refuses.
Parameters
_url
string
Ignored.
Returns
Promise<void>
Never; the promise rejects with IGX-1462.
Implementation of
paths()
paths():
Promise<HostPaths>
Refuses.
Returns
Promise<HostPaths>
Never; the promise rejects with IGX-1462.
Implementation of
quit()
quit():
Promise<void>
Refuses.
Returns
Promise<void>
Never; the promise rejects with IGX-1462.
Implementation of
setFullscreen()
setFullscreen(
_fullscreen):Promise<void>
Refuses.
Parameters
_fullscreen
boolean
Ignored.
Returns
Promise<void>
Never; the promise rejects with IGX-1462.
Implementation of
setWindowTitle()
setWindowTitle(
_title):Promise<void>
Refuses.
Parameters
_title
string
Ignored.
Returns
Promise<void>
Never; the promise rejects with IGX-1462.
Implementation of
showOpenDialog()
showOpenDialog(
_options?):Promise<HostOpenDialogResult>
Refuses.
Parameters
_options?
Ignored.
Returns
Promise<HostOpenDialogResult>
Never; the promise rejects with IGX-1462.
Implementation of
Vec2
A 2-component vector: a position or direction in the 2D toolkit's world space (Y up, X right, metres — ADR-0011), a UV coordinate, or a 2D scale.
Instance methods mutate the receiver and return this; ToRef statics write into a final out
argument and allocate nothing; the remaining statics allocate and say so.
Example
const velocity = new Vec2(1, 0);
velocity.scale(speed);
Vec2.addToRef(position, velocity, position);Constructors
Constructor
new Vec2(
x?,y?):Vec2
Creates a vector.
Parameters
x?
number
The X component. Defaults to 0.
y?
number
The Y component. Defaults to 0.
Returns
Properties
x
x:
number
The X component; positive is right.
y
y:
number
The Y component; positive is up.
Methods
add()
staticadd(a,b):Vec2
Adds two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
A new vector. Allocates.
add()
add(
v):this
Adds another vector to this one.
Parameters
v
The vector to add.
Returns
this
This vector.
addScaled()
addScaled(
v,scale):this
Adds a scaled vector to this one, without a temporary.
Parameters
v
The vector to add.
scale
number
The factor to multiply v by first.
Returns
this
This vector.
addToRef()
staticaddToRef<TOut>(a,b,out):TOut
Writes a + b into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
clone()
clone():
Vec2
Copies this vector into a new one.
Returns
A new vector. Allocates.
copyFrom()
copyFrom(
v):this
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
this
This vector.
cross()
staticcross(a,b):number
The 2D cross product of two vectors — the Z component of their 3D cross product.
Parameters
a
The left-hand vector.
b
The right-hand vector.
Returns
number
The scalar cross product.
cross()
cross(
v):number
The 2D cross product — the Z component of the 3D cross product. Its sign says which side of this vector the other one falls on.
Parameters
v
The other vector.
Returns
number
The scalar cross product.
distance()
staticdistance(a,b):number
The distance between two positions, in metres.
Parameters
a
The first position.
b
The second position.
Returns
number
The distance.
distance()
distance(
v):number
The distance from this vector to another, in metres.
Parameters
v
The other position.
Returns
number
The distance.
distanceSquared()
distanceSquared(
v):number
The squared distance from this vector to another.
Parameters
v
The other position.
Returns
number
The squared distance.
dot()
staticdot(a,b):number
The dot product of two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
number
The dot product.
dot()
dot(
v):number
The dot product of this vector with another.
Parameters
v
The other vector.
Returns
number
The dot product.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two vectors component by component, with a tolerance.
Parameters
a
The first vector.
b
The second vector.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
v,epsilon?):boolean
Compares this vector with another, component by component, with a tolerance.
Parameters
v
The vector to compare against.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
from()
staticfrom(v):Vec2
Copies any vector-shaped value into a Vec2.
Parameters
v
The vector to copy.
Returns
A new vector. Allocates.
length()
staticlength(v):number
The length of a vector, in metres.
Parameters
v
The vector to measure.
Returns
number
The length.
length()
length():
number
The length of this vector, in metres.
Returns
number
The length.
lengthSquared()
staticlengthSquared(v):number
The squared length of a vector.
Parameters
v
The vector to measure.
Returns
number
The squared length.
lengthSquared()
lengthSquared():
number
The squared length of this vector.
Returns
number
The squared length.
lerp()
staticlerp(a,b,t):Vec2
Linearly interpolates between two vectors.
Parameters
a
The vector returned at t === 0.
b
The vector returned at t === 1.
t
number
The interpolant; not clamped.
Returns
A new vector. Allocates.
lerp()
lerp(
target,t):this
Moves this vector towards a target by an interpolant.
Parameters
target
The vector reached at t === 1.
t
number
The interpolant; not clamped.
Returns
this
This vector.
lerpToRef()
staticlerpToRef<TOut>(a,b,t,out):TOut
Writes the interpolation of a and b into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
a
The vector written at t === 0.
b
The vector written at t === 1.
t
number
The interpolant; not clamped.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
multiply()
multiply(
v):this
Multiplies this vector by another component by component.
Parameters
v
The vector to multiply by.
Returns
this
This vector.
multiplyToRef()
staticmultiplyToRef<TOut>(a,b,out):TOut
Writes the component-wise product a * b into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
negate()
negate():
this
Flips this vector to point the other way.
Returns
this
This vector.
negateToRef()
staticnegateToRef<TOut>(v,out):TOut
Writes -v into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
v
The vector to flip.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
normalize()
staticnormalize(v):Vec2
A unit-length copy of a vector.
Parameters
v
The vector to normalize.
Returns
A new vector. Allocates.
normalize()
normalize():
this
Scales this vector to unit length; a zero-length vector is left at zero rather than becoming
NaN.
Returns
this
This vector.
normalizeToRef()
staticnormalizeToRef<TOut>(v,out):TOut
Writes a unit-length copy of v into out; a zero-length input is written as zero.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
v
The vector to normalize.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
one()
staticone():Vec2
The vector whose components are both one.
Returns
A new (1, 1). Allocates.
scale()
staticscale(v,scale):Vec2
Multiplies a vector by a number.
Parameters
v
The vector to scale.
scale
number
The factor.
Returns
A new vector. Allocates.
scale()
scale(
scale):this
Multiplies every component by a number.
Parameters
scale
number
The factor.
Returns
this
This vector.
scaleToRef()
staticscaleToRef<TOut>(v,scale,out):TOut
Writes v * scale into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
v
The vector to scale.
scale
number
The factor.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
set()
set(
x,y):this
Assigns every component at once.
Parameters
x
number
The new X component.
y
number
The new Y component.
Returns
this
This vector.
subtract()
staticsubtract(a,b):Vec2
Subtracts one vector from another.
Parameters
a
The vector to subtract from.
b
The vector to subtract.
Returns
A new vector holding a - b. Allocates.
subtract()
subtract(
v):this
Subtracts another vector from this one.
Parameters
v
The vector to subtract.
Returns
this
This vector.
subtractToRef()
staticsubtractToRef<TOut>(a,b,out):TOut
Writes a - b into out.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
a
The vector to subtract from.
b
The vector to subtract.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
toArray()
toArray(
out,offset?):Float32Array
Writes this vector into a Float32Array, for GPU upload. The output comes first to mirror
Babylon Lite's toArray helpers.
Parameters
out
Float32Array
The array to write into.
offset?
number
The index of the X component. Defaults to 0.
Returns
Float32Array
out.
zero()
staticzero():Vec2
The zero vector.
Returns
A new (0, 0). Allocates.
Vec3
A 3-component vector: a position or a direction in metres, or a per-axis scale. ignifx is
left-handed with Y up and +Z forward (ADR-0011), so Vec3.forward is (0, 0, 1) and
Vec3.right is (1, 0, 0).
The fields are plain mutable numbers, which is what makes a Vec3 interchangeable with Babylon
Lite's { x, y, z } vectors and with the live MutableVec3 views a Transform exposes.
Three families of operations, and the names say which is which:
- instance methods mutate the receiver and return
this(a.add(b)meansa += b); ToRefstatics write into a finaloutargument, allocate nothing, and are safe whenoutaliases an input — these are what per-frame code uses (coding standards section 7);- the remaining statics return a fresh vector and are documented as allocating.
Example
// convenience code
const offset = Vec3.add(position, Vec3.scale(direction, distance));
// per-frame code: no allocation
Vec3.scaleToRef(direction, distance, scratch);
Vec3.addToRef(position, scratch, position);Constructors
Constructor
new Vec3(
x?,y?,z?):Vec3
Creates a vector.
Parameters
x?
number
The X component. Defaults to 0.
y?
number
The Y component. Defaults to 0.
z?
number
The Z component. Defaults to 0.
Returns
Properties
x
x:
number
The X component; positive is right.
y
y:
number
The Y component; positive is up.
z
z:
number
The Z component; positive is forward.
Methods
add()
staticadd(a,b):Vec3
Adds two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
A new vector. Allocates; use Vec3.addToRef in per-frame code.
add()
add(
v):this
Adds another vector to this one.
Parameters
v
The vector to add.
Returns
this
This vector.
addScaled()
addScaled(
v,scale):this
Adds a scaled vector to this one — the "move by velocity times delta time" step, without a temporary.
Parameters
v
The vector to add.
scale
number
The factor to multiply v by first.
Returns
this
This vector.
Example
position.addScaled(velocity, time.deltaTime);addToRef()
staticaddToRef<TOut>(a,b,out):TOut
Writes a + b into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
backward()
staticbackward():Vec3
The world backward direction.
Returns
A new (0, 0, -1). Allocates.
clone()
clone():
Vec3
Copies this vector into a new one.
Returns
A new vector. Allocates.
copyFrom()
copyFrom(
v):this
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
this
This vector.
cross()
staticcross(a,b):Vec3
The cross product of two vectors.
Parameters
a
The left-hand vector.
b
The right-hand vector.
Returns
A new vector holding a x b. Allocates.
cross()
cross(
v):this
Replaces this vector with its cross product with another (this = this x v).
Parameters
v
The right-hand vector.
Returns
this
This vector.
crossToRef()
staticcrossToRef<TOut>(a,b,out):TOut
Writes a x b into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The left-hand vector.
b
The right-hand vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
distance()
staticdistance(a,b):number
The distance between two positions, in metres.
Parameters
a
The first position.
b
The second position.
Returns
number
The distance.
distance()
distance(
v):number
The distance from this vector to another, in metres.
Parameters
v
The other position.
Returns
number
The distance.
distanceSquared()
staticdistanceSquared(a,b):number
The squared distance between two positions. Compare squared distances to avoid a square root.
Parameters
a
The first position.
b
The second position.
Returns
number
The squared distance.
distanceSquared()
distanceSquared(
v):number
The squared distance from this vector to another.
Parameters
v
The other position.
Returns
number
The squared distance.
dot()
staticdot(a,b):number
The dot product of two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
number
The dot product.
dot()
dot(
v):number
The dot product of this vector with another.
Parameters
v
The other vector.
Returns
number
The dot product.
down()
staticdown():Vec3
The world down direction.
Returns
A new (0, -1, 0). Allocates.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two vectors component by component, with a tolerance.
Parameters
a
The first vector.
b
The second vector.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
v,epsilon?):boolean
Compares this vector with another, component by component, with a tolerance.
Parameters
v
The vector to compare against.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
forward()
staticforward():Vec3
The world forward direction. ignifx is left-handed, so forward is +Z (ADR-0011).
Returns
A new (0, 0, 1). Allocates; see VEC3_FORWARD.
from()
staticfrom(v):Vec3
Copies any vector-shaped value into a Vec3.
Parameters
v
The vector to copy.
Returns
A new vector. Allocates.
Example
const position = Vec3.from(node.position); // snapshot of a live Lite viewleft()
staticleft():Vec3
The world left direction.
Returns
A new (-1, 0, 0). Allocates.
length()
staticlength(v):number
The length of a vector, in metres.
Parameters
v
The vector to measure.
Returns
number
The length.
length()
length():
number
The length of this vector, in metres.
Returns
number
The length.
lengthSquared()
staticlengthSquared(v):number
The squared length of a vector.
Parameters
v
The vector to measure.
Returns
number
The squared length.
lengthSquared()
lengthSquared():
number
The squared length of this vector. Prefer it over length() when comparing distances:
it skips the square root.
Returns
number
The squared length.
lerp()
staticlerp(a,b,t):Vec3
Linearly interpolates between two vectors.
Parameters
a
The vector returned at t === 0.
b
The vector returned at t === 1.
t
number
The interpolant; not clamped.
Returns
A new vector. Allocates.
lerp()
lerp(
target,t):this
Moves this vector towards a target by an interpolant.
Parameters
target
The vector reached at t === 1.
t
number
The interpolant; not clamped.
Returns
this
This vector.
lerpToRef()
staticlerpToRef<TOut>(a,b,t,out):TOut
Writes the interpolation of a and b into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The vector written at t === 0.
b
The vector written at t === 1.
t
number
The interpolant; not clamped.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
maxToRef()
staticmaxToRef<TOut>(a,b,out):TOut
Writes the component-wise maximum of two vectors into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
minToRef()
staticminToRef<TOut>(a,b,out):TOut
Writes the component-wise minimum of two vectors into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
multiply()
multiply(
v):this
Multiplies this vector by another component by component.
Parameters
v
The vector to multiply by.
Returns
this
This vector.
multiplyToRef()
staticmultiplyToRef<TOut>(a,b,out):TOut
Writes the component-wise product a * b into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
negate()
negate():
this
Flips this vector to point the other way.
Returns
this
This vector.
negateToRef()
staticnegateToRef<TOut>(v,out):TOut
Writes -v into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
v
The vector to flip.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
normalize()
staticnormalize(v):Vec3
A unit-length copy of a vector.
Parameters
v
The vector to normalize.
Returns
A new vector. Allocates.
normalize()
normalize():
this
Scales this vector to unit length. A zero-length vector is left at zero rather than becoming
NaN, so callers can normalize an unchecked direction safely.
Returns
this
This vector.
normalizeToRef()
staticnormalizeToRef<TOut>(v,out):TOut
Writes a unit-length copy of v into out. A zero-length input is written as zero rather than
NaN.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
v
The vector to normalize.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
one()
staticone():Vec3
The vector whose components are all one.
Returns
A new (1, 1, 1). Allocates.
right()
staticright():Vec3
The world right direction.
Returns
A new (1, 0, 0). Allocates; see VEC3_RIGHT.
scale()
staticscale(v,scale):Vec3
Multiplies a vector by a number.
Parameters
v
The vector to scale.
scale
number
The factor.
Returns
A new vector. Allocates.
scale()
scale(
scale):this
Multiplies every component by a number.
Parameters
scale
number
The factor.
Returns
this
This vector.
scaleToRef()
staticscaleToRef<TOut>(v,scale,out):TOut
Writes v * scale into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
v
The vector to scale.
scale
number
The factor.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
set()
set(
x,y,z):this
Assigns every component at once.
Parameters
x
number
The new X component.
y
number
The new Y component.
z
number
The new Z component.
Returns
this
This vector.
subtract()
staticsubtract(a,b):Vec3
Subtracts one vector from another.
Parameters
a
The vector to subtract from.
b
The vector to subtract.
Returns
A new vector holding a - b. Allocates.
subtract()
subtract(
v):this
Subtracts another vector from this one.
Parameters
v
The vector to subtract.
Returns
this
This vector.
subtractToRef()
staticsubtractToRef<TOut>(a,b,out):TOut
Writes a - b into out.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
a
The vector to subtract from.
b
The vector to subtract.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
toArray()
toArray(
out,offset?):Float32Array
Writes this vector into a Float32Array, for GPU upload. The output comes first to mirror
Babylon Lite's ObservableVec3.toArray, the shape the adapter has to interoperate with.
Parameters
out
Float32Array
The array to write into.
offset?
number
The index of the X component. Defaults to 0.
Returns
Float32Array
out.
transformCoordinatesToRef()
statictransformCoordinatesToRef<TOut>(v,m,out):TOut
Transforms a position by a matrix into out: the matrix's translation is applied and the
result is divided by w, so a projection matrix gives clip-space coordinates.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
v
The position to transform, in metres.
m
The transformation, column-major.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
Example
Vec3.transformCoordinatesToRef(localPoint, node.worldMatrix, worldPoint);transformNormalToRef()
statictransformNormalToRef<TOut>(v,m,out):TOut
Transforms a direction by a matrix into out, ignoring the matrix's translation.
Type Parameters
TOut
TOut extends MutableVec3
Parameters
v
The direction to transform.
m
The transformation, column-major.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
up()
staticup():Vec3
The world up direction.
Returns
A new (0, 1, 0). Allocates; see VEC3_UP.
zero()
staticzero():Vec3
The zero vector.
Returns
A new (0, 0, 0). Allocates; use VEC3_ZERO when a read-only value will do.
Vec4
A 4-component vector: homogeneous coordinates, a tangent with a handedness sign, or any packed quadruple headed for a shader. Rotations use Quat, not this type.
Instance methods mutate the receiver and return this; ToRef statics write into a final out
argument and allocate nothing; the remaining statics allocate and say so.
Example
const tangent = new Vec4(1, 0, 0, -1);
tangent.toArray(vertexBuffer, offset);Constructors
Constructor
new Vec4(
x?,y?,z?,w?):Vec4
Creates a vector.
Parameters
x?
number
The X component. Defaults to 0.
y?
number
The Y component. Defaults to 0.
z?
number
The Z component. Defaults to 0.
w?
number
The W component. Defaults to 0.
Returns
Properties
w
w:
number
The W component.
x
x:
number
The X component.
y
y:
number
The Y component.
z
z:
number
The Z component.
Methods
add()
staticadd(a,b):Vec4
Adds two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
A new vector. Allocates.
add()
add(
v):this
Adds another vector to this one.
Parameters
v
The vector to add.
Returns
this
This vector.
addToRef()
staticaddToRef<TOut>(a,b,out):TOut
Writes a + b into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
clone()
clone():
Vec4
Copies this vector into a new one.
Returns
A new vector. Allocates.
copyFrom()
copyFrom(
v):this
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
this
This vector.
dot()
staticdot(a,b):number
The dot product of two vectors.
Parameters
a
The first vector.
b
The second vector.
Returns
number
The dot product.
dot()
dot(
v):number
The dot product of this vector with another.
Parameters
v
The other vector.
Returns
number
The dot product.
equalsWithEpsilon()
staticequalsWithEpsilon(a,b,epsilon?):boolean
Compares two vectors component by component, with a tolerance.
Parameters
a
The first vector.
b
The second vector.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
equalsWithEpsilon()
equalsWithEpsilon(
v,epsilon?):boolean
Compares this vector with another, component by component, with a tolerance.
Parameters
v
The vector to compare against.
epsilon?
number
The largest per-component difference still considered equal.
Returns
boolean
true when every component matches within epsilon.
from()
staticfrom(v):Vec4
Copies any vector-shaped value into a Vec4.
Parameters
v
The vector to copy.
Returns
A new vector. Allocates.
length()
staticlength(v):number
The length of a vector.
Parameters
v
The vector to measure.
Returns
number
The length.
length()
length():
number
The length of this vector.
Returns
number
The length.
lengthSquared()
staticlengthSquared(v):number
The squared length of a vector.
Parameters
v
The vector to measure.
Returns
number
The squared length.
lengthSquared()
lengthSquared():
number
The squared length of this vector.
Returns
number
The squared length.
lerp()
staticlerp(a,b,t):Vec4
Linearly interpolates between two vectors.
Parameters
a
The vector returned at t === 0.
b
The vector returned at t === 1.
t
number
The interpolant; not clamped.
Returns
A new vector. Allocates.
lerp()
lerp(
target,t):this
Moves this vector towards a target by an interpolant.
Parameters
target
The vector reached at t === 1.
t
number
The interpolant; not clamped.
Returns
this
This vector.
lerpToRef()
staticlerpToRef<TOut>(a,b,t,out):TOut
Writes the interpolation of a and b into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
a
The vector written at t === 0.
b
The vector written at t === 1.
t
number
The interpolant; not clamped.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
multiply()
multiply(
v):this
Multiplies this vector by another component by component.
Parameters
v
The vector to multiply by.
Returns
this
This vector.
multiplyToRef()
staticmultiplyToRef<TOut>(a,b,out):TOut
Writes the component-wise product a * b into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
a
The first vector.
b
The second vector.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
negate()
negate():
this
Flips every component's sign.
Returns
this
This vector.
negateToRef()
staticnegateToRef<TOut>(v,out):TOut
Writes -v into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
v
The vector to flip.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
normalize()
staticnormalize(v):Vec4
A unit-length copy of a vector.
Parameters
v
The vector to normalize.
Returns
A new vector. Allocates.
normalize()
normalize():
this
Scales this vector to unit length; a zero-length vector is left at zero rather than becoming
NaN.
Returns
this
This vector.
normalizeToRef()
staticnormalizeToRef<TOut>(v,out):TOut
Writes a unit-length copy of v into out; a zero-length input is written as zero.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
v
The vector to normalize.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
one()
staticone():Vec4
The vector whose components are all one.
Returns
A new (1, 1, 1, 1). Allocates.
scale()
staticscale(v,scale):Vec4
Multiplies a vector by a number.
Parameters
v
The vector to scale.
scale
number
The factor.
Returns
A new vector. Allocates.
scale()
scale(
scale):this
Multiplies every component by a number.
Parameters
scale
number
The factor.
Returns
this
This vector.
scaleToRef()
staticscaleToRef<TOut>(v,scale,out):TOut
Writes v * scale into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
v
The vector to scale.
scale
number
The factor.
out
TOut
The vector to write; may alias v.
Returns
TOut
out.
set()
set(
x,y,z,w):this
Assigns every component at once.
Parameters
x
number
The new X component.
y
number
The new Y component.
z
number
The new Z component.
w
number
The new W component.
Returns
this
This vector.
subtract()
staticsubtract(a,b):Vec4
Subtracts one vector from another.
Parameters
a
The vector to subtract from.
b
The vector to subtract.
Returns
A new vector holding a - b. Allocates.
subtract()
subtract(
v):this
Subtracts another vector from this one.
Parameters
v
The vector to subtract.
Returns
this
This vector.
subtractToRef()
staticsubtractToRef<TOut>(a,b,out):TOut
Writes a - b into out.
Type Parameters
TOut
TOut extends MutableVec4
Parameters
a
The vector to subtract from.
b
The vector to subtract.
out
TOut
The vector to write; may alias a or b.
Returns
TOut
out.
toArray()
toArray(
out,offset?):Float32Array
Writes this vector into a Float32Array, for GPU upload. The output comes first to mirror
Babylon Lite's toArray helpers.
Parameters
out
Float32Array
The array to write into.
offset?
number
The index of the X component. Defaults to 0.
Returns
Float32Array
out.
zero()
staticzero():Vec4
The zero vector.
Returns
A new (0, 0, 0, 0). Allocates.
VirtualButton
An on-screen button.
Example
const jump = new VirtualButton(app, { control: "jump", label: "A" });Constructors
Constructor
new VirtualButton(
app,options):VirtualButton
Builds the widget and mounts it.
Parameters
app
The running app; app.ui and app.input.devices.virtual are the parts used.
options
The control name, the label, the layer, and the placement styles.
Returns
Throws
IgnifxError with code IGX-1305 when @ignifx/input is not registered.
Accessors
control
Get Signature
get control():
string
The control this button writes.
Returns
string
The name, as it appears after <Virtual>/.
element
Get Signature
get element():
HTMLButtonElement|null
The button element, so a template can restyle or reposition it.
Returns
HTMLButtonElement | null
The element, or null when the app has no DOM overlay.
isPressed
Get Signature
get isPressed():
boolean
Whether the button is currently held.
Returns
boolean
true while it is pressed.
Methods
dispose()
dispose():
void
Removes the widget, unsubscribes, and releases the control.
Returns
void
VirtualDevice
A device whose controls are created on demand.
Example
const stick = app.input.devices.virtual.declare("joystick", "vector2");
app.input.devices.virtual.setVector("joystick", 0, 1);Extends
Constructors
Constructor
new VirtualDevice():
VirtualDevice
Builds an empty virtual device.
Returns
Overrides
Properties
deviceIndex
readonlydeviceIndex:number
Which device of its family this is; 0 for every family that has only one.
Inherited from
kind
readonlykind:DeviceKind
The device family this device belongs to.
Inherited from
Accessors
controls
Get Signature
get controls(): readonly
ControlDescriptor[]
The device's controls, in index order.
Returns
readonly ControlDescriptor[]
The control table.
Inherited from
isConnected
Get Signature
get isConnected():
boolean
Whether the device is present. Only gamepads ever report false.
Returns
boolean
true when bindings to this device can produce input.
Inherited from
Methods
control()
control(
name):ControlDescriptor|null
Looks a control up by name. Call it at binding time, never per frame.
Parameters
name
string
The control name, for example dpad/up.
Returns
ControlDescriptor | null
The descriptor, or null when the device has no such control.
Inherited from
declare()
declare(
name,kind?):ControlDescriptor
Returns the named control, creating it when the device does not have it yet.
Parameters
name
string
The control name, as it appears after <Virtual>/.
kind?
What the control produces. Ignored when the control already exists.
Returns
The descriptor.
set()
set(
name,value):void
Writes a scalar control, creating it when it does not exist.
Parameters
name
string
The control name.
value
number
The new value.
Returns
void
setVector()
setVector(
name,x,y):void
Writes a vector control, creating it when it does not exist.
Parameters
name
string
The control name.
x
number
The new x component.
y
number
The new y component.
Returns
void
valueAt()
valueAt(
offset):number
Reads one component of the device's value array.
Parameters
offset
number
The slot, from a ControlDescriptor.
Returns
number
The value, or 0 when the slot is out of range.
Inherited from
VirtualJoystick
An on-screen thumbstick.
Example
const stick = new VirtualJoystick(app, { control: "joystick" });
// later
stick.dispose();Constructors
Constructor
new VirtualJoystick(
app,options?):VirtualJoystick
Builds the widget and mounts it.
Parameters
app
The running app; app.ui and app.input.devices.virtual are the parts used.
options?
The control name, the layer, the geometry, and the placement styles.
Returns
Throws
IgnifxError with code IGX-1305 when @ignifx/input is not registered.
Accessors
control
Get Signature
get control():
string
The control this stick writes.
Returns
string
The name, as it appears after <Virtual>/.
element
Get Signature
get element():
HTMLDivElement|null
The pad element, so a template can restyle or reposition it.
Returns
HTMLDivElement | null
The element, or null when the app has no DOM overlay.
isActive
Get Signature
get isActive():
boolean
Whether a pointer currently holds the stick.
Returns
boolean
true while the stick is being dragged.
Methods
dispose()
dispose():
void
Removes the widget, unsubscribes, and centres the control.
Returns
void
WebAudioBackend
The audio backend that runs in a browser.
Implements
Constructors
Constructor
new WebAudioBackend(
engine):WebAudioBackend
Wraps an audio engine Lite has already created.
Parameters
engine
AudioEngine
The engine from createAudioEngineAsync.
Returns
Properties
kind
readonlykind:AudioBackendKind
Which implementation this is.
Implementation of
Accessors
lite
Get Signature
get lite():
AudioLiteHandles
The Lite objects this backend owns. Unstable escape hatch.
Returns
The engine.
The Lite objects this backend owns, or null when it owns none.
Implementation of
onStateChanged
Get Signature
get onStateChanged():
SignalLike<AudioBackendState>
Emitted whenever the state changes.
Returns
The signal.
Emitted whenever AudioBackend.state changes.
Implementation of
state
Get Signature
get state():
AudioBackendState
The audio context's state.
Returns
Lite's AudioEngineState, which is always "running" for an OfflineAudioContext.
The audio context's current state.
Implementation of
Methods
createBus()
createBus(
request):Promise<BackendBus>
Creates a Lite bus routed into its parent.
Parameters
request
The name, gain, and parent bus.
Returns
Promise<BackendBus>
The bus.
Implementation of
createSound()
createSound(
request):Promise<BackendSound>
Creates a Lite sound: buffer-backed for a static clip, media-element-backed for a streaming one.
Parameters
request
The clip, routing, and per-sound options.
Returns
Promise<BackendSound>
The sound.
Throws
IgnifxError with code IGX-1008 when a static clip cannot be decoded, or IGX-1009
when a streaming clip is asked for on a context that cannot stream.
Implementation of
decode()
decode(
clip):Promise<void>
Decodes a static clip's bytes into a buffer every sound built from it shares.
Parameters
clip
The clip to decode.
Returns
Promise<void>
Throws
IgnifxError with code IGX-1008 when the bytes are not audio this browser can decode.
Implementation of
dispose()
dispose():
void
Stops every sound, tears down the graph, and closes the audio context.
Returns
void
Implementation of
disposeBus()
disposeBus(
bus):void
Releases a bus and its sub-graph.
Parameters
bus
The bus.
Returns
void
Implementation of
disposeSound()
disposeSound(
sound):void
Releases a sound and its sub-graph.
Parameters
sound
The sound.
Returns
void
Implementation of
getMasterVolume()
getMasterVolume():
number
Reads the master gain.
Returns
number
The gain.
Implementation of
pause()
pause(
sound):void
Pauses every instance.
Parameters
sound
The sound.
Returns
void
Implementation of
play()
play(
sound,request):void
Starts one instance, or resumes a paused sound — which is what Lite's playSound does
(index.d.ts 8955).
Parameters
sound
The sound.
request
The per-play overrides.
Returns
void
Implementation of
resume()
resume(
sound):void
Resumes every paused instance.
Parameters
sound
The sound.
Returns
void
Implementation of
setBusVolume()
setBusVolume(
bus,volume):void
Sets a bus's gain.
Parameters
bus
The bus.
volume
number
The gain to apply now.
Returns
void
Implementation of
setListener()
setListener(
target):void
Attaches Lite's spatial listener to a world transform, or leaves it at the world origin.
Parameters
target
SpatialTarget | null
The transform to follow, or null.
Returns
void
Implementation of
setMasterVolume()
setMasterVolume(
volume):void
Sets the master gain.
Parameters
volume
number
The gain to apply now.
Returns
void
Implementation of
setSoundPan()
setSoundPan(
sound,pan):void
Sets a sound's stereo pan, building the panner sub-node on first use.
Parameters
sound
The sound.
pan
number
The pan in [-1, 1].
Returns
void
Implementation of
setSoundVolume()
setSoundVolume(
sound,volume):void
Sets a sound's gain.
Parameters
sound
The sound.
volume
number
The gain to apply now.
Returns
void
Implementation of
stop()
stop(
sound):void
Stops every instance.
Parameters
sound
The sound.
Returns
void
Implementation of
unlock()
unlock():
Promise<void>
Resumes the audio context. Browsers only honour this from inside a user-gesture handler; Lite
also resumes on the first click anywhere in the document on its own.
Returns
Promise<void>
A promise that settles once the context is running.
Implementation of
update()
update(
deltaSeconds):void
Re-reads the world matrix of every attached source and of the listener.
Parameters
deltaSeconds
number
The frame delta; Lite's pump reads poses rather than integrating, so it is not used and is accepted only to satisfy the contract.
Returns
void
Implementation of
World
The running simulation: the entity registry, the scene instances, and the lifecycle queues
(docs/architecture/02-scene-graph.md §2). One world per app in the MVP.
Remarks
Phase 1 ships the subset that needs no asset system: entity creation, queries, the implicit
"default" scene, and the lifecycle. loadScene, unloadScene, instantiate,
instantiateAsync, and moveEntityToScene arrive in Phase 2, and onSceneLoaded/
onSceneUnloaded exist here but never fire until then.
Example
const player = app.world.createEntity("Player");
for (const script of app.world.components(Script)) {
script.enabled = false;
}Implements
WorldHost
Accessors
activeScene
Get Signature
get activeScene():
SceneInstance
The scene that owns entities created in code without an explicit scene option. Assigning to
it makes another instance the default owner.
Returns
The active instance.
Set Signature
set activeScene(
scene):void
Parameters
scene
Returns
void
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Implementation of
WorldHost.app
isDisposed
Get Signature
get isDisposed():
boolean
true once World.dispose has run.
Returns
boolean
true when the world has been disposed.
layers
Get Signature
get layers():
LayerTable
The project's resolved layer names. world.layers.mask("Player", "Enemy") builds a mask.
Returns
The layer table.
Implementation of
WorldHost.layers
lite
Get Signature
get lite():
WorldLiteHandles
Babylon Lite objects the world owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Returns
The render scene, and the physics simulation scene once an extension has set one. The object is the same one on every read and is updated in place; do not retain a copy of its fields.
mainCamera
Get Signature
get mainCamera():
Camera|null
The camera this world renders through: the enabled Camera with the highest priority
(docs/architecture/07-rendering.md §2.1).
Remarks
The PreRender render-sync system chooses it and assigns it to the Lite scene, so the value is
the one the last rendered frame used, not a live query. A world with no enabled camera
renders nothing and logs IGX-0706 once.
Example
const ray = world.mainCamera?.screenToRay(event.offsetX, event.offsetY) ?? null;Returns
Camera | null
The main camera, or null when the world has none.
onEntityCreated
Get Signature
Emitted for every entity the world creates.
Returns
The signal.
onEntityDestroyed
Get Signature
Emitted for every entity the destroy flush releases.
Returns
The signal.
onSceneLoaded
Get Signature
get onSceneLoaded():
Signal<SceneInstance>
Emitted when a scene instance finishes loading. Never fires before Phase 2.
Returns
The signal.
onSceneUnloaded
Get Signature
get onSceneUnloaded():
Signal<SceneInstance>
Emitted when a scene instance is unloaded. Never fires before Phase 2.
Returns
The signal.
registry
Get Signature
get registry():
ComponentRegistry
The component-class table.
Returns
The registry.
Implementation of
WorldHost.registry
scenes
Get Signature
get scenes(): readonly
SceneInstance[]
Every loaded scene instance, in load order; the implicit "default" scene is always first.
Returns
readonly SceneInstance[]
The live scene list.
world
Get Signature
get world():
World
The world itself; WorldHost names it so entities can reach it.
Returns
This world.
Implementation of
WorldHost.world
Methods
components()
components<
T>(type): readonlyT[]
Every component of a class, by identity and inheritance — the primary iteration API for
systems (docs/architecture/02-scene-graph.md §9).
Type Parameters
T
T extends Component
The component type.
Parameters
type
The component class, abstract or concrete; components(Script) returns every
script.
Returns
readonly T[]
The live list. O(1) to obtain, stable within a phase, and never allocated per call.
createEntity()
createEntity(
name?,options?):Entity
Creates an entity with a transform and a Lite node.
Parameters
name?
string
The display name; defaults to "Entity".
options?
The parent, the owning scene, and an initial world position and rotation.
Returns
The new entity, already active and registered.
Example
const hand = world.createEntity("Hand", { parent: player, position: { x: 0.3, y: 1.2, z: 0 } });dispose()
dispose():
void
Destroys every entity, cancels every coroutine, releases every Lite node, and clears every index. The Lite scene itself belongs to the app and is left alone.
Returns
void
findAllByName()
findAllByName(
name):Entity[]
Every entity with a name, depth-first from the roots of every scene.
Parameters
name
string
The name to match exactly.
Returns
Entity[]
A freshly allocated array; empty when nothing matches.
findByName()
findByName(
name):Entity|null
The first entity with a name, depth-first from the roots of every scene.
Parameters
name
string
The name to match exactly.
Returns
Entity | null
The first match, or null.
Remarks
Linear in the number of entities, and names are not unique: this is a prototyping and tooling
convenience, not a lookup the engine itself uses
(docs/architecture/02-scene-graph.md §4).
findByTag()
findByTag(
tag): readonlyEntity[]
Every entity carrying a tag.
Parameters
tag
string
The tag.
Returns
readonly Entity[]
The live list of tagged entities. A tag nothing carries yields a shared frozen empty array.
Remarks
Indexed, not searched: the world maintains one array per tag as tags.add/tags.delete run
and as entities are destroyed, so this is O(1) to obtain and allocates nothing. The array is
live and its identity is stable for the tag's lifetime in this world, so it can be cached
in awake; treat it as read-only.
getComponentByHandle()
getComponentByHandle(
handle):Component|null
Resolves a dense component handle.
Parameters
handle
The handle, as a Lite node's metadata.ignifx tag carries it.
Returns
Component | null
The component, or null when the handle is stale.
getEntity()
getEntity(
uid):Entity|null
Looks an entity up by its stable identifier.
Parameters
uid
string
The ULID.
Returns
Entity | null
The entity, or null when nothing in this world carries that uid.
getEntityByHandle()
getEntityByHandle(
handle):Entity|null
Resolves a dense runtime handle.
Parameters
handle
The handle.
Returns
Entity | null
The entity, or null when the handle is stale — a handle kept across a destroy never
resolves to whatever entity recycled the slot.
instantiate()
instantiate(
scene,options?):Entity
Instantiates a loaded scene asset as a prefab (ADR-0005) and answers with its root.
Parameters
scene
The loaded scene asset.
options?
Parent, owning instance, name, and initial placement.
Returns
The instance root.
Remarks
Synchronous, because a SceneAsset carries its dependencies already loaded. Every entity gets
a fresh uid and an Entity.prefab link (02-scene-graph.md §6, §10). A file with exactly one
root answers with that root; a file with several gets a container entity named after the scene,
so the call always answers with one entity.
awake follows the same rule as addComponent: queued for the frame's lifecycle flush, or run
nested and synchronously when instantiate is called from inside a callback
(01-lifecycle-and-time.md §4).
Throws
IgnifxError with code IGX-0301 when a scene the file instances is not loaded, and
IGX-0302 when instancing would nest a scene inside itself.
Example
const enemy = world.instantiate(enemyPrefab, { position: { x: 4, y: 0, z: 2 } });instantiateAsync()
instantiateAsync(
scene,options?):Promise<Entity>
Loads a scene asset and instantiates it (docs/architecture/02-scene-graph.md §2).
Parameters
scene
string | AssetRef<SceneAsset>
The scene address, or a reference carrying one.
options?
Parent, owning instance, name, and initial placement.
Returns
Promise<Entity>
The instance root, once the asset and its dependencies have loaded.
Example
const enemy = await world.instantiateAsync("prefabs/enemy.prefab.json");loadScene()
loadScene(
scene,options?):Promise<SceneInstance>
Loads a scene file and builds its entities (docs/architecture/02-scene-graph.md §2).
Parameters
scene
string | AssetRef<SceneAsset>
The scene address, or a reference carrying one.
options?
The mode, cancellation, progress, and whether to make the result active.
Returns
Promise<SceneInstance>
The instance, once every entity exists, every reference is resolved, and awake has
run.
Remarks
"single" (the default) unloads every instance that is not persistent first — the implicit
"default" scene is persistent, so entities created in code survive. The asset and everything
it references are loaded before a single entity is created, which is what lets asset() fields
be usable in awake (06-serialization-and-scene-format.md §4 step 2).
Construction happens in one synchronous block once the asset is in memory, so nothing observes
a half-built scene; awake and onEnable then run in tree order, through the world's own
lifecycle flush, before the returned promise settles. A component queued for awake by
something else earlier in the frame is flushed with it — the flush drains the whole queue, as
it does in the frame.
Throws
IgnifxError with code IGX-0502 when options.signal aborts, and whatever the asset
system throws for a missing or malformed file.
Example
const level = await world.loadScene("levels/level01.scene.json", { mode: "additive" });moveEntityToScene()
moveEntityToScene(
entity,scene):void
Moves a root entity and its subtree to another scene instance
(docs/architecture/02-scene-graph.md §6). This is the per-object equivalent of marking a
whole instance persistent.
Parameters
entity
The entity to move; it must be a root.
scene
The instance that will own it.
Returns
void
Throws
IgnifxError with code IGX-0309 when the entity has a parent — a child follows its
parent's instance, so reparent it first — and IGX-0101 when it has been destroyed.
Example
world.moveEntityToScene(player, world.scenes[0]);raycastRender()
raycastRender(
ray,options?):RenderPick|null
Casts a ray against every renderable mesh in the world, on the CPU
(docs/architecture/07-rendering.md §3).
Parameters
ray
The ray to cast.
options?
An entity filter.
Returns
RenderPick | null
What was hit, or null for a miss.
Remarks
Distinct from a physics raycast (09-physics.md §5): this hits render geometry, including
meshes that carry no collider, and it ignores visibility — a hidden mesh still occludes, which
is Lite's documented behaviour (src/lite/picking.ts). It reads each mesh's CPU vertex copy, so
a mesh built from a GPU-only path is silently skipped and app.renderer.pickAsync is the exact
answer.
Example
const hit = world.raycastRender(camera.screenToRay(x, y) ?? createRay());unloadScene()
unloadScene(
instance):Promise<void>
Unloads a scene instance: onUnloading fires while its entities are still valid, its roots are
destroyed through the normal destroy path (children before parents, onDisable then
onDestroy), and the assets it held are released
(docs/architecture/02-scene-graph.md §3).
Parameters
instance
The instance to unload. Unloading the implicit "default" scene, or an
instance this world does not own, does nothing.
Returns
Promise<void>
A promise that settles once the destroy flush has run.
Example
await world.unloadScene(level);WorldAnchor
An entity-to-element anchor.
Example
const tag = document.createElement("div");
tag.textContent = "Boss";
app.ui.layer("hud").element?.append(tag);
const anchor = enemy.addComponent(WorldAnchor);
anchor.element = tag;
anchor.offset = { x: 0, y: 2, z: 0 };Extends
Implements
Constructors
Constructor
new WorldAnchor():
WorldAnchor
Builds an anchor with the schema's defaults.
Returns
Overrides
Properties
allowMultiple
staticallowMultiple:boolean
One anchored element per entity.
clampToScreen
clampToScreen:
boolean
Whether the element is kept inside the overlay's bounds instead of being hidden off-screen.
element
element:
HTMLElement|null
The element to position. Not serialised — a DOM node cannot be — so a scene file carries the
flags and the game assigns the element in awake.
hideWhenBehindCamera
hideWhenBehindCamera:
boolean
Whether the element is hidden when the anchor point is behind the camera.
maxScale
maxScale:
number
The largest scale distance scaling may produce.
minScale
minScale:
number
The smallest scale distance scaling may produce.
offset
offset:
Vec3Like
A world-space offset added to the entity's position before projecting, in metres.
referenceDistance
referenceDistance:
number
The distance at which WorldAnchor.scaleWithDistance produces a scale of 1, in metres.
scaleWithDistance
scaleWithDistance:
boolean
Whether the element shrinks with distance.
schema
staticschema:Schema
The declarative fields (ADR-0004).
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
placement
Get Signature
get placement():
Readonly<AnchorPlacement>
Where the element was placed on the last synchronised frame.
Returns
Readonly<AnchorPlacement>
The placement; visible is false before the first sync.
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Hides the element when the component goes away, so an orphaned tag does not linger.
Returns
void
Implementation of
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
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
WorldText
World-space 3D text.
Example
const sign = app.world.createEntity("sign").addComponent(WorldText);
sign.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
sign.text = "Danger";
sign.billboard = true;Extends
Implements
Constructors
Constructor
new WorldText():
WorldText
Builds a sign with the schema's defaults.
Returns
Overrides
Properties
align
align:
"left"|"center"|"right"
Which edge the lines align to.
Inherited from
allowMultiple
staticallowMultiple:boolean
One sign per entity.
alwaysOnTop
alwaysOnTop:
boolean
Whether the text draws through geometry in front of it.
billboard
billboard:
boolean
Whether the text turns to face the camera instead of following the entity's rotation.
color
color:
ColorLike
The colour every glyph starts with.
Inherited from
font
font:
AssetHandle<FontAsset> |null
The TTF or OTF the glyphs come from.
Inherited from
fontSize
fontSize:
number
The em size, in render-target pixels.
Inherited from
i18nKey
i18nKey:
string
A translation key looked up in app.i18n; wins over TextComponent.text.
Inherited from
lineHeight
lineHeight:
number
The line-height multiplier.
Inherited from
maxWidth
maxWidth:
number
The wrap width, in render-target pixels; 0 does not wrap.
Inherited from
offset
offset:
Vec3Like
A local offset added to the entity's world position, in metres.
opacity
opacity:
number
The whole-block alpha multiplier.
Inherited from
pixelsPerUnit
pixelsPerUnit:
number
How many pixels of laid-out text span one world metre.
schema
staticschema:Schema
The declarative fields (ADR-0004).
text
text:
string
The literal string to draw; ignored when TextComponent.i18nKey is set.
Inherited from
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
TextComponent.isEnabledInHierarchy
lite
Get Signature
get lite():
object
The Babylon Lite objects the component owns. Unstable escape hatch.
Returns
object
The renderable, or null before the first frame that had a font and a string.
renderable
readonlyrenderable:TextRenderable|null
metrics
Get Signature
get metrics():
TextMetrics
The block's laid-out size, in render-target pixels.
Remarks
{ width: 0, height: 0 } until the block exists. This is Lite's only text measurement, and
it is what a caller centring a block on the screen needs — Lite's align aligns lines against
each other, not against the screen.
Example
const label = entity.addComponent(HudText);
label.metrics.width; // 0 until a font and a string are setReturns
The size.
Inherited from
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Silences and releases the renderable when the component goes away.
Returns
void
Implementation of
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
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
TextComponent.requireComponent
resolveText()
resolveText(
i18n):string
The string that will actually be drawn: the translated i18nKey, or text.
Parameters
i18n
I18nService | null
The localization service, or null when the app has none.
Returns
string
The resolved string.
Inherited from
WorldText2D
World-anchored pixel-space text.
Example
const damage = app.world.createEntity("damage").addComponent(WorldText2D);
damage.font = app.assets.load<FontAsset>("ui/Inter-Regular.ttf");
damage.text = "-12";
damage.offset = { x: 0, y: 1.8, z: 0 };Extends
Implements
Constructors
Constructor
new WorldText2D():
WorldText2D
Builds a floating label with the schema's defaults.
Returns
Overrides
Properties
align
align:
"left"|"center"|"right"
Which edge the lines align to.
Inherited from
allowMultiple
staticallowMultiple:boolean
One floating label per entity.
color
color:
ColorLike
The colour every glyph starts with.
Inherited from
font
font:
AssetHandle<FontAsset> |null
The TTF or OTF the glyphs come from.
Inherited from
fontSize
fontSize:
number
The em size, in render-target pixels.
Inherited from
hideWhenBehindCamera
hideWhenBehindCamera:
boolean
Whether the label is hidden when the anchor point is behind the camera.
i18nKey
i18nKey:
string
A translation key looked up in app.i18n; wins over TextComponent.text.
Inherited from
lineHeight
lineHeight:
number
The line-height multiplier.
Inherited from
maxWidth
maxWidth:
number
The wrap width, in render-target pixels; 0 does not wrap.
Inherited from
offset
offset:
Vec3Like
A world-space offset added to the entity's position before projecting, in metres.
opacity
opacity:
number
The whole-block alpha multiplier.
Inherited from
order
order:
number
The sort order within the text renderer; lower draws first.
pivot
pivot:
"topLeft"|"top"|"topRight"|"left"|"center"|"right"|"bottomLeft"|"bottom"|"bottomRight"
Which point of the block sits on the projected position.
schema
staticschema:Schema
The declarative fields (ADR-0004).
screenOffset
screenOffset:
Vec2Like
A screen-space offset added after projecting, in render-target pixels.
text
text:
string
The literal string to draw; ignored when TextComponent.i18nKey is set.
Inherited from
typeId
statictypeId:string
The registration id the serializer writes into scene files.
Accessors
app
Get Signature
get app():
App
The app that owns the world.
Returns
The app.
Inherited from
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
entity
Get Signature
get entity():
Entity
The entity this component is attached to.
Returns
The owning entity.
Inherited from
handle
Get Signature
get handle():
ComponentHandle
The dense runtime handle; invalid after destruction.
Returns
The handle.
Inherited from
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.
Whether the owner has already been destroyed.
Inherited from
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
TextComponent.isEnabledInHierarchy
lite
Get Signature
get lite():
object
The Babylon Lite objects the component owns. Unstable escape hatch.
Returns
object
The text layer, or null before the first frame that had a font and a string.
layer
readonlylayer:TextLayer|null
metrics
Get Signature
get metrics():
TextMetrics
The block's laid-out size, in render-target pixels.
Remarks
{ width: 0, height: 0 } until the block exists. This is Lite's only text measurement, and
it is what a caller centring a block on the screen needs — Lite's align aligns lines against
each other, not against the screen.
Example
const label = entity.addComponent(HudText);
label.metrics.width; // 0 until a font and a string are setReturns
The size.
Inherited from
onDestroyed
Get Signature
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
The signal. It is created on first access, so a component nobody listens to allocates nothing.
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
Inherited from
transform
Get Signature
get transform():
Transform
The entity's transform — sugar for this.entity.transform, the most-used lookup there is.
Returns
The entity's transform.
Inherited from
uid
Get Signature
get uid():
string
The stable ULID; the key files use to reference this component.
Returns
string
The identifier.
Inherited from
world
Get Signature
get world():
World
The world the entity belongs to.
Returns
The world.
Inherited from
Methods
define()
staticdefine<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
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
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
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
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
The component class; matching is by class identity and inheritance.
Returns
T | null
The first match in attach order, or null.
Inherited from
onDetach()
onDetach():
void
Drops the layer and the block when the component goes away.
Returns
void
Implementation of
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
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
TextComponent.requireComponent
resolveText()
resolveText(
i18n):string
The string that will actually be drawn: the translated i18nKey, or text.
Parameters
i18n
I18nService | null
The localization service, or null when the app has none.
Returns
string
The resolved string.
Inherited from
Interfaces
ActionDefinition
One action of one map.
Properties
bindings
readonlybindings: readonlyBindingDefinition[]
The bindings that feed it.
name
readonlyname:string
The action name game code asks for, for example move.
type?
readonlyoptionaltype?:InputActionType
What the action produces. Defaults to button.
ActionMapDefinition
One action map: a named context such as Player, UI, or Vehicle.
Properties
actions
readonlyactions: readonlyActionDefinition[]
The actions the map declares.
enabled?
readonlyoptionalenabled?:boolean
Whether the map starts enabled. Defaults to true.
name
readonlyname:string
The map name.
ActionSetOptions
How a private action set differs from the document it is built from.
Properties
deviceSlot?
readonlyoptionaldeviceSlot?:number
The gamepad slot every <Gamepad>/… path is pinned to. Defaults to 0.
scheme?
readonlyoptionalscheme?:string
The control scheme to keep; "" keeps every binding whatever its tag.
AnchorPlacement
Where the element goes, written in place so the per-frame path allocates nothing.
Properties
scale
scale:
number
The uniform scale to draw the element at.
visible
visible:
boolean
Whether the element is shown at all.
x
x:
number
The x, in UI units from the overlay root's left edge.
y
y:
number
The y, in UI units from the overlay root's top edge.
AnimatedTilemapSink
Anything that owns animated tiles and can step them.
Methods
advanceAnimatedTiles()
advanceAnimatedTiles(
world,deltaSeconds):void
Advances every animated tile by one frame's worth of scaled time.
Parameters
world
The world holding the tilemaps.
deltaSeconds
number
The scaled frame delta, time.deltaTime.
Returns
void
AnimatorBlendChildDefinition
One child of a 1D blend tree.
Properties
clip
readonlyclip:string
The animation-group name this child plays.
threshold
readonlythreshold: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
readonlychildren: readonlyAnimatorBlendChildDefinition[]
The children, sorted ascending by threshold.
name
readonlyname:string
The tree's name; what a state's blendTree takes.
param
readonlyparam:string
The parameter the tree reads.
AnimatorConditionDefinition
One condition of one transition.
Properties
op
readonlyop:"gt"|"gte"|"lt"|"lte"|"eq"|"neq"|"trigger"
The comparison.
param
readonlyparam:string
The parameter to test.
value
readonlyvalue:number
What to compare against. Booleans are 1 and 0; ignored by trigger.
AnimatorDefinition
The parsed .animator.json document.
Properties
blendTrees1D
readonlyblendTrees1D: readonlyAnimatorBlendTreeDefinition[]
Every 1D blend tree.
format
readonlyformat:"ignifx.animator"
Always "ignifx.animator".
formatVersion
readonlyformatVersion:number
Always 1 in this build.
layers
readonlylayers: readonlyAnimatorLayerDefinition[]
Every layer, in blend order: the first is the base.
parameters
readonlyparameters: readonlyAnimatorParameterDefinition[]
Every parameter, in declaration order.
states
readonlystates: readonlyAnimatorStateDefinition[]
Every state, in declaration order.
transitions
readonlytransitions: readonlyAnimatorTransitionDefinition[]
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
readonlyname:string
The name emitted on Animator.onEvent.
time
readonlytime: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?
readonlyoptionalblendTrees1D?: readonlyunknown[]
The 1D blend trees.
format?
readonlyoptionalformat?:string
Always "ignifx.animator" when present.
formatVersion?
readonlyoptionalformatVersion?:number
The document version.
layers?
readonlyoptionallayers?: readonlyunknown[]
The layers; a document that declares none gets one base layer.
parameters?
readonlyoptionalparameters?: readonlyunknown[]
The parameters.
states?
readonlyoptionalstates?: readonlyunknown[]
The states.
transitions?
readonlyoptionaltransitions?: readonlyunknown[]
The transitions.
AnimatorLayerDefinition
One layer: an independent state machine whose pose is blended over the layers below it.
Properties
additive
readonlyadditive:boolean
Whether the layer adds to the pose beneath it rather than replacing it.
defaultState
readonlydefaultState:string
The state the layer starts in; the layer's first state when the document omits it.
mask
readonlymask: readonlystring[]
The bone names the layer's mask lists. Empty means "no mask".
maskMode
readonlymaskMode:"include"|"exclude"
Whether mask lists the bones that animate or the bones that do not.
name
readonlyname:string
The layer's name; what play({ layer }) and currentState(layer) take.
weight
readonlyweight:number
How much of this layer's pose reaches the result, in [0, 1].
AnimatorParameterDefinition
One declared parameter.
Properties
kind
readonlykind:"bool"|"trigger"|"float"|"int"
What kind of value it holds.
name
readonlyname:string
The name setFloat and a condition's param use.
value
readonlyvalue:number
The value it starts at. Ignored for trigger, which always starts clear.
AnimatorPlayOptions
What Animator.play accepts.
Properties
layer?
readonlyoptionallayer?:string
Which layer to play on; the state's own layer when omitted.
transitionSeconds?
readonlyoptionaltransitionSeconds?:number
How long to crossfade for, in seconds. 0 — the default — cuts.
AnimatorStateDefinition
One state of one layer.
Properties
blendTree
readonlyblendTree:string
The 1D blend tree this state plays. Empty when clip names a single clip.
clip
readonlyclip:string
The animation-group name this state plays. Empty when blendTree names one instead.
events
readonlyevents: readonlyAnimatorEventDefinition[]
The events fired as the state plays.
layer
readonlylayer:string
The layer the state belongs to; the first layer when the document omits it.
loop
readonlyloop:boolean
Whether the state restarts at its end.
name
readonlyname:string
The state's name, unique in the document; what play and a transition's to take.
speed
readonlyspeed:number
A multiplier on the clip's own rate. Negative values play the state backwards.
AnimatorTransitionDefinition
One transition.
Properties
conditions
readonlyconditions: readonlyAnimatorConditionDefinition[]
Every condition, all of which must pass. An empty list passes.
duration
readonlyduration:number
How long the crossfade takes, in seconds. 0 cuts.
exitTime
readonlyexitTime: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
readonlyfrom:string
The state this leaves, or ANY_STATE.
interruptible
readonlyinterruptible:boolean
Whether the transition may start while another transition is already in flight.
to
readonlyto:string
The state this enters.
App
The root object of a game and the surface a script sees through this.app
(docs/architecture/00-overview.md §1). There are no globals: every engine service is reached
from here, or from the entity/world a script belongs to (CONSTITUTION.md §3.6).
Remarks
Extensions add typed properties through declaration merging
(docs/architecture/03-scripting-and-components.md §7), so this.app.input is fully typed when
@ignifx/input is installed and a compile error when it is not.
Example
class Menu extends Script {
static updateWhenPaused = true;
onEnable(): void {
this.app.pause();
}
}Properties
assets
readonlyassets:Assets
Addressed, reference-counted asset loading (docs/architecture/05-assets-and-loading.md §4).
audio
readonlyaudio:AudioService
The audio service (docs/architecture/10-audio.md §1): the mixer tree, the unlock state,
one-shots, and the listener.
coroutines
readonlycoroutines:CoroutineHost
The coroutine scheduler.
desktop
readonlydesktop:Desktop
The desktop service (docs/architecture/14-platform-electron.md §3): full screen, the window
title, quitting, the open dialog, external links, and the host window's lifecycle events.
Remarks
Always defined once electron() is registered. In a browser build every method rejects with
IGX-1462 and isElectron is false.
devtools
readonlydevtools:DevtoolsService
The devtools overlay (docs/architecture/15-devtools-and-diagnostics.md §4): open and close,
the nine panels, and the inspector's selection.
diagnostics
readonlydiagnostics:Diagnostics
Per-frame counters and profiling scopes.
events
readonlyevents:AppEvents
Engine-wide events (docs/architecture/02-scene-graph.md §8).
hotReload
readonlyhotReload:HotReloadHost
Script and scene hot reload (docs/architecture/15-devtools-and-diagnostics.md §5). The Vite
plugin's HMR client drives it in development; it works headlessly with no bundler at all.
i18n
readonlyi18n:I18nService
The localization service (docs/architecture/13-ui.md §3): .i18n.json documents,
{name} interpolation, ICU-style plurals, and the active locale.
input
readonlyinput:InputService
The input service (docs/architecture/08-input.md §1): devices, action maps, control
schemes, pointer lock, the cursor, and the frame's raw event stream.
isHeadless
readonlyisHeadless:boolean
true when the app runs on Lite's null engine with no render surface.
isRunning
readonlyisRunning:boolean
true between start() and stop()/dispose().
lite
readonlylite:AppLiteHandles
Unstable Babylon Lite escape hatch (docs/architecture/00-overview.md §3).
log
readonlylog:Logger
The app-scoped logger.
navigation
readonlynavigation:NavigationService
Navigation (docs/architecture/12-3d-toolkit.md §5): path queries, the navmesh surfaces in
the world, and the lazily loaded Recast module behind both.
onError
readonlyonError:Signal<ErrorReport>
Every failure the engine caught at a boundary rather than rethrowing.
physics
readonlyphysics:PhysicsService
3D physics: gravity, queries, the debug viewer, and the Lite escape hatch.
physics2d
readonlyphysics2d:Physics2DService
2D physics: gravity, queries, and the Rapier escape hatch.
platform
readonlyplatform:PlatformInfo
Where the app is running, what it is running on, and what its WebGPU adapter offers
(docs/architecture/14-platform-electron.md §1).
renderer
readonlyrenderer:Renderer
Surface sizing, material warm-up, GPU picking, screenshots, and the render diagnostics
(docs/architecture/07-rendering.md §1, §3, §5).
services
readonlyservices:ServiceRegistry
Services registered by extensions.
settings
readonlysettings:AppSettings
Resolved project settings.
storage
readonlystorage:Storage
The asynchronous key-value store settings, save games, and input rebindings live in
(docs/architecture/14-platform-electron.md §2). The backend is chosen from
PlatformInfo.kind — IndexedDB in a browser, memory under Node — unless createApp was
given one.
time
readonlytime:Time
The clock.
tweens
readonlytweens:Tweens
The app-wide tween list (docs/architecture/12-3d-toolkit.md §4), advanced in PostUpdate on
ignifx's clock and used by both toolkits.
twoD
readonlytwoD:TwoDService
The 2D service (docs/architecture/11-2d-toolkit.md §1): the pixels-per-unit conversion, the
active Camera2D, sprite picking, the sprite-layer diagnostics, and the Lite escape hatch.
ui
readonlyui:UiHost
The DOM overlay host (docs/architecture/13-ui.md §1): the root over the canvas, the named
layers, the scaling modes, the safe-area variables, and the focus flag.
version
readonlyversion:string
The @ignifx/core version this app was built from.
world
readonlyworld:World
The running simulation.
Methods
dispose()
dispose():
void
Stops the loop, disposes the world, the extensions, and the Lite objects.
Returns
void
pause()
pause():
void
Sets time.paused.
Returns
void
registerComponents()
registerComponents(
types):void
Makes component typeIds known to the serializer and the inspector
(docs/architecture/03-scripting-and-components.md §4).
Parameters
types
readonly ConcreteComponentType<Component>[]
The component classes to register.
Returns
void
Throws
IgnifxError with code IGX-0203 when a typeId is already registered.
resume()
resume():
void
Clears time.paused.
Returns
void
start()
start():
Promise<void>
Runs extension onStart hooks and starts the frame loop.
Returns
Promise<void>
A promise that settles once the first frame has been submitted.
step()
step(
deltaSeconds):void
Runs exactly one frame with a supplied delta — the headless driver
(docs/architecture/01-lifecycle-and-time.md §8).
Parameters
deltaSeconds
number
The raw frame delta in seconds, before the maximum-delta clamp.
Returns
void
stop()
stop():
void
Stops the frame loop without disposing anything.
Returns
void
AppEvents
The engine-wide events reached as app.events (docs/architecture/02-scene-graph.md §8,
07-rendering.md §4). Extensions add their own signals through declaration merging, the same way
they add app properties.
Example
class Hud extends Script {
onEnable(): void {
this.app.events.onSceneLoaded.connect((scene) => this.rebuild(scene), { owner: this });
}
}Properties
onDeviceLost
readonlyonDeviceLost:SignalLike<DeviceLostInfo>
The WebGPU device was lost; rendering is suspended while Lite rebuilds it.
onDeviceRecovered
readonlyonDeviceRecovered:SignalLike
The WebGPU device and its resources were rebuilt.
onDeviceRecoveryFailed
readonlyonDeviceRecoveryFailed:SignalLike<unknown>
Recovery failed; the payload is whatever the recovery path reported.
onSceneLoaded
readonlyonSceneLoaded:SignalLike<SceneInstance>
A scene instance and its entities exist.
onSceneUnloaded
readonlyonSceneUnloaded:SignalLike<SceneInstance>
A scene instance is about to be unloaded and its entities destroyed.
AppLiteHandles
Babylon Lite objects an app owns. Unstable escape hatch
(docs/architecture/00-overview.md §3); excluded from the stability guarantees of
CONSTITUTION.md Article IV.
Properties
engine
readonlyengine:EngineContext
The Lite engine — a WebGPU engine, or the null engine in headless mode.
scene
readonlyscene:SceneContext
The Lite scene the world renders into.
AppSettings
Resolved project settings, reached as app.settings
(docs/architecture/04-extensions.md §5). Each section is validated against the schema the
owning extension registered.
Properties
layers
readonlylayers:LayersSettings
The core layers section.
sortingLayers
readonlysortingLayers:SortingLayersSettings
The core sortingLayers section.
time
readonlytime:TimeSettings
The core time section.
Methods
section()
section<
S>(name):S
Reads an extension-registered section.
Type Parameters
S
S
The section's resolved shape.
Parameters
name
string
The section name the extension registered.
Returns
S
The resolved section.
Throws
IgnifxError with code IGX-0407 when the section was never registered.
ArgumentNode
A {name} substitution.
Properties
kind
readonlykind:"argument"
The discriminator.
name
readonlyname:string
The parameter name.
ArrayFieldSpec
Kind-specific data for array.
Properties
item
readonlyitem:FieldDefinition<unknown>
The field definition every element follows.
kind
readonlykind:"array"
The array kind.
AsepriteAnimationImportOptions
What importAsepriteAnimations accepts alongside the document.
Properties
atlas?
readonlyoptionalatlas?:string
The .atlas.json address the clips index into. Defaults to "", the renderer's own atlas.
defaultFps?
readonlyoptionaldefaultFps?:number
The rate a tag gets when Aseprite recorded no usable frame durations. Defaults to 12.
frameNameOf?
readonlyoptionalframeNameOf?: (index) =>string
Names the atlas frame at a document frame index. Defaults to the same normalisation
importAsepriteAtlas applies to the document's own frame keys, which is what makes the two
imports agree; override it when the atlas was produced some other way.
Parameters
index
number
Returns
string
AsepriteImportOptions
What importAsepriteAtlas accepts alongside the document.
Properties
image?
readonlyoptionalimage?:string
The image address to write into the atlas. Defaults to the document's meta.image.
premultipliedAlpha?
readonlyoptionalpremultipliedAlpha?:boolean
Whether the image's RGB is already multiplied by its alpha. Defaults to false.
sampling?
readonlyoptionalsampling?:"linear"|"nearest"
The min/mag filter. Defaults to "linear"; pixel art wants "nearest".
AssetFieldSpec
Kind-specific data for asset.
Properties
assetType
readonlyassetType:AssetTypeToken<unknown>
The asset class the field may point at.
kind
readonlykind:"asset"
The asset-reference kind.
typeName
readonlytypeName:string|null
The type discriminator written into files, or null when the address is unambiguous.
AssetHandle
The reference-counted handle every load returns
(docs/architecture/05-assets-and-loading.md §3). Handles are shared: two loads of the same
(address, type) return the same object with refCount incremented, and each load must be
paired with exactly one AssetHandle.release.
Remarks
A handle never becomes an invalid object. After the last holder releases it and the collector
has run, state is "released" and reading value throws IGX-0501; loading the same address
again starts a fresh load and returns a fresh handle.
Example
const model = app.assets.load<ModelAsset>("models/hero.glb");
// In a coroutine: `yield model.promise` resumes on the first Update after delivery.
await model.promise;
model.release();Type Parameters
T
T = unknown
The loaded value type.
Properties
address
readonlyaddress:string
The address this handle was requested under, fragment included.
error
readonlyerror:AssetLoadError|null
Why the load failed, or null when it has not.
onReplaced
readonlyonReplaced:SignalLike<T>
Emitted at delivery when hot reload replaced the value; value is already the new one.
progress
readonlyprogress:number
How far along the load is, in [0, 1]; bytes-weighted when the sizes are known.
promise
readonlypromise:Promise<T>
Resolves with AssetHandle.value at delivery, or rejects with an AssetLoadError.
refCount
readonlyrefCount:number
How many holders the handle has.
state
readonlystate:AssetState
Where the handle is in its life.
type
readonlytype:string
The asset type the loader is registered under, for example "model".
value
readonlyvalue:T
The loaded value.
Throws
IgnifxError with code IGX-0501 unless state is "loaded".
Methods
[dispose]()
[dispose]():
void
Releases one holder when the handle leaves a using block — exactly AssetHandle.release
(docs/architecture/05-assets-and-loading.md §3).
Returns
void
Example
using icon = app.assets.load<TextureAsset>("ui/icon.png");
await icon.promise;release()
release():
void
Removes a holder. At zero the asset is unloaded after assets.gcDelay seconds.
Returns
void
retain()
retain():
this
Adds a holder.
Returns
this
This handle, so a retain reads inline.
AssetLoader
How one asset type is turned into a value
(docs/architecture/05-assets-and-loading.md §5). Loaders are pure with respect to the world:
they produce values and never create entities.
Example
const jsonLoader: AssetLoader<unknown> = {
type: "json",
extensions: [".json"],
load: (ctx) => ctx.fetchJson(),
};Type Parameters
T
T = unknown
The value the loader produces.
Properties
extensions
readonlyextensions: readonlystring[]
The address suffixes that select this loader, each with its leading dot.
type
readonlytype:string
The type name the loader is registered under, for example "texture".
Methods
load()
load(
ctx):Promise<T>
Produces the value.
Parameters
ctx
The address, the fetch helpers, and the abort signal.
Returns
Promise<T>
The loaded value.
parseFragment()?
optionalparseFragment(fragment,value):unknown
Extracts a sub-asset named by an address fragment, such as #animation:Run.
Parameters
fragment
string
The text after #.
value
T
The base address's value.
Returns
unknown
The sub-asset.
Remarks
Declaring it is what makes models/hero.glb#animation:Run load the base address once and share
it: the fragment handle retains the base handle and its value is whatever this returns. A
loader that does not declare it is invoked with the fragment in LoaderContext.fragment
and owns the whole address itself.
reload()?
optionalreload(ctx,previous):Promise<T>
Re-produces the value in development hot reload. Defaults to unload plus load.
Parameters
ctx
The context for the new load.
previous
T
The value being replaced.
Returns
Promise<T>
The new value.
unload()?
optionalunload(value,ctx):void
Releases whatever the value owns — GPU buffers, audio nodes, object URLs.
Parameters
value
T
The value AssetLoader.load produced.
ctx
The same context the load ran with.
Returns
void
AssetLoadErrorOptions
Options accepted by AssetLoadError.
Extends
Properties
address
readonlyaddress:string
The address that failed.
cause?
optionalcause?:unknown
Inherited from
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure. Defaults to an empty record.
Inherited from
hint?
readonlyoptionalhint?:string|null
One sentence telling the developer what to do about it. Defaults to null.
Inherited from
mode?
readonlyoptionalmode?:ErrorFormatMode
How verbose message should be. Defaults to "development".
Inherited from
url
readonlyurl:string
The URL it resolved to.
AssetManifest
The address-to-URL table generated by @ignifx/vite-plugin
(docs/architecture/05-assets-and-loading.md §7).
Properties
entries
readonlyentries: readonlyAssetManifestEntry[]
Every addressed file.
format
readonlyformat:"ignifx.manifest"
The file's format discriminator.
formatVersion
readonlyformatVersion:1
The format version this build can read.
root
readonlyroot:string
The asset root every relative address is resolved against.
AssetManifestEntry
One address in the manifest (docs/architecture/05-assets-and-loading.md §7).
Properties
address
readonlyaddress:string
The address game code asks for.
bytes?
readonlyoptionalbytes?:number
The byte size, when the build knows it; it makes progress bytes-weighted.
groups?
readonlyoptionalgroups?: readonlystring[]
The group labels this entry belongs to, such as "boot" or "level1".
hash?
readonlyoptionalhash?:string
The content hash, for cache validation.
meta?
readonlyoptionalmeta?:JsonObject
The .meta.json sidecar the build read for this address, verbatim
(docs/architecture/05-assets-and-loading.md §7). Loaders read the sub-object they own — the
texture loader reads meta.texture, the model loader reads meta.model — and ignore the rest,
so one sidecar can carry options for several tools.
Example
{ "groups": ["level1"], "texture": { "srgb": true, "mipMaps": false } }type?
readonlyoptionaltype?:string
The asset type, when the extension does not identify it.
url
readonlyurl:string
The URL to fetch, usually content-hashed in production builds.
AssetProgress
The aggregate payload of Assets.onProgress: how the current batch of work is going
(docs/architecture/05-assets-and-loading.md §4).
Properties
bytesLoaded
readonlybytesLoaded:number
Bytes received so far.
bytesTotal
readonlybytesTotal:number
Bytes expected, as far as the manifest and the response headers say.
loaded
readonlyloaded:number
How many of the loads in flight have settled.
total
readonlytotal:number
How many loads are in the current run.
AssetRef
The serializable form of an asset reference (docs/architecture/05-assets-and-loading.md §2).
It is a plain object so that it survives JSON.stringify and the schema codec unchanged; the way
to turn one into a handle is app.assets.load(ref), never a method on the reference.
Example
const hero: AssetRef<ModelAsset> = assetRef("models/hero.glb");
const handle = app.assets.load(hero);Type Parameters
T
T = unknown
The loaded value type this reference points at. It is a compile-time marker only:
assetOf is never assigned at runtime and is never serialized. It exists so that
AssetRef<TextureAsset> and AssetRef<ModelAsset> are different types.
Properties
address
readonlyaddress:string
The address, for example models/hero.glb or sprites/ui.atlas.json#frame:button_idle.
assetOf?
readonlyoptionalassetOf?:T
Compile-time marker for the loaded value type; never present at runtime.
type?
readonlyoptionaltype?:string
The asset type name, when the address alone does not identify it.
AssetRefValue
The plain, serializable form of an asset reference: what { "$asset": … } decodes to before the
asset service turns it into a handle, and what a tool that reads a scene file without an app
works with (docs/architecture/05-assets-and-loading.md §2).
Remarks
It is not the runtime value of an asset() field. Since Phase 2 that value is
AssetHandle<A> | null: a component receives the handle already loaded
(docs/architecture/05-assets-and-loading.md §3), so this.mesh?.value reaches the asset with no
second lookup. The two shapes overlap on address/type, which is why the encoder accepts
either.
Type Parameters
A
A
The asset value type this reference points at. It is a compile-time marker only:
assetOf is never assigned at runtime and is never serialized. It exists so that
AssetRefValue<Texture> and AssetRefValue<Mesh> are different types.
Properties
address
readonlyaddress:string
The address the asset is registered under, for example models/hero.glb#mesh:Body.
assetOf?
readonlyoptionalassetOf?:A
Compile-time marker for the asset type; never present at runtime.
type?
readonlyoptionaltype?:string
The asset type name, when the address alone does not identify it.
Assets
The asset service, reached as app.assets
(docs/architecture/05-assets-and-loading.md §4).
Example
const batch = app.assets.loadAll(["ui/font.ttf", "sprites/hero.png"]);
app.assets.onProgress.connect((p) => bar.set(p.loaded / p.total));
await batch.promise;Properties
gcDelay
gcDelay:
number
How many seconds a zero-reference asset stays cached. 0 unloads at the next delivery.
manifest
readonlymanifest:AssetManifest
The address-to-URL table, empty until a build supplies one.
onProgress
readonlyonProgress:SignalLike<AssetProgress>
Emitted at delivery whenever the aggregate progress of the loads in flight changed.
Methods
gc()
gc():
void
Unloads every zero-reference asset now, without waiting for Assets.gcDelay.
Returns
void
get()
get<
T>(address):AssetHandle<T> |null
Looks a cached handle up without changing its reference count.
Type Parameters
T
T
The loaded value type.
Parameters
address
string
The address, fragment included.
Returns
AssetHandle<T> | null
The handle, or null when the address is not cached.
load()
load<
T>(ref,options?):AssetHandle<T>
Requests an asset and returns its handle immediately.
Type Parameters
T
T
The loaded value type.
Parameters
ref
string | AssetRef<T>
The address, or a reference carrying one.
options?
Priority, type, progress, and cancellation.
Returns
AssetHandle<T>
The shared handle, with one more holder.
Remarks
Completion is delivered in the PreUpdate phase of a later frame, never mid-phase: state
flips and promise settles at that one point
(docs/architecture/01-lifecycle-and-time.md §3 step 2).
An options.signal abort drops this request's hold. It aborts the shared load only when no
other request is still interested in it; a load two scripts asked for keeps going when one of
them cancels, and the shared handle still resolves.
Throws
IgnifxError with code IGX-0504 when no loader claims the address, or IGX-0106 when
the app has been disposed.
loadAll()
loadAll(
refs,options?):BatchHandle
Requests several assets as one batch.
Parameters
refs
readonly (string | AssetRef<unknown>)[]
The addresses or references.
options?
Priority, type, progress, and cancellation, applied to every member.
Returns
The batch.
loadAsync()
loadAsync<
T>(ref,options?):Promise<AssetHandle<T>>
Requests an asset and waits for the same delivery point Assets.load settles at.
Type Parameters
T
T
The loaded value type.
Parameters
ref
string | AssetRef<T>
The address, or a reference carrying one.
options?
Priority, type, progress, and cancellation.
Returns
Promise<AssetHandle<T>>
The handle, once it has loaded.
preloadGroup()
preloadGroup(
group,options?):BatchHandle
Loads every manifest entry carrying a group label.
Parameters
group
string
The label, such as "boot".
options?
Priority, progress, and cancellation.
Returns
The batch; empty when the manifest knows no such group.
register()
register<
T>(value,options):AssetHandle<T>
Publishes a value built in code as an asset, so an asset() field can hold it
(docs/architecture/05-assets-and-loading.md §3). This is what MeshAsset.box(…) and
MaterialAsset.pbr(…) return.
Type Parameters
T
T
The value type.
Parameters
value
T
The already-built value.
options
The asset type it is registered under, and an explicit address to publish it at instead of the generated one.
Returns
AssetHandle<T>
The handle, with one holder.
Remarks
The handle is created already loaded, under a synthetic memory:<type>/<ulid> address, with
one holder — the caller. It plays by the ordinary rules from there: retain/release count,
the collector unloads it gcDelay seconds after the last holder lets go, and the registered
type's loader unload runs then if one exists. Because the address names no file, serializing
a component that references it writes null and reports the loss.
Example
using box = app.assets.register(mesh, { type: "mesh" });registerLoader()
registerLoader(
loader):void
Registers a loader. Extensions normally call ctx.registerAssetLoader instead.
Parameters
loader
The loader.
Returns
void
Throws
IgnifxError with code IGX-0506 when the type is already registered.
registerType()
registerType(
type):void
Declares an asset type that has no loader yet.
Parameters
type
The type name and the extensions that select it.
Returns
void
release()
release(
handleOrAddress):void
Removes one holder from a handle, by object or by address.
Parameters
handleOrAddress
string | AssetHandle<unknown>
The handle, or the address it was requested under.
Returns
void
reload()
reload(
address):void
Reloads a loaded asset from its source, delivering the new value through onReplaced the way a
development hot reload does (docs/architecture/05-assets-and-loading.md §7); a handle that is
not loaded is left alone. The Vite plugin's HMR channel and the devtools Assets panel call it.
Parameters
address
string
The asset's address.
Returns
void
resolveUrl()
resolveUrl(
address):string
Resolves an address to the URL the service fetches.
Parameters
address
string
The address; the fragment is stripped.
Returns
string
The manifest's URL for the address, or <root>/<address>.
AssetsCreateOptions
The asset options CreateAppOptions.assets carries.
Properties
fetch?
readonlyoptionalfetch?: (input,init?) =>Promise<Response>
The fetch every asset read goes through. Defaults to globalThis.fetch.
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
manifest?
readonlyoptionalmanifest?:AssetManifest
The address-to-URL table. Defaults to an empty manifest rooted at the assets setting.
AssetsSettings
The assets project settings section
(docs/architecture/04-extensions.md §5, 05-assets-and-loading.md §4).
Properties
concurrency
readonlyconcurrency:number
How many fetches may be in flight at once. Defaults to 6.
gcDelay
readonlygcDelay:number
How many seconds a zero-reference asset stays cached. Defaults to 5.
preload
readonlypreload: readonlystring[]
Manifest group labels loaded during app.start(). Defaults to none.
retries
readonlyretries:number
How many times a failed fetch is retried. Defaults to 2.
root
readonlyroot:string
The asset root relative addresses resolve against. Defaults to "assets".
AssetTypeDefinition
An asset type declared without a loader, so that addresses resolve to a type before the loader
that reads them is registered (docs/architecture/04-extensions.md §1).
Properties
extensions
readonlyextensions: readonlystring[]
The address suffixes that select it, each with its leading dot.
type
readonlytype:string
The type name, for example "texture".
AssetTypeToken
How an asset class is named in a schema. Like ComponentTypeToken, a class satisfies it
structurally; assetType supplies the type discriminator written into { "$asset": … } when
the loader cannot infer it from the address extension
(docs/architecture/05-assets-and-loading.md §2).
Type Parameters
A
A
The asset value type the token stands for.
Properties
assetType?
readonlyoptionalassetType?:string
The asset type name written into files when the extension is ambiguous.
prototype?
readonlyoptionalprototype?:A
The instance shape the token names. A class token carries it for free; a plain token for an
asset that has no class (a scene, a prefab) leaves it out and fixes A through its annotation —
see SceneAssetToken. Nothing reads it at runtime.
AudioBackend
The audio implementation behind app.audio
(docs/architecture/10-audio.md §1, §7).
Remarks
A game never touches this. It exists so the service and the components have exactly one thing to
talk to, and so audio({ createBackend }) can substitute a recording double in a test.
Example
const app = await createApp({ headless: true, extensions: [audio({ createBackend: () => spy })] });Properties
kind
readonlykind:AudioBackendKind
Which implementation this is.
lite
readonlylite:AudioLiteHandles|null
The Lite objects this backend owns, or null when it owns none.
onStateChanged
readonlyonStateChanged:SignalLike<AudioBackendState>
Emitted whenever AudioBackend.state changes.
state
readonlystate:AudioBackendState
The audio context's current state.
Methods
createBus()
createBus(
request):Promise<BackendBus>
Creates one mixer bus.
Parameters
request
The name, gain, and parent bus.
Returns
Promise<BackendBus>
The bus.
createSound()
createSound(
request):BackendSound|Promise<BackendSound>
Creates a playable sound.
Parameters
request
The clip, routing, and per-sound options.
Returns
BackendSound | Promise<BackendSound>
The sound, or a promise for it when the backend has to decode first.
decode()
decode(
clip):Promise<void>
Decodes a static clip's bytes into a buffer every sound built from it can share, and records the exact duration on the clip. Calling it twice is a no-op, and a backend that never decodes — the headless one — does nothing at all.
Parameters
clip
The clip to decode.
Returns
Promise<void>
A promise that settles once the clip is playable.
dispose()
dispose():
void
Releases everything the backend owns, including the audio context.
Returns
void
disposeBus()
disposeBus(
bus):void
Releases a bus and its sub-graph.
Parameters
bus
The bus.
Returns
void
disposeSound()
disposeSound(
sound):void
Releases a sound and its sub-graph.
Parameters
sound
The sound.
Returns
void
getMasterVolume()
getMasterVolume():
number
Reads the master output gain.
Returns
number
The gain, where 1 is unity.
pause()
pause(
sound):void
Pauses every instance of a sound, keeping its position.
Parameters
sound
The sound.
Returns
void
play()
play(
sound,request):void
Starts one new instance of a sound, stealing the oldest when maxInstances is reached. A
paused sound is resumed instead, which is Babylon Lite's documented behaviour
(index.d.ts 8955).
Parameters
sound
The sound.
request
The per-play overrides.
Returns
void
resume()
resume(
sound):void
Resumes a paused sound.
Parameters
sound
The sound.
Returns
void
setBusVolume()
setBusVolume(
bus,volume):void
Sets a bus's own gain.
Parameters
bus
The bus.
volume
number
The gain to apply now.
Returns
void
setListener()
setListener(
target):void
Points the spatial listener at a world transform.
Parameters
target
SpatialTarget | null
The transform to follow, or null to leave the listener at the world origin.
Returns
void
setMasterVolume()
setMasterVolume(
volume):void
Sets the master output gain.
Parameters
volume
number
The gain to apply now, where 1 is unity.
Returns
void
setSoundPan()
setSoundPan(
sound,pan):void
Sets a non-spatial sound's stereo pan.
Parameters
sound
The sound.
pan
number
The pan in [-1, 1].
Returns
void
setSoundVolume()
setSoundVolume(
sound,volume):void
Sets a sound's gain.
Parameters
sound
The sound.
volume
number
The gain to apply now.
Returns
void
stop()
stop(
sound):void
Stops every instance of a sound immediately. Fading is the service's job, so that both backends fade identically.
Parameters
sound
The sound.
Returns
void
unlock()
unlock():
Promise<void>
Resumes a suspended context — what a "tap to start" prompt calls.
Returns
Promise<void>
A promise that settles once the context is running, or immediately when the backend needs no gesture.
update()
update(
deltaSeconds):void
Advances the backend by one frame: the web backend pumps updateSpatialAudio, the headless
backend advances simulated playback and fires onEnded.
Parameters
deltaSeconds
number
The frame delta in seconds.
Returns
void
AudioBackendContext
What a backend factory is handed (audio({ createBackend })).
Properties
audioContext
readonlyaudioContext:BaseAudioContext|null
An existing Web Audio context to build the engine on — an OfflineAudioContext in tests.
isHeadless
readonlyisHeadless:boolean
true when the app runs with no render surface.
masterVolume
readonlymasterVolume:number
The initial master gain.
AudioBus
A named gain in the mixer tree.
Example
app.audio.bus("Music").setVolume(0.2, 1.5); // duck the music over a second and a half
app.audio.bus("SFX").muted = true;Properties
effectiveVolume
readonlyeffectiveVolume:number
The gain that actually reaches the output: this bus's applied gain times its parents'.
lite
readonlylite:AudioBus|null
Lite's bus, or null under the headless backend. Unstable escape hatch.
muted
muted:
boolean
Silences the bus and everything under it without losing AudioBus.volume.
name
readonlyname:string
The bus name; what AudioSource.bus and app.audio.bus(name) use.
parent
readonlyparent:AudioBus|null
The bus this one routes into, or null for the root.
pausable
readonlypausable:boolean
Whether app.pause() pauses the sounds routed directly to this bus.
volume
volume:
number
This bus's own linear gain, ignoring its parents. Setting it applies immediately.
Methods
setVolume()
setVolume(
volume,rampSeconds?):void
Fades this bus's own gain.
Parameters
volume
number
The target linear gain.
rampSeconds?
number
How long the fade takes, in frame time; 0 applies immediately.
Returns
void
AudioBusDefinition
One bus of a tree, as the file declares it and as app.audio builds it.
Properties
name
readonlyname:string
The bus name, unique within the tree; what app.audio.bus(name) and AudioSource.bus use.
parent
readonlyparent:string|null
The bus this one routes into, or null for the root.
pausable
readonlypausable:boolean|null
Whether app.pause() pauses the sounds on this bus. null defers to the audio settings
section's pausableBuses list, which is the usual case.
volume
readonlyvolume:number
The bus's own linear gain, in [0, 1]. Defaults to 1.
AudioClipInit
What the loader hands AudioClip's constructor.
Properties
address
readonlyaddress:string
The address the clip was loaded from, fragment included.
bytes
readonlybytes:ArrayBuffer|null
The undecoded bytes, kept only until a backend decodes them; null for a streaming clip and
for a headless load, neither of which will ever decode.
channels
readonlychannels:number|null
How many channels the data holds, or null when unknown.
duration
readonlyduration:number|null
The playing length in seconds, or null when this build cannot tell yet.
isStreaming
readonlyisStreaming:boolean
Whether the clip streams from a media element rather than decoding into memory.
sampleRate
readonlysampleRate:number|null
Samples per second, or null when unknown.
url
readonlyurl:string
The URL the address resolved to; a streaming clip plays straight from it.
AudioClipLiteHandles
The Babylon Lite objects an AudioClip owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
buffer
readonlybuffer:SoundBuffer|null
The decoded buffer shared by every sound built from this clip, or null — headless always,
streaming always, and in a browser until the first sound is created from the clip.
AudioClipLoaderOptions
Options accepted by createAudioClipLoader.
Properties
decoder
readonlydecoder: () =>AudioDecoder|null
Returns the decoder to run on a freshly loaded static clip, or null to leave the clip
undecoded until a source plays it.
Returns
AudioDecoder | null
AudioConeSettings
The directional cone of a spatial source, in degrees (docs/architecture/10-audio.md §3).
360 on both angles is an omnidirectional source, which is the default.
Properties
innerAngle
innerAngle:
number
The angle inside which the source is heard at full volume.
outerAngle
outerAngle:
number
The angle outside which the source is heard at outerVolume.
outerVolume
outerVolume:
number
The gain outside the outer cone, in [0, 1].
AudioErrorOptions
Options accepted by audioError: the same subset of IgnifxErrorOptions this package uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
AudioLiteHandles
The Babylon Lite objects an AudioBackend owns. Unstable escape hatch
(docs/architecture/00-overview.md §3); null on the headless backend, which owns none.
Properties
engine
readonlyengine:AudioEngine
Lite's audio engine (index.d.ts 926).
AudioOptions
What audio() accepts. Every field that names a settings value overrides the matching audio
section value, which is the shape 04-extensions.md §1 shows for physics().
Properties
audioContext?
readonlyoptionalaudioContext?:BaseAudioContext|null
An existing Web Audio context to build the engine on. Pass an OfflineAudioContext to render
deterministically in a browser test.
buses?
readonlyoptionalbuses?:string
The address of the .audio.json bus tree; empty builds AudioOptions.defaultBuses.
busTree?
readonlyoptionalbusTree?: readonlyAudioBusDefinition[]
The bus tree, given directly instead of through a file. It is the only way to have a custom tree in place before the first frame, because a file has to be delivered first.
createBackend?
readonlyoptionalcreateBackend?: (context) =>AudioBackend|Promise<AudioBackend>
Builds the backend. Defaults to the Web Audio backend in a browser and the headless one
everywhere else; a test passes a recording double, or a HeadlessBackend configured to start
suspended so the unlock flow can be exercised under Node.
Parameters
context
Returns
AudioBackend | Promise<AudioBackend>
defaultBuses?
readonlyoptionaldefaultBuses?: readonlystring[]
The tree built when neither a file nor busTree is given; the first name is the root.
masterVolume?
readonlyoptionalmasterVolume?:number
The master output gain the app starts at.
pausableBuses?
readonlyoptionalpausableBuses?: readonlystring[]
Which buses app.pause() pauses.
pauseWithApp?
readonlyoptionalpauseWithApp?:boolean
Whether app.pause() pauses the sounds on pausable buses.
queueWhileLocked?
readonlyoptionalqueueWhileLocked?:boolean
Whether plays made before the first unlock are queued rather than dropped.
AudioServiceLiteHandles
The Babylon Lite objects app.audio owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
engine
readonlyengine:AudioEngine|null
Lite's audio engine, or null under the headless backend.
AudioServiceOptions
What AudioService's constructor is handed. The extension builds this; a game never does.
Properties
app
readonlyapp:App
The app the service belongs to.
backend
readonlybackend:AudioBackend
The backend every call is forwarded to.
log
readonlylog:Logger
A logger scoped to the extension.
settings
readonlysettings:AudioSettings
The resolved audio settings section, with the extension's options merged over it.
AudioSettings
The resolved audio settings section.
Example
// ignifx.config.ts
export default defineConfig({ audio: { buses: "audio/buses.audio.json", masterVolume: 0.8 } });Properties
buses
readonlybuses:string
The address of the .audio.json bus tree loaded at startup; empty builds the defaults.
defaultBuses
readonlydefaultBuses: readonlystring[]
The tree built when buses is empty: the first name is the root, the rest route into it.
masterVolume
readonlymasterVolume:number
The master output gain the app starts at, in [0, 1].
pausableBuses
readonlypausableBuses: readonlystring[]
Which buses app.pause() pauses. A bus file's own pausable field overrides this per bus.
pauseWithApp
readonlypauseWithApp:boolean
Whether app.pause() pauses the sounds on pausable buses.
queueWhileLocked
readonlyqueueWhileLocked:boolean
Whether play() calls made before the first unlock are queued and flushed on unlock.
BackendBus
A mixer bus as the backend knows it: an opaque token the service hands back with every sound it creates.
Properties
lite
readonlylite:AudioBus|null
Lite's bus, or null on the headless backend. Unstable escape hatch.
name
readonlyname:string
The bus name, as the tree declared it.
BackendBusRequest
What AudioBackend.createBus is asked for.
Properties
name
readonlyname:string
The bus name.
parent
readonlyparent:BackendBus|null
The bus it outputs into, or null to output into the engine's main bus.
volume
readonlyvolume:number
Its own linear gain, before the parent chain.
BackendPlayRequest
The per-play overrides AudioBackend.play applies, matching Babylon Lite's
StaticSoundPlayOptions (index.d.ts 12375).
Properties
delay
readonlydelay:number
How long to wait before the instance starts, in seconds.
duration
readonlyduration:number
How long the instance plays, in seconds; 0 means "to the end of the clip".
loop
readonlyloop:boolean
Whether the instance loops.
playbackRate
readonlyplaybackRate:number
The instance's playback rate.
startOffset
readonlystartOffset:number
Where in the clip the instance starts, in seconds.
volume
readonlyvolume:number
The instance's linear gain.
BackendSound
A playable sound as the backend knows it: one clip routed to one bus, able to carry several
concurrent instances (Babylon Lite's StaticSound/StreamingSound model, index.d.ts 12336 and
12499).
Remarks
There is deliberately no onEnded here. Lite raises its own onEnded from a Web Audio ended
event, which lands at an arbitrary point between frames, and a stopped sound raises it too; the
service instead polls BackendSound.isPlaying once per frame in the PreRender pump and
raises SoundInstance.onEnded there. That is what makes "the sound finished" arrive at a defined
point in the frame, the same way every other engine event does, and identical on both backends.
Properties
instanceCount
readonlyinstanceCount:number
How many instances of this sound are live.
isPaused
readonlyisPaused:boolean
true when every instance has been paused.
isPlaying
readonlyisPlaying:boolean
true while at least one instance is playing or about to.
BackendSoundRequest
What AudioBackend.createSound is asked for.
Properties
bus
readonlybus:BackendBus|null
The bus it routes into, or null for the engine's main bus.
clip
readonlyclip:AudioClip
The clip to play.
loop
readonlyloop:boolean
Whether instances loop.
maxInstances
readonlymaxInstances:number
How many instances may play at once; the oldest is stolen above it.
pan
readonlypan:number
Stereo pan in [-1, 1] for a non-spatial sound.
playbackRate
readonlyplaybackRate:number
Playback rate multiplier; ignifx's pitch field maps onto it.
spatial
readonlyspatial:BackendSpatialRequest|null
The 3D placement, or null for a non-spatial sound.
volume
readonlyvolume:number
The sound's own linear gain.
BackendSpatialRequest
The 3D placement of a spatial sound, already converted into the units Babylon Lite wants: angles
in radians (SpatialSoundOptions, index.d.ts 11771), distances in metres.
Properties
attachedTo
readonlyattachedTo:SpatialTarget|null
The world transform the source follows, or null to stay at the origin.
coneInnerAngleRadians
readonlyconeInnerAngleRadians:number
Cone inner angle in radians; 2π for an omnidirectional source.
coneOuterAngleRadians
readonlyconeOuterAngleRadians:number
Cone outer angle in radians.
coneOuterVolume
readonlyconeOuterVolume:number
Gain outside the outer cone, in [0, 1].
distanceModel
readonlydistanceModel:"linear"|"inverse"|"exponential"
Which attenuation curve to use.
maxDistance
readonlymaxDistance:number
Maximum distance, used by the "linear" model.
minDistance
readonlyminDistance:number
Reference distance below which no attenuation is applied.
rolloffFactor
readonlyrolloffFactor:number
Attenuation roll-off factor.
BatchHandle
A group of loads requested together
(docs/architecture/05-assets-and-loading.md §4).
Properties
handles
readonlyhandles: readonlyAssetHandle<unknown>[]
The handles the batch retains.
progress
readonlyprogress:number
The mean of the batch's handle progresses, in [0, 1].
promise
readonlypromise:Promise<void>
Settles once every handle in the batch has settled; rejects with the first failure.
Methods
cancel()
cancel():
void
Aborts every load the batch started and releases it.
Returns
void
release()
release():
void
Releases every handle the batch retains. Calling it twice is a no-op.
Returns
void
BindingContext
What evaluation needs to know about the frame.
Properties
currentScheme
readonlycurrentScheme:string
The control scheme in use this frame.
strictSchemes
readonlystrictSchemes:boolean
true when bindings tagged with another control scheme must not resolve.
uiHasFocus
readonlyuiHasFocus:boolean
true while a DOM text field has focus; keyboard controls then read as released.
uiHasPointer
readonlyuiHasPointer:boolean
true while a pointer is pressed on the UI overlay; pointing-device controls then read as
released, so a drag that started on a slider does not also turn the camera.
BindingDefinition
One binding of one action, as it appears in a document. A binding is either a single path or a
composite whose named parts each carry a path.
Example
{ "composite": "2DVector", "up": "<Keyboard>/w", "down": "<Keyboard>/s",
"left": "<Keyboard>/a", "right": "<Keyboard>/d" }Properties
button?
readonlyoptionalbutton?:string
The ButtonWithModifier button part.
composite?
readonlyoptionalcomposite?:string
The composite name, for a composite binding.
down?
readonlyoptionaldown?:string
The 2DVector down part.
left?
readonlyoptionalleft?:string
The 2DVector left part.
modifier?
readonlyoptionalmodifier?:string
The ButtonWithModifier modifier part.
negative?
readonlyoptionalnegative?:string
The 1DAxis negative part.
path?
readonlyoptionalpath?:string
The control path, for a simple binding.
positive?
readonlyoptionalpositive?:string
The 1DAxis positive part.
processors?
readonlyoptionalprocessors?: readonlystring[]
The processors applied to the binding's value, in order.
right?
readonlyoptionalright?:string
The 2DVector right part.
scheme?
readonlyoptionalscheme?:string
The control scheme this binding belongs to; empty means every scheme.
up?
readonlyoptionalup?:string
The 2DVector up part.
BindingResolver
What a Binding needs from the rest of the engine: path resolution, and a way to tell the service that its resolved controls changed.
Methods
invalidateBindings()
invalidateBindings():
void
Tells the owner that this binding's control set changed and subscriptions must be rebuilt.
Returns
void
resolveControl()
resolveControl(
path,kind?):ControlRef
Resolves a binding path to a device control.
Parameters
path
string
The binding path.
kind?
The kind a <Virtual> control is created with when it does not exist yet.
Returns
The resolved control.
BloomEffectSettings
The bloom record a PostProcessStack declares (docs/architecture/07-rendering.md §2.7).
Properties
enabled
enabled:
boolean
Whether the glow pass runs.
exposure
exposure:
number
An exposure applied while extracting highlights.
kernel
kernel:
number
The blur kernel width, in pixels.
order
order:
number
Position in the chain; lower runs first.
scale
scale:
number
The fraction of full resolution the blur runs at.
threshold
threshold:
number
The luminance above which a pixel glows.
weight
weight:
number
How strongly the glow is mixed back in.
BoolFieldSpec
Kind-specific data for bool.
Properties
kind
readonlykind:"bool"
The boolean kind.
BoxMeshOptions
How MeshAsset.box sizes its box, in metres. Give size for a cube, or the three
dimensions.
Properties
depth?
readonlyoptionaldepth?:number
Size along Z, overriding size.
height?
readonlyoptionalheight?:number
Size along Y, overriding size.
size?
readonlyoptionalsize?:number
Edge length on every axis.
width?
readonlyoptionalwidth?:number
Size along X, overriding size.
CapsuleMeshOptions
How MeshAsset.capsule sizes its capsule, which stands along Y.
Remarks
height is the total height including both caps, the same convention @ignifx/physics uses
for a capsule collider, so one pair of numbers describes both.
Properties
height?
readonlyoptionalheight?:number
Total height including both caps, in metres.
radius?
readonlyoptionalradius?:number
Radius of the body and the caps.
tessellation?
readonlyoptionaltessellation?:number
Radial segment count.
CharacterCollision
What CharacterController.onCollided reports: one dynamic body the character pushed this step.
Properties
impulse
readonlyimpulse:Vec3Like
The world-space impulse the character applied.
other
readonlyother:Entity|null
The entity that was pushed, or null when it is not an ignifx body.
point
readonlypoint:Vec3Like
Where the impulse was applied.
CharacterCollision2D
What CharacterController2D.onCollided reports: one obstacle the character hit this step.
Properties
normal
readonlynormal:Vec2Like
The world-space outward normal on the obstacle.
other
readonlyother:Entity|null
The entity that was hit, or null when it is not an ignifx body.
otherCollider
readonlyotherCollider:Collider2D|null
The collider that was hit, or null.
point
readonlypoint:Vec2Like
The world-space contact point.
ClipWeight
One clip's contribution to the pose this frame.
Properties
additive
readonlyadditive:boolean
Whether the clip belongs to an additive layer.
clip
readonlyclip:string
The animation-group name.
layer
readonlylayer:string
The layer the clip came from, so the adapter can find the mask.
speed
readonlyspeed:number
The playback rate to set on the group.
weight
readonlyweight:number
How much of the pose it contributes, before Lite normalizes anything.
Clock
A source of monotonically non-decreasing milliseconds.
Remarks
Only Time.realtimeSinceStartup and the development-only phase timings read it; frame deltas are
supplied by Babylon Lite's render loop or by app.step(dt), never measured from this clock, so
swapping the clock never changes simulation results (CONSTITUTION.md §2.1).
Example
const clock = createManualClock();
const app = await createApp({ headless: true, clock });
clock.advance(1000); // app.time.realtimeSinceStartup === 1Extended by
Methods
nowMs()
nowMs():
number
Reads the clock.
Returns
number
Milliseconds since an unspecified epoch; only differences are meaningful.
Collision
What a script's onCollisionEnter/onCollisionStay/onCollisionExit is handed.
Remarks
other is null under the default collisionIdentities: "upstream" mode, because
@babylonjs/[email protected] reports collisions without body identities (§4, ADR-0013). Register
physics({ collisionIdentities: "internal" }) to opt into the waived drain that recovers them.
Properties
contacts
readonlycontacts: readonlyContactPoint[]
The contacts of this event. Pooled; valid only during the callback.
other
readonlyother:Entity|null
The entity that was hit, or null when the identity is unavailable.
otherCollider
readonlyotherCollider:Collider|null
The other entity's first collider, or null.
relativeVelocity
readonlyrelativeVelocity:Vec3Like|null
The relative velocity at the contact, or null when a body identity is unavailable.
self
readonlyself:Entity
The entity whose script is being called.
Collision2D
What a script's onCollisionEnter/onCollisionStay/onCollisionExit is handed in a 2D world.
Properties
contacts
readonlycontacts: readonlyContactPoint2D[]
The contacts of this event. Pooled; valid only during the callback.
other
readonlyother:Entity|null
The entity that was hit, or null when its body is already gone.
otherCollider
readonlyotherCollider:Collider2D|null
The exact collider on the other entity.
relativeVelocity
readonlyrelativeVelocity:Vec2Like
The relative velocity of the two bodies at the contact, in metres per second.
self
readonlyself:Entity
The entity whose script is being called.
selfCollider
readonlyselfCollider:Collider2D|null
The collider on this entity that took part.
CollisionMergeOptions
The grid mergeTileCollisions walks.
Properties
cellSize
readonlycellSize:number
The edge length of one cell, in metres.
chunkSize
readonlychunkSize:number
The edge length of one chunk, in cells; 32 is what TilemapRenderer uses.
height
readonlyheight:number
The grid's height, in cells.
width
readonlywidth:number
The grid's width, in cells.
ColorFieldSpec
Kind-specific data for color.
Properties
kind
readonlykind:"color"
The color kind.
ColorLike
The structural shape of an RGBA color.
Properties
a
readonlya:number
The alpha channel.
b
readonlyb:number
The blue channel.
g
readonlyg:number
The green channel.
r
readonlyr:number
The red channel.
ComponentClassInfo
Everything the engine needs to know about a component class, computed once and cached.
Properties
allowMultiple
readonlyallowMultiple:boolean
false when at most one instance may live on an entity.
ancestors
readonlyancestors: readonlyComponentType<Component>[]
The class and every component class it derives from, nearest first, ending at Component.
world.components(Type) and getComponent(Type) match against this list, which is why they
are inheritance-aware without touching a prototype chain per frame.
classIndex
readonlyclassIndex:number
A dense index assigned in registration order, for array-indexed per-class bookkeeping.
isScript
readonlyisScript:boolean
true when the class derives from Script.
requires
readonlyrequires: readonlyComponentType<Component>[]
Component types auto-added to, and validated on, the entity.
schema
readonlyschema:Readonly<Record<string,FieldDefinition<unknown>>> |null
The declared serialized fields, or null when the class was not built with define.
script
readonlyscript:ScriptClassInfo|null
Callback and ordering data, or null for a plain component.
trackedFields
readonlytrackedFields: readonlystring[]
The names of the entityRef/componentRef fields the schema declares. The world's reference
tracker nulls exactly these when their target is destroyed
(docs/architecture/02-scene-graph.md §4).
type
readonlytype:ComponentType
The class itself.
typeId
readonlytypeId:string|null
The namespaced registration id, or null when the class declares none.
ComponentHooks
The optional hooks every component may implement
(docs/architecture/03-scripting-and-components.md §1).
Remarks
They are declared here rather than on Component for the reason spelled out on
ScriptCallbacks: a member declared on the base class would force every implementation to carry
an override modifier under noImplicitOverride (coding standards §3). Write
implements ComponentHooks to have the signatures checked.
Methods
onAttach()?
optionalonAttach():void
Runs after the component's fields are assigned and before awake. It may run while the entity
is inactive, so it must not assume the component is enabled.
Returns
void
onDetach()?
optionalonDetach():void
Runs just before the component is removed, after onDestroy.
Returns
void
ComponentRefFieldSpec
Kind-specific data for componentRef.
Properties
componentType
readonlycomponentType:ComponentTypeToken<unknown>
The component class the field may point at.
kind
readonlykind:"componentRef"
The component-reference kind.
ComponentReplacement
What ComponentRegistry.replace swapped, for the hot-reload path that has to re-file every live instance of the class that went away.
Properties
info
readonlyinfo:ComponentClassInfo
The replacement's freshly built info.
previous
readonlyprevious:ComponentType<Component> |null
The class registered under the id before, or null when nothing was.
ComponentStatics
The static members a component class may declare, as structural, optional properties
(docs/architecture/03-scripting-and-components.md §1). They are deliberately not declared on
the Component class: a static declared on the base class would make every
static typeId = "mygame/Mover" an override and force the override keyword on it under
noImplicitOverride (coding standards §3). Declaring the shape here instead means a plain
static typeId on a subclass satisfies it structurally, and the registry supplies the defaults.
Example
class Mover extends Script.define({ speed: f32(5) }) {
static typeId = "mygame/Mover";
}Extended by
Properties
allowMultiple?
readonlyoptionalallowMultiple?:boolean
false when at most one instance may be attached to an entity; defaults to true.
requires?
readonlyoptionalrequires?: readonlyComponentType<Component>[]
Component types auto-added to, and validated on, any entity this one is attached to.
schema?
readonlyoptionalschema?:Readonly<Record<string,FieldDefinition<unknown>>>
The serialized field declarations, set by Component.define / Script.define.
typeId?
readonlyoptionaltypeId?:string
The namespaced registration id (<package-or-game>/<Name>), required for any component that is
serialized (docs/architecture/03-scripting-and-components.md §4). It is explicit, never
derived from the class name, so minification and renames cannot change a file's meaning.
ComponentType
A component class used as a query token — entity.getComponent(Type),
world.components(Type), componentRef(Type). Abstract classes qualify, which is what makes
getComponent(Script) legal (docs/architecture/02-scene-graph.md §4).
Example
function first<T extends Component>(entity: Entity, type: ComponentType<T>): T | null {
return entity.getComponent(type);
}Extends
Extended by
Type Parameters
T
T extends Component = Component
The component instance type the token stands for.
Properties
allowMultiple?
readonlyoptionalallowMultiple?:boolean
false when at most one instance may be attached to an entity; defaults to true.
Inherited from
ComponentStatics.allowMultiple
prototype
readonlyprototype:T
The instance shape the token names.
requires?
readonlyoptionalrequires?: readonlyComponentType<Component>[]
Component types auto-added to, and validated on, any entity this one is attached to.
Inherited from
schema?
readonlyoptionalschema?:Readonly<Record<string,FieldDefinition<unknown>>>
The serialized field declarations, set by Component.define / Script.define.
Inherited from
typeId?
readonlyoptionaltypeId?:string
The namespaced registration id (<package-or-game>/<Name>), required for any component that is
serialized (docs/architecture/03-scripting-and-components.md §4). It is explicit, never
derived from the class name, so minification and renames cannot change a file's meaning.
Inherited from
ComponentTypeToken
How a component class is named in a schema. A class satisfies it structurally through its
prototype, so componentRef(Camera) infers Camera without the class having to implement
anything. The optional typeId is the namespaced registration id from
docs/architecture/03-scripting-and-components.md §4 when the class carries one.
Type Parameters
C
C
The component instance type the token stands for.
Properties
prototype
readonlyprototype:C
The instance shape the token names.
typeId?
readonlyoptionaltypeId?:string
The component's namespaced registration id, when it declares one.
ConcreteComponentType
A component class the engine can construct: everything ComponentType requires plus a
no-argument constructor. entity.addComponent and app.registerComponents take this shape,
because both have to be able to new the class.
Extends
Type Parameters
T
T extends Component = Component
The component instance type.
Constructors
Constructor
new ConcreteComponentType():
T
Constructs an instance. Components are constructed by the engine only: initial values come from
schema defaults, then from the file or the init object.
Returns
T
Inherited from
ComponentType<T>.constructor
Properties
allowMultiple?
readonlyoptionalallowMultiple?:boolean
false when at most one instance may be attached to an entity; defaults to true.
Inherited from
prototype
readonlyprototype:T
The instance shape the token names.
Inherited from
requires?
readonlyoptionalrequires?: readonlyComponentType<Component>[]
Component types auto-added to, and validated on, any entity this one is attached to.
Inherited from
schema?
readonlyoptionalschema?:Readonly<Record<string,FieldDefinition<unknown>>>
The serialized field declarations, set by Component.define / Script.define.
Inherited from
typeId?
readonlyoptionaltypeId?:string
The namespaced registration id (<package-or-game>/<Name>), required for any component that is
serialized (docs/architecture/03-scripting-and-components.md §4). It is explicit, never
derived from the class name, so minification and renames cannot change a file's meaning.
Inherited from
ConnectOptions
Options for Signal.connect.
Properties
deferred?
readonlyoptionaldeferred?:boolean
Queue the delivery on the signal's DeferredQueue instead of calling the handler inside
emit (Godot's CONNECT_DEFERRED).
once?
readonlyoptionalonce?:boolean
Disconnect the handler after its first delivery.
owner?
readonlyoptionalowner?:SignalOwner
Disconnect the handler automatically when this object is destroyed.
ConsoleLike
The part of the host console a LogSink needs. Declaring it keeps the sink testable and
keeps ignifx off the DOM Console type, which Node's console does not implement in full.
Methods
debug()
debug(...
data):void
Writes a debug line.
Parameters
data
...readonly unknown[]
The message followed by its structured extras.
Returns
void
error()
error(...
data):void
Writes an error line.
Parameters
data
...readonly unknown[]
The message followed by its structured extras.
Returns
void
info()
info(...
data):void
Writes an info line.
Parameters
data
...readonly unknown[]
The message followed by its structured extras.
Returns
void
warn()
warn(...
data):void
Writes a warning line.
Parameters
data
...readonly unknown[]
The message followed by its structured extras.
Returns
void
ConsoleSinkOptions
Options for createConsoleSink.
Properties
target?
readonlyoptionaltarget?:ConsoleLike
The console to write to. Defaults to the host console.
ContactPoint
One contact point of a collision. Pooled with its owning Collision.
Properties
impulse
readonlyimpulse:number
The magnitude of the impulse Havok applied to resolve it; 0 for a contact that just ended.
normal
readonlynormal:Vec3Like
The world-space contact normal.
point
readonlypoint:Vec3Like
The world-space contact point.
ContactPoint2D
One contact point of a 2D collision. Pooled with its owning Collision2D.
Properties
impulse
readonlyimpulse:number
The magnitude of the impulse Rapier's solver applied; 0 for a contact that just ended.
normal
readonlynormal:Vec2Like
The world-space contact normal, pointing away from the other collider.
point
readonlypoint:Vec2Like
The world-space contact point, in metres.
ControlDescriptor
One control of a device, as the binding layer sees it after path resolution.
Properties
components
readonlycomponents:number
How many Float32Array slots the control occupies: 1, or 2 for a vector.
index
readonlyindex:number
The control's stable index inside its device's control table.
kind
readonlykind:ControlKind
What the control produces.
name
readonlyname:string
The control's name inside its device, for example leftStick or dpad/up.
offset
readonlyoffset:number
Where the control's components start in the device's value array.
ControlRef
One control of one device, as a binding holds it after resolution.
Properties
control
readonlycontrol:ControlDescriptor
The control itself.
device
readonlydevice:InputDevice
The device the control belongs to.
path
readonlypath:string
The path the reference was resolved from.
ControlSchemeDefinition
One control scheme: a name and the device families it pairs with
(docs/architecture/08-input.md §4).
Properties
devices
readonlydevices: readonlystring[]
The device family tokens the scheme uses, for example ["Keyboard", "Mouse"].
name
readonlyname:string
The scheme name, for example KeyboardMouse.
ControlSpec
A control declaration, before offsets are assigned.
Properties
kind
readonlykind:ControlKind
What the control produces.
name
readonlyname:string
The control's name inside its device.
ControlValue
A two-component value carried through a processor chain. Scalar controls use x and leave y
at 0.
Properties
x
x:
number
The scalar value, or the vector's x component.
y
y:
number
The vector's y component; 0 for scalar controls.
CoroutineHandle
The observable state of a running coroutine, returned by Script.startCoroutine.
Properties
isDone
readonlyisDone:boolean
true once the coroutine has finished, been stopped, or been cancelled.
isRunning
readonlyisRunning:boolean
true while the coroutine is still scheduled — including while it is paused.
CoroutineHost
The coroutine scheduler, reached as app.coroutines and driven by Script.startCoroutine
(docs/architecture/01-lifecycle-and-time.md §5). The kernel calls
CoroutineHost.setPaused on every enable transition and CoroutineHost.cancelAll
when a script is destroyed.
Methods
cancelAll()
cancelAll(
owner):void
Cancels every coroutine a script started and detaches any promise they were waiting on, so the continuation never runs. Called by the destroy flush and by world disposal.
Parameters
owner
The owning script.
Returns
void
setPaused()
setPaused(
owner,paused):void
Pauses or resumes every coroutine a script started, without discarding their state.
Parameters
owner
The owning script.
paused
boolean
true to pause, false to resume.
Returns
void
start()
start(
owner,routine):CoroutineHandle
Schedules a coroutine owned by a script.
Parameters
owner
The script whose enabled state gates the coroutine.
routine
The generator to drive.
Returns
A handle for stopping it or waiting on it.
stop()
stop(
handle):void
Stops one coroutine. Stopping an already finished coroutine is a no-op.
Parameters
handle
The handle returned by CoroutineHost.start.
Returns
void
stopAll()
stopAll(
owner):void
Stops every coroutine a script started.
Parameters
owner
The owning script.
Returns
void
CreateAppOptions
Options accepted by createApp.
Example
const app = await createApp({ canvas, extensions: [physics(), input()] });
await app.start();Properties
assets?
readonlyoptionalassets?:AssetsCreateOptions
The asset service's construction options
(docs/architecture/05-assets-and-loading.md §7). The manifest normally arrives from
@ignifx/vite-plugin; tests and Electron tooling pass it here.
Remarks
The assets settings section configures the root, the concurrency limit, the collector
delay, and the retry count. The manifest and the injected fetch are not settings: neither
survives schema validation, so they are creation options instead.
canvas?
readonlyoptionalcanvas?:RenderSurface
The canvas to render into. Ignored when headless is true.
clock?
readonlyoptionalclock?:Clock
The wall clock behind time.realtimeSinceStartup and the development phase timings. Defaults
to performance.now(); headless tests pass createManualClock.
extensions?
readonlyoptionalextensions?: readonlyExtension[]
The extensions to register, after the implicit core extension.
fetch?
readonlyoptionalfetch?: (input,init?) =>Promise<Response>
The fetch the asset service reads through, as a shorthand for assets.fetch. Defaults to
globalThis.fetch; headless tests pass a fake so responses are deterministic.
Parameters
input
RequestInfo | URL
init?
RequestInit
Returns
Promise<Response>
headless?
readonlyoptionalheadless?:boolean
Run on Babylon Lite's null engine with no render surface
(docs/architecture/01-lifecycle-and-time.md §8). Defaults to true when no canvas is
given, so createApp({}) is a headless app.
hotReload?
readonlyoptionalhotReload?:HotReloadOptions
Script and scene hot reload (docs/architecture/15-devtools-and-diagnostics.md §5).
app.hotReload.apply always works; the only thing to configure is whether a changed scene file
rebuilds the live instances built from it.
logLevel?
readonlyoptionallogLevel?:LogThreshold
The lowest level app.log writes to the sink. Defaults to "info" in every mode, so an app
prints nothing at startup; pass "debug" to see the kernel's own diagnostics.
logSink?
readonlyoptionallogSink?:LogSink
Where app.log writes. Defaults to the console sink.
mode?
readonlyoptionalmode?:ErrorFormatMode
"development" turns on per-phase CPU timings, full error messages, and the strict half of
every rule 04-extensions.md §2 relaxes in production. Defaults to "development"; the Vite
plugin sets it from the build mode in Phase 2.
settings?
readonlyoptionalsettings?:Readonly<Record<string,unknown>>
Project settings, as ignifx.config.ts would supply them
(docs/architecture/04-extensions.md §5). The Vite plugin injects the resolved config in
Phase 2; tests and Electron tooling pass it here.
storage?
readonlyoptionalstorage?:StorageBackend|FileStorageOptions
Where app.storage puts things (docs/architecture/14-platform-electron.md §2). Pass a
StorageBackend to install one, or { directory } to write a directory tree under Node.
Defaults to IndexedDB in a browser and to an in-memory store everywhere else.
CreateBusOptions
Options accepted by AudioService.createBus.
Properties
parent?
readonlyoptionalparent?:string
The name of the bus the new one routes into; empty routes it to the root.
pausable?
readonlyoptionalpausable?:boolean
Whether app.pause() pauses it. Defaults to whatever the audio settings section says.
volume?
readonlyoptionalvolume?:number
The new bus's own linear gain. Defaults to 1.
CreateEntityOptions
Options accepted by World.createEntity.
Properties
active?
readonlyoptionalactive?:boolean
The entity's own active flag at creation. Defaults to true.
Remarks
Scene loading passes false so that no component can awake before the whole scene exists and
its references are resolved (docs/architecture/01-lifecycle-and-time.md §4), then sets the
file's value in tree order once construction is complete.
parent?
readonlyoptionalparent?:Entity
The parent to attach the new entity to; undefined makes it a root of its scene.
position?
readonlyoptionalposition?:Vec3Like
The initial world position, in metres.
rotation?
readonlyoptionalrotation?:QuatLike
The initial world rotation.
scene?
readonlyoptionalscene?:SceneInstance
The owning scene instance; defaults to the parent's scene, or world.activeScene.
uid?
readonlyoptionaluid?:string
The uid to adopt instead of a freshly minted ULID.
Remarks
Scene loading passes the uid the file carries, which is what makes save → load → save
byte-identical (docs/architecture/06-serialization-and-scene-format.md §1). A uid another
entity of this world already holds is ignored and a fresh one minted, so two instances of one
scene never collide (02-scene-graph.md §10).
CurveFieldSpec
Kind-specific data for curve.
Properties
kind
readonlykind:"curve"
The curve kind.
CurveValue
The value a curve() field holds.
Properties
keys
readonlykeys: readonlyCurveKey[]
The curve's keys, ordered by time.
CustomFieldCodec
The hand-written encoder and decoder behind a custom() field. The codec owns both the default
value and the JSON representation, so custom is the escape hatch for value types the built-in
kinds cannot express.
Type Parameters
T
T
The runtime value type.
Properties
jsonSchema?
readonlyoptionaljsonSchema?:JsonObject
A JSON Schema fragment describing the encoded form, merged into the generated document.
Methods
createDefault()
createDefault():
T
Builds a fresh default value. It is a factory, not a constant, so two components never share one mutable default object.
Returns
T
A newly allocated default value.
deserialize()
deserialize(
json):T
Rebuilds a runtime value from JSON.
Parameters
json
The JSON previously produced by serialize.
Returns
T
The runtime value.
serialize()
serialize(
value):JsonValue
Converts a runtime value into JSON.
Parameters
value
T
The value to serialize.
Returns
The JSON representation written into the file.
CustomFieldSpec
Kind-specific data for custom.
Properties
codec
readonlycodec:CustomFieldCodec<unknown>
The hand-written codec that owns the value's default and JSON form.
kind
readonlykind:"custom"
The custom kind.
CylinderMeshOptions
How MeshAsset.cylinder sizes its cylinder, which stands along Y.
Properties
diameter?
readonlyoptionaldiameter?:number
Diameter of both ends.
diameterBottom?
readonlyoptionaldiameterBottom?:number
Diameter of the bottom cap, overriding diameter.
diameterTop?
readonlyoptionaldiameterTop?:number
Diameter of the top cap, overriding diameter — a cone is diameterTop: 0.
height?
readonlyoptionalheight?:number
Height along Y, in metres.
tessellation?
readonlyoptionaltessellation?:number
Radial segment count.
DecodeResult
What decoding produced: a value that is always usable — the field's default when the JSON could not be read — plus every problem found on the way.
Type Parameters
T
T
The decoded value type.
Properties
issues
readonlyissues: readonlySchemaIssue[]
Every problem found, in discovery order; empty on a clean decode.
value
readonlyvalue:T
The decoded value, or the field's freshly built default when decoding failed.
DeferredQueue
The scheduler that runs deferred deliveries. The core frame loop implements it on the
EndOfFrame phase; tests can pass a queue that runs callbacks on demand.
Methods
enqueue()
enqueue(
callback):void
Schedules a callback to run at the next flush point.
Parameters
callback
() => void
The delivery to run.
Returns
void
Desktop
The desktop service reached as app.desktop.
Example
class PauseMenu extends Script {
async toggleFullscreen(): Promise<void> {
if (this.app.desktop.isElectron) {
await this.app.desktop.setFullscreen(!(await this.app.desktop.isFullscreen()));
}
}
}Properties
isElectron
readonlyisElectron:boolean
Whether a preload bridge was found — that is, whether this really is a desktop build.
Remarks
The one member that works everywhere. Everything else rejects with IGX-1462 when this is
false.
onWindowEvent
readonlyonWindowEvent:SignalLike<HostWindowEvent>
The host window's lifecycle events, as the main process reports them.
Remarks
This signal is the only source of minimize and restore in an Electron renderer.
Measured on Electron 44.2.0 / macOS arm64 (S9.1): minimising, restoring, and blurring the
window fired the matching BrowserWindow events in the main process and delivered nothing
to the page — no visibilitychange, no window focus/blur, and document.hidden stayed
false throughout. electron() turns focus and blur into onApplicationFocus, which
needs no document reading; minimize and restore have no onApplicationPause path today,
so a game that must pause on minimise subscribes here.
Example
app.desktop.onWindowEvent.connect((event) => {
if (event === "minimize") {
app.time.timeScale = 0;
}
}, { owner: this });versions
readonlyversions:HostVersions|null
The Electron, Chromium, and Node versions, or null in a browser build.
Methods
isFullscreen()
isFullscreen():
Promise<boolean>
Reports whether the window is full screen.
Returns
Promise<boolean>
true when it is.
openExternal()
openExternal(
url):Promise<void>
Opens a URL in the user's browser or mail client.
Parameters
url
string
The absolute URL to open.
Returns
Promise<void>
A promise that settles once the OS accepted it.
Remarks
The main process checks the protocol against an allow-list — https: and mailto: by default
— and rejects with IGX-1464 for anything else, rather than silently doing nothing.
paths()
paths():
Promise<HostPaths>
Resolves the platform directories.
Returns
Promise<HostPaths>
The directories the host reported.
quit()
quit():
Promise<void>
Closes the window and quits the application.
Returns
Promise<void>
A promise that settles once the quit has been requested.
setFullscreen()
setFullscreen(
fullscreen):Promise<void>
Enters or leaves full screen.
Parameters
fullscreen
boolean
true to enter, false to leave.
Returns
Promise<void>
A promise that settles once the host applied it.
setWindowTitle()
setWindowTitle(
title):Promise<void>
Sets the window title.
Parameters
title
string
The new title.
Returns
Promise<void>
A promise that settles once the host applied it.
showOpenDialog()
showOpenDialog(
options?):Promise<HostOpenDialogResult>
Shows a modal open dialog over the game window.
Parameters
options?
What the dialog offers.
Returns
Promise<HostOpenDialogResult>
What the user chose.
DeviceLostInfo
What Babylon Lite reported when the WebGPU device was lost
(docs/architecture/07-rendering.md §4).
Properties
message
readonlymessage:string
The human-readable message.
reason
readonlyreason:string|null
The GPUDeviceLostInfo.reason string, or null when the host gave none.
DevtoolsDomTarget
The DOM objects one app's overlay is built in.
Properties
canvas
readonlycanvas:HTMLCanvasElement
The canvas the overlay is positioned over.
document
readonlydocument:Document
The document the overlay's elements and its stylesheet are created in.
window
readonlywindow:Window
The window the toggle key and resize events are read from.
DevtoolsErrorOptions
Options accepted by devtoolsError: the same subset of IgnifxErrorOptions this package
uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
DevtoolsLogSink
A LogSink that keeps the most recent records for the Console panel and, optionally,
forwards each one to a second sink so the browser console keeps working.
Example
const sink = createDevtoolsLogSink({ limit: 500 });
const app = await createApp({ headless: true, logSink: sink, extensions: [devtools({ logSink: sink })] });Extends
Properties
length
readonlylength:number
How many records are currently retained, never more than DevtoolsLogSink.limit.
limit
readonlylimit:number
The maximum number of records retained.
Methods
at()
at(
index):LogRecord|null
Reads one retained record.
Parameters
index
number
0 is the oldest retained record, length - 1 the newest.
Returns
LogRecord | null
The record, or null when the index is out of range.
clear()
clear():
void
Drops every retained record.
Returns
void
query()
query(
level,search,out,max):LogRecord[]
Copies the records that pass a level threshold and a case-insensitive substring search, newest first, into a caller-owned array.
Parameters
level
The lowest severity to keep; "silent" keeps nothing.
search
string
A substring matched against the scope and the message; "" matches everything.
out
The array to fill. It is truncated first, so one array serves every refresh.
max
number
How many records to copy at most.
Returns
The same out array.
write()
write(
record):void
Writes one record. Called synchronously from the logging call site, so implementations must be cheap and must not throw.
Parameters
record
The record to write.
Returns
void
Inherited from
DevtoolsLogSinkOptions
What createDevtoolsLogSink accepts.
Properties
limit?
readonlyoptionallimit?:number
How many records to retain. Defaults to DEFAULT_DEVTOOLS_LOG_LIMIT.
tee?
readonlyoptionaltee?:LogSink
A second sink every record is also written to — the console sink, in a normal game.
DevtoolsOptions
What devtools() accepts. Every field that names a settings value overrides the matching
devtools section value, which is the shape 04-extensions.md §1 shows for physics().
Properties
logSink?
readonlyoptionallogSink?:DevtoolsLogSink
The sink the Console panel reads its log lines from. By default the extension creates one and
adds it to app.log with Logger.addSink, so log lines appear without any wiring; pass your own
to share it with something else (a tee to the console, a file sink) or to size its buffer.
opacity?
readonlyoptionalopacity?:number
The overlay's background opacity, 0–1.
openOnStart?
readonlyoptionalopenOnStart?:boolean
Whether the overlay is open the moment the app starts.
panels?
readonlyoptionalpanels?: readonlystring[]
The panels to show, in tab order.
position?
readonlyoptionalposition?:"top"|"left"|"right"|"bottom"
The canvas edge the overlay docks to.
reloadScenes?
readonlyoptionalreloadScenes?:boolean
Whether a changed scene file re-instantiates its live scene instances.
toggleKey?
readonlyoptionaltoggleKey?:string
The KeyboardEvent.code that toggles the overlay. Defaults to "Backquote".
DevtoolsPanelHandle
One panel, as app.devtools.panel(name) hands it out.
Properties
name
readonlyname:string
The panel's name.
title
readonlytitle:string
The tab label.
visible
readonlyvisible:boolean
Whether the panel's tab is shown.
Methods
hide()
hide():
void
Hides the panel's tab; the neighbouring tab takes over when it was the visible one.
Returns
void
show()
show():
void
Shows the panel's tab and brings it to the front.
Returns
void
DevtoolsSettings
The resolved devtools settings section.
Example
// ignifx.config.ts
export default defineConfig({
devtools: { toggleKey: "F1", openOnStart: true, panels: ["stats", "console"] },
});Properties
opacity
readonlyopacity:number
The overlay's background opacity, 0–1. Defaults to 0.92.
openOnStart
readonlyopenOnStart:boolean
Whether the overlay is open the moment the app starts. Defaults to false.
panels
readonlypanels: readonlystring[]
The panels to show, in tab order. Names outside DEVTOOLS_PANEL_NAMES are ignored. Defaults to every panel in the documented order.
position
readonlyposition:"top"|"left"|"right"|"bottom"
The canvas edge the overlay docks to. Defaults to "right".
reloadScenes
readonlyreloadScenes:boolean
Whether a SceneAsset that hot-reloads re-instantiates its live scene instances
(15-devtools-and-diagnostics.md §5). Defaults to false.
toggleKey
readonlytoggleKey:string
The KeyboardEvent.code that toggles the overlay. Defaults to "Backquote" — the backtick
15-devtools-and-diagnostics.md §4 names. The listener is a raw keydown on the document, so
the key works with or without @ignifx/input (08-input.md §5).
DiagnosticsGroup
A named set of numeric counters owned by one subsystem — render, physics, assets, input,
audio, twoD, animation (docs/architecture/15-devtools-and-diagnostics.md §3).
Remarks
Counter names are resolved to array indices once, at registration. Per-frame code holds the index and never performs a string-keyed lookup (coding standards §7).
Example
const counters = app.diagnostics.registerGroup("render", ["drawCalls", "triangles"]);
const drawCalls = counters.index("drawCalls");
// …per frame…
counters.set(drawCalls, scene.drawCallCount);Properties
counterNames
readonlycounterNames: readonlystring[]
The counter names in index order.
name
readonlyname:string
The group name, unique within one Diagnostics.
Methods
add()
add(
index,delta):void
Adds to a counter. Out-of-range indices are ignored.
Parameters
index
number
The index from DiagnosticsGroup.index.
delta
number
The amount to add.
Returns
void
get()
get(
index):number
Reads a counter.
Parameters
index
number
The index from DiagnosticsGroup.index.
Returns
number
The current value, or 0 when the index is out of range.
index()
index(
counter):number
Resolves a counter name to its index. Call it at registration or awake, never per frame.
Parameters
counter
string
The counter name.
Returns
number
The index to pass to DiagnosticsGroup.get, set, and add.
Throws
IgnifxError with code IGX-1504 when the group has no such counter.
reset()
reset():
void
Zeroes every counter in the group.
Returns
void
set()
set(
index,value):void
Replaces a counter's value. Out-of-range indices are ignored.
Parameters
index
number
The index from DiagnosticsGroup.index.
value
number
The new value.
Returns
void
DiagnosticsOptions
Options for the Diagnostics constructor.
Properties
development?
readonlyoptionaldevelopment?:boolean
Whether this is a development build. Per-phase CPU timings and performance.mark/measure
entries are only produced when it is true. Defaults to false.
historyLength?
readonlyoptionalhistoryLength?:number
How many frames of history to keep. Defaults to FRAME_HISTORY_LENGTH.
now?
readonlyoptionalnow?: () =>number
The clock used for profile scopes, in milliseconds. Defaults to performance.now when the host
has it and Date.now otherwise; tests pass a counter so timings are deterministic.
Returns
number
DialogButton
One button in a dialog.
Properties
id
readonlyid:string
The identifier onChosen reports.
label
readonlylabel:string
The text drawn on the button.
DialogOptions
What new Dialog(app.ui, options) accepts.
Properties
buttons?
readonlyoptionalbuttons?: readonlyDialogButton[]
The buttons, left to right.
dismissOnBackdrop?
readonlyoptionaldismissOnBackdrop?:boolean
Whether a click on the backdrop dismisses the dialog. Defaults to false.
layer?
readonlyoptionallayer?:string
The layer to mount into. Defaults to "menu".
message?
readonlyoptionalmessage?:string
The body text. Omit for a dialog with no message.
title?
readonlyoptionaltitle?:string
The heading. Omit for a dialog with no title.
visible?
readonlyoptionalvisible?:boolean
Whether the dialog starts shown. Defaults to false.
DomSource
One adapter's subscription lifetime.
Methods
attach()
attach():
void
Subscribes to the DOM.
Returns
void
detach()
detach():
void
Unsubscribes. Calling it twice is a no-op.
Returns
void
DomTarget
The DOM objects one app's input adapters subscribe to.
Properties
canvas
readonlycanvas:HTMLCanvasElement
The canvas pointer and wheel events are read from, and pointer lock is requested on.
document
readonlydocument:Document
The document visibilitychange and pointerlockchange are read from.
window
readonlywindow:Window
The window keyboard events and blur are read from.
ElectronErrorOptions
Options accepted by electronError: the same subset of IgnifxErrorOptions this package
uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
ElectronOptions
What electron() accepts.
Properties
applicationEvents?
readonlyoptionalapplicationEvents?:boolean
Whether the host's focus and blur events are delivered as onApplicationFocus.
Default Value
true
hostScope?
readonlyoptionalhostScope?:unknown
Where to look for the bridge. Tests pass a fake global; a game never sets this.
Default Value
globalThis
storage?
readonlyoptionalstorage?:boolean
Whether the file-system storage backend replaces whatever createApp installed.
Default Value
true
EntityPrefabLink
The prefab link Entity.prefab returns for an entity a scene file's instance entry produced
(docs/architecture/02-scene-graph.md §6).
Properties
address
readonlyaddress:string
The address of the instanced scene.
asset
readonlyasset:AssetHandle<SceneAsset> |null
The handle the instanced scene was loaded through, or null when no asset service resolved one.
instanceRoot
readonlyinstanceRoot:Entity
The entity the instance entry sat on — the root of this instance.
EntityRefFieldSpec
Kind-specific data for entityRef.
Properties
kind
readonlykind:"entityRef"
The entity-reference kind.
EnumFieldSpec
Kind-specific data for enumOf.
Properties
kind
readonlykind:"enum"
The enumeration kind.
values
readonlyvalues: readonlystring[]
Every accepted string value, in declaration order.
EnvironmentAssetLiteHandles
The Babylon Lite objects an EnvironmentAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
textures
readonlytextures:EnvironmentTextures|null
The GPU-resident cube map, BRDF table, samplers, and harmonics, or null under a headless app.
EnvironmentDefinition
What an .environment.json declares, or what an .env address implies
(docs/architecture/06-serialization-and-scene-format.md §6).
Remarks
The description file exists so a project can pin the skybox and the BRDF table next to the IBL
rather than repeating them on every Environment component. Loading a bare .env address
produces the same shape with everything but environment left at its default.
Properties
blur
readonlyblur:number
How blurred the specular reflection is, 0 to 1.
brdfLut
readonlybrdfLut:string
The RGBD BRDF lookup table, or empty to take rendering.brdfLut.
environment
readonlyenvironment:string
The .env file holding the prefiltered specular cube map and its spherical harmonics.
rotation
readonlyrotation:number
Rotation around the world Y axis, in degrees.
skybox
readonlyskybox:string
A .dds or .env skybox, or empty for none.
skyboxEnabled
readonlyskyboxEnabled:boolean
Whether a skybox is drawn at all.
skyboxSize
readonlyskyboxSize:number
The skybox cube's size, in metres. Lite defaults to 20.
EnvironmentFogSettings
The fog record an Environment declares (docs/architecture/07-rendering.md §2.5).
Properties
color
color:
ColorLike
The fog's sRGB colour.
density
density:
number
Density, for the exponential modes.
end
end:
number
Where linear fog reaches full strength, in metres.
mode
mode:
"none"|"linear"|"exp"|"exp2"
The falloff, or "none" to disable fog.
start
start:
number
Where linear fog begins, in metres.
ErrorCodeDescription
What the registry knows about one code.
Properties
code
readonlycode:`IGX-${number}`
The code itself.
message
readonlymessage:string
The one-line message template; context keys appear in braces.
owner
readonlyowner:string
The extension that owns the code ("@ignifx/core" for the codes in CoreErrorCode).
ErrorCodeRegistry
The per-app table of every diagnostic code the running game can produce. Devtools resolves codes
to messages through it, and ExtensionContext.registerErrorCodes writes to it.
Remarks
There is one registry per App, never a module-level one (CONSTITUTION.md §3.5, §3.6):
two apps in one test process must not see each other's extensions.
Methods
describe()
describe(
code):ErrorCodeDescription|null
Looks a code up.
Parameters
code
string
The code to describe.
Returns
ErrorCodeDescription | null
The description, or null when the code was never registered — an unknown code is an
expected absence, not a failure (coding standards §5.5).
isRegistered()
isRegistered(
code):boolean
Reports whether a code is known.
Parameters
code
string
The code to test.
Returns
boolean
true when the code has been registered.
register()
register(
codes,owner):void
Adds a block of codes.
Parameters
codes
Readonly<Record<string, string>>
A map of IGX-#### code to one-line message template.
owner
string
The extension name recorded as the owner of every code in the block.
Returns
void
Throws
IgnifxError with code IGX-1502 when a key is not a valid code, or IGX-1501 when a
code is already registered.
ErrorReport
A failure the engine caught at a boundary and reported instead of rethrowing
(docs/architecture/01-lifecycle-and-time.md §5, 15-devtools-and-diagnostics.md §1). One
script throwing never stops the others.
Example
app.onError.connect((report) => {
app.log.error("{source} callback threw on {entity}", report.source, report.entity?.name ?? "-");
});Properties
component
readonlycomponent:Component|null
The component involved, or null when the failure is not component-scoped.
entity
readonlyentity:Entity|null
The entity involved, or null when the failure is not entity-scoped.
error
readonlyerror:unknown
Whatever was thrown. Usually an Error, often an IgnifxError.
phase
readonlyphase:Phase|null
The phase that was running, or null outside a phase (a lifecycle flush, say).
source
readonlysource:"asset"|"lifecycle"|"coroutine"|"system"|"extension"
Which boundary caught it.
Extension
The unit of optional functionality (docs/architecture/04-extensions.md §1). Core features are
extensions too (CONSTITUTION.md §8.1).
Properties
engine?
readonlyoptionalengine?:string
The semver range of @ignifx/core this extension supports, checked at registration.
name
readonlyname:string
Unique name; the npm package name for published extensions.
optional?
readonlyoptionaloptional?: readonlystring[]
Extensions this one integrates with when they are present.
requires?
readonlyoptionalrequires?: readonlystring[]
Extensions that must be registered before this one.
version
readonlyversion:string
The semver version of the extension itself.
Methods
dispose()?
optionaldispose(app):void
Releases everything the extension owns, in reverse registration order.
Parameters
app
The app being disposed.
Returns
void
onStart()?
optionalonStart(app):void|Promise<void>
Runs after every extension registered and the Lite engine exists, before the first frame.
Parameters
app
The app being started.
Returns
void | Promise<void>
Nothing, or a promise app.start() awaits.
onStop()?
optionalonStop(app):void
Runs when the app stops, in reverse registration order.
Parameters
app
The app being stopped.
Returns
void
register()
register(
ctx):void|Promise<void>
Declares components, systems, services, loaders, and settings.
Parameters
ctx
The registration surface.
Returns
void | Promise<void>
Nothing, or a promise the host awaits before registering the next extension.
ExtensionContext
An extension's registration surface (docs/architecture/04-extensions.md §1). Everything an
extension contributes is declared here; nothing happens at module import time
(CONSTITUTION.md §3.5).
Properties
app
readonlyapp:App
The app being built.
log
readonlylog:Logger
A logger scoped to this extension.
Methods
defineAppProperty()
defineAppProperty(
name,getter):void
Defines a property on App, pairing with a module augmentation of the App interface.
Parameters
name
string
The property name, for example "input".
getter
() => unknown
Returns the value each time the property is read.
Returns
void
Throws
IgnifxError with code IGX-0401 when the property is already defined.
dispatchScriptCallback()
dispatchScriptCallback(
entity,kind,argument):void
Beta
Delivers one physics callback to every script on an entity that implements it, for extension
authors (docs/architecture/09-physics.md §4). The scheduler stays the only thing that calls a
script callback: this routes through the same guarded call site the frame loop uses
(03-scripting-and-components.md §6).
Parameters
entity
The entity whose scripts should receive the callback.
kind
Which physics callback to deliver.
argument
unknown
The single argument the callback receives — a collision or a trigger event.
Returns
void
Remarks
Delivery is synchronous and in component order, to effectively-enabled scripts only; a
destroyed or inactive entity receives nothing. A handler that throws is reported to
app.onError with source: "lifecycle" and the running phase, and the remaining scripts still
receive the callback. Nothing is allocated per call.
Throws
IgnifxError with code IGX-0409 in development when called from outside the fixed
loop, where 01-lifecycle-and-time.md §3 says these callbacks never run. Production builds
deliver it anyway rather than losing the event.
Example
for (let index = 0; index < events.length; index += 1) {
ctx.dispatchScriptCallback(events[index].entity, PhysicsCallbackName.onTriggerEnter, events[index]);
}entityImplements()
entityImplements(
entity,kind):boolean
Beta
Whether any script on an entity implements a physics callback, for extension authors. This is
what Rigidbody.collisionEvents auto-detection asks (09-physics.md §2.1).
Parameters
entity
The entity to inspect.
kind
Which physics callback.
Returns
boolean
true when at least one script on the entity implements it.
Remarks
The answer ignores enabled, so it stays stable while scripts are toggled and only changes
when a component is added or removed — the two moments the physics extension recomputes it.
Components already queued for destruction do not count.
onDispose()
onDispose(
callback):void
Registers a callback that runs when the app is disposed.
Parameters
callback
() => void
The teardown to run.
Returns
void
registerAssetLoader()
registerAssetLoader(
loader):void
Registers an asset loader (docs/architecture/05-assets-and-loading.md §5).
Parameters
loader
The loader, which also declares the extensions that select its type.
Returns
void
Throws
IgnifxError with code IGX-0506 when another extension already owns the type.
registerAssetType()
registerAssetType(
type):void
Declares an asset type whose loader is registered separately, or not at all, so that addresses
with its extensions resolve to a type (docs/architecture/04-extensions.md §1).
Parameters
type
The type name and the extensions that select it.
Returns
void
registerComponent()
registerComponent(
type,options?):void
Registers one component class.
Parameters
type
The component class.
options?
An explicit typeId, when the class does not declare one.
Returns
void
registerComponents()
registerComponents(
types):void
Registers several component classes.
Parameters
types
readonly ConcreteComponentType<Component>[]
The component classes.
Returns
void
registerErrorCodes()
registerErrorCodes(
codes):void
Adds diagnostic codes to the app's error-code registry.
Parameters
codes
Readonly<Record<string, string>>
IGX-#### to one-line message template.
Returns
void
registerService()
registerService<
T>(key,instance):void
Registers a service instance under a key.
Type Parameters
T
T
The service instance type.
Parameters
key
ServiceKey<T>
The class or named key.
instance
T
The service.
Returns
void
registerSettings()
registerSettings<
S>(section,schema,defaults):void
Registers a project settings section.
Type Parameters
S
S
The section's resolved shape.
Parameters
section
string
The section name as it appears in ignifx.config.ts.
schema
The schema the section is validated against.
defaults
S
The values used when the project omits the section.
Returns
void
registerSystem()
registerSystem(
system,options):void
Registers a system in a phase.
Parameters
system
The system.
options
The phase and the ascending order within it; core uses [-1000, 1000].
Returns
void
require()
require<
T>(key):T
Looks up a service registered by an earlier extension.
Type Parameters
T
T
The service instance type.
Parameters
key
ServiceKey<T>
The class or named key.
Returns
T
The instance.
Throws
IgnifxError with code IGX-0405 when the service is not registered.
requireRenderingFeature()
requireRenderingFeature(
feature):void
Declares that this extension needs a rendering feature switched on
(docs/architecture/07-rendering.md §1.1).
Parameters
feature
keyof RenderingFeatureSettings
The feature the extension needs.
Returns
void
Remarks
Babylon Lite compiles its shader permutations and records its frame graph inside
registerScene, so every feature that changes what gets compiled has to be on before that
call. register runs before app.start() does it, so this is a declaration there: the
feature is switched on whether or not the project listed it. After the scene is registered it
is a refusal instead.
Throws
IgnifxError with code IGX-0704 when the render scene has already been registered.
Example
register(ctx: ExtensionContext): void {
ctx.requireRenderingFeature("skeletons");
}setSimulationScene()
setSimulationScene(
scene):void
Beta
Publishes the scene an extension simulates in as world.lite.simulationScene, for extension
authors (docs/architecture/09-physics.md §1, 02-scene-graph.md §2).
Parameters
scene
SceneContext | null
The simulation scene, or null to clear it from the extension's dispose.
Returns
void
Throws
IgnifxError with code IGX-0410 when the world already has a different simulation
scene.
settings()
settings<
S>(section):S
Reads a resolved settings section.
Type Parameters
S
S
The section's resolved shape.
Parameters
section
string
The section name.
Returns
S
The resolved section.
Throws
IgnifxError with code IGX-0407 when the section was never registered.
tryGet()
tryGet<
T>(key):T|null
Looks up a service registered by an earlier extension, tolerating its absence.
Type Parameters
T
T
The service instance type.
Parameters
key
ServiceKey<T>
The class or named key.
Returns
T | null
The instance, or null when it is not registered.
FieldDefinition
One declared field of a component schema. Field definitions are plain, immutable data built by
the constructors in this module; nothing about them is reflective and nothing runs at import
time (ADR-0004, CONSTITUTION.md §3.5).
The type parameter is the field's runtime value type, which is what
Script.define({ … }) uses to type the generated properties.
Example
const speed = f32(5, { min: 0, max: 50, tooltip: "Units per second" });
speed.kind; // "f32"
speed.createDefault(); // 5Type Parameters
T
T
The runtime value type of the field.
Properties
kind
readonlykind:FieldKind
The field kind, mirroring spec.kind for quick reads by tooling and the docs harness.
options
readonlyoptions:FieldOptions
Inspector and serializer metadata.
spec
readonlyspec:FieldSpec
The kind-specific data, discriminated by spec.kind.
Methods
createDefault()
createDefault():
T
Builds a fresh default value. Object-valued kinds allocate on every call, so two components never share one mutable default.
Returns
T
A newly allocated default value.
FieldOptions
Inspector and serializer metadata carried by every field
(docs/architecture/03-scripting-and-components.md §3,
docs/architecture/06-serialization-and-scene-format.md §5). Options never change a field's
value type; they constrain and present it.
Properties
group?
readonlyoptionalgroup?:string
Name of the inspector group the field is folded into.
hidden?
readonlyoptionalhidden?:boolean
Hides the field from the inspector while still serializing it.
max?
readonlyoptionalmax?:number
Highest accepted value for numeric kinds; validation reports IGX-0606 above it.
min?
readonlyoptionalmin?:number
Lowest accepted value for numeric kinds; validation reports IGX-0606 below it.
readonly?
readonlyoptionalreadonly?:boolean
Shows the field in the inspector but forbids editing it there.
step?
readonlyoptionalstep?:number
Increment used by the inspector's drag and spinner controls.
tooltip?
readonlyoptionaltooltip?:string
Help text shown next to the field in the inspector.
transient?
readonlyoptionaltransient?:boolean
Excludes the field from saved games and scene files; it always takes its default on load.
FileStorageOptions
Options accepted by createFileStorageBackend.
Properties
directory
readonlydirectory:string
The root directory. It is created on first write, together with every namespace directory
under it. Under Electron this is app.getPath("userData"); in a test it is a temporary
directory.
FontAssetLiteHandles
The Babylon Lite objects a FontAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
font
readonlyfont:Font
The parsed font. Present in headless mode too: parsing needs no device.
FrameSample
One frame's counters.
Remarks
The numeric fields are mutable on purpose: the frame loop writes them in place so that publishing diagnostics costs no allocation (coding standards §7). Everything outside the loop treats a sample as read-only, and history samples are read through Diagnostics.readFrame into a caller-owned sample.
Properties
coroutinesResumed
coroutinesResumed:
number
How many coroutines were resumed this frame.
cpuMs
readonlycpuMs:Float64Array
CPU milliseconds per phase, indexed by PhaseIndex. Always PHASE_COUNT long and only filled in development builds.
destroyed
destroyed:
number
How many entities and components were destroyed in this frame's flush.
droppedMs
droppedMs:
number
How much of rawDeltaMs was discarded by the maximum-delta clamp, in milliseconds.
fixedSteps
fixedSteps:
number
How many fixed steps ran this frame.
frame
frame:
number
The monotonically increasing frame number, starting at 1.
rawDeltaMs
rawDeltaMs:
number
The wall-clock delta the loop was handed, before clamping, in milliseconds.
scriptsUpdated
scriptsUpdated:
number
How many scripts received update this frame.
FrameState
Where in the frame the engine currently is, as far as the scene graph needs to know
(docs/architecture/01-lifecycle-and-time.md §4, §6). The scheduler and the lifecycle queue
write it; Entity and the queue read it to decide whether awake runs nested and synchronously
and whether destroyImmediate is legal.
Properties
isInsideCallback
readonlyisInsideCallback:boolean
true while a lifecycle callback, a script callback, or a coroutine body is on the stack.
isInsideFixedStep
readonlyisInsideFixedStep:boolean
true while the fixed loop is running (time.inFixedStep).
FreezeRotation
Whether each rotation axis is frozen.
Properties
x
readonlyx:boolean
Freeze rotation about X.
y
readonlyy:boolean
Freeze rotation about Y.
z
readonlyz:boolean
Freeze rotation about Z.
GamepadLike
The subset of the DOM Gamepad object this package reads.
Properties
axes
readonlyaxes: readonlynumber[]
The pad's axes, in its raw order.
buttons
readonlybuttons: readonlyobject[]
The pad's buttons, in its raw order.
connected
readonlyconnected:boolean
Whether the pad is still present.
id
readonlyid:string
The pad's identifier string.
mapping
readonlymapping:string
The pad's mapping: "standard", "xr-standard", or "".
vibrationActuator?
readonlyoptionalvibrationActuator?:VibrationActuatorLike|null
The haptic actuator, when the pad has one.
GamepadRemap
How one non-standard pad's raw indices map onto the standard ones
(docs/architecture/08-input.md §4, "a small remap table for common non-standard pads").
Properties
axes
readonlyaxes: readonlynumber[]
Standard axis index (0 lx, 1 ly, 2 rx, 3 ry) to raw axis index.
buttons
readonlybuttons: readonlynumber[]
Standard button index to raw button index; -1 means the pad has no such button.
id
readonlyid:string
A substring of Gamepad.id that selects this remap, matched case-insensitively.
GamepadSnapshot
One frame's reading of a physical gamepad, in the shape navigator.getGamepads() reports.
Declared as its own type so the mapping is testable without a browser.
Properties
axes
readonlyaxes: readonlynumber[]
Axis values in [-1, 1], in the pad's raw order.
buttons
readonlybuttons: readonlynumber[]
Button values in [0, 1], in the pad's raw order.
id
readonlyid:string
The pad's id string.
mapping
readonlymapping:string
The pad's mapping: "standard", "xr-standard", or "".
GpuAdapterInfo
Who made the GPU, as WebGPU reports it.
Remarks
Browsers deliberately blur these strings — most return an empty architecture and device on
the default, non-unmaskHints path — so treat every field as a hint for a bug report rather than
as something to branch on.
Properties
architecture
readonlyarchitecture:string
The GPU family, "metal-3"; "" when the browser withholds it.
description
readonlydescription:string
A human-readable summary; "" when the browser withholds it.
device
readonlydevice:string
The specific device; "" when the browser withholds it.
vendor
readonlyvendor:string
The GPU vendor, "apple" or "nvidia"; "" when the browser withholds it.
GridAtlasImportOptions
What gridAtlas needs to cut an evenly spaced sheet into frames.
Properties
cellHeight
readonlycellHeight:number
One cell's height, in pixels. Must be positive.
cellWidth
readonlycellWidth:number
One cell's width, in pixels. Must be positive.
columns?
readonlyoptionalcolumns?:number
How many columns to emit. Defaults to as many as the image holds; clamped to that.
image
readonlyimage:string
The address of the image the frames are cut from.
imageHeight
readonlyimageHeight:number
The image's full height, in pixels.
imageWidth
readonlyimageWidth:number
The image's full width, in pixels.
margin?
readonlyoptionalmargin?:number
The border left around the whole grid, in pixels. Defaults to 0.
namePrefix?
readonlyoptionalnamePrefix?:string
The <prefix>_<index> frame names use. Defaults to "tile".
pivot?
readonlyoptionalpivot?:Vec2Like
The pivot every frame gets, in [0, 1]. Defaults to the centre.
premultipliedAlpha?
readonlyoptionalpremultipliedAlpha?:boolean
Whether the image's RGB is already multiplied by its alpha. Defaults to false.
rows?
readonlyoptionalrows?:number
How many rows to emit. Defaults to as many as the image holds; clamped to that.
sampling?
readonlyoptionalsampling?:"linear"|"nearest"
The min/mag filter. Defaults to "linear"; pixel art wants "nearest".
spacing?
readonlyoptionalspacing?:number
The gap between adjacent cells, in pixels. Defaults to 0.
GroundMeshOptions
How MeshAsset.ground sizes and subdivides its grid, which lies in the XZ plane facing
+Y.
Properties
height?
readonlyoptionalheight?:number
Size along Z, in metres.
subdivisions?
readonlyoptionalsubdivisions?:number
Quads per side.
uvScale?
readonlyoptionaluvScale?: readonly [number,number]
UV multiplier, for tiling a texture across the grid.
width?
readonlyoptionalwidth?:number
Size along X, in metres.
HeadlessBackendOptions
Options accepted by HeadlessBackend.
Properties
masterVolume?
readonlyoptionalmasterVolume?:number
The initial master gain. Defaults to 1.
startSuspended?
readonlyoptionalstartSuspended?:boolean
Start in the "suspended" state, so app.audio.state reads "locked" and plays are queued
until app.audio.unlock() — the browser's behaviour, reproduced under Node so the unlock flow
can be tested without a browser. Defaults to false.
HostDialogs
The dialogs the bridge exposes.
Methods
showOpenDialog()
showOpenDialog(
options?):Promise<HostOpenDialogResult>
Shows a modal open dialog over the game window.
Parameters
options?
What the dialog offers.
Returns
Promise<HostOpenDialogResult>
What the user chose.
HostFileFilter
One file-type row of an open dialog.
Properties
extensions
readonlyextensions: readonlystring[]
Extensions without a leading dot, for example ["sav", "json"].
name
readonlyname:string
The row's label, for example "Saved games".
HostOpenDialogOptions
What HostDialogs.showOpenDialog accepts. A deliberate subset of Electron's
OpenDialogOptions (electron.d.ts 15318): everything here is a plain value, so nothing about
the main process leaks into the renderer's types.
Properties
buttonLabel?
readonlyoptionalbuttonLabel?:string
The confirm button's label.
defaultPath?
readonlyoptionaldefaultPath?:string
The directory the dialog opens in.
directories?
readonlyoptionaldirectories?:boolean
Whether directories may be chosen. Defaults to false.
files?
readonlyoptionalfiles?:boolean
Whether files may be chosen. Defaults to true.
filters?
readonlyoptionalfilters?: readonlyHostFileFilter[]
The file-type rows.
multiple?
readonlyoptionalmultiple?:boolean
Whether more than one entry may be chosen. Defaults to false.
title?
readonlyoptionaltitle?:string
The dialog's title, where the platform shows one.
HostOpenDialogResult
What an open dialog returned.
Properties
canceled
readonlycanceled:boolean
Whether the user dismissed the dialog.
paths
readonlypaths: readonlystring[]
The absolute paths chosen; empty when the dialog was dismissed.
HostPaths
The directories a desktop build is allowed to know about, resolved once at startup.
Remarks
Read-only strings, not handles: a game that wants to write somewhere uses app.storage, which
goes through the same bridge and cannot escape userData.
Properties
appData
readonlyappData:string
The platform's roaming application-data directory.
appPath
readonlyappPath:string
The directory the packaged application resources were loaded from.
documents
readonlydocuments:string
The current user's documents directory, or "" where the platform has none.
downloads
readonlydownloads:string
The current user's downloads directory, or "" where the platform has none.
home
readonlyhome:string
The current user's home directory.
temp
readonlytemp:string
The platform's temporary directory.
userData
readonlyuserData:string
The per-user, per-app directory Electron gives the app; where app.storage lives.
HostShell
The shell half of the bridge.
Methods
openExternal()
openExternal(
url):Promise<void>
Opens a URL in the user's browser or mail client.
Parameters
url
string
The absolute URL to open.
Returns
Promise<void>
A promise that settles once the OS accepted it.
Remarks
The main process checks the protocol against an allow-list before handing it to the OS; a refusal rejects rather than silently doing nothing.
HostStorage
The storage half of the bridge. Namespaces and keys arrive already validated by the Storage
facade, so the main process treats a key as opaque text and encodes it for the file system.
Methods
clear()
clear(
namespace):Promise<void>
Removes every value of one namespace.
Parameters
namespace
string
The namespace path.
Returns
Promise<void>
A promise that settles once the namespace is empty.
delete()
delete(
namespace,key):Promise<void>
Removes one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside that namespace.
Returns
Promise<void>
A promise that settles once the value is gone.
get()
get(
namespace,key):Promise<HostStoredValue|null>
Reads one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside that namespace.
Returns
Promise<HostStoredValue | null>
The stored value, or null when there is none.
keys()
keys(
namespace,prefix?):Promise<readonlystring[]>
Lists the keys of one namespace.
Parameters
namespace
string
The namespace path.
prefix?
string
When given, only keys that start with this string are returned.
Returns
Promise<readonly string[]>
The matching keys, sorted ascending.
set()
set(
namespace,key,value):Promise<void>
Writes one value, replacing whatever was there.
Parameters
namespace
string
The namespace path.
key
string
The key inside that namespace.
value
The JSON text or the octets to persist.
Returns
Promise<void>
A promise that settles once the value is durable.
HostVersions
The runtime versions the bridge reports, read from process.versions in the preload script.
Properties
chrome
readonlychrome:string
The Chromium version.
electron
readonlyelectron:string
The Electron version, for example "44.2.0".
node
readonlynode:string
The Node version bundled with Electron.
HostWindow
The window controls the bridge exposes.
Methods
isFullscreen()
isFullscreen():
Promise<boolean>
Reports whether the window is full screen.
Returns
Promise<boolean>
true when it is.
onEvent()
onEvent(
listener): () =>void
Subscribes to the window lifecycle events the main process forwards.
Parameters
listener
(event) => void
Called with each event name.
Returns
A function that unsubscribes.
() => void
quit()
quit():
Promise<void>
Closes the window and quits the application.
Returns
Promise<void>
A promise that settles once the quit has been requested.
setFullscreen()
setFullscreen(
fullscreen):Promise<void>
Enters or leaves full screen.
Parameters
fullscreen
boolean
true to enter, false to leave.
Returns
Promise<void>
A promise that settles once the main process has applied it.
setTitle()
setTitle(
title):Promise<void>
Sets the window's title.
Parameters
title
string
The new title.
Returns
Promise<void>
A promise that settles once the main process has applied it.
HotReloadHost
The app's hot-reload service, reached as app.hotReload
(docs/architecture/15-devtools-and-diagnostics.md §5). It works with no Vite and no browser:
@ignifx/vite-plugin generates a client that calls HotReloadHost.apply, and a headless
test calls it directly.
Example
const report = app.hotReload.apply([{ types: [NextMover] }]);
console.log(report.kind, report.typeIds, report.instances);Properties
onApplied
readonlyonApplied:SignalLike<HotReloadReport>
Emitted once per completed HotReloadHost.apply or HotReloadHost.reloadScene with the report that call returns.
reloadScenes
readonlyreloadScenes:boolean
Whether a changed scene file re-instantiates the live scene instances built from it, set with
createApp({ hotReload: { reloadScenes: true } }). Off by default, because rebuilding a scene
throws away everything the running game has done to it.
Methods
apply()
apply(
modules):HotReloadReport
Applies replaced component classes to the running app.
Parameters
modules
readonly HotReloadModule[]
The replaced modules and the classes they export.
Returns
What was reloaded.
Throws
IgnifxError with code IGX-0208 when called from inside a lifecycle callback, where a
half-swapped world would be observable.
reloadScene()
reloadScene(
instance):Promise<SceneInstance>
Rebuilds one scene instance from its asset's current value, honouring the file's instance overrides wherever their paths still resolve.
Parameters
instance
The instance to rebuild. It is unloaded and a fresh one takes its place.
Returns
Promise<SceneInstance>
The new instance.
Throws
IgnifxError with code IGX-0209 when the instance was not built from a scene asset.
HotReloadModule
One replaced module's worth of component classes, as the HMR client hands them over. Classes the
app has never seen are registered; classes whose typeId is already registered to a different
class are reloaded under their policy; classes that are already the registered ones are skipped.
Properties
types
readonlytypes: readonlyConcreteComponentType<Component>[]
Every component or script class the replaced module exports.
HotReloadOptions
The hotReload section of createApp's options.
Properties
reloadScenes?
readonlyoptionalreloadScenes?:boolean
Sets HotReloadHost.reloadScenes. Defaults to false.
HotReloadReport
What one hot reload did, for logs, tests, and the devtools overlay.
Properties
durationMs
readonlydurationMs:number
How long the operation took, in milliseconds.
errors
readonlyerrors: readonlyunknown[]
Everything that threw on the way; the reload continues past each one.
instances
readonlyinstances:number
How many live component instances were swapped or re-created, or entities rebuilt for a scene.
kind
readonlykind:HotReloadKind
Which of the three operations this report describes.
typeIds
readonlytypeIds: readonlystring[]
The typeIds actually reloaded, in the order they were applied; empty when nothing changed.
HotReloadStatics
The statics a component or script class may declare to steer its own hot reload
(docs/architecture/15-devtools-and-diagnostics.md §5). Structural and optional, for the reason
given on ComponentStatics: a member declared on the Component base class would force the
override keyword on every static hotReload = "recreate" under noImplicitOverride.
Example
class Inventory extends Script.define({ slots: u32(4) }) {
static typeId = "mygame/Inventory";
static hotReload = "recreate" as const;
}Properties
hotReload?
readonlyoptionalhotReload?:HotReloadPolicy
The policy for this class; defaults to "patch".
Methods
onHotReload()?
optionalonHotReload(previous):void
Runs once on the new class after every live instance of it has been swapped or re-created,
with the class that was registered before as previous. It is the seam for class-level
transient state — a cache keyed off the old class, a static counter — and it is deliberately
not per instance: under "patch" the instances are the very same objects, so there is
nothing to copy across (PlayCanvas's swap(old) exists only because it re-instantiates), and
under "recreate" per-instance state is re-derived from the schema by design.
Parameters
previous
The class this one replaces.
Returns
void
HudPlacement
A layer position, written in place so the per-frame path allocates nothing.
Properties
x
x:
number
The layer's x, in render-target pixels.
y
y:
number
The layer's y — the first baseline — in render-target pixels.
HudPlacementInput
What computeHudPlacement needs.
Properties
anchor
readonlyanchor:"topLeft"|"top"|"topRight"|"left"|"center"|"right"|"bottomLeft"|"bottom"|"bottomRight"
Which point of the target the position is measured from, and which point of the block lands there.
blockHeight
readonlyblockHeight:number
The block's laid-out height.
blockWidth
readonlyblockWidth:number
The block's laid-out width.
fontSize
readonlyfontSize:number
The em size the block was shaped at.
offsetX
readonlyoffsetX:number
The offset from that point, in render-target pixels; x grows right, y grows down.
offsetY
readonlyoffsetY:number
The offset from that point, in render-target pixels.
targetHeight
readonlytargetHeight:number
The render target's height, in pixels.
targetWidth
readonlytargetWidth:number
The render target's width, in pixels.
IgnifxErrorOptions
Options accepted by IgnifxError. Extends the standard ErrorOptions, so cause keeps
the original failure when an error is wrapped.
Extends
ErrorOptions
Extended by
Properties
cause?
optionalcause?:unknown
Inherited from
ErrorOptions.cause
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure. Defaults to an empty record.
hint?
readonlyoptionalhint?:string|null
One sentence telling the developer what to do about it. Defaults to null.
mode?
readonlyoptionalmode?:ErrorFormatMode
How verbose message should be. Defaults to "development".
IgnifxHost
window.ignifxHost: everything the preload script exposes to the renderer
(docs/architecture/14-platform-electron.md §3).
Remarks
Every member is a function or a plain value. No ipcRenderer, no Electron object, and nothing
with a prototype the renderer could walk back to Node — contextBridge would refuse most of that
anyway, and the ones it would allow are exactly the ones CONSTITUTION.md §9.2 forbids.
Example
if (window.ignifxHost !== undefined) {
const { userData } = await window.ignifxHost.paths();
}Properties
dialogs
readonlydialogs:HostDialogs
Native dialogs.
shell
readonlyshell:HostShell
The OS shell.
storage
readonlystorage:HostStorage
Reference-counted key/value storage under userData.
version
readonlyversion:string
The HOST_CONTRACT_VERSION this bridge was built from.
versions
readonlyversions:HostVersions
The Electron, Chromium, and Node versions the app is running on.
window
readonlywindow:HostWindow
Window controls and window lifecycle events.
Methods
paths()
paths():
Promise<HostPaths>
Resolves the platform directories.
Returns
Promise<HostPaths>
The directories, resolved by the main process.
ImageProcessingEffectSettings
The imageProcessing record a PostProcessStack declares
(docs/architecture/07-rendering.md §2.7).
Properties
enabled
enabled:
boolean
Whether a full-screen grading pass runs.
order
order:
number
Position in the chain; lower runs first.
ImageProcessingSettings
The imageProcessing record an Environment declares
(docs/architecture/07-rendering.md §2.5).
Properties
contrast
contrast:
number
Contrast multiplier.
exposure
exposure:
number
Exposure multiplier.
toneMapping
toneMapping:
"none"|"standard"|"aces"|"neutral"
The tone-mapping curve.
InputActionEvent
The payload of InputAction.onStarted, InputAction.onPerformed, and InputAction.onCanceled.
Remarks
One event object is reused per action, so a handler that needs the values after its call returns must copy them. Reusing it is what keeps the steady frame allocation-free (coding standards §7).
Properties
action
readonlyaction:InputAction
The action that changed.
magnitude
readonlymagnitude:number
The action's magnitude this frame, in [0, 1] for normalised controls.
phase
readonlyphase:"started"|"performed"|"canceled"
Which signal is delivering: started, performed, or canceled.
x
readonlyx:number
The x component of the action's value.
y
readonlyy:number
The y component of the action's value; 0 unless the action is a vector2.
InputActionsDefinition
A whole ignifx.inputactions document.
Properties
controlSchemes
readonlycontrolSchemes: readonlyControlSchemeDefinition[]
The control schemes the document declares.
format
readonlyformat:"ignifx.inputactions"
Always ignifx.inputactions.
formatVersion
readonlyformatVersion:number
The format version; 1 before ignifx 1.0.
maps
readonlymaps: readonlyActionMapDefinition[]
The action maps the document declares.
InputActionsInput
What defineInputActions accepts: a document with the two header fields optional, because code that builds the object does not have to repeat what the format already fixes.
Properties
controlSchemes?
readonlyoptionalcontrolSchemes?: readonlyControlSchemeDefinition[]
The control schemes; defaults to none.
format?
readonlyoptionalformat?:"ignifx.inputactions"
Always ignifx.inputactions when present.
formatVersion?
readonlyoptionalformatVersion?:number
The format version when present; defaults to 1.
maps
readonlymaps: readonlyActionMapDefinition[]
The action maps.
InputErrorOptions
Options accepted by inputError: the same subset of IgnifxErrorOptions this package uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
InputEventRecord
One raw event of the current frame (docs/architecture/08-input.md §5).
Remarks
Every field is always present; the ones an event kind does not use read 0 or "". A fixed
shape is what lets the records be pooled, and reading deltaX on a keydown is harmless.
The records are recycled: keep a copy of anything needed after the frame ends.
Properties
button
readonlybutton:number
The PointerEvent.button index, for pointer events.
code
readonlycode:string
The physical KeyboardEvent.code, for key events.
deltaX
readonlydeltaX:number
The pointer movement x, or the wheel's horizontal delta.
deltaY
readonlydeltaY:number
The pointer movement y, or the wheel's vertical delta.
key
readonlykey:string
The layout-dependent KeyboardEvent.key, or the composed text of a textinput event.
pointerId
readonlypointerId:number
The PointerEvent.pointerId, for pointer events.
pointerType
readonlypointerType:string
The PointerEvent.pointerType: mouse, pen, or touch.
repeat
readonlyrepeat:boolean
Whether a key event is an auto-repeat.
sequence
readonlysequence:number
A monotonically increasing arrival number, shared by every event of one app.
type
readonlytype:InputEventType
Which kind of event this is.
x
readonlyx:number
The pointer x, in CSS pixels from the canvas's left edge.
y
readonlyy:number
The pointer y, in CSS pixels from the canvas's top edge.
InputOptions
What input() accepts. Every field overrides the matching input settings section value, which
is the shape 04-extensions.md §1 shows for physics().
Properties
actions?
readonlyoptionalactions?:string
The address of the .input.json document loaded at startup.
defaultScheme?
readonlyoptionaldefaultScheme?:string
The control scheme the app starts in.
gamepadPolling?
readonlyoptionalgamepadPolling?:boolean
Whether gamepads are polled each frame.
gamepadReader?
readonlyoptionalgamepadReader?:GamepadReader|null
How gamepads are read. Defaults to navigator.getGamepads(), or to no polling at all under
Node. Tests pass their own reader.
pointerLock?
readonlyoptionalpointerLock?:PointerLockSettings
Pointer-lock policy.
pressPoint?
readonlyoptionalpressPoint?:number
The magnitude at which an analog value counts as pressed.
strictSchemes?
readonlyoptionalstrictSchemes?:boolean
Whether a scheme tag filters resolution as well as device pairing.
InputOverrideEntry
One overridden binding.
Properties
action
readonlyaction:string
The action name.
bindingIndex
readonlybindingIndex:number
Which of the action's bindings is overridden.
map
readonlymap:string
The map the action belongs to.
path
readonlypath:string
The path the binding now reads.
InputOverridesJson
A saved set of binding overrides.
Example
const saved = app.input.saveOverrides();
localStorage.setItem("bindings", JSON.stringify(saved));Properties
format
readonlyformat:string
Always ignifx.inputoverrides. Typed as a string because the value is read back from JSON.
formatVersion
readonlyformatVersion:number
The format version; 1 before ignifx 1.0.
overrides
readonlyoverrides: readonlyInputOverrideEntry[]
The overridden bindings.
InputServiceOptions
What InputService is constructed with.
Properties
app
readonlyapp:App
The app the service belongs to.
gamepadReader?
readonlyoptionalgamepadReader?:GamepadReader|null
The gamepad reader; defaults to navigator.getGamepads() when the host has it.
settings
readonlysettings:InputSettings
The resolved input settings section.
InputSettings
The resolved input settings section.
Example
// ignifx.config.ts
export default defineConfig({ input: { actions: "input/default.input.json", pressPoint: 0.4 } });Properties
actions
readonlyactions:string
The address of the .input.json document loaded at startup; empty loads none.
defaultScheme
readonlydefaultScheme:string
The control scheme the app starts in; empty picks the first the document declares.
gamepadPolling
readonlygamepadPolling:boolean
Whether gamepads are polled each frame. Defaults to true.
pointerLock
readonlypointerLock:PointerLockSettings
Pointer-lock policy.
pressPoint
readonlypressPoint:number
The magnitude at which an analog value counts as pressed. Defaults to 0.5.
strictSchemes
readonlystrictSchemes:boolean
Whether a binding tagged with a control scheme resolves only while that scheme is active.
Defaults to false, which is Unity's behaviour and what most games want.
InstantiateOptions
Options accepted by World.instantiate and World.instantiateAsync
(docs/architecture/02-scene-graph.md §2).
Properties
name?
readonlyoptionalname?:string
Renames the instance root.
parent?
readonlyoptionalparent?:Entity|null
The parent to attach the instance root to; null or omitted makes it a root.
position?
readonlyoptionalposition?:Vec3Like
Places the instance root.
rotation?
readonlyoptionalrotation?:QuatLike
Rotates the instance root.
scene?
readonlyoptionalscene?:SceneInstance
The instance that owns the new entities; defaults to the parent's, else world.activeScene.
strictInstanceHashes?
readonlyoptionalstrictInstanceHashes?:boolean
true turns an IGX-0604 instance hash mismatch from a logged warning into a throw.
worldSpace?
readonlyoptionalworldSpace?:boolean
true reads position/rotation as world values; false (the default) as local ones.
InstantiateSceneOptions
Options accepted by instantiateScene.
Properties
asInstance?
readonlyoptionalasInstance?:boolean
true treats the whole file as one instance: every entity gets a fresh uid and an
Entity.prefab link. This is what world.instantiate does; world.loadScene leaves it off so
that the scene's own entities keep the uids the file gave them
(docs/architecture/02-scene-graph.md §10).
assetHandle?
readonlyoptionalassetHandle?:AssetHandle<SceneAsset> |null
The handle the scene was loaded through, recorded on Entity.prefab when asInstance.
parent?
readonlyoptionalparent?:Entity|null
The entity the scene's roots attach to; null or omitted makes them roots of scene.
rootEntity?
readonlyoptionalrootEntity?:Entity|null
The entity that stands for the instance when asInstance is set and the file has more or fewer
than one root. world.instantiate creates it and passes it as both parent and rootEntity,
so that the call still answers with one entity.
scene?
readonlyoptionalscene?:SceneInstance
The instance that owns the new entities; defaults to the parent's, else world.activeScene.
strictInstanceHashes?
readonlyoptionalstrictInstanceHashes?:boolean
true turns an IGX-0604 hash mismatch from a diagnostic into a throw.
InteractiveRebindOptions
Options accepted by app.input.performInteractiveRebind.
Properties
bindingIndex?
readonlyoptionalbindingIndex?:number
Which of the action's bindings to override. Defaults to 0.
cancelPath?
readonlyoptionalcancelPath?:string
A path that cancels the rebind when actuated, usually <Keyboard>/escape.
excludePaths?
readonlyoptionalexcludePaths?: readonlystring[]
Paths the rebind refuses to bind to, for example the movement keys.
magnitudeThreshold?
readonlyoptionalmagnitudeThreshold?:number
The magnitude a control must reach to count as actuated. Defaults to 0.5.
timeoutSeconds?
readonlyoptionaltimeoutSeconds?:number
How long to listen before giving up, in unscaled seconds. 0 waits forever.
InteractiveRebindResult
What app.input.performInteractiveRebind resolves with.
Properties
action
readonlyaction:InputAction
The action that was being rebound.
bindingIndex
readonlybindingIndex:number
The binding index that was being rebound.
canceled
readonlycanceled:boolean
Whether the cancel control ended the rebind.
path
readonlypath:string|null
The path the player chose, or null when the rebind was cancelled or timed out.
timedOut
readonlytimedOut:boolean
Whether the timeout ended the rebind.
LayerMaskFieldSpec
Kind-specific data for layerMask.
Properties
kind
readonlykind:"layerMask"
The layer-mask kind.
LayersSettings
The layers project settings section (docs/architecture/04-extensions.md §5,
02-scene-graph.md §7).
Properties
layers
readonlylayers: readonlystring[]
The project's layer names in declaration order.
LdtkImportOptions
How importLdtkLevel maps LDtk's conventions onto ignifx's.
Properties
atlasFor?
readonlyoptionalatlasFor?: (relPath) =>string
Maps an LDtk tileset's relPath onto the address of the ignifx .atlas.json generated from it.
Defaults to swapping the file extension for .atlas.json.
Parameters
relPath
string
Returns
string
intGridColliders?
readonlyoptionalintGridColliders?:Readonly<Record<number,TileColliderDefinition>>
Replaces LDTK_DEFAULT_INTGRID_COLLIDERS for this import.
level?
readonlyoptionallevel?:string
The identifier of the level to import. Defaults to the project's first level.
pixelsPerUnit?
readonlyoptionalpixelsPerUnit?:number
The pixels one world metre spans. Defaults to 100, matching twoD.pixelsPerUnit.
sortingLayer?
readonlyoptionalsortingLayer?:string
The sorting layer every layer lands in. Defaults to "Default".
LightShadowSettings
The shadows record a Light declares (docs/architecture/07-rendering.md §2.2).
Properties
bias
bias:
number
Depth bias applied while sampling.
cascades
cascades:
number
Cascade count, CSM only; Lite clamps it to four.
darkness
darkness:
number
How dark a fully shadowed texel is: 0 is black, 1 is unshadowed.
enabled
enabled:
boolean
Whether this light casts shadows.
mapSize
mapSize:
number
Shadow map resolution, in texels per side.
maxDistance
maxDistance:
number
The distance beyond which nothing is shadowed, in metres; 0 takes Lite's default.
normalBias
normalBias:
number
Offset along the surface normal, PCF only.
technique
technique:
"esm"|"pcf"|"csm"
The technique; spot lights ignore it and always use PCF, the only one Lite offers them.
LoaderContext
What a loader is handed for one load
(docs/architecture/05-assets-and-loading.md §5).
Remarks
The three fetch* methods share one code path: the bytes are streamed through the service's
priority queue, counted into the handle's progress, and aborted with LoaderContext.signal.
A loader that reaches the network any other way loses progress, cancellation, and retries.
Properties
address
readonlyaddress:string
The address being loaded, fragment included.
app
readonlyapp:App
The app the load belongs to.
fragment
readonlyfragment:string|null
The #fragment part of the address, or null when it carries none.
lite
readonlylite:object
Unstable Babylon Lite escape hatch for GPU loaders (docs/architecture/00-overview.md §3).
engine
readonlyengine:EngineContext
meta
readonlymeta:JsonObject|null
The .meta.json sidecar the build recorded for this address, or null when the manifest lists
none (docs/architecture/05-assets-and-loading.md §7).
Remarks
Read the sub-object your loader owns and ignore the rest: one sidecar carries options for
several tools, and groups in it belongs to the manifest generator, not to a loader.
Example
const srgb = asRecord(ctx.meta?.["texture"])?.["srgb"] === true;signal
readonlysignal:AbortSignal
Aborted when the request is cancelled or the app is disposed.
type
readonlytype:string
The asset type the loader is registered under.
url
readonlyurl:string
The URL the address resolved to, fragment stripped.
Methods
fetchBytes()
fetchBytes():
Promise<ArrayBuffer>
Fetches the address as bytes, with progress and cancellation.
Returns
Promise<ArrayBuffer>
The response body.
fetchJson()
fetchJson<
J>():Promise<J>
Fetches the address and parses it as JSON.
Type Parameters
J
J = unknown
The parsed shape, as the loader declares it.
Returns
Promise<J>
The parsed body.
fetchText()
fetchText():
Promise<string>
Fetches the address as UTF-8 text.
Returns
Promise<string>
The decoded body.
loadDependency()
loadDependency<
D>(ref,options?):Promise<AssetHandle<D>>
Loads another asset as a dependency of this one: its progress counts into this load and the retain it takes is released when this asset is unloaded.
Type Parameters
D
D
The dependency's loaded value type.
Parameters
ref
string | AssetRef<D>
The dependency's address or reference.
options?
Priority, type, progress, and cancellation.
Returns
Promise<AssetHandle<D>>
The dependency's handle, once it has been delivered.
reportProgress()
reportProgress(
fraction):void
Reports progress for loaders that cannot express it in bytes.
Parameters
fraction
number
How far along the load is, in [0, 1].
Returns
void
LoadingScreenOptions
What new LoadingScreen(app.ui, options) accepts.
Properties
label?
readonlyoptionallabel?:string
The initial label. Defaults to "Loading…".
layer?
readonlyoptionallayer?:string
The layer to mount into. Defaults to "overlay".
visible?
readonlyoptionalvisible?:boolean
Whether the screen starts shown. Defaults to true — a boot screen is up before anything else.
LoadOptions
Options accepted by every load entry point of Assets.
Properties
onProgress?
readonlyoptionalonProgress?: (fraction) =>void
Called at delivery whenever this request's progress changed.
Parameters
fraction
number
How far along the load is, in [0, 1].
Returns
void
priority?
readonlyoptionalpriority?:number
Higher runs first; ties break in request order. Defaults to 0.
signal?
readonlyoptionalsignal?:AbortSignal
Aborts this request. Whether it aborts the shared load is documented on Assets.load.
type?
readonlyoptionaltype?:string
The asset type, when the address's extension does not identify it.
LoadProgress
How far a scene load has got, as world.loadScene's onProgress reports it.
Properties
address
readonlyaddress:string
The address being loaded.
fraction
readonlyfraction:number
How far along, in [0, 1], counting every dependency the scene pulls in.
LoadSceneOptions
Options accepted by World.loadScene (docs/architecture/02-scene-graph.md §2).
Properties
mode?
readonlyoptionalmode?:"single"|"additive"
"single" (the default) unloads every instance that is not persistent first; "additive"
keeps them.
onProgress?
readonlyoptionalonProgress?: (progress) =>void
Called as the scene and its dependencies load.
Parameters
progress
Returns
void
setActive?
readonlyoptionalsetActive?:boolean
Makes the loaded instance world.activeScene. Defaults to true for a "single" load and
false for an additive one, which is what "the level you just loaded owns new entities" means.
signal?
readonlyoptionalsignal?:AbortSignal
Cancels the load; an abort after the asset arrived still rejects with IGX-0502.
strictInstanceHashes?
readonlyoptionalstrictInstanceHashes?:boolean
true turns an IGX-0604 instance hash mismatch from a logged warning into a throw.
LocaleDocument
A parsed ignifx.i18n document.
Properties
defaultLocale
readonlydefaultLocale:string
The locale used when nothing else selected one.
locales
readonlylocales:Readonly<Record<string,Readonly<Record<string,string>>>>
Every locale's message table, keyed by BCP 47 tag.
LodLevel
One level of detail.
Properties
distance
readonlydistance:number
The distance from the camera, in metres, beyond which this level takes over.
renderer
readonlyrenderer:MeshRenderer|null
The renderer this level draws.
Logger
The logging front end reached as app.log and, per extension, as ctx.log
(docs/architecture/15-devtools-and-diagnostics.md §2).
Remarks
Calls below the current threshold return before any record is built, so a disabled debug() costs
one numeric comparison. The rest parameter itself is still materialised by the JavaScript engine,
so per-frame call sites guard with Logger.isEnabled instead (coding standards §7).
Example
const log = app.log.child("physics");
log.info("stepping at {hz}Hz", 60);
if (log.isEnabled("debug")) {
log.debug("contacts", collectContacts());
}Properties
level
readonlylevel:LogThreshold
The threshold below which records are dropped. Shared with every child logger.
scope
readonlyscope:string|null
The dotted scope prefix of this logger, or null for the root.
Methods
addSink()
addSink(
sink): () =>void
Adds a second sink that receives every record this logger tree writes, alongside the one
createApp({ logSink }) installed. Children share the list, so a sink added on app.log sees
ctx.log records too. This is how @ignifx/devtools fills its Console panel without the game
wiring anything.
Parameters
sink
The sink to add.
Returns
A function that removes it again.
() => void
child()
child(
scope):Logger
Creates a logger that prefixes its records with an additional scope segment and shares this
logger's sink, threshold, clock, and warnOnce memory.
Parameters
scope
string
The segment to append, for example "physics".
Returns
The scoped logger.
debug()
debug(
message, ...data):void
Writes a debug record.
Parameters
message
string
The message.
data
...readonly unknown[]
Structured extras.
Returns
void
error()
error(
message, ...data):void
Writes an error record.
Parameters
message
string
The message.
data
...readonly unknown[]
Structured extras.
Returns
void
info()
info(
message, ...data):void
Writes an info record.
Parameters
message
string
The message.
data
...readonly unknown[]
Structured extras.
Returns
void
isEnabled()
isEnabled(
level):boolean
Reports whether a record at this level would be written.
Parameters
level
The level to test.
Returns
boolean
true when the level passes the current threshold.
setLevel()
setLevel(
level):void
Raises or lowers the threshold for this logger, its parents, and its children — they share one
setting so devtools can turn debug on for the whole app at once.
Parameters
level
The new threshold.
Returns
void
warn()
warn(
message, ...data):void
Writes a warn record.
Parameters
message
string
The message.
data
...readonly unknown[]
Structured extras.
Returns
void
warnOnce()
warnOnce(
key,message, ...data):void
Writes a warn record the first time this key is seen and drops every later call with the same
key. This is the rate limiter for warnings that would otherwise repeat every frame.
Parameters
key
string
The de-duplication key, scoped to this logger's scope.
message
string
The message, used on the first call only.
data
...readonly unknown[]
Structured extras, used on the first call only.
Returns
void
LoggerOptions
Options for createLogger.
Properties
level?
readonlyoptionallevel?:LogThreshold
The initial threshold. Defaults to "info".
now?
readonlyoptionalnow?: () =>number
The clock used for LogRecord.timeMs. Defaults to performance.now when the host has
it and Date.now otherwise; tests pass a counter so records are deterministic.
Returns
number
scope?
readonlyoptionalscope?:string|null
The root scope. Defaults to null.
sink
readonlysink:LogSink
Where records go.
LogRecord
One line of log output, as handed to a LogSink.
Properties
data
readonlydata: readonlyunknown[]
Structured extras passed after the message. Empty when there were none.
level
readonlylevel:LogLevel
The severity of the line.
message
readonlymessage:string
The human-readable message.
scope
readonlyscope:string|null
The dotted scope of the logger that produced it, or null for the root logger.
timeMs
readonlytimeMs:number
The logger clock's reading when the line was produced, in milliseconds.
LogSink
Where log records go: the console, a devtools panel, a file in Electron, or an in-memory buffer in tests. A sink is passed to createLogger and is never discovered globally.
Extended by
Methods
write()
write(
record):void
Writes one record. Called synchronously from the logging call site, so implementations must be cheap and must not throw.
Parameters
record
The record to write.
Returns
void
ManualClock
A clock that only moves when a test moves it.
Extends
Methods
advance()
advance(
milliseconds):void
Moves the clock forward.
Parameters
milliseconds
number
How far to advance. Negative values are rejected so the clock stays monotonic.
Returns
void
nowMs()
nowMs():
number
Reads the clock.
Returns
number
Milliseconds since an unspecified epoch; only differences are meaningful.
Inherited from
set()
set(
milliseconds):void
Sets the clock to an absolute reading.
Parameters
milliseconds
number
The new reading.
Returns
void
MapFieldSpec
Kind-specific data for map.
Properties
kind
readonlykind:"map"
The map kind.
value
readonlyvalue:FieldDefinition<unknown>
The field definition every entry's value follows.
Mat4Like
A read-only 4x4 matrix stored as 16 numbers in column-major order (m[column * 4 + row]),
the layout WGSL's mat4x4<f32> expects and the one Babylon Lite uses, so a Lite Mat4 is a
Mat4Like and vice versa. Translation lives in slots 12/13/14.
The storage type is deliberately unspecified: it is a Float32Array in both Lite and ignifx
today (see Mat4.elements) but callers must only rely on indexed reads and length.
Example
function translationX(m: Mat4Like): number {
return m[12] ?? 0;
}Indexable
[
index:number]:number
Element access in column-major order; m[column * 4 + row].
Properties
length
readonlylength:16
Always exactly 16.
MaterialAssetLiteHandles
The Babylon Lite objects a MaterialAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
material
readonlymaterial:Material
The Lite material. Present in headless mode too: a material is plain data.
MemorySink
A LogSink that keeps the most recent records in a fixed-size ring buffer. Used by the devtools console panel, which needs scrollback without unbounded growth, and by unit tests, which assert on what was logged.
Extends
Properties
length
readonlylength:number
How many records are currently retained, never more than MemorySink.limit.
limit
readonlylimit:number
The maximum number of records retained.
Methods
at()
at(
index):LogRecord|null
Reads one retained record without copying the buffer.
Parameters
index
number
0 is the oldest retained record, length - 1 the newest.
Returns
LogRecord | null
The record, or null when the index is out of range.
clear()
clear():
void
Drops every retained record.
Returns
void
toArray()
toArray(): readonly
LogRecord[]
Copies the retained records, oldest first.
Returns
readonly LogRecord[]
A new array; allocating here is fine because only tests and devtools call it.
write()
write(
record):void
Writes one record. Called synchronously from the logging call site, so implementations must be cheap and must not throw.
Parameters
record
The record to write.
Returns
void
Inherited from
MeshAssetLiteHandles
The Babylon Lite objects a MeshAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
mesh
readonlymesh:Mesh|null
The template mesh, or null under a headless app, which uploads no geometry.
MeshGeometryData
Raw vertex data for MeshAsset.fromData.
Remarks
Lite keeps references to these arrays rather than copying them — they are what its CPU ray pick
and its bounds read (lib/mesh/mesh-factories.js) — so a caller must not mutate them afterwards.
Properties
indices
readonlyindices:Uint32Array
Three indices per triangle.
normals
readonlynormals:Float32Array
Three floats per vertex, one normal each.
positions
readonlypositions:Float32Array
Three floats per vertex.
uvs?
readonlyoptionaluvs?:Float32Array<ArrayBufferLike>
Two floats per vertex, or omitted for a mesh with no texture coordinates.
MessagePattern
A parsed message, or the reason it could not be parsed.
Properties
error
readonlyerror:string|null
Why the pattern could not be read, or null when it parsed.
nodes
readonlynodes: readonlyMessageNode[]
The nodes to render. Holds the raw pattern as one text node when MessagePattern.error is set.
ModelAssetLiteHandles
The Babylon Lite objects a ModelAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
container
readonlycontainer:AssetContainer|null
The template container, or null under a headless app.
ModelInstantiation
One instantiated copy of a model, as a Model component holds it.
Properties
nodes
readonlynodes:ReadonlyMap<string,SceneNode>
Every named node in the clone, keyed by its glTF node name.
root
readonlyroot:SceneNode
The cloned container root, parented under the entity's node.
MusicPlayOptions
Options accepted by MusicPlayer.play.
Properties
fadeIn?
readonlyoptionalfadeIn?:number
Seconds to fade the new track up over. Defaults to no fade.
MusicStopOptions
Options accepted by MusicPlayer.stop.
Properties
fadeOut?
readonlyoptionalfadeOut?:number
Seconds to fade the current track out over. Defaults to stopping now.
MutableQuat
A writable quaternion — the out shape of every Quat ToRef function, and the type
Transform.localRotation exposes. Babylon Lite's ObservableQuat satisfies it exactly, so
rotations are written straight into the Lite node (docs/architecture/02-scene-graph.md section 5).
Example
Quat.fromEulerDegreesToRef(0, 90, 0, transform.localRotation);Properties
w
w:
number
The real (scalar) component.
x
x:
number
The imaginary X component.
y
y:
number
The imaginary Y component.
z
z:
number
The imaginary Z component.
Methods
copyFrom()
copyFrom(
q):void
Copies every component from another quaternion.
Parameters
q
The quaternion to read.
Returns
void
set()
set(
x,y,z,w):void
Assigns every component at once. Live views use this to emit a single change notification.
Parameters
x
number
The new imaginary X component.
y
number
The new imaginary Y component.
z
number
The new imaginary Z component.
w
number
The new real component.
Returns
void
MutableVec2
A writable 2-component vector — the out shape of every Vec2 ToRef function.
Example
const out = new Vec2();
Vec2.addToRef(a, b, out);Properties
x
x:
number
The X component.
y
y:
number
The Y component.
Methods
copyFrom()
copyFrom(
v):void
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
void
set()
set(
x,y):void
Assigns every component at once.
Parameters
x
number
The new X component.
y
number
The new Y component.
Returns
void
MutableVec3
A writable 3-component vector — the out shape of every Vec3 ToRef function, and the type
Transform.localPosition/localScale expose. Babylon Lite's ObservableVec3 (the live view over
a SceneNode's TRS) satisfies this interface exactly, so writing through it notifies Lite's
hierarchy without any copy (docs/architecture/02-scene-graph.md section 5).
Example
// `transform.localPosition` is a live MutableVec3 over the Lite node.
Vec3.addToRef(transform.localPosition, velocity, transform.localPosition);Properties
x
x:
number
The X component.
y
y:
number
The Y component.
z
z:
number
The Z component.
Methods
copyFrom()
copyFrom(
v):void
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
void
set()
set(
x,y,z):void
Assigns every component at once. Live views use this to emit a single change notification.
Parameters
x
number
The new X component.
y
number
The new Y component.
z
number
The new Z component.
Returns
void
MutableVec4
A writable 4-component vector — the out shape of every Vec4 ToRef function.
Example
const out = new Vec4();
Vec4.lerpToRef(a, b, 0.5, out);Properties
w
w:
number
The W component.
x
x:
number
The X component.
y
y:
number
The Y component.
z
z:
number
The Z component.
Methods
copyFrom()
copyFrom(
v):void
Copies every component from another vector.
Parameters
v
The vector to read.
Returns
void
set()
set(
x,y,z,w):void
Assigns every component at once.
Parameters
x
number
The new X component.
y
number
The new Y component.
z
number
The new Z component.
w
number
The new W component.
Returns
void
NumberFieldSpec
Kind-specific data for the numeric kinds.
Properties
kind
readonlykind:"f32"|"f64"|"i32"|"u32"
The numeric kind.
OneShotOptions
Options accepted by AudioService.playOneShot.
Extends
Properties
bus?
readonlyoptionalbus?:string
The bus to route through. Defaults to "SFX".
delay?
readonlyoptionaldelay?:number
How long to wait before it starts, in seconds.
Inherited from
duration?
readonlyoptionalduration?:number
How long to play for, in seconds; 0 plays to the end of the clip.
Inherited from
loop?
readonlyoptionalloop?:boolean
Whether this play loops; defaults to the source's loop.
Inherited from
pitch?
readonlyoptionalpitch?:number
Playback rate for this play; defaults to the source's pitch.
Inherited from
startOffset?
readonlyoptionalstartOffset?:number
Where in the clip to start, in seconds.
Inherited from
volume?
readonlyoptionalvolume?:number
Linear gain for this play; defaults to the source's volume.
Inherited from
OneShotVolume
Options accepted by AudioSource.playOneShot.
Properties
volume?
readonlyoptionalvolume?:number
Linear gain for this one play.
OptionalFieldSpec
Kind-specific data for optional.
Properties
inner
readonlyinner:FieldDefinition<unknown>
The field definition a non-null value follows.
kind
readonlykind:"optional"
The optional kind.
ParsedControlPath
A parsed binding path.
Properties
control
readonlycontrol:string
The control name, sub-control segments included, for example dpad/up.
device
readonlydevice:DeviceKind
The device family the path names.
deviceIndex
readonlydeviceIndex:number
Which device of the family, zero-based. 0 when the path carries no {index}.
PbrMaterialDefinition
The properties a "pbr" material declares. Every colour is sRGB; every factor is unitless.
Properties
alpha
readonlyalpha:number
Overall material alpha, 0 to 1.
alphaCutoff
readonlyalphaCutoff:number
The cutoff below which a "mask" material discards a fragment.
alphaMode
readonlyalphaMode:"opaque"|"mask"|"blend"
How the alpha channel is interpreted.
baseColor
readonlybaseColor:ColorLike
sRGB base colour and alpha, multiplied with the base colour texture.
doubleSided
readonlydoubleSided:boolean
Whether back faces are drawn.
emissive
readonlyemissive:ColorLike
sRGB emissive colour.
environmentIntensity
readonlyenvironmentIntensity:number
How strongly the environment map contributes.
kind
readonlykind:"pbr"
The family discriminator.
metallic
readonlymetallic:number
Metallic factor, 0 to 1.
name
readonlyname:string
A human-readable name; glTF material overrides match on it.
normalScale
readonlynormalScale:number
Normal map strength.
occlusionStrength
readonlyocclusionStrength:number
How strongly ambient occlusion darkens the surface, 0 to 1.
roughness
readonlyroughness:number
Roughness factor, 0 to 1.
textures
readonlytextures:Readonly<Record<string,string>>
The addresses of the textures the material samples, by slot; absent slots are unset.
unlit
readonlyunlit:boolean
Whether lighting is skipped entirely.
Physics2DErrorOptions
Options accepted by physics2DError.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
Physics2DMaterialValues
A surface, either as the physics2d.defaultMaterial setting or inline on a collider.
Properties
friction
readonlyfriction:number
The friction coefficient.
restitution
readonlyrestitution:number
How much of the approach speed is returned, 0 to 1.
Physics2DOptions
What physics2d() accepts.
Properties
initialize?
readonlyoptionalinitialize?: () =>Promise<void>
Replaces the step that instantiates Rapier's WebAssembly module. The default awaits
RAPIER.init(), which decodes the base64 payload the -compat build inlines; a host that has
already preloaded the module, or a test that wants to observe the failure path, supplies its
own.
Returns
Promise<void>
Physics2DRapierHandles
The Rapier objects the 2D physics extension owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
world
readonlyworld:World
Rapier's World.
Physics2DSettings
The resolved physics2d settings section.
Example
// ignifx.config.ts
export default {
layers: { layers: ["Default", "Player", "Enemy"] },
physics2d: {
gravity: { x: 0, y: -9.81 },
collisionMatrix: { Player: ["Default", "Enemy"], Enemy: ["Default"] },
},
};Properties
collisionMatrix
readonlycollisionMatrix:Readonly<Record<string, readonlystring[]>>
Which layers each layer collides with. A layer the map does not mention collides with everything, which is what makes the default project need no matrix at all.
defaultMaterial
readonlydefaultMaterial:Physics2DMaterialValues
The surface a collider with no material of its own uses.
gravity
readonlygravity:Vec2Like
World gravity in metres per second squared; +Y is up (11-2d-toolkit.md §3).
interpolation
readonlyinterpolation:boolean
Whether dynamic bodies and character controllers interpolate between fixed steps.
velocityIterations
readonlyvelocityIterations:number
How many iterations Rapier's constraint solver runs; 0 leaves Rapier's own default (4).
PhysicsDebugViewer
The wireframe overlay @ignifx/devtools toggles (09-physics.md §9).
Properties
enabled
enabled:
boolean
Whether Lite's physics viewer is drawing the bodies into the render scene. It needs a GPU device, so switching it on in a headless app is a no-op that logs a warning.
PhysicsErrorOptions
Options accepted by physicsError: the same subset of IgnifxErrorOptions this package
uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
PhysicsLiteHandles
The Babylon Lite objects the physics extension owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
simulationScene
readonlysimulationScene:SceneContext
The null-engine scene the world is stepped on; also world.lite.simulationScene.
world
readonlyworld:PhysicsWorld
Lite's Havok world handle.
PhysicsMaterialValues
A surface material, either as the physics.defaultMaterial setting or inline on a collider
(09-physics.md §2.2, §2.4).
Properties
friction
readonlyfriction:number
The dynamic friction coefficient.
restitution
readonlyrestitution:number
How much of the approach speed is returned, 0 to 1.
staticFriction
readonlystaticFriction:number
The static friction coefficient.
PhysicsOptions
What physics() accepts.
Properties
collisionIdentities?
readonlyoptionalcollisionIdentities?:"upstream"|"internal"
How collision callbacks learn which bodies took part (ADR-0013). "upstream" is the default and
delivers contacts with other === null, because @babylonjs/[email protected] reports no identities;
"internal" opts into the waived adapter-internal drain that recovers them.
havok?
readonlyoptionalhavok?:unknown
An already-instantiated Havok module, which skips loading entirely.
wasmBinary?
readonlyoptionalwasmBinary?:ArrayBuffer
The HavokPhysics.wasm bytes, for a host that reads them itself.
PhysicsSettings
The resolved physics settings section.
Example
// ignifx.config.ts
export default {
layers: { layers: ["Default", "Player", "Enemy"] },
physics: {
gravity: { x: 0, y: -9.81, z: 0 },
collisionMatrix: { Player: ["Default", "Enemy"], Enemy: ["Default"] },
},
};Properties
collisionMatrix
readonlycollisionMatrix:Readonly<Record<string, readonlystring[]>>
Which layers each layer collides with. A layer the map does not mention collides with everything, which is what makes the default project need no matrix at all.
defaultMaterial
readonlydefaultMaterial:PhysicsMaterialValues
The material a collider with no material of its own uses.
gravity
readonlygravity:Vec3Like
World gravity in metres per second squared.
havokWasm
readonlyhavokWasm:string
"auto" to resolve HavokPhysics.wasm through the asset manifest, or an explicit URL.
interpolation
readonlyinterpolation:boolean
Whether dynamic bodies and character controllers interpolate between fixed steps.
velocityLimits
readonlyvelocityLimits:VelocityLimitSettings
The world speed clamps.
PlaneMeshOptions
How MeshAsset.plane sizes its quad, which lies in the XY plane facing -Z.
Properties
height?
readonlyoptionalheight?:number
Height, overriding size.
size?
readonlyoptionalsize?:number
Edge length on both axes, in metres.
width?
readonlyoptionalwidth?:number
Width, overriding size.
PlatformInfo
What the kernel knows about the host, reached as app.platform.
Example
if (app.platform.isMobile) {
app.renderer.resolutionScale = 0.75;
}
if (app.platform.reducedMotion) {
disableScreenShake();
}Properties
hasGamepads
readonlyhasGamepads:boolean
true when the host implements the Gamepad API.
hasPointerLock
readonlyhasPointerLock:boolean
true when the host implements the Pointer Lock API.
isMobile
readonlyisMobile:boolean
true on a phone or a tablet.
kind
readonlykind:PlatformKind
Whether the app runs in a document, in an Electron renderer, or in a bare JavaScript runtime.
locale
readonlylocale:string
The host's BCP 47 language tag, "en-AU". Never empty.
os
readonlyos:PlatformOs
The operating system, or "unknown" when the host does not say.
reducedMotion
readonlyreducedMotion:boolean
true when the user asked their system for reduced motion.
webgpu
readonlywebgpu:WebGpuInfo|null
What WebGPU offers, or null in a headless app and on a host with no WebGPU.
PlayClipOptions
What SpriteAnimator.play accepts.
Properties
restart?
readonlyoptionalrestart?:boolean
Whether to rewind a clip that is already playing. Defaults to false.
PlayOptions
The per-play overrides a game passes to play() (docs/architecture/10-audio.md §3).
Extended by
Properties
delay?
readonlyoptionaldelay?:number
How long to wait before it starts, in seconds.
duration?
readonlyoptionalduration?:number
How long to play for, in seconds; 0 plays to the end of the clip.
loop?
readonlyoptionalloop?:boolean
Whether this play loops; defaults to the source's loop.
pitch?
readonlyoptionalpitch?:number
Playback rate for this play; defaults to the source's pitch.
startOffset?
readonlyoptionalstartOffset?:number
Where in the clip to start, in seconds.
volume?
readonlyoptionalvolume?:number
Linear gain for this play; defaults to the source's volume.
PlayStateOptions
What AnimatorStateMachine.play accepts.
Properties
layer?
readonlyoptionallayer?:string
Which layer to play on; the base layer when omitted.
transitionSeconds?
readonlyoptionaltransitionSeconds?:number
How long to crossfade for, in seconds. 0 — the default — cuts.
PluralNode
A {name, plural, …} selection.
Properties
branches
readonlybranches:ReadonlyMap<string, readonlyMessageNode[]>
The branches, keyed by "=0"-style exact matches and by plural category.
kind
readonlykind:"plural"
The discriminator.
name
readonlyname:string
The parameter name holding the number.
PointerLockSettings
The pointer-lock half of the input section.
Properties
allowed
readonlyallowed:boolean
Whether app.input.pointerLock.request() is allowed to ask the browser. Defaults to true.
Processor
One parsed processor: its kind and its two numeric parameters, already defaulted.
Properties
first
readonlyfirst:number
The first parameter: min for deadzone and clamp, x for scale.
kind
readonlykind:ProcessorKind
Which processor this is.
second
readonlysecond:number
The second parameter: max for deadzone and clamp, y for scale.
ProfileScope
A timing scope opened by Diagnostics.profile. Ending it twice is a no-op.
Remarks
Scopes are pooled per nesting depth, so opening one allocates nothing after the first frame, and
outside development builds profile returns a shared scope that does nothing at all.
Properties
durationMs
readonlydurationMs:number
How long the scope was open, in milliseconds of the diagnostics clock. Valid between
ProfileScope.end and the next Diagnostics.profile call at the same nesting
depth, because scopes are pooled. Always 0 outside development builds.
Methods
end()
end():
void
Closes the scope and, in development, records a performance.measure entry.
Returns
void
QuatLike
The structural shape of a quaternion.
Properties
w
readonlyw:number
The scalar part.
x
readonlyx:number
The x component of the vector part.
y
readonlyy:number
The y component of the vector part.
z
readonlyz:number
The z component of the vector part.
QueryOptions
Options every query accepts.
Properties
hitTriggers?
readonlyoptionalhitTriggers?:boolean
Whether trigger volumes count as hits. Defaults to false.
layerMask?
readonlyoptionallayerMask?:LayerMask
Which layers the query may hit. Defaults to everything.
QueryOptions2D
Options every 2D query accepts.
Properties
hitTriggers?
readonlyoptionalhitTriggers?:boolean
Whether trigger volumes count as hits. Defaults to false.
layerMask?
readonlyoptionallayerMask?:LayerMask
Which layers the query may hit. Defaults to everything.
RandomSource
Where generateUlid gets its randomness. Injecting it is what lets a test replay a scene
with the same uids every run (CONSTITUTION.md §2.1) without ignifx depending on a random
library (coding standards §13).
Methods
fillBytes()
fillBytes(
bytes):void
Fills every byte of the buffer with new random values.
Parameters
bytes
Uint8Array<ArrayBuffer>
The buffer to overwrite in place. The buffer is a plain ArrayBuffer view;
crypto.getRandomValues refuses shared memory, so the type says so.
Returns
void
Remarks
Named fillBytes rather than fill so that call sites are not mistaken for Array.prototype.fill
by the linter's reference-value rule.
Ray
A world-space ray, as Camera.screenToRay produces and world.raycastRender consumes
(docs/architecture/07-rendering.md §3).
Remarks
Both vectors are written in place, so a picking loop reuses one ray and allocates nothing (coding standards §7).
Properties
direction
readonlydirection:RayVector
The unit direction it travels in.
length
length:
number
How far it reaches, in metres.
origin
readonlyorigin:RayVector
Where the ray starts, in world space.
RaycastHit
What a ray hit.
Remarks
The object is freshly allocated per hit, so it is safe to keep. Queries are not a per-frame path for most games; a game that raycasts every frame should hoist the result and reuse the vectors it copies out of it.
Properties
collider
readonlycollider:Collider|null
The collider on that entity, or null when the entity has none registered any more.
distance
readonlydistance:number
The distance from the ray origin, in metres.
entity
readonlyentity:Entity
The entity that was hit.
normal
readonlynormal:Vec3Like
The world-space surface normal.
point
readonlypoint:Vec3Like
The world-space contact point.
triangleIndex
readonlytriangleIndex:number
The triangle index on a MeshCollider, or -1 for a primitive.
RaycastHit2D
What a 2D ray or shape query hit.
Remarks
The object is freshly allocated per hit, so it is safe to keep. raycastAll returns a reused
array of freshly allocated hits.
Properties
collider
readonlycollider:Collider2D|null
The collider that was hit.
distance
readonlydistance:number
The distance from the ray origin, in metres.
entity
readonlyentity:Entity
The entity that was hit.
normal
readonlynormal:Vec2Like
The world-space surface normal.
point
readonlypoint:Vec2Like
The world-space contact point, in metres.
RayVector
A writable { x, y, z } a ray's origin and direction are stated in.
Remarks
Deliberately the minimal shape rather than the math module's MutableVec3: the engine's Vec3,
a plain object literal, and a live view over a Lite node all satisfy it, so nothing has to be
converted to build or read a ray.
Properties
x
x:
number
The x component.
y
y:
number
The y component.
z
z:
number
The z component.
RecordFieldSpec
Kind-specific data for record.
Properties
fields
readonlyfields:Schema
The sub-fields, in declaration order.
kind
readonlykind:"record"
The record kind.
ReferenceDecoder
How the loader turns a uid read from a file back into a live entity or component.
Methods
asset()
asset(
address,type):unknown
Resolves an asset address to the loaded handle an asset() field should hold
(docs/architecture/05-assets-and-loading.md §3).
Parameters
address
string
The address the file carries, fragment included.
type
string | null
The asset type the field or the file declared, or null when the address's
extension identifies it on its own.
Returns
unknown
The handle, or null when nothing loaded stands at that address.
Remarks
The scene loader answers from the dependency handles the SceneAsset already retains, so the
field never starts a load of its own and never owns a reference count. A resolver that returns
null — an address nothing loaded — makes the field null and adds an IGX-0602 issue.
component()
component(
uid):unknown
Looks up a component by its file-local uid.
Parameters
uid
string
The uid read from the file.
Returns
unknown
The component, or null when the uid is unknown.
entity()
entity(
uid):unknown
Looks up an entity by its file-local uid.
Parameters
uid
string
The uid read from the file.
Returns
unknown
The entity, or null when the uid is unknown.
ReferenceEncoder
How the serializer turns a live entity or component reference into the uid written to a file. Reference kinds cannot be encoded without a world, so the kernel implements this and tests pass a fake.
Methods
componentUid()
componentUid(
value):string|null
Resolves a component reference to its file-local uid.
Parameters
value
unknown
The component the field points at.
Returns
string | null
The uid, or null when the target is not part of the file being written.
entityUid()
entityUid(
value):string|null
Resolves an entity reference to its file-local uid.
Parameters
value
unknown
The entity the field points at.
Returns
string | null
The uid, or null when the target is not part of the file being written.
RegisterAssetOptions
Options accepted by Assets.register.
Properties
address?
readonlyoptionaladdress?:string
The address to publish it at. Defaults to a generated memory:<type>/<ulid>; pass one only to
make an in-code asset reachable by name from app.assets.get.
type
readonlytype:string
The asset type the value is published under, for example "mesh" or "material".
RegisterComponentOptions
Options accepted by ExtensionContext.registerComponent.
Properties
typeId?
readonlyoptionaltypeId?:string
An explicit registration id, when the class does not declare one.
RegisterSystemOptions
Options accepted by ExtensionContext.registerSystem.
Properties
order?
readonlyoptionalorder?:number
Ascending order within the phase; core uses [-1000, 1000], extensions [1001, 9999].
phase
readonlyphase:Phase
Which phase the system runs in.
RenderCapture
A captured frame (docs/architecture/07-rendering.md §5).
Remarks
Tightly packed RGBA8, four bytes per pixel, row-major with the top row first — the layout
ImageData wants. Alpha is forced to 255 because the swapchain is presented opaque, and the
values are the final presented 8-bit colours, so comparing two captures compares what the player
saw.
Properties
data
readonlydata:Uint8ClampedArray
width * height * 4 bytes of RGBA8.
height
readonlyheight:number
The capture height, in device pixels.
width
readonlywidth:number
The capture width, in device pixels.
Renderer
The rendering service, reached as app.renderer
(docs/architecture/07-rendering.md §1, §3, §5).
Example
app.renderer.resolutionScale = 0.75;
const hit = await app.renderer.pickAsync(event.offsetX, event.offsetY);
hit?.entity.name;Properties
drawCalls
readonlydrawCalls:number
GPU draw calls in the last rendered frame. 0 under a headless app.
features
readonlyfeatures:Readonly<RenderingFeatureSettings>
Which rendering features are on. Read-only once app.start() has registered the scene.
gpuFrameTimeMs
readonlygpuFrameTimeMs:number
How long the last measured frame took on the GPU, in milliseconds. 0 until timing is on.
pixelRatio
pixelRatio:
number
The clamp on the device pixel ratio the swapchain is sized at; 0 does not clamp. Writing it
resizes the backing store before the next frame.
profileTasks
profileTasks:
boolean
Whether per-task GPU timings are collected. Off by default; it costs timestamp queries.
resolutionScale
resolutionScale:
number
A live quality multiplier on the resolution, clamped to 0.25–1 and implemented by lowering the
effective device pixel ratio (docs/architecture/07-rendering.md §1).
surface
readonlysurface:RenderSurface|null
The canvas the app draws into, or null under a headless app.
Remarks
An extension that adds a second rendering context — @ignifx/2d's sprite renderer — creates it
on this surface and registers it after the render scene (07-rendering.md §1).
Methods
captureScreenshot()
captureScreenshot():
Promise<RenderCapture>
Captures the next presented frame (docs/architecture/07-rendering.md §5).
Returns
Promise<RenderCapture>
The frame, as tightly packed RGBA8 with the top row first.
Throws
IgnifxError with code IGX-0707 when no render loop is running, because the capture
would never settle.
pickAsync()
pickAsync(
x,y,options?):Promise<RenderPick|null>
Picks the object under one pixel of the canvas, exactly, on the GPU
(docs/architecture/07-rendering.md §3).
Parameters
x
number
The backing-store pixel x, from the canvas's left edge.
y
number
The backing-store pixel y, from the canvas's top edge.
options?
An entity filter.
Returns
Promise<RenderPick | null>
What was hit, or null for a miss.
Remarks
Coordinates are backing-store pixels — the canvas's width/height, the space
Camera.worldToScreen answers in — not CSS pixels; multiply a DOM event's offsetX/offsetY
by devicePixelRatio first. Picks are serialised per app: Lite's picker owns one set of staging
buffers and chains each call onto the previous one's promise. A headless app has no picker and
always misses.
requireFeature()
requireFeature(
feature):void
Declares that a rendering feature must be on — what an extension calls from register
(docs/architecture/07-rendering.md §1.1).
Parameters
feature
keyof RenderingFeatureSettings
The feature the caller needs.
Returns
void
Throws
IgnifxError with code IGX-0704 when the render scene has already been registered, at
which point Lite has compiled what it is going to compile.
setSize()
setSize(
width,height):void
Sets the swapchain's backing-store size explicitly, in device pixels — the OffscreenCanvas
path (docs/architecture/07-rendering.md §1).
Parameters
width
number
The width, in device pixels.
height
number
The height, in device pixels.
Returns
void
Remarks
On a laid-out DOM canvas the size survives exactly one frame: Lite's render loop re-reads the layout size at the start of every frame. Use Renderer.pixelRatio there instead.
taskTimings()
taskTimings():
RenderTaskTimings
The latest per-task GPU timing snapshot. Check status before reading tasks.
Returns
The snapshot.
warmUp()
warmUp(
materials):void
Compiles the material families of the given materials now, so a mesh that uses one of them later draws on the next frame instead of several frames after that (ADR-0014).
Parameters
materials
readonly MaterialAsset[]
The materials whose families must be compiled.
Returns
void
Remarks
app.start() already does this for every material in the boot preload group. Call it by hand
for a spawn-heavy game that loads a material mid-level and wants to pay the cost at a moment of
its choosing.
RenderingFeatureSettings
The rendering features a project switches on (docs/architecture/07-rendering.md §1.1). Every one
of them changes what Lite compiles at registerScene, so they are declared up front and a late
toggle is IGX-0704.
Properties
asyncPipelines
readonlyasyncPipelines:boolean
Compile shader pipelines asynchronously instead of blocking the first draw.
boneControl
readonlyboneControl:boolean
Build the glTF loader's skeleton handles, needed before loading a skinned asset.
deviceLostRecovery
readonlydeviceLostRecovery:boolean
Rebuild scenes and their resources after the WebGPU device is lost.
lightmaps
readonlylightmaps:boolean
Load the PBR lightmap fragment extension.
materialPlugins
readonlymaterialPlugins:boolean
Install the material plugin bridges and the scene hook they need.
postProcessing
readonlypostProcessing:boolean
Render the scene into an offscreen target and composite it, so a PostProcessStack has
something it is allowed to sample. Off by default: it costs one full-screen blit per frame.
shadows
readonlyshadows:boolean
Register the scene with a shadow pass, so a Light can cast.
skeletons
readonlyskeletons:boolean
Compile the Standard pipeline's skinning fragment, for skinned meshes.
stencil
readonlystencil:boolean
Install stencil resolvers on the PBR, Standard, and Shader pipelines.
RenderingSettings
The resolved rendering settings section
(docs/architecture/04-extensions.md §5, 07-rendering.md §1).
Example
const app = await createApp({
canvas,
settings: { rendering: { features: { shadows: true }, msaaSamples: 1 } },
});Properties
alphaMode
readonlyalphaMode:"opaque"|"premultiplied"
How the canvas composites with the page. "premultiplied" lets HTML show through.
brdfLut
readonlybrdfLut:string
The address of the RGBD BRDF lookup table loadEnvironment requires.
clearColor
readonlyclearColor:ColorLike
The colour the scene is cleared to each frame, in sRGB.
Remarks
Applied to the render scene as it is created, which makes it the floor of a three-step
precedence (docs/architecture/07-rendering.md §2.1, §2.5): Camera.clearColor on the main
camera wins whenever it is not null, an Environment.clearColor wins over this setting, and
this setting wins over Babylon Lite's own mid grey.
features
readonlyfeatures:RenderingFeatureSettings
The feature opt-ins, applied during app.start() before the scene is registered.
format
readonlyformat:string
An explicit swapchain texture format; empty means Lite's own choice. Never an *-srgb one.
maxDevicePixelRatio
readonlymaxDevicePixelRatio:number
Clamp on the device pixel ratio the swapchain is sized at. 0 means "do not clamp".
msaaSamples
readonlymsaaSamples:number
MSAA sample count for the main pass. WebGPU allows 1 or 4; anything else is read as 4.
requiredLimits
readonlyrequiredLimits:Readonly<Record<string,number>>
Extra WebGPU device limits to request, such as a larger maxColorAttachmentBytesPerSample.
srgb
readonlysrgb:boolean
Render through an sRGB swapchain view so alpha blending is gamma-correct.
useFloatingOrigin
readonlyuseFloatingOrigin:boolean
Eye-relative upload for large-world coordinates. Requires useHighPrecisionMatrix.
useHighPrecisionMatrix
readonlyuseHighPrecisionMatrix:boolean
Float64 intermediate precision for world matrices, for large worlds.
RenderPick
What a GPU pick found (docs/architecture/07-rendering.md §3).
Properties
component
readonlycomponent:Component|null
The component that created the mesh, when it was not the entity's own transform.
distance
readonlydistance:number
How far along the ray the hit is, in metres.
entity
readonlyentity:Entity
The entity that owns the mesh the ray hit.
normal
readonlynormal: readonly [number,number,number] |null
The world-space surface normal, or null unless detailed picking is on.
point
readonlypoint: readonly [number,number,number] |null
The world-space hit point, or null unless detailed picking is on.
RenderPickOptions
How a GPU pick is restricted (docs/architecture/07-rendering.md §3).
Properties
filter?
readonlyoptionalfilter?: (entity) =>boolean
Restricts the pick to the entities this accepts. A rejected entity neither occludes nor returns, which is what makes a "pick only the pickups" query exact rather than approximate.
Parameters
entity
The candidate.
Returns
boolean
true to consider the entity.
RenderTaskTiming
One frame-graph task's measured GPU time (docs/architecture/07-rendering.md §5).
Properties
durationMs
readonlydurationMs:number
How long the task took on the GPU, in milliseconds.
name
readonlyname:string
The task's name in the frame graph: "shadow", "scene", or a post-process task's own.
RenderTaskTimings
A per-task GPU timing snapshot (docs/architecture/07-rendering.md §5).
Properties
status
readonlystatus:string
Whether the numbers mean anything: "unsupported" on a device with no timestamp queries — the
CI software adapter is one — "disabled" until profileTasks is on, "pending" until the
first readback lands, "error" when it failed, "ok" otherwise.
tasks
readonlytasks: readonlyRenderTaskTiming[]
The tasks, in frame execution order. Empty unless status is "ok".
Rigidbody2DRapierHandles
The Rapier objects a Rigidbody2D owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
body
readonlybody:RigidBody|null
The Rapier body, or null before the first fixed step has built it.
RigidbodyLiteHandles
The Babylon Lite objects a Rigidbody owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
body
readonlybody:PhysicsBody|null
The Havok body, or null before the first fixed step has built it.
SceneAsset
What the scene loader produces for a *.scene.json or *.prefab.json address: the parsed file,
every asset it pulled in, and the content hash instance overrides are recorded against
(docs/architecture/05-assets-and-loading.md §2, 06-serialization-and-scene-format.md §2).
Remarks
The handles are already loaded and retained by the asset. That is what lets
world.instantiate(sceneAsset) be synchronous: everything the file references — textures,
materials, and the scene assets its instance entries name — is in memory by the time the
SceneAsset exists (02-scene-graph.md §2).
Properties
address
readonlyaddress:string
The address the asset was loaded from.
dependencies
readonlydependencies: readonlyAssetHandle<unknown>[]
Every asset the file references, already loaded, in resolution order.
file
readonlyfile:SceneFile
The parsed, validated file.
hash
readonlyhash:string
The content hash of SceneAsset.file, as sha256:<hex>.
SceneBuildResult
What instantiateScene produced.
Properties
issues
readonlyissues: readonlySceneLoadIssue[]
Every recoverable problem, in discovery order.
remap
readonlyremap:UidRemap
The file-local uid to runtime object table (docs/architecture/02-scene-graph.md §10).
roots
readonlyroots: readonlyEntity[]
The entities that ended up parentless within the built subtree, in file order.
SceneFile
A whole scene or prefab file (docs/architecture/06-serialization-and-scene-format.md §2).
Example
const file = serializeScene(world.activeScene);
await app.storage.write("save.scene.json", stringifySceneFile(file));Properties
engineVersion?
readonlyoptionalengineVersion?:string
The @ignifx/core version that wrote the file; informational.
entities
readonlyentities: readonlySceneFileEntity[]
Every entity, in tree order.
format
readonlyformat:string
Always SCENE_FILE_FORMAT.
formatVersion
readonlyformatVersion:number
Always SCENE_FORMAT_VERSION for files this build writes.
name
readonlyname:string
The scene's name.
settings?
readonlyoptionalsettings?:JsonObject
Scene-level values interpreted by systems (environment, clear colour, physics overrides).
SceneFileAssetRef
A serialized asset reference: { "$asset": "<address>", "type"?: "<type>" }
(docs/architecture/06-serialization-and-scene-format.md §3).
Properties
$asset
readonly$asset:string
The address the asset is registered under.
type?
readonlyoptionaltype?:string
The asset type name, written only when the address extension does not identify it.
SceneFileComponent
One component of one entity.
Properties
enabled?
readonlyoptionalenabled?:boolean
Omitted when true, the default.
props?
readonlyoptionalprops?:JsonObject
Values in the component schema's declaration order (§3).
schemaVersion?
readonlyoptionalschemaVersion?:number
Written only when the class's schemaVersion differs from 1 (§7).
type
readonlytype:string
The component class's registered typeId.
uid
readonlyuid:string
ULID, unique within the file.
SceneFileEntity
One entity of a scene file. Entities appear in tree order — parents before children, siblings in
children order — and parent names the uid of the parent, or null for a root.
Properties
active?
readonlyoptionalactive?:boolean
Omitted when true, the default.
components?
readonlyoptionalcomponents?: readonlySceneFileComponent[]
The entity's own components; on an instance root, the ones added on top of the instance.
instance?
readonlyoptionalinstance?:SceneFileInstance
Present only on instance roots.
layer?
readonlyoptionallayer?:string
The layer name, omitted when "Default". Names, never indices, so reordering is safe.
name
readonlyname:string
The display name.
parent
readonlyparent:string|null
The parent's uid, or null for a root.
static?
readonlyoptionalstatic?:boolean
Omitted when false, the default.
tags?
readonlyoptionaltags?: readonlystring[]
The tags, omitted when empty.
transform
readonlytransform:SceneFileTransform
Always present.
uid
readonlyuid:string
ULID, unique within the file.
SceneFileInstance
The instance entry that turns an entity into the root of an instanced scene — what other
engines call a prefab instance (ADR-0005).
Properties
hash?
readonlyoptionalhash?:string
The content hash of that asset at save time; a mismatch reports IGX-0604.
overrides?
readonlyoptionaloverrides?: readonlySceneFileOverride[]
The patches applied to the instanced entities, in order.
scene
readonlyscene:SceneFileAssetRef
The scene asset to instance.
SceneFileIssue
One structural problem in a scene file.
Properties
message
readonlymessage:string
An actionable description.
path
readonlypath:string
Where the problem is, in JSON-pointer-like notation, for example entities/3/transform.
SceneFileOverride
One override patch applied to an instanced scene, addressed by the instanced file's uids
(docs/architecture/06-serialization-and-scene-format.md §2).
Remarks
op defaults to "replace", which is why the common case is the two-key
{ path, value } object shown in the format document.
Properties
op?
readonlyoptionalop?:"replace"|"remove"|"add"
"replace" (the default) patches a value, "remove" deletes a component, "add" appends one.
path
readonlypath:string
The path into the instanced file; see parseOverridePath.
value?
readonlyoptionalvalue?:JsonValue
The new value, for "replace" and "add".
SceneFileTransform
An entity's local transform, always present in the file and always three plain number arrays
(docs/architecture/06-serialization-and-scene-format.md §2).
Remarks
The values are local — relative to parent — because the file already stores the tree and
local values are the ones that survive a parent being moved. The document says only "arrays
[x, y, z], [x, y, z, w], [x, y, z]"; this is the reading that round trips.
Properties
position
readonlyposition: readonly [number,number,number]
Local position, [x, y, z], in metres.
rotation
readonlyrotation: readonly [number,number,number,number]
Local rotation quaternion, [x, y, z, w].
scale
readonlyscale: readonly [number,number,number]
Local scale, [x, y, z].
SceneLoaderOptions
Options accepted by createSceneLoader.
Properties
validate?
readonlyoptionalvalidate?:boolean
true (the default) validates every file against the scene format before building anything,
reporting IGX-0608 with the issue list. Production builds may switch it off once the content
has been validated at build time by the Vite plugin
(docs/architecture/06-serialization-and-scene-format.md §8).
SceneLoadIssue
One recoverable problem found while a scene was being built. Nothing here stops the load: a file
degrades one field, one reference, or one layer rather than failing whole
(docs/architecture/06-serialization-and-scene-format.md §4).
Properties
code
readonlycode:string
The diagnostic code, for example IGX-0602 or IGX-0303.
message
readonlymessage:string
The actionable sentence.
SchemaDescription
One component schema as the documentation harness sees it. pnpm docs:schemas reads a record of
these, keyed by component typeId, from each built package's schemas export and turns it into
references/formats/<format>.md and ignifx.schemas.json.
Properties
description?
readonlyoptionaldescription?:string
A one-line summary of what the component does.
fields
readonlyfields:Readonly<Record<string,SchemaFieldDescription>>
Every declared field, in declaration order.
format
readonlyformat:string
The format page the entry is grouped onto; components unless overridden.
title
readonlytitle:string
The human-readable name, by default the last segment of the type id.
SchemaDescriptionMeta
Optional overrides for describeSchema.
Properties
description?
readonlyoptionaldescription?:string
A one-line summary of what the component does.
format?
readonlyoptionalformat?:string
Overrides the default components grouping.
title?
readonlyoptionaltitle?:string
Overrides the title derived from the type id.
SchemaFieldDescription
One field as the documentation harness sees it (scripts/README.md, "Schema discovery
convention").
Properties
default?
readonlyoptionaldefault?:JsonValue
The field's default value, already encoded as JSON.
description?
readonlyoptionaldescription?:string
The field's tooltip, when it declares one.
kind
readonlykind:FieldKind
The field kind, for example f32 or asset.
SchemaIssue
One problem found while validating, encoding, or decoding a schema value. Issues are plain data:
this module never throws for bad values, it reports them, and the caller decides whether that
is a development-time throw or a logged diagnostic (CONSTITUTION.md §3.9).
Properties
code
readonlycode:SchemaIssueCode
The stable IGX-#### code for the problem.
message
readonlymessage:string
An actionable description of what went wrong.
path
readonlypath:string
Where the problem is, in dotted/bracketed property notation, for example waypoints[2].x.
ScriptCallbacks
Every callback a script may implement, with the signature the engine calls it with
(docs/architecture/01-lifecycle-and-time.md §4). All of them are optional; implement only the
ones the script needs.
Remarks
The interface is deliberately not merged into Script — see the note there. Adding
implements ScriptCallbacks to a script is free at run time and checks that every callback the
class does implement has the right name and signature.
Example
class Door extends Script implements ScriptCallbacks {
awake(): void {
this.body = this.requireComponent(Rigidbody);
}
fixedUpdate(dt: number): void {
this.body.move(dt);
}
}Methods
awake()?
optionalawake():void
Runs once, the first time the script becomes effectively enabled inside a loaded world. During
a scene load it runs after every entity and component of that scene instance exists, in tree
order, with entityRef/componentRef fields already resolved.
Returns
void
fixedUpdate()?
optionalfixedUpdate(dt):void
Runs once per fixed step, before physics.
Parameters
dt
number
The fixed step in seconds; always time.fixedDeltaTime.
Returns
void
lateUpdate()?
optionallateUpdate(dt):void
Runs once per frame, after animation has posed the scene.
Parameters
dt
number
Scaled seconds since the previous frame.
Returns
void
onApplicationFocus()?
optionalonApplicationFocus(focused):void
Runs on window focus changes.
Parameters
focused
boolean
true when the window just gained focus.
Returns
void
onApplicationPause()?
optionalonApplicationPause(paused):void
Runs when the document is hidden or shown, or the Electron window is minimized or restored.
Parameters
paused
boolean
true when the app just became hidden.
Returns
void
onCollisionEnter()?
optionalonCollisionEnter(collision):void
Runs when a contact begins, inside the fixed loop after the physics step.
Parameters
collision
unknown
The contact, supplied by the physics extension.
Returns
void
onCollisionExit()?
optionalonCollisionExit(collision):void
Runs when a contact ends.
Parameters
collision
unknown
The contact.
Returns
void
onCollisionStay()?
optionalonCollisionStay(collision):void
Runs while a contact persists.
Parameters
collision
unknown
The contact.
Returns
void
onDestroy()?
optionalonDestroy():void
Runs once, in the destroy flush of the frame destroy() was called in.
Returns
void
onDisable()?
optionalonDisable():void
Runs on every transition off effectively enabled, including just before destruction.
Returns
void
onEnable()?
optionalonEnable():void
Runs after awake, and on every later transition to effectively enabled.
Returns
void
onTriggerEnter()?
optionalonTriggerEnter(trigger):void
Runs when an overlap with a trigger shape begins.
Parameters
trigger
unknown
The overlap, supplied by the physics extension.
Returns
void
onTriggerExit()?
optionalonTriggerExit(trigger):void
Runs when an overlap with a trigger shape ends.
Parameters
trigger
unknown
The overlap.
Returns
void
start()?
optionalstart():void
Runs once, in the first frame the script is effectively enabled, after the fixed loop.
Returns
void
update()?
optionalupdate(dt):void
Runs once per frame.
Parameters
dt
number
Scaled seconds since the previous frame.
Returns
void
ScriptClassInfo
What the registry worked out about a script class by inspecting its prototype exactly once.
Properties
callbacks
readonlycallbacks:number
One bit per ScriptCallbackKind: set when the class implements that callback.
executionOrder
readonlyexecutionOrder:number
static executionOrder, resolved at registration.
updateWhenPaused
readonlyupdateWhenPaused:boolean
static updateWhenPaused, resolved at registration.
ScriptStatics
The static members a script class may declare: everything ComponentStatics allows plus
the two scheduling flags (docs/architecture/01-lifecycle-and-time.md §3). Structural and
optional for the reason given on ComponentStatics.
Extends
Properties
allowMultiple?
readonlyoptionalallowMultiple?:boolean
false when at most one instance may be attached to an entity; defaults to true.
Inherited from
ComponentStatics.allowMultiple
executionOrder?
readonlyoptionalexecutionOrder?:number
Lower runs first within a phase; ties break on creation order. Core systems use
[-1000, 1000]. Defaults to 0.
requires?
readonlyoptionalrequires?: readonlyComponentType<Component>[]
Component types auto-added to, and validated on, any entity this one is attached to.
Inherited from
schema?
readonlyoptionalschema?:Readonly<Record<string,FieldDefinition<unknown>>>
The serialized field declarations, set by Component.define / Script.define.
Inherited from
typeId?
readonlyoptionaltypeId?:string
The namespaced registration id (<package-or-game>/<Name>), required for any component that is
serialized (docs/architecture/03-scripting-and-components.md §4). It is explicit, never
derived from the class name, so minification and renames cannot change a file's meaning.
Inherited from
updateWhenPaused?
readonlyoptionalupdateWhenPaused?:boolean
When true, the script still receives update/lateUpdate while app.pause() is in effect.
Defaults to false.
SerializeIssue
One problem found while writing a file. Serialization is total — it always produces valid JSON —
so a problem means one value was written as null or one link was dropped, never that the save
failed (docs/architecture/06-serialization-and-scene-format.md §3).
Properties
code
readonlycode:string
The diagnostic code, for example IGX-0602.
message
readonlymessage:string
The actionable sentence.
SerializeSceneOptions
Options accepted by serializeScene.
Properties
engineVersion?
readonlyoptionalengineVersion?:string|null
Overrides the recorded engineVersion; null omits it, which is what byte-stable tests use.
flatten?
readonlyoptionalflatten?:boolean
true writes every entity of an instanced subtree as a plain entity instead of one instance
entry with computed overrides (docs/architecture/06-serialization-and-scene-format.md §5).
Flattened files no longer track the prefab and their uids are the runtime ones, which differ
per load.
name?
readonlyoptionalname?:string
Overrides the file's name; defaults to the instance's name, or "scene".
onIssue?
readonlyoptionalonIssue?: (issue) =>void
Receives every problem found, in discovery order.
Parameters
issue
Returns
void
settings?
readonlyoptionalsettings?:JsonObject|null
Overrides the file's settings block; defaults to the instance's.
ServiceNameKey
A service key created from a name, for services that are plain objects rather than classes.
Type Parameters
T
T
The service instance type. It is a compile-time marker only: serviceOf is never
assigned at runtime, and it is what makes two keys with different service types different types.
Properties
serviceName
readonlyserviceName:string
The name the key was created with, used in error messages.
serviceOf?
readonlyoptionalserviceOf?:T
Compile-time marker for the service type; never present at runtime.
ServiceRegistry
The per-app service table (docs/architecture/04-extensions.md §1). Extensions write to it
through ExtensionContext.registerService; scripts read from it.
Methods
get()
get<
T>(key):T
Looks a service up, requiring it to be present.
Type Parameters
T
T
The service instance type.
Parameters
key
ServiceKey<T>
The class or named key the service was registered under.
Returns
T
The registered instance.
Throws
IgnifxError with code IGX-0405 when no extension registered the service.
has()
has(
key):boolean
Reports whether a service is registered.
Parameters
key
ServiceKey<unknown>
The class or named key.
Returns
boolean
true when an instance is registered under the key.
tryGet()
tryGet<
T>(key):T|null
Looks a service up, tolerating its absence — the pattern for game code that must work with or without an optional extension.
Type Parameters
T
T
The service instance type.
Parameters
key
ServiceKey<T>
The class or named key the service was registered under.
Returns
T | null
The instance, or null when it is not registered.
SetParentOptions
Options accepted by Entity.setParent. Written as code rather than as a documentation link
because Entity is a class and an interface at once: an unqualified reference is ambiguous to
API Extractor, and the qualified form it asks for is unresolvable to TypeDoc.
Properties
worldPositionStays?
readonlyoptionalworldPositionStays?:boolean
true (the default) preserves the entity's world transform by rewriting its local values;
false keeps the local values, so the entity moves with the new parent
(docs/architecture/02-scene-graph.md §5.1).
ShapeCastHit
What a shape sweep hit.
Properties
collider
readonlycollider:Collider|null
The collider on that entity, or null.
distance
readonlydistance:number
The distance travelled before contact, in metres.
entity
readonlyentity:Entity|null
The entity the swept shape hit, or null when the bounds index cannot identify it.
fraction
readonlyfraction:number
How far along the sweep the contact occurs, in [0, 1].
normal
readonlynormal:Vec3Like
The world-space contact normal on the hit body.
point
readonlypoint:Vec3Like
The world-space contact point on the hit body.
ShapeCastHit2D
What a 2D shape sweep hit.
Properties
collider
readonlycollider:Collider2D|null
The collider it hit.
distance
readonlydistance:number
The distance travelled before contact, in metres.
entity
readonlyentity:Entity
The entity the swept shape hit.
fraction
readonlyfraction:number
How far along the sweep the contact occurs, in [0, 1].
normal
readonlynormal:Vec2Like
The world-space contact normal.
point
readonlypoint:Vec2Like
The world-space contact point on the hit collider.
SignalLike
The read-only half of a Signal: what a public API exposes when callers may subscribe but
must not emit, where T is the payload the signal emits.
Example
interface Assets {
readonly onLoaded: SignalLike<AssetHandle>;
}Type Parameters
T
T = void
Properties
connectionCount
readonlyconnectionCount:number
How many handlers are currently attached.
Methods
connect()
connect(
handler,options?):Disconnect
Attaches a handler.
Parameters
handler
The listener.
options?
once, deferred, and owner.
Returns
A function that detaches the handler.
SignalOptions
Options for the Signal constructor, where T is the payload the signal emits.
Type Parameters
T
T
Properties
deferredQueue?
readonlyoptionaldeferredQueue?:DeferredQueue
The scheduler used by deferred connections. Without it, deferred: true throws.
onHandlerError?
readonlyoptionalonHandlerError?: (error,signal) =>void
Where handler exceptions go. When set, every exception is reported here and delivery continues;
when absent, the first exception is rethrown as IGX-0104 once every handler has run. The app
passes a reporter that routes to app.onError. It must not throw.
Parameters
error
unknown
signal
Signal<T>
Returns
void
SignalOwner
Anything whose destruction should take its signal connections with it: an Entity, a
Component, a SceneInstance. Connecting with an owner is how scripts avoid leaking handlers,
and the ignifx/signal-connect-owner lint rule requires it inside a Script
(docs/architecture/02-scene-graph.md §8).
Properties
isDestroyed
readonlyisDestroyed:boolean
Whether the owner has already been destroyed.
onDestroyed
readonlyonDestroyed:SignalLike<unknown>
Emitted once when the owner is destroyed; the signal uses it to detach the handler.
Remarks
Typed as SignalLike rather than Signal so that an owner may expose a precisely
typed signal — Entity.onDestroyed is a Signal<Entity> per
docs/architecture/02-scene-graph.md §4. Signal carries private state, which makes it
invariant in T; the read-only interface is not, and connect is all this contract needs.
SimulatedEvent
What InputService.simulateEvent accepts: an event record with everything but type
optional.
Properties
button?
readonlyoptionalbutton?:number
The PointerEvent.button index.
code?
readonlyoptionalcode?:string
The control name a key event names, for example w — not the raw KeyboardEvent.code.
deltaX?
readonlyoptionaldeltaX?:number
The pointer movement x, or the wheel's horizontal delta.
deltaY?
readonlyoptionaldeltaY?:number
The pointer movement y, or the wheel's vertical delta.
key?
readonlyoptionalkey?:string
The layout-dependent key, or the composed text of a textinput event.
pointerId?
readonlyoptionalpointerId?:number
The PointerEvent.pointerId.
pointerType?
readonlyoptionalpointerType?:string
The PointerEvent.pointerType: mouse, pen, or touch. Defaults to mouse.
repeat?
readonlyoptionalrepeat?:boolean
Whether a key event is an auto-repeat.
type
readonlytype:InputEventType
Which kind of event to queue.
x?
readonlyoptionalx?:number
The pointer x, in CSS pixels from the canvas's left edge.
y?
readonlyoptionaly?:number
The pointer y, in CSS pixels from the canvas's top edge.
SmaaEffectSettings
The smaa record a PostProcessStack declares (docs/architecture/07-rendering.md §2.7).
Properties
cornerDetection
cornerDetection:
boolean
Whether corner patterns are attenuated.
diagonalDetection
diagonalDetection:
boolean
Whether 45-degree patterns are detected.
enabled
enabled:
boolean
Whether subpixel morphological anti-aliasing runs.
maxSearchSteps
maxSearchSteps:
number
How far the pattern search runs along an edge, in pixels.
order
order:
number
Position in the chain; lower runs first.
threshold
threshold:
number
The luma difference that counts as an edge.
SortingLayersSettings
The sortingLayers project settings section, consumed by the 2D toolkit.
Properties
sortingLayers
readonlysortingLayers: readonlystring[]
The project's sorting-layer names, back to front.
SoundInstance
A playing sound: what AudioSource.play() and app.audio.playOneShot() return
(docs/architecture/10-audio.md §1, §3).
Remarks
It names the sound, not one of its concurrent instances — see the note on this module. Two
play() calls on the same AudioSource therefore return the same object with
instanceCount === 2, and stop() stops both.
Example
const engineLoop = this.source.play({ loop: true });
engineLoop.setVolume(0.2, 0.5);
engineLoop.onEnded.connect(() => this.spawnPuff(), { owner: this });Properties
bus
readonlybus:AudioBus|null
The bus it routes into, or null when it goes straight to the engine's main bus.
clip
readonlyclip:AudioClip
The clip being played.
instanceCount
readonlyinstanceCount:number
How many instances are live, including ones queued behind the unlock.
isPaused
readonlyisPaused:boolean
true when every live instance is paused.
isPlaying
readonlyisPlaying:boolean
true while at least one instance is sounding, or waiting for the unlock.
onEnded
readonlyonEnded:SignalLike
Emitted in PreRender on the frame the last instance stops sounding, whether it ran out or was
stopped. Never emitted for a sound that is merely paused.
volume
readonlyvolume:number
The gain, where a fade in progress has reached.
Methods
pause()
pause():
void
Pauses every instance, keeping its position.
Returns
void
resume()
resume():
void
Resumes every paused instance.
Returns
void
setVolume()
setVolume(
volume,rampSeconds?):void
Fades the gain.
Parameters
volume
number
The target linear gain.
rampSeconds?
number
How long the fade takes, in frame time; 0 applies immediately.
Returns
void
stop()
stop(
fadeSeconds?):void
Stops every instance, optionally fading out first.
Parameters
fadeSeconds?
number
Seconds of frame time to fade over; 0 stops now.
Returns
void
SphereMeshOptions
How MeshAsset.sphere tessellates its sphere.
Properties
diameter?
readonlyoptionaldiameter?:number
Diameter on every axis, in metres. Lite defaults to 1.
segments?
readonlyoptionalsegments?:number
Ring count; higher is smoother. Lite defaults to 32.
SpriteAnimationDefinition
The parsed .spriteanim.json document.
Properties
atlas
readonlyatlas:string
The address of the .atlas.json the clips index into; empty uses the renderer's own atlas.
clips
readonlyclips: readonlySpriteClipDefinition[]
The clips, in declaration order; the first is the default when the component names none.
format
readonlyformat:"ignifx.spriteanimation"
Always "ignifx.spriteanimation".
formatVersion
readonlyformatVersion:number
Always 1 in this build.
SpriteAnimationEvent
A frame event: a name emitted on SpriteAnimator.onEvent when the clip reaches a frame.
Properties
frame
readonlyframe:number
The zero-based index within the clip, not within the atlas.
name
readonlyname:string
The name emitted on SpriteAnimator.onEvent.
SpriteAnimationInput
What defineSpriteAnimation accepts.
Properties
atlas?
readonlyoptionalatlas?:string
The address of the .atlas.json the clips index into.
clips
readonlyclips: readonlySpriteClipDefinition[]
The clips.
format?
readonlyoptionalformat?:string
Always "ignifx.spriteanimation" when present.
formatVersion?
readonlyoptionalformatVersion?:number
The document version.
SpriteAsset
A sprite: one frame of one atlas, which is what SpriteRenderer.sprite points at.
Remarks
A bare "2d/hero.atlas.json" address resolves to frame 0; the #frame: fragment picks another
(docs/architecture/11-2d-toolkit.md §2.2). The asset service shares the underlying atlas
between every fragment of the same address, so ten sprites off one atlas upload one texture.
Properties
atlas
readonlyatlas:SpriteAtlasAsset
The atlas the frame lives in.
frame
readonlyframe:number
The frame index.
name
readonlyname:string
The frame's name.
SpriteAtlasAssetLiteHandles
The Babylon Lite objects a SpriteAtlasAsset owns.
Properties
atlas
readonlyatlas:SpriteAtlas|null
The Lite atlas, or null under a headless app, which uploads nothing.
SpriteAtlasDefinition
The parsed .atlas.json document.
Example
const atlas = defineSpriteAtlas({
image: "2d/hero.png",
sampling: "nearest",
frames: [{ name: "idle_0", x: 0, y: 0, w: 32, h: 32, pivot: { x: 0.5, y: 1 } }],
});Properties
format
readonlyformat:"ignifx.spriteatlas"
Always "ignifx.spriteatlas".
formatVersion
readonlyformatVersion:number
Always 1 in this build.
frames
readonlyframes: readonlySpriteFrameDefinition[]
The frames, in the order they are indexed.
image
readonlyimage:string
The address of the image the frames are cut from.
premultipliedAlpha
readonlypremultipliedAlpha:boolean
Whether the image's RGB is already multiplied by its alpha. Defaults to false.
sampling
readonlysampling:"linear"|"nearest"
The min/mag filter. "nearest" is what pixel art wants. Defaults to "linear".
SpriteAtlasInput
What defineSpriteAtlas accepts: the document with every defaulted field optional.
Properties
format?
readonlyoptionalformat?:string
Always "ignifx.spriteatlas" when present.
formatVersion?
readonlyoptionalformatVersion?:number
The document version.
frames
readonlyframes: readonlySpriteFrameDefinition[]
The frames.
image
readonlyimage:string
The address of the image the frames are cut from.
premultipliedAlpha?
readonlyoptionalpremultipliedAlpha?:boolean
Whether the image is premultiplied. Defaults to false.
sampling?
readonlyoptionalsampling?:"linear"|"nearest"
The min/mag filter. Defaults to "linear".
SpriteClip
One clip, resolved against an atlas.
Properties
durationSeconds
readonlydurationSeconds:number
How long one pass through the clip takes, in seconds.
events
readonlyevents: readonlySpriteAnimationEvent[]
Events fired as the clip passes a frame.
fps
readonlyfps:number
Frames per second.
frames
readonlyframes: readonlynumber[]
The atlas frame indices, in play order.
loop
readonlyloop:boolean
Whether the clip restarts at its end.
name
readonlyname:string
The clip's name.
SpriteClipDefinition
One clip: an ordered run of atlas frames with a rate and a loop flag.
Properties
events?
readonlyoptionalevents?: readonlySpriteAnimationEvent[]
Events fired as the clip passes a frame.
fps?
readonlyoptionalfps?:number
Frames per second. Defaults to 12.
frames?
readonlyoptionalframes?: readonlystring[]
The atlas frame names, in play order. Empty when from/to name a range instead.
from?
readonlyoptionalfrom?:string
The first frame of a contiguous atlas range, when frames is absent.
loop?
readonlyoptionalloop?:boolean
Whether the clip restarts at its end. Defaults to true.
name
readonlyname:string
The clip's name, unique within the document; what SpriteAnimator.play takes.
to?
readonlyoptionalto?:string
The last frame of a contiguous atlas range, inclusive.
SpriteFrameDefinition
One frame rectangle, in image pixels with a top-left origin.
Properties
h
readonlyh:number
The height, in image pixels.
name
readonlyname:string
The frame's name, unique within the document; what #frame: addresses.
pivot?
readonlyoptionalpivot?:Vec2Json
The pivot in [0, 1] of the frame — [0, 0] top-left, [0.5, 0.5] centre, [1, 1]
bottom-right. Defaults to the centre. Written either as [x, y] or as { x, y }.
sourceSize?
readonlyoptionalsourceSize?:Vec2Json
The untrimmed source size, when the packer trimmed transparent margins. Defaults to w/h.
w
readonlyw:number
The width, in image pixels.
x
readonlyx:number
The left edge, in image pixels.
y
readonlyy:number
The top edge, in image pixels.
SpriteFrameInfo
One frame of a loaded atlas, as game code sees it.
Properties
heightPx
readonlyheightPx:number
Its drawn height, in image pixels.
index
readonlyindex:number
Its index in the atlas, which is what Lite addresses frames by.
name
readonlyname:string
The frame's name.
pivot
readonlypivot:Vec2Like
Its pivot in [0, 1] of the frame, [0, 0] top-left.
widthPx
readonlywidthPx:number
Its drawn width, in image pixels.
SpriteLayerEntry
One Lite layer and everything the registry tracks alongside it.
Properties
count
readonlycount:number
How many sprites the layer currently holds.
key
readonlykey:string
The composite key, built by spriteLayerKey.
layer
readonlylayer:Sprite2DLayer
The Lite layer.
screenSpace
readonlyscreenSpace:boolean
Whether the layer keeps the identity view instead of following the Camera2D.
sortingLayer
readonlysortingLayer:string
The sorting layer's name.
ySort
readonlyySort:boolean
Whether the layer is Y-sorted.
SpriteLayerKey
The layer key a sprite belongs to.
Remarks
Two sprites share a Lite layer exactly when all four parts match. The atlas is part of the key
because a Sprite2DLayer is bound to one atlas for its whole life (index.d.ts 11885,
readonly atlas), and the blend mode is part of it for the same reason (readonly blendMode).
Properties
atlas
readonlyatlas:SpriteAtlasAsset
The atlas every sprite in the layer draws from.
blend
readonlyblend:"opaque"|"premultiplied"|"alpha"|"additive"|"multiply"
The blend mode.
screenSpace
readonlyscreenSpace:boolean
Whether the layer keeps the identity view instead of following the Camera2D.
sortingLayer
readonlysortingLayer:string
The sorting layer's name.
StandardMaterialDefinition
The properties a "standard" material declares — the cheap non-PBR path
(docs/architecture/07-rendering.md §2.6).
Properties
alpha
readonlyalpha:number
Overall material alpha, 0 to 1.
alphaCutoff
readonlyalphaCutoff:number
The cutoff below which a fragment is discarded. 0 disables the alpha test.
diffuse
readonlydiffuse:ColorLike
sRGB diffuse colour.
doubleSided
readonlydoubleSided:boolean
Whether back faces are drawn.
emissive
readonlyemissive:ColorLike
sRGB emissive colour.
kind
readonlykind:"standard"
The family discriminator.
name
readonlyname:string
A human-readable name.
specular
readonlyspecular:ColorLike
sRGB specular colour.
specularPower
readonlyspecularPower:number
Specular exponent; higher values give a tighter highlight.
textures
readonlytextures:Readonly<Record<string,string>>
The addresses of the textures the material samples, by slot.
unlit
readonlyunlit:boolean
Whether lighting is skipped entirely.
StateChange
A state change, as AnimatorStateMachine.drainStateChanges reports it.
Properties
entered
readonlyentered:boolean
Whether the state was entered or left.
layer
readonlylayer:string
The layer the change happened on.
state
readonlystate:string
The state's name.
Storage
The store reached as app.storage, and as app.storage.namespace(name).
Remarks
Values are JSON, or binary: a Blob, an ArrayBuffer, or any typed array is stored as octets
and read back as a Uint8Array. Numbers inside JSON values are canonicalized the way scene files
canonicalize them (docs/architecture/06-serialization-and-scene-format.md §2), so writing the
same state twice produces the same bytes.
Reads and writes are asynchronous on every backend, including the in-memory one, so that game code written against a test app keeps working on IndexedDB.
Example
const settings = app.storage.namespace("settings");
await settings.set("audio", { master: 0.8, music: 0.5 });
const audio = await settings.get<{ master: number; music: number }>("audio");Methods
delete()
delete(
key):Promise<void>
Removes one value.
Parameters
key
string
The key.
Returns
Promise<void>
A promise that settles once the value is gone. Deleting an absent key is a no-op.
Throws
IgnifxError with code IGX-1422 when the key is invalid, or IGX-1425 when the
backend fails.
get()
get<
T>(key):Promise<T|null>
Reads one value.
Type Parameters
T
T
What the caller declares the key holds; unchecked, as for JSON.parse.
Parameters
key
string
The key, 1–512 characters with no control characters.
Returns
Promise<T | null>
The value, or null when the key was never written.
Throws
IgnifxError with code IGX-1422 when the key is invalid, IGX-1426 when the stored
value cannot be read back, or IGX-1425 when the backend fails.
keys()
keys(
prefix?):Promise<readonlystring[]>
Lists this namespace's keys.
Parameters
prefix?
string
When given, only keys that start with this string are returned.
Returns
Promise<readonly string[]>
The keys, sorted ascending. Keys of nested namespaces are not included.
Throws
IgnifxError with code IGX-1425 when the backend fails.
namespace()
namespace(
name):Storage
Narrows to a child namespace — "saves", "settings", "input-overrides".
Parameters
name
string
1–64 characters of A–Z, a–z, 0–9, ., _, -; not . or ...
Returns
The child store, which shares this store's backend and sees none of its keys.
Throws
IgnifxError with code IGX-1421 when the name is not a legal namespace segment.
set()
set<
T>(key,value):Promise<void>
Writes one value, replacing whatever was there.
Type Parameters
T
T
The value's type.
Parameters
key
string
The key, 1–512 characters with no control characters.
value
T
A JSON value, a Blob, an ArrayBuffer, or a typed array.
Returns
Promise<void>
A promise that settles once the value is durable.
Throws
IgnifxError with code IGX-1422 when the key is invalid, IGX-1423 when the value has
no JSON form, IGX-1424 when the host is out of quota, or IGX-1425 when the backend fails.
StorageBackend
Where app.storage actually puts things (docs/architecture/14-platform-electron.md §2).
Remarks
The contract. Implementations may assume all of the following, because the Storage facade
guarantees them before every call:
namespaceis a non-empty/-joined path of segments; each segment is 1–64 characters ofA–Z,a–z,0–9,.,_, or-, and no segment is.or... A backend that maps namespaces onto a hierarchy (directories, object stores) must encode each segment so that two namespaces differing only in case cannot collide on a case-insensitive file system.keyis 1–512 characters, contains no C0 or C1 control character, and is otherwise arbitrary Unicode — including/,..,:, and characters Windows forbids in file names. Keys are opaque: a backend never interprets a key's structure, andkeys(namespace, prefix)is a plain string-prefix filter, not a path walk.- Namespaces are scopes, not prefixes:
get("saves", "a")andget("saves/coop", "a")name two different values, and neither appears in the other'skeys()listing.
Implementations must guarantee all of the following:
getresolvesnullfor an absent key — absence is not an error.setreplaces any existing value under the same(namespace, key), whatever its kind, and is atomic against a crash: a reader either sees the whole previous value or the whole new one, never a partial write.deleteon an absent key resolves without error.keysresolves the keys of one namespace, filtered byprefixwhen it is given, sorted ascending with the defaultArray.prototype.sortcomparison (UTF-16 code unit order). An unknown namespace lists as[]rather than throwing.clearremoves every key of one namespace and leaves other namespaces untouched. Clearing an unknown namespace resolves without error.- Every rejection is an
IgnifxErrorcarrying a code from the storage block:IGX-1424when the host is out of quota,IGX-1426when a stored value cannot be read back, andIGX-1425for every other backend failure, with the underlying failure ascause. Backends never reject with a rawDOMExceptionor a NodeSystemError. - Every method is safe to call concurrently. Two
setcalls on the same key may land in either order, but neither may leave the store damaged.
Example
const backend: StorageBackend = new MemoryStorageBackend();
await backend.set("saves", "slot1", { kind: "json", json: '{"level":3}' });
await backend.keys("saves"); // ["slot1"]Properties
name
readonlyname:string
A short, stable identifier for this backend — "memory", "file", "indexeddb",
"electron-file". It appears in error context so a failure names the store it came from.
Methods
clear()
clear(
namespace):Promise<void>
Removes every value of one namespace.
Parameters
namespace
string
The namespace path.
Returns
Promise<void>
A promise that settles once the namespace is empty; an unknown namespace is a no-op.
delete()
delete(
namespace,key):Promise<void>
Removes one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside that namespace.
Returns
Promise<void>
A promise that settles once the value is gone; removing an absent key is a no-op.
dispose()?
optionaldispose():void
Releases whatever the backend holds open — an IndexedDB connection, a file handle, a bridge
subscription. Called from app.dispose(). Disposing twice is a no-op, and a backend that holds
nothing may omit the method entirely.
Returns
void
get()
get(
namespace,key):Promise<StoredValue|null>
Reads one value.
Parameters
namespace
string
The namespace path.
key
string
The key inside that namespace.
Returns
Promise<StoredValue | null>
The stored value, or null when the namespace has no such key.
keys()
keys(
namespace,prefix?):Promise<readonlystring[]>
Lists the keys of one namespace.
Parameters
namespace
string
The namespace path.
prefix?
string
When given, only keys that start with this string are returned.
Returns
Promise<readonly string[]>
The matching keys, sorted ascending; [] for an unknown namespace.
set()
set(
namespace,key,value):Promise<void>
Writes one value, replacing whatever was there.
Parameters
namespace
string
The namespace path, created on demand.
key
string
The key inside that namespace.
value
The JSON text or the octets to persist.
Returns
Promise<void>
A promise that settles once the value is durable.
StringFieldSpec
Kind-specific data for str.
Properties
kind
readonlykind:"str"
The string kind.
System
Engine-level logic that runs once per phase over many components, registered by an extension
(docs/architecture/03-scripting-and-components.md §6). Systems are not attached to entities and
never call script callbacks themselves.
Example
class SpriteSyncSystem implements System {
readonly name = "sprite-sync";
update(ctx: SystemContext): void {
const sprites = ctx.world.components(SpriteRenderer);
for (let index = 0; index < sprites.length; index += 1) {
sprites[index]?.sync();
}
}
}Properties
name
readonlyname:string
A unique, human-readable name used in diagnostics and error reports.
Methods
dispose()?
optionaldispose():void
Releases resources the system owns.
Returns
void
onWorldCreated()?
optionalonWorldCreated(world):void
Called once when the world the system belongs to has been created.
Parameters
world
The new world.
Returns
void
onWorldDisposed()?
optionalonWorldDisposed(world):void
Called once when the world the system belongs to is being disposed.
Parameters
world
The world going away.
Returns
void
update()?
optionalupdate(ctx):void
Runs the system's work for one phase.
Parameters
ctx
The world, clock, phase, and delta for this invocation.
Returns
void
SystemContext
What a System is handed when its phase runs
(docs/architecture/03-scripting-and-components.md §6).
Properties
dt
readonlydt:number
Seconds elapsed: time.deltaTime, or time.fixedDeltaTime inside the fixed loop. Systems run
while the app is paused and dt is not zeroed then — only scripts are filtered by
updateWhenPaused — so a system that animates checks time.paused itself.
phase
readonlyphase:Phase
The phase currently running.
time
readonlytime:Time
The app clock.
world
readonlyworld:World
The world the system operates on.
TextMetrics
The pixel size of a laid-out block.
Properties
height
readonlyheight:number
The number of lines times the line height, in render-target pixels.
width
readonlywidth:number
The width of the longest line, in render-target pixels.
TextNode
A run of literal text.
Properties
kind
readonlykind:"text"
The discriminator.
value
readonlyvalue:string
The literal.
TextureAssetLiteHandles
The Babylon Lite objects a TextureAsset owns. Unstable escape hatch
(docs/architecture/00-overview.md §3).
Properties
texture
readonlytexture:Texture2D|null
The GPU texture, or null under a headless app.
TextureImportOptions
The import options a texture's .meta.json sidecar can declare, under its texture key
(docs/architecture/05-assets-and-loading.md §7).
Remarks
They are the sampler and decode options, not scene state: two materials that sample one address get one texture with one set of options, because the cache is keyed by address.
Example
{ "texture": { "srgb": true, "addressModeU": "clamp-to-edge" } }Properties
addressModeU
readonlyaddressModeU:string
Address mode along U.
addressModeV
readonlyaddressModeV:string
Address mode along V.
invertY
readonlyinvertY:boolean
Flip the image vertically at upload. Lite defaults to true, matching Babylon.js.
magFilter
readonlymagFilter:string
Magnification filter.
minFilter
readonlyminFilter:string
Minification filter.
mipMaps
readonlymipMaps:boolean
Generate a mip chain. Lite defaults to true.
premultiplyAlpha
readonlypremultiplyAlpha:boolean
Premultiply alpha at decode time; for atlases drawn with a premultiplied blend pipeline.
srgb
readonlysrgb:boolean
Decode to linear on sample (rgba8unorm-srgb). Base colour and emissive want it; data maps must not.
TexturePackerImportOptions
What importTexturePackerAtlas accepts alongside the document.
Properties
image?
readonlyoptionalimage?:string
The image address to write into the atlas. Defaults to the document's meta.image.
keepExtensions?
readonlyoptionalkeepExtensions?:boolean
Whether to keep the .png on frame names. Defaults to false, which strips it.
premultipliedAlpha?
readonlyoptionalpremultipliedAlpha?:boolean
Whether the image's RGB is already multiplied by its alpha. Defaults to false.
sampling?
readonlyoptionalsampling?:"linear"|"nearest"
The min/mag filter. Defaults to "linear".
ThreeDErrorOptions
Options accepted by threeDError: the same subset of IgnifxErrorOptions this package
uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?: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?
readonlyoptionalautoBakeNavMesh?:boolean
Whether a NavMeshSurface bakes itself when the world loads.
navigationSeed?
readonlyoptionalnavigationSeed?:number
The seed Recast's randomized queries start from.
navigationWasmUrl?
readonlyoptionalnavigationWasmUrl?: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
// ignifx.config.ts
export default defineConfig({
threeD: { navigationSeed: 42, navigationWasmUrl: "/recast-navigation.wasm" },
});Properties
autoBakeNavMesh
readonlyautoBakeNavMesh:boolean
Whether a NavMeshSurface bakes itself when the world loads, without being asked.
navigationSeed
readonlynavigationSeed: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
readonlynavigationWasmUrl: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.
TileAnimationFrame
One frame of an animated tile.
Properties
durationMs
readonlydurationMs:number
How long the step lasts, in milliseconds.
frame
readonlyframe:string
The atlas frame name drawn during this step.
TileChange
One tile change, as Tilemap.onTileChanged reports it.
Properties
current
readonlycurrent:number
The tile id that is there now.
layer
readonlylayer:number
The layer's index in the document.
previous
readonlyprevious:number
The tile id that was there.
x
readonlyx:number
The cell's column, with 0 at the left.
y
readonlyy:number
The cell's row, with 0 at the bottom.
TileCollisionInfo
Everything a physics backend needs to know about one tile of a tileset.
Properties
oneWay
readonlyoneWay:boolean
Whether the tile is a one-way platform (solid only when crossed from above).
properties
readonlyproperties:Readonly<Record<string,string|number|boolean>>
The tile's custom properties, carried through from the tileset or the importer.
shape
readonlyshape:TileCollisionShape
The tile's collision footprint in cell-local metres.
TileDefinition
One tile of a tileset: what it draws, what it collides with, and what it carries.
Properties
animation?
readonlyoptionalanimation?: readonlyTileAnimationFrame[]
The animation frames, when the tile animates. A single frame is treated as a static tile.
collider?
readonlyoptionalcollider?:TileColliderDefinition
The collision footprint, in cell-normalised top-left-origin units. Absent means no collider.
frame
readonlyframe:string
The atlas frame the tile draws, by name.
id
readonlyid:number
The tile's index within its tileset, zero-based; the global id is tileset.firstId + id.
properties?
readonlyoptionalproperties?:Readonly<Record<string,string|number|boolean>>
The tile's custom properties, carried through from the editor.
TiledImportOptions
How importTiledMap maps Tiled's conventions onto ignifx's.
Properties
atlasFor?
readonlyoptionalatlasFor?: (imageSource) =>string
Maps a Tiled tileset's image path onto the address of the ignifx .atlas.json that was
generated from it. Defaults to swapping the file extension for .atlas.json.
Parameters
imageSource
string
Returns
string
pixelsPerUnit?
readonlyoptionalpixelsPerUnit?:number
The pixels one world metre spans. Defaults to 100, matching twoD.pixelsPerUnit.
sortingLayer?
readonlyoptionalsortingLayer?:string
The sorting layer every tile layer lands in unless it says otherwise. Defaults to "Default".
TilemapCollisionChunk
The merged collision geometry of one chunk of a tilemap, in world-space metres relative to the tilemap entity's origin.
Remarks
Adjacent solid tiles are merged into as few polygons as possible before they reach this shape, so a solid 3x2 block of tiles arrives as a single six-vertex rectangle rather than six boxes.
Properties
chunkX
readonlychunkX:number
The chunk's column index, in chunks.
chunkY
readonlychunkY:number
The chunk's row index, in chunks.
oneWayEdges
readonlyoneWayEdges: readonly readonly [Vec2Like,Vec2Like][]
The one-way platform edges, each a [from, to] pair with solid side to the left of from → to.
polygons
readonlypolygons: readonly readonlyVec2Like[][]
The merged solid outlines, each wound counter-clockwise.
TilemapCollisionData
The whole collision surface of a Tilemap, chunked so a physics backend can rebuild only the
chunks that changed.
Remarks
version increments whenever any chunk changes; a backend that caches colliders compares it to
the version it last consumed and rebuilds when they differ. Tilemap.onCollisionChanged fires at
the same moment.
Properties
cellSize
readonlycellSize:number
The edge length of one cell, in metres.
chunks
readonlychunks: readonlyTilemapCollisionChunk[]
The chunks that carry at least one collider; empty chunks are omitted.
chunkSize
readonlychunkSize:number
The edge length of one chunk, in cells.
version
readonlyversion:number
Increments on every change to the merged geometry.
TilemapDefinition
The parsed .tilemap.json document.
Example
const map = defineTilemap({
tileWidth: 32,
width: 2,
height: 1,
tilesets: [{ name: "hero", atlas: "2d/hero.atlas.json", firstId: 1, tiles: [{ id: 0, frame: "hero_0" }] }],
layers: [{ name: "Ground", tiles: [1, 0] }],
});
map.cellSize; // 0.32 — 32 px at the default 100 pixels per unitProperties
cellSize
readonlycellSize:number
The world size of one cell, in metres — tileWidth / pixelsPerUnit.
Remarks
Collision uses this single number on both axes. A map whose tiles are not square still gets a square collision cell; that is a deliberate MVP limitation and it is why the importers warn nothing and simply record both pixel sizes above.
format
readonlyformat:"ignifx.tilemap"
Always "ignifx.tilemap".
formatVersion
readonlyformatVersion:number
Always 1 in this build.
height
readonlyheight:number
The map's height, in cells.
layers
readonlylayers: readonlyTilemapLayerDefinition[]
The tile layers, back to front: index 0 draws behind index 1.
objects
readonlyobjects: readonlyTilemapObjectDefinition[]
The objects gathered from every object layer, in document order.
properties
readonlyproperties:Readonly<Record<string,string|number|boolean>>
The map's custom properties.
tileHeight
readonlytileHeight:number
The height of one tile, in pixels.
tilesets
readonlytilesets: readonlyTilesetDefinition[]
The tilesets, sorted by ascending TilesetDefinition.firstId.
tileWidth
readonlytileWidth:number
The width of one tile, in pixels.
width
readonlywidth:number
The map's width, in cells.
TilemapInput
What defineTilemap accepts: the document with every defaulted field optional.
Properties
cellSize?
readonlyoptionalcellSize?:number
The metre size of one cell. Defaults to tileWidth / 100, the default pixels-per-unit.
format?
readonlyoptionalformat?:string
Always "ignifx.tilemap" when present.
formatVersion?
readonlyoptionalformatVersion?:number
The document version.
height
readonlyheight:number
The map's height, in cells.
layers?
readonlyoptionallayers?: readonlyTilemapLayerInput[]
The tile layers, back to front. Defaults to none.
objects?
readonlyoptionalobjects?: readonlyTilemapObjectDefinition[]
The objects. Defaults to none.
properties?
readonlyoptionalproperties?:Readonly<Record<string,string|number|boolean>>
The map's custom properties. Defaults to none.
tileHeight?
readonlyoptionaltileHeight?:number
The height of one tile, in pixels. Defaults to tileWidth.
tilesets?
readonlyoptionaltilesets?: readonlyTilesetDefinition[]
The tilesets. Defaults to none.
tileWidth
readonlytileWidth:number
The width of one tile, in pixels.
width
readonlywidth:number
The map's width, in cells.
TilemapLayerDefinition
One layer of tiles.
Remarks
tiles is always the dense, decoded array in the parsed form: width * height global tile
ids in row-major order with the top row first, which is how every editor stores a grid.
0 (EMPTY_TILE_ID) means the cell is empty. Runtime code that thinks in +Y-up cell
coordinates reads index (height - 1 - cellY) * width + cellX.
Properties
collision
readonlycollision:boolean
Whether the layer contributes collision geometry.
height
readonlyheight:number
The layer's height, in cells.
name
readonlyname:string
The layer's name, unique within the document.
opacity
readonlyopacity:number
The layer's opacity in [0, 1].
orderInLayer
readonlyorderInLayer:number
The order within the sorting layer; higher draws in front.
parallax
readonlyparallax:Vec2Like
The parallax multiplier; { x: 1, y: 1 } moves with the camera.
sortingLayer
readonlysortingLayer:string
The sorting layer the tiles draw in (docs/architecture/11-2d-toolkit.md §1).
tiles
readonlytiles: readonlynumber[]
width * height global tile ids, row-major, top row first.
width
readonlywidth:number
The layer's width, in cells.
TilemapLayerInput
What defineTilemap accepts for one layer: every defaulted field optional, and tiles
either dense or run-length encoded.
Properties
collision?
readonlyoptionalcollision?:boolean
Whether the layer collides. Defaults to false.
height?
readonlyoptionalheight?:number
The layer's height in cells. Defaults to the map's height.
name
readonlyname:string
The layer's name, unique within the document.
opacity?
readonlyoptionalopacity?:number
The opacity in [0, 1]. Defaults to 1.
orderInLayer?
readonlyoptionalorderInLayer?:number
The order within the sorting layer. Defaults to 0.
parallax?
readonlyoptionalparallax?:Vec2Like
The parallax multiplier. Defaults to { x: 1, y: 1 }.
sortingLayer?
readonlyoptionalsortingLayer?:string
The sorting layer. Defaults to "Default".
tiles
readonlytiles: readonlynumber[] |TileRleData
The tile ids, dense (row-major, top row first) or run-length encoded.
width?
readonlyoptionalwidth?:number
The layer's width in cells. Defaults to the map's width.
TilemapObjectDefinition
One object placed on the map, to be turned into an entity by a registered TileObjectFactory.
Remarks
x, y, width and height are world metres with +Y up, and x/y name the object's
bottom-left corner. Importers do the conversion out of the editor's top-left pixel space, so
nothing downstream has to know what editor the map came from.
Properties
height
readonlyheight:number
The height, in world metres.
name
readonlyname:string
The object's name, as authored; not required to be unique.
properties
readonlyproperties:Readonly<Record<string,string|number|boolean>>
The object's custom properties.
type
readonlytype:string
The object's type — what app.twoD.registerTileObjectFactory keys on.
width
readonlywidth:number
The width, in world metres.
x
readonlyx:number
The left edge, in world metres.
y
readonlyy:number
The bottom edge, in world metres, +Y up.
TileObjectContext
What a TileObjectFactory is handed.
Properties
name
readonlyname:string
The object's name, as the map wrote it.
position
readonlyposition:Vec2Like
The object's bottom-left corner, in world metres relative to the tilemap entity.
properties
readonlyproperties:Readonly<Record<string,string|number|boolean>>
The object's custom properties.
size
readonlysize:Vec2Like
The object's size, in world metres.
tilemap
readonlytilemap:Entity
The tilemap entity the object came from, so a factory can parent to it.
type
readonlytype:string
The object's type, which selected this factory.
world
readonlyworld:World
The world to create the entity in.
TileRleData
A run-length-encoded tile array, as a .tilemap.json may store it to keep sparse maps small.
Properties
rle
readonlyrle: readonlynumber[]
Flattened [count, value, count, value, …] pairs; see decodeTileRle.
TilesetDefinition
A block of tiles cut from one atlas, occupying a contiguous run of global tile ids.
Properties
atlas
readonlyatlas:string
The address of the .atlas.json the frames come from; empty for a collision-only tileset.
firstId
readonlyfirstId:number
The global id of this tileset's tile 0. Always at least 1, because 0 means empty.
name
readonlyname:string
The tileset's name, unique within the document; also the frame-name prefix.
tiles
readonlytiles: readonlyTileDefinition[]
The tiles, indexed by their local TileDefinition.id.
Time
The clock reached as app.time (docs/architecture/01-lifecycle-and-time.md §2). Every value is
in seconds unless its name ends in Ms.
Example
class Spin extends Script {
update(dt: number): void {
// `dt` is the argument, never `app.time.deltaTime`, inside a callback.
this.transform.rotate({ x: 0, y: 90 * dt, z: 0 });
}
}Properties
deltaTime
readonlydeltaTime:number
Scaled seconds since the previous frame; what update and lateUpdate receive.
fixedDeltaTime
fixedDeltaTime:
number
The size of one fixed step; what fixedUpdate receives. Defaults to 1 / 60.
fixedStepAlpha
readonlyfixedStepAlpha:number
accumulator / fixedDeltaTime after the fixed loop, in [0, 1); the interpolation alpha.
fixedTime
readonlyfixedTime:number
Scaled seconds advanced by fixed steps so far.
frameCount
readonlyframeCount:number
How many frames have started. Starts at 0.
inFixedStep
readonlyinFixedStep:boolean
true while fixedUpdate and physics run.
maximumDeltaTime
maximumDeltaTime:
number
Upper clamp on one frame's delta, in seconds. Defaults to 0.1.
paused
paused:
boolean
When true, fixed steps stop and only updateWhenPaused scripts receive update.
realtimeSinceStartup
readonlyrealtimeSinceStartup:number
Wall-clock seconds since the app was created, unaffected by pause or time scale.
time
readonlytime:number
Scaled seconds since app.start().
timeScale
timeScale:
number
Multiplier applied to Time.unscaledDeltaTime; 0 freezes scaled time. Defaults to 1.
unscaledDeltaTime
readonlyunscaledDeltaTime:number
Wall-clock frame delta after the Time.maximumDeltaTime clamp, unscaled.
unscaledTime
readonlyunscaledTime:number
Unscaled seconds since app.start().
TimeSettings
The time project settings section (docs/architecture/01-lifecycle-and-time.md §2).
Properties
fixedDeltaTime?
readonlyoptionalfixedDeltaTime?:number
The initial fixed step in seconds. Defaults to 1 / 60.
maximumDeltaTime?
readonlyoptionalmaximumDeltaTime?:number
The initial frame-delta clamp in seconds. Defaults to 0.1.
timeScale?
readonlyoptionaltimeScale?:number
The initial time scale. Defaults to 1.
ToastOptions
What new Toast(app.ui, options) accepts.
Properties
duration?
readonlyoptionalduration?:number
How long a message stays up, in seconds, unless Toast.show overrides it.
layer?
readonlyoptionallayer?:string
The layer to mount the stack into. Defaults to "overlay".
maxVisible?
readonlyoptionalmaxVisible?:number
How many messages are stacked before the oldest is dropped. Defaults to 4.
TorusMeshOptions
How MeshAsset.torus sizes its ring, which lies in the XZ plane.
Properties
diameter?
readonlyoptionaldiameter?:number
Outer diameter, in metres.
tessellation?
readonlyoptionaltessellation?:number
Segment count around the ring.
thickness?
readonlyoptionalthickness?:number
Tube thickness, in metres.
TriggerEvent
What a script's onTriggerEnter/onTriggerExit is handed.
Example
class Pickup extends Script implements ScriptCallbacks {
static typeId = "mygame/Pickup";
onTriggerEnter(trigger: TriggerEvent): void {
if (trigger.other?.tags.has("player") === true) {
this.entity.destroy();
}
}
}Properties
other
readonlyother:Entity|null
The entity that entered or left, or null when Havok no longer tracks its body.
otherCollider
readonlyotherCollider:Collider|null
The other entity's first collider, or null. Lite reports no shape identity (§4).
self
readonlyself:Entity
The entity whose script is being called.
TriggerEvent2D
What a script's onTriggerEnter/onTriggerExit is handed in a 2D world.
Example
class Coin extends Script implements ScriptCallbacks {
static typeId = "mygame/Coin";
onTriggerEnter(trigger: TriggerEvent2D): void {
if (trigger.other?.tags.has("player") === true) {
this.entity.destroy();
}
}
}Properties
other
readonlyother:Entity|null
The entity that entered or left, or null when its body is already gone.
otherCollider
readonlyotherCollider:Collider2D|null
The exact collider on the other entity — Rapier reports shape identity, unlike Havok.
self
readonlyself:Entity
The entity whose script is being called.
selfCollider
readonlyselfCollider:Collider2D|null
The collider on this entity that took part.
TweenOptions
What app.tweens.to(...) accepts.
Properties
delay?
readonlyoptionaldelay?:number
How long to wait before the first cycle starts, in seconds. Defaults to 0.
duration
readonlyduration:number
How long one cycle takes, in seconds. Must be finite and greater than zero.
ease?
readonlyoptionalease?:"linear"|EasingFunction|"quadIn"|"quadOut"|"quadInOut"|"cubicIn"|"cubicOut"|"cubicInOut"|"sineInOut"|"backOut"|"elasticOut"|"bounceOut"
The curve, by name or as a custom (t) => number. Defaults to "linear".
loop?
readonlyoptionalloop?:number
How many extra cycles to run; -1 repeats forever. Defaults to 0 — one cycle.
onComplete?
readonlyoptionalonComplete?: () =>void
Called once when the tween finishes on its own or through Tween.complete.
Returns
void
updateWhenPaused?
readonlyoptionalupdateWhenPaused?:boolean
Whether the tween keeps running while app.pause() holds. A tween that does advances on
time.unscaledDeltaTime; every other tween advances on time.deltaTime and is frozen by a
pause. Defaults to false.
yoyo?
readonlyoptionalyoyo?:boolean
Whether every other cycle plays backwards. Defaults to false.
Tweens
The app-wide tween list.
Example
app.tweens.to(entity.transform, { position: { x: 0, y: 3, z: 0 } }, {
duration: 0.6,
ease: "backOut",
yoyo: true,
loop: 1,
});Properties
count
readonlycount:number
How many tweens are alive.
Methods
stopAll()
stopAll():
void
Stops every tween, without firing any onComplete.
Returns
void
stopAllOf()
stopAllOf(
target):number
Stops every tween that moves one object.
Parameters
target
object
The object.
Returns
number
How many tweens were stopped.
to()
to<
T>(target,props,options):Tween
Starts a tween towards props and returns the handle.
Type Parameters
T
T extends object
The target object's type.
Parameters
target
T
The object whose fields move. Any object with numeric or vector fields works.
props
TweenProps<T>
The destination value of each field to move.
options
Duration, curve, delay, looping, and the completion callback.
Returns
The running tween.
Throws
IgnifxError with code IGX-0109 when an option is outside its domain.
Throws
IgnifxError with code IGX-0110 when a named field is not tweenable.
TwoDErrorOptions
Options accepted by twoDError: the same subset of IgnifxErrorOptions this package uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
TwoDLiteHandles
The Babylon Lite objects app.twoD owns.
Properties
renderer
readonlyrenderer:SpriteRenderer|null
The sprite rendering context, or null under a headless app or before the first frame.
TwoDOptions
What twoD() accepts. Every field overrides the matching twoD settings section value.
Properties
mode?
readonlyoptionalmode?:"sprite"|"mixed"
Whether sprites are the whole frame ("sprite") or composite over the 3D scene ("mixed").
pixelsPerUnit?
readonlyoptionalpixelsPerUnit?:number
How many pixels one world metre spans.
ySort?
readonlyoptionalySort?:Readonly<Record<string,boolean>>
Which sorting layers draw back-to-front by world Y.
TwoDPick
What app.twoD.pickAt returns.
Properties
component
readonlycomponent:SpriteRenderer
The sprite component that was hit.
entity
readonlyentity:Entity
The entity carrying the sprite that was hit.
u
readonlyu:number
Where inside the sprite's quad the hit landed, in [0, 1].
v
readonlyv:number
Where inside the sprite's quad the hit landed, in [0, 1].
TwoDSettings
The resolved twoD settings section.
Example
// ignifx.config.ts
export default defineConfig({
sortingLayers: { sortingLayers: ["Background", "Default", "Foreground"] },
twoD: { mode: "sprite", pixelsPerUnit: 16, ySort: { Default: true } },
});Properties
mode
readonlymode:"sprite"|"mixed"
Whether sprites are the whole frame ("sprite") or composite over the 3D scene ("mixed").
pixelsPerUnit
readonlypixelsPerUnit:number
How many pixels one world metre spans. Defaults to 100.
ySort
readonlyySort:Readonly<Record<string,boolean>>
Which sorting layers draw back-to-front by world Y rather than by orderInLayer. A layer the
record does not mention does not Y-sort.
UiDomTarget
The DOM objects one app's overlay is built in.
Properties
canvas
readonlycanvas:HTMLCanvasElement
The canvas the overlay is positioned over.
document
readonlydocument:Document
The document the overlay's elements and its stylesheet are created in.
window
readonlywindow:Window
The window resize and focus events are read from, and the pixel ratio is read from.
UiErrorOptions
Options accepted by uiError: the same subset of IgnifxErrorOptions this package uses.
Properties
cause?
readonlyoptionalcause?:unknown
The failure being wrapped, when there is one.
context?
readonlyoptionalcontext?:Readonly<Record<string,string|number|boolean|null>>
Identifiers that locate the failure.
hint?
readonlyoptionalhint?:string
One sentence telling the developer what to do about it.
UiLayerOptions
Options accepted by app.ui.layer.
Properties
visible?
readonlyoptionalvisible?:boolean
Whether the layer starts visible. Defaults to true.
zIndex?
readonlyoptionalzIndex?:number
The stacking order. Defaults to the layer's declaration index times UI_LAYER_Z_STEP.
UiLayout
Where the overlay root sits and how big it is, in the units the mode chose.
Properties
height
readonlyheight:number
The root's height, in UI units.
mode
readonlymode:"css"|"fit"|"dpi"
The mode this layout was computed for.
offsetX
readonlyoffsetX:number
The root's left edge, in CSS pixels from the canvas's left edge.
offsetY
readonlyoffsetY:number
The root's top edge, in CSS pixels from the canvas's top edge.
scale
readonlyscale:number
The uniform CSS scale applied to the root.
width
readonlywidth:number
The root's width, in UI units.
UiOptions
What ui() accepts. Every field that names a settings value overrides the matching ui section
value, which is the shape 04-extensions.md §1 shows for physics().
Properties
layers?
readonlyoptionallayers?: readonlystring[]
The layers created up front, back to front.
locale?
readonlyoptionallocale?:string
The locale the app starts in, before any document is loaded. Defaults to "en".
referenceResolution?
readonlyoptionalreferenceResolution?: readonlynumber[]
The [width, height] the "fit" mode scales to.
scaling?
readonlyoptionalscaling?:"css"|"fit"|"dpi"
How the overlay's coordinate system relates to the canvas.
strings?
readonlyoptionalstrings?:string
The address of a .i18n.json document to load into app.i18n at start-up. Empty loads
nothing; a game that ships one file per locale calls app.i18n.load itself.
visible?
readonlyoptionalvisible?:boolean
Whether the overlay starts shown.
UiPixelMapping
How a render-target pixel maps onto a UI unit under one layout.
Remarks
Camera.worldToScreen answers in backing-store pixels (it divides by
RendererImpl.readTargetSize, which reads canvas.width/canvas.height), and a DOM element is
placed in UI units inside a root that is itself translated by offsetX/offsetY CSS pixels and
scaled by scale. This is the conversion between the two, expressed so a per-frame loop needs
two multiplies and a subtract and allocates nothing.
Properties
originX
readonlyoriginX:number
Then subtract this.
originY
readonlyoriginY:number
Then subtract this.
scaleX
readonlyscaleX:number
Multiply a backing-store x by this.
scaleY
readonlyscaleY:number
Multiply a backing-store y by this.
UiSettings
The resolved ui settings section.
Example
// ignifx.config.ts
export default defineConfig({
ui: { scaling: "fit", referenceResolution: [640, 360], layers: ["hud", "menu"] },
});Properties
layers
readonlylayers: readonlystring[]
The layers created eagerly, back to front. Declaring them here is what makes their stacking order independent of the order the game happens to call UiHost.layer in.
referenceResolution
readonlyreferenceResolution: readonlynumber[]
The [width, height], in UI units, that "fit" scales to. Ignored by the other two modes.
Defaults to [1920, 1080].
scaling
readonlyscaling:"css"|"fit"|"dpi"
How the overlay's coordinate system relates to the canvas. Defaults to "css".
visible
readonlyvisible:boolean
Whether the overlay is shown at all. Defaults to true.
UiSurfaceMetrics
The two sizes of the canvas the overlay covers, both measured by the host.
Properties
cssHeight
readonlycssHeight:number
The canvas's laid-out height, in CSS pixels.
cssWidth
readonlycssWidth:number
The canvas's laid-out width, in CSS pixels.
deviceHeight
readonlydeviceHeight:number
The canvas's backing-store height, in device pixels — canvas.height.
deviceWidth
readonlydeviceWidth:number
The canvas's backing-store width, in device pixels — canvas.width.
UiSystemOptions
What the system is built with.
Properties
app
readonlyapp:App
The app, for the render surface's size and the Lite scene.
host
readonlyhost:UiHost
The overlay host, for the layout the anchors are placed in.
i18n
readonlyi18n:I18nService
The localization service i18nKey is resolved through.
runtime
readonlyruntime:TextRuntime
The text renderer's life.
UlidFactoryOptions
Options for createUlidFactory.
Properties
now?
readonlyoptionalnow?: () =>number
The clock, in milliseconds since the Unix epoch. Defaults to Date.now.
Returns
number
random?
readonlyoptionalrandom?:RandomSource
Where randomness comes from. Defaults to createCryptoRandom.
Vec2Like
The structural shape of a 2D vector. Public APIs accept this interface so that plain object
literals, typed views, and the engine's Vec2 class are interchangeable.
Properties
x
readonlyx:number
The x component.
y
readonlyy:number
The y component.
Vec3Like
The structural shape of a 3D vector.
Properties
x
readonlyx:number
The x component.
y
readonlyy:number
The y component.
z
readonlyz:number
The z component.
Vec4Like
The structural shape of a 4D vector.
Properties
w
readonlyw:number
The w component.
x
readonlyx:number
The x component.
y
readonlyy:number
The y component.
z
readonlyz:number
The z component.
VectorFieldSpec
Kind-specific data for the vector kinds. components says how many numbers the encoded array
holds, so encoders do not have to re-derive it from the kind.
Properties
components
readonlycomponents:2|3|4
How many components the value has: 2, 3, or 4.
kind
readonlykind:"vec2"|"vec3"|"vec4"|"quat"
The vector kind.
VelocityLimitSettings
The world-wide speed clamps Havok applies (setPhysicsVelocityLimits, index.d.ts 10880). A
value of 0 means "leave Havok's own default alone".
Properties
angular
readonlyangular:number
Maximum angular speed in radians per second, or 0 for Havok's default.
linear
readonlylinear:number
Maximum linear speed in metres per second, or 0 for Havok's default.
VibrationActuatorLike
The subset of the DOM GamepadHapticActuator this package uses.
Methods
playEffect()
playEffect(
type,parameters):Promise<unknown>
Plays one haptic effect.
Parameters
type
string
The effect type; "dual-rumble" is the only one every pad supports.
parameters
How long the effect lasts and how hard the motors run.
Returns
Promise<unknown>
Whatever the host resolves the effect with.
VibrationEffectParameters
The shape of one dual-rumble haptic effect.
Properties
duration
readonlyduration:number
How long the effect lasts, in milliseconds.
strongMagnitude
readonlystrongMagnitude:number
The low-frequency motor magnitude, in [0, 1].
weakMagnitude
readonlyweakMagnitude:number
The high-frequency motor magnitude, in [0, 1].
VirtualButtonOptions
What new VirtualButton(app, options) accepts.
Properties
ariaLabel?
readonlyoptionalariaLabel?:string
An accessible label. Defaults to the control name.
control
readonlycontrol:string
The <Virtual>/… control to write.
label?
readonlyoptionallabel?:string
The glyph or word drawn on the button. Defaults to the control name.
layer?
readonlyoptionallayer?:string
The layer to mount into. Defaults to "hud".
style?
readonlyoptionalstyle?:Readonly<Record<string,string>>
Inline styles applied to the button, for placement.
VirtualDeviceLike
The part of @ignifx/input's virtual device the touch widgets use.
Remarks
Structural on purpose. A test passes a recording double; a game passes
app.input.devices.virtual.
Methods
set()
set(
name,value):void
Writes a scalar control, creating it when it does not exist.
Parameters
name
string
The control name, as it appears after <Virtual>/.
value
number
The new value.
Returns
void
setVector()
setVector(
name,x,y):void
Writes a vector control, creating it when it does not exist.
Parameters
name
string
The control name.
x
number
The new x component.
y
number
The new y component.
Returns
void
VirtualJoystickOptions
What new VirtualJoystick(app, options) accepts.
Properties
ariaLabel?
readonlyoptionalariaLabel?:string
An accessible label for the pad. Defaults to the control name.
control?
readonlyoptionalcontrol?:string
The <Virtual>/… control to write. Defaults to "joystick".
deadZone?
readonlyoptionaldeadZone?:number
Deflections shorter than this fraction of the radius read as zero. Defaults to 0.15.
layer?
readonlyoptionallayer?:string
The layer to mount into. Defaults to "hud".
radius?
readonlyoptionalradius?:number
How far the knob travels, in UI units, before the stick reads as fully deflected.
style?
readonlyoptionalstyle?:Readonly<Record<string,string>>
Inline styles applied to the pad, for placement.
VoiceHost
What a voice needs from the service to decide whether to play now or later. AudioService
implements it; nothing else has any reason to.
Properties
backend
readonlybackend:AudioBackend
The backend every call is forwarded to.
isLocked
readonlyisLocked:boolean
true before the first unlock, when a browser would refuse to make a sound.
queueWhileLocked
readonlyqueueWhileLocked:boolean
Whether plays made while locked are held rather than dropped.
Methods
reportError()
reportError(
error):void
Reports a failure that has no caller to throw at — a decode that rejected, say.
Parameters
error
unknown
What went wrong.
Returns
void
VoiceRequest
What the service is asked to build a voice from: an AudioSource's fields, or the
arguments of one playOneShot.
Properties
bus
readonlybus:string
The name of the bus it routes into; empty routes to the default sound bus.
clip
readonlyclip:AudioClip
The clip to play.
loop
readonlyloop:boolean
Whether instances loop.
maxInstances
readonlymaxInstances:number
How many instances may play at once; the oldest is stolen above it.
pan
readonlypan:number
Stereo pan in [-1, 1], for a non-spatial sound.
playbackRate
readonlyplaybackRate:number
Playback rate; ignifx's pitch maps onto it.
spatial
readonlyspatial:BackendSpatialRequest|null
The 3D placement, or null for a non-spatial sound.
volume
readonlyvolume:number
The sound's own linear gain.
WaitInstruction
A wait a coroutine yielded, built by waitSeconds, waitSecondsRealtime, waitFixedUpdate,
waitUntil, or waitWhile.
Properties
kind
readonlykind:"fixedUpdate"|"seconds"|"secondsRealtime"|"until"|"while"
Which kind of wait this is; the scheduler switches on it.
predicate?
readonlyoptionalpredicate?: () =>boolean
The condition, for the two predicate kinds.
Returns
boolean
seconds?
readonlyoptionalseconds?:number
How long to wait, for the two timed kinds.
WavHeader
What a WAV header says about the audio it introduces.
Properties
channels
readonlychannels:number
How many interleaved channels the data holds.
duration
readonlyduration:number
How long the sample data plays, in seconds.
sampleRate
readonlysampleRate:number
Samples per second per channel.
WebGpuInfo
What the host's WebGPU adapter offers.
Properties
adapterInfo
readonlyadapterInfo:GpuAdapterInfo
Who made the adapter.
features
readonlyfeatures: readonlystring[]
The optional features the adapter supports, sorted ascending.
limits
readonlylimits:Readonly<Record<string,number>>
The adapter's limits, by their WebGPU names.
WorldBox
A caller-owned world-space box, so reading the camera's bounds allocates nothing.
Properties
max
readonlymax:MutableVec2
The upper corner, in world metres.
min
readonlymin:MutableVec2
The lower corner, in world metres.
WorldLiteHandles
Babylon Lite objects a world owns. Unstable escape hatch
(docs/architecture/00-overview.md §3, 02-scene-graph.md §2); excluded from the stability
guarantees of CONSTITUTION.md Article IV.
Properties
scene
readonlyscene:SceneContext
The Lite scene the world's entities are rendered from.
simulationScene
readonlysimulationScene:SceneContext|null
The scene a physics extension steps its simulation in (docs/architecture/09-physics.md §1),
or null when no extension has set one.
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.
AssetState
AssetState =
"loading"|"loaded"|"failed"|"released"
Where an AssetHandle is in its life
(docs/architecture/05-assets-and-loading.md §3).
AudioBackendKind
AudioBackendKind =
"web"|"headless"
Which implementation of AudioBackend is running.
AudioBackendState
AudioBackendState =
"running"|"suspended"|"interrupted"|"closed"
The audio context's state, mirroring Babylon Lite's AudioEngineState (index.d.ts 970) and,
through it, Web Audio's AudioContextState plus "interrupted".
AudioDecoder
AudioDecoder = (
clip) =>Promise<void>
How a clip's bytes are turned into a decoded buffer, when the app has a backend that can.
Parameters
clip
Returns
Promise<void>
Remarks
The loader is registered in register, long before onStart creates the backend, so it holds a
lookup rather than a backend: the function answers null until there is one.
AudioDistanceModel
AudioDistanceModel = typeof
AUDIO_DISTANCE_MODELS[number]
The union of the distance models AUDIO_DISTANCE_MODELS declares.
AudioErrorCode
AudioErrorCode = typeof
AudioErrorCode[keyof typeofAudioErrorCode]
The union of the codes the AudioErrorCode table declares.
AudioServiceState
AudioServiceState =
"locked"|"running"|"suspended"|"interrupted"|"closed"
What app.audio.state reports: Babylon Lite's AudioEngineState (index.d.ts 970) plus
"locked", the state before the first unlock.
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.
BodyType
BodyType = typeof
BODY_TYPES[number]
The union of BODY_TYPES.
BodyType2D
BodyType2D = typeof
BODY_TYPES_2D[number]
The union of BODY_TYPES_2D.
CameraProjection
CameraProjection = typeof
PROJECTIONS[number]
The union of the camera projections.
CanvasAlphaMode
CanvasAlphaMode = typeof
CANVAS_ALPHA_MODES[number]
The union of the canvas alpha modes.
Capsule2DDirection
Capsule2DDirection = typeof
CAPSULE_2D_DIRECTIONS[number]
The union of CAPSULE_2D_DIRECTIONS.
CapsuleDirection
CapsuleDirection = typeof
CAPSULE_DIRECTIONS[number]
The union of CAPSULE_DIRECTIONS.
CharacterShape2D
CharacterShape2D = typeof
CHARACTER_SHAPES_2D[number]
The union of CHARACTER_SHAPES_2D.
CollisionEventMode
CollisionEventMode = typeof
COLLISION_EVENT_MODES[number]
The union of COLLISION_EVENT_MODES.
CollisionEventMode2D
CollisionEventMode2D = typeof
COLLISION_EVENT_MODES_2D[number]
The union of COLLISION_EVENT_MODES_2D.
CollisionIdentityMode
CollisionIdentityMode = typeof
COLLISION_IDENTITY_MODES[number]
The union of COLLISION_IDENTITY_MODES.
CombineRule
CombineRule = typeof
COMBINE_RULES[number]
The union of COMBINE_RULES.
ComponentDefinition
ComponentDefinition<
S> = () =>Component&FieldsOf<S> &object
The abstract base class Component.define returns: a Component that also carries every
field the schema declares, typed.
Type Declaration
prototype
The instance shape, so the class satisfies ComponentType.
schema
readonlyschema:S
The schema the class was defined from, carried as a value on the returned class. The other
statics (ComponentStatics) are deliberately not declared here: a subclass must be
able to write a plain static typeId without the override keyword.
Type Parameters
S
S extends Schema
The schema the class was defined from.
ComponentHandle
ComponentHandle =
number&object
The dense runtime id of a component, with the same lifetime rules as EntityHandle.
Type Declaration
__brand
readonly__brand:"ComponentHandle"
ComponentInit
ComponentInit<
T> ={ readonly [K in keyof T as K extends keyof Component ? never : NonNullable<T[K]> extends (args: never[]) => unknown ? never : K]?: T[K] }
The values entity.addComponent(Type, init) accepts: the component's serialized fields, each
optional. Engine-owned members (entity, enabled, …) and methods are excluded, so an init
object can only set declared data.
Type Parameters
T
T extends Component
The component instance type.
Example
entity.addComponent(Mover, { speed: 12, label: "hero" });CompositeKind
CompositeKind = typeof
CompositeKind[keyof typeofCompositeKind]
The union of the composite names.
ControlKind
ControlKind = typeof
ControlKind[keyof typeofControlKind]
The union of the control kinds.
ControlTouchHandler
ControlTouchHandler = (
actions) =>void
Called when a control's value changed, with the action indices bound to that control. The service installs it so that the frame's resolution can visit actions in the arrival order of the events that actuated them.
Parameters
actions
readonly number[]
Returns
void
CoreErrorCode
CoreErrorCode = typeof
CoreErrorCode[keyof typeofCoreErrorCode]
The union of the codes @ignifx/core owns. Use it to narrow catch blocks to core failures.
Coroutine
Coroutine =
Generator<CoroutineYield,void,unknown>
A generator coroutine (docs/architecture/01-lifecycle-and-time.md §5, ADR-0010). The scheduler
resumes it synchronously at defined points in the frame; it is never an async function.
CoroutineYield
CoroutineYield =
null|undefined|WaitInstruction|CoroutineHandle|Promise<unknown>
Everything a coroutine may yield: null/undefined for "next frame", a wait instruction, a
handle to another coroutine to wait for, or a promise to resume on once it settles.
CurveKey
CurveKey = readonly [
number,number,number,number]
One key of an animation curve: time, value, incoming tangent, outgoing tangent
(docs/architecture/06-serialization-and-scene-format.md §3).
DeviceKind
DeviceKind = typeof
DeviceKind[keyof typeofDeviceKind]
The union of the device families.
DevtoolsErrorCode
DevtoolsErrorCode = typeof
DevtoolsErrorCode[keyof typeofDevtoolsErrorCode]
The union of the codes the DevtoolsErrorCode table declares.
DevtoolsPanelName
DevtoolsPanelName = typeof
DEVTOOLS_PANEL_NAMES[number]
The union of the nine panel names.
DevtoolsPosition
DevtoolsPosition = typeof
DEVTOOLS_POSITIONS[number]
The edge of the canvas the overlay is docked to.
Disconnect
Disconnect = () =>
void
Detaches a handler from a Signal. Calling it more than once is a no-op.
Returns
void
EasingFunction
EasingFunction = (
t) =>number
A curve mapping normalized time to a normalized value. Custom curves have this shape.
Parameters
t
number
Normalized time in [0, 1].
Returns
number
The eased value; 0 at t = 0 and 1 at t = 1, free to overshoot in between.
EasingName
EasingName = typeof
EASING_NAMES[number]
The union of the named easing curves.
ElectronErrorCode
ElectronErrorCode = typeof
ElectronErrorCode[keyof typeofElectronErrorCode]
The union of the codes the ElectronErrorCode table declares.
EntityHandle
EntityHandle =
number&object
The dense runtime id of an entity. Valid until the entity is destroyed; a handle that outlives
its entity resolves to null through world.getEntityByHandle rather than to whatever object
recycled the slot.
Type Declaration
__brand
readonly__brand:"EntityHandle"
Remarks
The __brand property exists only in the type system — a handle is a number at runtime — so a
handle can be stored in a Float64Array or written into Lite's node metadata unchanged.
Example
const handle: EntityHandle = entity.handle;
world.getEntityByHandle(handle)?.destroy();EntityOverrideField
EntityOverrideField =
"name"|"active"|"static"|"layer"|"tags"
The entity properties an override may patch directly.
EnvironmentFogMode
EnvironmentFogMode = typeof
FOG_MODE_NAMES[number]
The union of the fog modes.
ErrorCode
ErrorCode =
`IGX-${number}`
The shape of every ignifx diagnostic code: the literal IGX- followed by four digits.
Remarks
The template literal is the widest useful type; it accepts strings such as "IGX-1" that are not
real codes. isValidErrorCode is the runtime check, CoreErrorCode is the narrowed
string-literal union for the codes this package owns, and extensions narrow their own the same
way.
ErrorContext
ErrorContext =
Readonly<Record<string,string|number|boolean|null>>
The identifiers that make a failure actionable: entity and component uids, asset keys, layer names, extension names. Values are primitives so the whole record survives being sent to a devtools panel or a log sink without cloning engine objects.
ErrorFormatMode
ErrorFormatMode =
"development"|"production"
How much of an error is spelled out in Error.message.
Remarks
"development" writes the full sentence, the context values, and the hint. "production" keeps
the code and the names of the context keys and drops every value and the prose, so shipped
games neither leak content paths nor pay for message strings (CONSTITUTION.md §3.9). The
structured code, context, and hint properties are populated in both modes.
ErrorRange
ErrorRange = typeof
ErrorRange[keyof typeofErrorRange]
The union of the two-digit subsystem prefixes declared by ErrorRange.
FetchLike
FetchLike = typeof
globalThis.fetch
The fetch implementation the service performs every read through
(docs/architecture/05-assets-and-loading.md §8). Injecting it is how headless tests supply
deterministic responses and how a Node app maps addresses onto fs (Phase 9).
FieldKind
The union of every field kind.
FieldsOf
FieldsOf<
S> ={ -readonly [K in keyof S]: S[K] extends FieldDefinition<infer T> ? T : never }
The object type a schema describes: every field name mapped to its runtime value type. This is
what gives this.speed its number type inside a component declared with
Script.define({ speed: f32(5) }).
Type Parameters
S
S extends Schema
The schema to project.
Example
const schema = { speed: f32(5), label: str("") };
type Fields = FieldsOf<typeof schema>; // { speed: number; label: string }FieldSpec
FieldSpec =
NumberFieldSpec|BoolFieldSpec|StringFieldSpec|VectorFieldSpec|ColorFieldSpec|EnumFieldSpec|EntityRefFieldSpec|ComponentRefFieldSpec|AssetFieldSpec|ArrayFieldSpec|RecordFieldSpec|MapFieldSpec|OptionalFieldSpec|LayerMaskFieldSpec|CurveFieldSpec|CustomFieldSpec
The discriminated union of kind-specific field data. Switching on spec.kind narrows to the
member that carries the extra information that kind needs — the enumeration's values, an array's
item definition, a component reference's class token — so no branch has to guess.
GamepadReader
GamepadReader = () => readonly (
GamepadLike|null)[]
How one frame's pads are read. Injecting it is what makes the mapping testable in Node.
Returns
readonly (GamepadLike | null)[]
HostChannel
HostChannel = typeof
HOST_CHANNELS[keyof typeofHOST_CHANNELS]
The union of the channel names HOST_CHANNELS declares.
HostStoredValue
HostStoredValue = {
json:string;kind:"json"; } | {bytes:Uint8Array;kind:"bytes"; }
A stored value as it crosses the bridge: the wire form of @ignifx/core's StoredValue
(docs/architecture/14-platform-electron.md §2).
Union Members
Type Literal
{ json: string; kind: "json"; }
json
readonlyjson:string
The canonical JSON text of the value.
kind
readonlykind:"json"
Discriminant: this value is JSON text.
Type Literal
{ bytes: Uint8Array; kind: "bytes"; }
bytes
readonlybytes:Uint8Array
The octets. May be empty.
kind
readonlykind:"bytes"
Discriminant: this value is a byte array.
HostWindowEvent
HostWindowEvent =
"minimize"|"restore"|"focus"|"blur"|"enter-full-screen"|"leave-full-screen"
The window lifecycle events the main process forwards to the renderer.
Remarks
minimize/restore and focus/blur are the four 14-platform-electron.md §3 names; the
full-screen pair is carried too because app.desktop.setFullscreen is asynchronous and a game
that wants to reflect the state in its own menu needs to hear about the platform's own
full-screen gesture as well.
HotReloadKind
HotReloadKind =
"patch"|"recreate"|"scene"
What one HotReloadReport describes: a prototype swap, a destroy-and-rebuild of component instances, or a scene instance rebuilt from its file.
HotReloadPolicy
HotReloadPolicy =
"patch"|"recreate"
What a class asks the engine to do with its live instances when its module is replaced
(docs/architecture/15-devtools-and-diagnostics.md §5).
Remarks
"patch" is the default and the one to reach for while iterating on logic: the live instances
keep their identity and every field value, and no lifecycle callback re-runs. "recreate" is
required when the field layout changes, because a patched instance keeps whatever properties
its constructor assigned and a renamed or added field would read undefined.
HudAnchor
HudAnchor = typeof
HUD_ANCHORS[number]
Which point of the render target a HudText's position is measured from, and which point of the
block sits there.
InputActionSignal
InputActionSignal =
SignalLike<InputActionEvent>
The read-only half of an action's signals, for public shapes that expose them.
InputActionType
InputActionType =
"button"|"axis"|"vector2"
What an action produces (docs/architecture/08-input.md §2).
InputErrorCode
InputErrorCode = typeof
InputErrorCode[keyof typeofInputErrorCode]
The union of the codes the InputErrorCode table declares.
InputEventType
InputEventType =
"keydown"|"keyup"|"pointerdown"|"pointerup"|"pointermove"|"wheel"|"textinput"
The raw event kinds app.input.events publishes.
InterpolationMode
InterpolationMode = typeof
INTERPOLATION_MODES[number]
The union of INTERPOLATION_MODES.
InterpolationMode2D
InterpolationMode2D = typeof
INTERPOLATION_MODES_2D[number]
The union of INTERPOLATION_MODES_2D.
JsonArray
JsonArray = readonly
JsonValue[]
A JSON array. Read-only because encoded values are snapshots: callers copy before mutating.
JsonObject
JsonObject =
object
A JSON object. Keys are emitted in the canonical order defined by
docs/architecture/06-serialization-and-scene-format.md §1, so two saves of the same state
produce byte-identical files.
Index Signature
[key: string]: JsonValue
JsonSchemaObject
JsonSchemaObject =
JsonObject
A JSON Schema fragment. Kept as a plain JSON object because the generated document is assembled
— and validated — by the documentation harness, not by this module
(docs/architecture/06-serialization-and-scene-format.md §8).
JsonValue
JsonValue =
string|number|boolean|null|JsonArray|JsonObject
The JSON value model the serializer works in. Scene and prefab files are UTF-8 JSON
(docs/architecture/06-serialization-and-scene-format.md §1), so every encoded schema value is
one of these shapes. The type is recursive rather than unknown so that encoders cannot smuggle
a Date, a Map, or an undefined into a file (coding standards §5.2 bans any).
KinematicSyncMode
KinematicSyncMode = typeof
KINEMATIC_SYNC_MODES[number]
The union of KINEMATIC_SYNC_MODES.
LightType
LightType = typeof
LIGHT_TYPES[number]
The union of the light kinds.
LiteAnimationGroup
LiteAnimationGroup =
AnimationGroup
Beta
A Babylon Lite animation clip, re-exported under an ignifx name. Model.animations hands these
to @ignifx/3d's animator, which owns advancement (ADR-0003).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteAnimationManager
LiteAnimationManager =
AnimationManager
Beta
A Babylon Lite animation manager — one per Animator (index.d.ts 430).
Remarks
Unstable escape-hatch type.
LiteAssetContainer
LiteAssetContainer =
AssetContainer
The Babylon Lite asset container a ModelAsset holds, re-exported under an ignifx name
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteAtlasTexture
LiteAtlasTexture =
Texture2D
The GPU texture behind an atlas (index.d.ts 12907).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteAudioBus
LiteAudioBus =
AudioBus$1
Babylon Lite's generic mixer bus (index.d.ts 910). Unstable escape hatch.
LiteAudioEngine
LiteAudioEngine =
AudioEngine
Babylon Lite's audio engine (index.d.ts 926). Unstable escape hatch: excluded from the
stability guarantees of CONSTITUTION.md Article IV.
LiteBounds2D
LiteBounds2D =
Bounds2D
Mutable axis-aligned 2D bounds, the shape getSprite2DVisibleBoundsToRef writes
(index.d.ts 1352).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteCamera
LiteCamera =
FreeCamera
The Babylon Lite camera an ignifx Camera component owns, re-exported under an ignifx name so
feature code can name the type without importing @babylonjs/lite (CONSTITUTION.md §3.4,
coding standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteEngine
LiteEngine =
EngineContext
The Babylon Lite engine handle an ignifx app owns, re-exported under an ignifx name so that
feature code can name the type without importing @babylonjs/lite
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable: it is Lite's own type, reachable only through documented .lite escape hatches, and it
is excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteEnvironmentTextures
LiteEnvironmentTextures =
EnvironmentTextures
The GPU-resident image-based-lighting textures loadEnvironment resolves to, re-exported under an
ignifx name (CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteFont
LiteFont =
Font
The Babylon Lite font handle a FontAsset wraps, re-exported under an ignifx name so feature code
can name the type without importing @babylonjs/lite (CONSTITUTION.md §3.4, coding
standards §4).
Remarks
Unstable: it is Lite's own type, reachable only through documented .lite escape hatches, and it
is excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteLight
LiteLight =
DirectionalLight|PointLight|SpotLight|HemisphericLight
The Lite light kinds an ignifx Light component can own, re-exported under an ignifx name so
feature code can name the type without importing @babylonjs/lite (CONSTITUTION.md §3.4,
coding standards §4). The barrel exports it as LiteLight, the name Light.lite.light reads by.
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteMaterial
LiteMaterial =
Material
The Babylon Lite material a MaterialAsset owns, re-exported under an ignifx name
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteMesh
LiteMesh =
Mesh
The Babylon Lite mesh a MeshAsset template and a MeshRenderer clone are, re-exported under an
ignifx name so feature code can name the type without importing @babylonjs/lite
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable: it is Lite's own type, reachable only through documented .lite escape hatches, and it
is excluded from the stability guarantees of CONSTITUTION.md Article IV.
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.
LitePbrMaterial
LitePbrMaterial =
PbrMaterialProps
A Babylon Lite physically based material, re-exported under an ignifx name.
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteScene
LiteScene =
SceneContext
The Babylon Lite scene a world renders into (or simulates on), re-exported under an ignifx name for the same reason as LiteEngine.
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSceneNode
LiteSceneNode =
SceneNode
The Babylon Lite node an ignifx Transform wraps, re-exported under an ignifx name so that
feature code can name the type without importing @babylonjs/lite
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable: it is Lite's type, reachable only through documented .lite escape hatches, and it is
excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteShadowGenerator
LiteShadowGenerator =
ShadowGenerator
The Babylon Lite shadow generator a Light owns, re-exported under an ignifx name
(CONSTITUTION.md §3.4, coding standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSkeleton
LiteSkeleton =
Skeleton
Beta
A Babylon Lite skeleton, re-exported under an ignifx name. Present on a container only when
enableBoneControl() ran before the load (index.d.ts 653).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSoundBuffer
LiteSoundBuffer =
SoundBuffer
Babylon Lite's decoded audio buffer (index.d.ts 11707). Unstable escape hatch.
LiteSpatialTarget
LiteSpatialTarget =
SpatialTarget
Anything Lite's spatial nodes can follow: an object exposing a column-major worldMatrix
(index.d.ts 11807). A Lite SceneNode — which is what Transform.lite hands back — satisfies
it, which is how a spatial AudioSource follows its entity.
LiteSprite2DHandle
LiteSprite2DHandle =
Sprite2DHandle
A stable identity for one sprite that survives Lite's swap-remove reindexing
(index.d.ts 11880).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSprite2DLayer
LiteSprite2DLayer =
Sprite2DLayer
One ordered batch of sprites drawn from a single atlas with a single blend mode
(index.d.ts 11885).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSprite2DView
LiteSprite2DView =
Sprite2DView
A layer's 2D camera: pan, zoom, and rotation in Lite's pixel space (index.d.ts 11988).
Remarks
positionPx is the layer-pixel point that lands at the top-left of the viewport, not the
centre — verified against sprite2DWorldToScreenToRef in lib/sprite/sprite-2d-view.js.
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpriteAtlas
LiteSpriteAtlas =
SpriteAtlas
A loaded atlas: one texture plus the frame rectangles inside it (index.d.ts 12041).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpriteBlendMode
LiteSpriteBlendMode =
SpriteBlendMode
An opaque blend-mode descriptor (index.d.ts 12122).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpriteFrame
LiteSpriteFrame =
SpriteFrame
One frame of an atlas: UVs in [0, 1], source size in pixels, and a pivot (index.d.ts 12156).
Remarks
The pivot field is stored but not applied by the Sprite2DLayer pipeline; only Lite's
billboard family reads it. @ignifx/2d applies it itself — see pivotedPositionToRef.
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpritePickInfo
LiteSpritePickInfo =
SpritePickInfo
A pickSprite2D hit: the layer, the dense sprite index, and the within-quad UV
(index.d.ts 12179).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpriteRenderer
LiteSpriteRenderer =
SpriteRenderer$1
Lite's sprite rendering context — the second rendering context @ignifx/2d registers on the
app's surface, after the render scene, so 2D composites on top (index.d.ts 12215).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteSpriteSampling
LiteSpriteSampling =
SpriteSampling
A sprite atlas's min/mag filter (index.d.ts 12229).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteStandardMaterial
LiteStandardMaterial =
StandardMaterialProps
A Babylon Lite Babylon-Standard material, re-exported under an ignifx name.
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LiteStaticSound
LiteStaticSound =
StaticSound
Babylon Lite's buffer-backed sound (index.d.ts 12336). Unstable escape hatch.
LiteStreamingSound
LiteStreamingSound =
StreamingSound
Babylon Lite's media-element-backed sound (index.d.ts 12499). Unstable escape hatch.
LiteTextData
LiteTextData =
DefaultTextData
A shaped block of text, with its glyph storage.
Remarks
Unstable escape-hatch type.
LiteTextLayer
LiteTextLayer =
TextLayer
A 2D text layer placed in render-target pixel space.
Remarks
Unstable escape-hatch type.
LiteTextRenderable
LiteTextRenderable =
TextRenderable
A scene renderable that draws a block of text in world space.
Remarks
Unstable escape-hatch type.
LiteTextRenderer
LiteTextRenderer =
TextRenderer
The standalone rendering context that draws 2D text layers onto the swapchain.
Remarks
Unstable escape-hatch type.
LiteTexture2D
LiteTexture2D =
Texture2D
The Babylon Lite texture a TextureAsset wraps, re-exported under an ignifx name so feature code
can name the type without importing @babylonjs/lite (CONSTITUTION.md §3.4, coding
standards §4).
Remarks
Unstable; excluded from the stability guarantees of CONSTITUTION.md Article IV.
LogLevel
The union of the four severities a LogRecord can carry.
LogThreshold
LogThreshold =
LogLevel|"silent"
What a Logger is set to. A threshold is a LogLevel or "silent", which drops
everything; "silent" is never the level of a record.
Mat4Elements
Mat4Elements =
Float32Array&object
The backing store of a Mat4: a Float32Array of exactly 16 elements, in column-major
order (m[column * 4 + row]). The length: 16 refinement is what makes it a Mat4Like,
and therefore what makes it accepted anywhere Babylon Lite wants a Mat4.
Type Declaration
length
readonlylength:16
MaterialAlphaModeName
MaterialAlphaModeName =
MaterialAlphaMode
How a material interprets its alpha channel, in glTF's vocabulary.
MaterialDefinition
MaterialDefinition =
PbrMaterialDefinition|StandardMaterialDefinition
The parsed body of a .material.json, discriminated by kind.
MaterialKind
MaterialKind = typeof
MATERIAL_KINDS[number]
The union of the material families.
MessageNode
MessageNode =
TextNode|ArgumentNode|PluralNode
One piece of a parsed message.
MessageParams
MessageParams =
Readonly<Record<string,string|number>>
What a message's parameters may be.
NavObstacleShape
NavObstacleShape = typeof
NAV_OBSTACLE_SHAPES[number]
The union of NAV_OBSTACLE_SHAPES.
OverridePath
OverridePath = {
entity:string;kind:"entity"; } | {entity:string;field:EntityOverrideField;kind:"entityField"; } | {channel: keyofSceneFileTransform;entity:string;kind:"transform"; } | {entity:string;kind:"componentList"; } | {component:string;entity:string;kind:"component"; } | {component:string;entity:string;kind:"componentField"; } | {component:string;entity:string;kind:"prop";steps: readonlystring[]; }
The parsed form of an instance override path
(docs/architecture/06-serialization-and-scene-format.md §2). Every path starts with the uid of
an entity of the instanced file, so a path survives the per-instance uid remap
(02-scene-graph.md §10).
The grammar, in the order the parser tries it:
<uid> → entity (whole entity, "remove" only)
<uid>/name | active | static | layer | tags → entityField
<uid>/transform/position | rotation | scale → transform
<uid>/components → componentList ("add" only)
<uid>/components/<uid> → component ("remove" only)
<uid>/components/<uid>/enabled → componentField
<uid>/components/<uid>/props/<field>[/<key>…] → propPartialFieldsOf
PartialFieldsOf<
S> ={ [K in keyof FieldsOf<S>]?: FieldsOf<S>[K] }
The field object of a schema with every property optional, and an explicit undefined allowed.
exactOptionalPropertyTypes normally separates "absent" from "present and undefined"; both
mean "take the schema default" here, so both are accepted (applyInit, encodeProps).
Type Parameters
S
S extends Schema
The schema to project.
Phase
The union of the frame phases.
PhaseIndex
PhaseIndex =
0|1|2|3|4|5
A slot in FrameSample.cpuMs. The kernel's Phase ordinals index this array.
Physics2DErrorCode
Physics2DErrorCode = typeof
Physics2DErrorCode[keyof typeofPhysics2DErrorCode]
The union of the codes the Physics2DErrorCode table declares.
PhysicsCallbackName
PhysicsCallbackName = typeof
PhysicsCallbackName[keyof typeofPhysicsCallbackName]
Beta
The union of the physics callback names.
PhysicsErrorCode
PhysicsErrorCode = typeof
PhysicsErrorCode[keyof typeofPhysicsErrorCode]
The union of the codes the PhysicsErrorCode table declares.
PlatformKind
PlatformKind =
"browser"|"electron"|"node"
Where an app is running.
PlatformOs
PlatformOs =
"macos"|"windows"|"linux"|"ios"|"android"|"unknown"
Which operating system the host runs, as far as it will admit.
Remarks
"unknown" is a real answer, not a failure: a locked-down browser that freezes its user agent
and exposes no navigator.userAgentData genuinely does not say, and code that branches on the
operating system has to have a default anyway.
PluralSelector
PluralSelector = (
value) =>string
Chooses a plural category for a number, in one locale.
Parameters
value
number
Returns
string
ProcessorKind
ProcessorKind = typeof
ProcessorKind[keyof typeofProcessorKind]
The union of the processor names.
QueryShape
QueryShape = {
kind:"sphere";radius:number; } | {kind:"box";size:Vec3Like; } | {height:number;kind:"capsule";radius:number; }
A shape to sweep or to test for overlaps. It is a description, not a component: the service builds the Havok shape for the call and releases it afterwards.
RenderingFeature
RenderingFeature = keyof
RenderingFeatureSettings
A rendering feature a project or an extension asks for
(docs/architecture/07-rendering.md §1.1).
RenderSurface
RenderSurface =
HTMLCanvasElement|OffscreenCanvas
A canvas ignifx can render into: a DOM canvas on the main thread, or an OffscreenCanvas
transferred to a worker. Declared here so public signatures do not depend on a Babylon Lite type.
Schema
Schema =
Readonly<Record<string,FieldDefinition<unknown>>>
A component's declared fields, keyed by property name and ordered by declaration. Declaration
order is the canonical key order used when writing files
(docs/architecture/06-serialization-and-scene-format.md §1).
SchemaIssueCode
SchemaIssueCode = typeof
SchemaIssueCode[keyof typeofSchemaIssueCode]
The union of diagnostic codes this module reports.
ScriptCallbackKind
ScriptCallbackKind = typeof
ScriptCallbackKind[keyof typeofScriptCallbackKind]
The union of script callback ordinals.
ScriptDefinition
The abstract base class Script.define returns: a Script that also carries every field
the schema declares, typed.
Type Declaration
prototype
The instance shape, so the class satisfies ComponentType.
schema
readonlyschema:S
The schema the class was defined from, carried as a value on the returned class. The other
statics (ScriptStatics) are deliberately not declared here: a subclass must be able
to write a plain static typeId or static executionOrder without the override keyword.
Type Parameters
S
S extends Schema
The schema the class was defined from.
ServiceClassKey
ServiceClassKey<
T> = (...args) =>T
A service key that is a class: the constructor itself is the token.
Type Parameters
T
T
The service instance type.
Parameters
args
...never[]
Returns
T
ServiceKey
ServiceKey<
T> =ServiceClassKey<T> |ServiceNameKey<T>
The token a service is registered and looked up under
(docs/architecture/04-extensions.md §1). Either the service's own abstract class — the common
case, so ctx.require(PhysicsService) reads naturally — or a branded token from
createServiceKey for services that have no class of their own.
Type Parameters
T
T
The service instance type the key stands for.
SettingsInput
SettingsInput =
Readonly<Record<string,unknown>>
What a project hands createApp as its settings (docs/architecture/04-extensions.md §5). The
Vite plugin resolves ignifx.config.ts at build time and injects the same shape; tests and
Electron tooling pass it directly.
Remarks
Values are unknown because each section is owned — and validated — by the extension that
registered it. A section whose schema declares exactly one field may be written as that field's
value (layers: ["Default", "Ground"]), which is the form 04-extensions.md §5 shows.
Example
const app = await createApp({
headless: true,
settings: { layers: ["Default", "Player"], time: { fixedDeltaTime: 1 / 120 } },
});ShadowTechniqueName
ShadowTechniqueName = typeof
SHADOW_TECHNIQUES[number]
The union of the shadow techniques a directional light can use.
SignalHandler
SignalHandler<
T> = (value) =>void
A listener attached to a Signal.
Type Parameters
T
T
Parameters
value
T
Returns
void
SimulatedValue
SimulatedValue =
number|boolean|Vec2Like
What a value passed to InputService.simulate may be.
SpriteBlendName
SpriteBlendName = typeof
SPRITE_BLEND_MODES[number]
How a sprite's colour combines with what is already in the framebuffer
(docs/architecture/11-2d-toolkit.md §2.2).
SpriteEffectKind
SpriteEffectKind = typeof
SPRITE_EFFECT_KINDS[number]
Which shader a SpriteLayerEffect installs.
StoredValue
StoredValue = {
json:string;kind:"json"; } | {bytes:Uint8Array;kind:"bytes"; }
A value as a backend sees it: opaque JSON text, or opaque octets.
Union Members
Type Literal
{ json: string; kind: "json"; }
json
readonlyjson:string
The canonical JSON text of the value. Never undefined, never empty.
kind
readonlykind:"json"
Discriminant: this value is JSON text.
Type Literal
{ bytes: Uint8Array; kind: "bytes"; }
bytes
readonlybytes:Uint8Array
The octets. May be empty.
kind
readonlykind:"bytes"
Discriminant: this value is a byte array.
Remarks
The two members are a discriminated union on their kind, so a backend switches once
and the compiler proves both arms are handled. Backends must round-trip both members exactly: the
json string that comes back from StorageBackend.get has to be the same string that went
into StorageBackend.set, and the bytes have to be byte-identical and the same length. A
backend may copy the bytes (IndexedDB's structured clone does) but must never alias the caller's
buffer after set resolves.
Example
const value: StoredValue = { kind: "json", json: '{"volume":0.8}' };
await backend.set("settings", "audio", value);StoredValueKind
StoredValueKind =
"json"|"bytes"
Which of the two representations a stored value uses.
Remarks
"json" carries text produced by the facade's canonical JSON.stringify; "bytes" carries the
raw octets of a Blob, ArrayBuffer, or Uint8Array the caller handed to set. The kind is
stored alongside the payload — a backend that loses it cannot round-trip, because JSON text and
a UTF-8 byte array are indistinguishable once written.
SupportStateName
SupportStateName = typeof
SUPPORT_STATES[number]
The union of SUPPORT_STATES.
TextAlignment
TextAlignment = typeof
TEXT_ALIGNMENTS[number]
Which edge a block's lines align to. Lite aligns lines against the block's longest line, not
against maxWidth, so a single-line block looks the same in all three.
ThreeDErrorCode
ThreeDErrorCode = typeof
ThreeDErrorCode[keyof typeofThreeDErrorCode]
The union of the codes the ThreeDErrorCode table declares.
TileColliderDefinition
TileColliderDefinition = {
height:number;kind:"box";oneWay?:boolean;width:number;x:number;y:number; } | {kind:"polygon";oneWay?:boolean;points: readonlyVec2Like[]; } | {kind:"none"; }
A tile's collision footprint as authored: cell-normalised [0, 1] units with the origin at
the cell's top-left corner and +Y pointing down.
Union Members
Type Literal
{ height: number; kind: "box"; oneWay?: boolean; width: number; x: number; y: number; }
height
readonlyheight:number
The box's height, in cell-normalised units.
kind
readonlykind:"box"
Discriminant: an axis-aligned box.
oneWay?
readonlyoptionaloneWay?:boolean
Whether the tile is a one-way platform. Defaults to false.
width
readonlywidth:number
The box's width, in cell-normalised units.
x
readonlyx:number
The box's left edge, in cell-normalised units.
y
readonlyy:number
The box's top edge, in cell-normalised units measured downwards from the cell's top.
Type Literal
{ kind: "polygon"; oneWay?: boolean; points: readonly Vec2Like[]; }
kind
readonlykind:"polygon"
Discriminant: an outline.
oneWay?
readonlyoptionaloneWay?:boolean
Whether the tile is a one-way platform. Defaults to false.
points
readonlypoints: readonlyVec2Like[]
The vertices in cell-normalised units with a top-left origin, in the editor's winding.
Type Literal
{ kind: "none"; }
kind
readonlykind:"none"
Discriminant: the tile renders but does not collide.
Remarks
This is deliberately not TileCollisionShape, which is cell-local metres with a bottom-left origin, +Y up and counter-clockwise winding. Editors work top-down and the physics world works bottom-up; tileCollisionInfo converts, and nothing else should.
A box covering the top quarter of a cell — the usual one-way platform — is
{ kind: "box", x: 0, y: 0, width: 1, height: 0.25, oneWay: true }.
TileCollisionShape
TileCollisionShape = {
height:number;kind:"box";width:number;x:number;y:number; } | {kind:"polygon";points: readonlyVec2Like[]; } | {kind:"none"; }
The collision footprint of a single tile, expressed in cell-local metres with the origin at
the bottom-left corner of the cell (ignifx 2D is +Y up — docs/adr/0011).
Union Members
Type Literal
{ height: number; kind: "box"; width: number; x: number; y: number; }
height
readonlyheight:number
The box's height, in metres.
kind
readonlykind:"box"
Discriminant: an axis-aligned box.
width
readonlywidth:number
The box's width, in metres.
x
readonlyx:number
The box's left edge, in cell-local metres.
y
readonlyy:number
The box's bottom edge, in cell-local metres.
Type Literal
{ kind: "polygon"; points: readonly Vec2Like[]; }
kind
readonlykind:"polygon"
Discriminant: a convex or concave outline.
points
readonlypoints: readonlyVec2Like[]
The outline's vertices in cell-local metres, wound counter-clockwise.
Type Literal
{ kind: "none"; }
kind
readonlykind:"none"
Discriminant: the tile does not collide.
Remarks
"none" is the shape of a tile that renders but does not collide; it is the default for a tile
whose tileset entry declares no collider.
TileObjectFactory
TileObjectFactory = (
context) =>Entity|null
Builds the entities a tilemap's objects layer describes.
Parameters
context
Returns
Entity | null
ToneMappingCurve
ToneMappingCurve = typeof
TONE_MAPPING_NAMES[number]
The union of the tone-mapping curves.
TweenableValue
A value a tween knows how to interpolate: a plain number, or an object with x/y(/z(/w))
components.
TweenProps
TweenProps<
T> ={ readonly [K in keyof T as T[K] extends TweenableValue ? K : never]?: TweenTargetValue<T[K]> }
The destinations app.tweens.to accepts for a target: every numeric, Vec2, Vec3, or Quat
field of T, each one optional.
Type Parameters
T
T
The target object's type.
Example
const props: TweenProps<Transform> = { position: { x: 1, y: 2, z: 3 } };TweenTargetValue
TweenTargetValue<
V> =Vextendsnumber?number:VextendsQuatLike?QuatLike:VextendsVec3Like?Vec3Like:VextendsVec2Like?Vec2Like:never
The destination value the tween should reach for one field, narrowed to the field's own shape.
Type Parameters
V
V
The field's declared type.
Remarks
QuatLike is tested before Vec3Like because a quaternion satisfies both: { x, y, z, w } is
assignable to { x, y, z }.
TweenValueKind
TweenValueKind = typeof
TWEEN_VALUE_KINDS[number]
The union of TWEEN_VALUE_KINDS.
TwoDErrorCode
TwoDErrorCode = typeof
TwoDErrorCode[keyof typeofTwoDErrorCode]
The union of the codes the TwoDErrorCode table declares.
TwoDMode
TwoDMode = typeof
TWO_D_MODES[number]
How 2D composites with the 3D render scene.
Remarks
"sprite" is a pure 2D game: sprites are the only thing drawn. "mixed" is 2.5D — the render
scene draws first and the sprite pass composites on top without clearing, so meshes and sprites
share a frame.
UiErrorCode
UiErrorCode = typeof
UiErrorCode[keyof typeofUiErrorCode]
The union of the codes the UiErrorCode table declares.
UiScalingMode
UiScalingMode = typeof
UI_SCALING_MODES[number]
How the overlay's coordinate system relates to the canvas.
Remarks
"css"— one UI unit is one CSS pixel and nothing is scaled. The browser default, and what a responsive HTML menu wants."fit"— the root is exactly UiSettings.referenceResolution CSS pixels and is scaled uniformly to fit inside the canvas, keeping aspect and centring the letterbox. A HUD authored once at 1920x1080 then looks the same on every window size."dpi"— one UI unit is one render-target pixel: the root is sized to the canvas's backing store and scaled by1 / devicePixelRatioso it still covers the same area. This is the spaceCamera.worldToScreen,HudText, andapp.renderer.captureScreenshot()all work in, so an element placed atleft: 100pxlands on render-target column 100 exactly.
Vec2Json
Vec2Json =
Vec2Like| readonly [number,number]
A 2D value as a document may write it: [x, y], the form @ignifx/core encodes every vec2
field into a file as (schema/encode.ts line 393), or { x, y }, the form an importer emits.
Variables
ANIMATOR_ASSET_TYPE
constANIMATOR_ASSET_TYPE:"animator"="animator"
The asset type name the loader registers.
ANIMATOR_CONDITION_OPS
constANIMATOR_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
constANIMATOR_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the animator loader.
ANIMATOR_FORMAT
constANIMATOR_FORMAT:"ignifx.animator"="ignifx.animator"
The format discriminator every .animator.json document carries.
ANIMATOR_FORMAT_VERSION
constANIMATOR_FORMAT_VERSION:1=1
The document version this build reads and writes.
ANIMATOR_MASK_MODES
constANIMATOR_MASK_MODES: readonly ["include","exclude"]
How a layer's pose combines with the layers under it.
ANIMATOR_PARAMETER_KINDS
constANIMATOR_PARAMETER_KINDS: readonly ["float","int","bool","trigger"]
Every parameter kind a document can declare, in the order an inspector should list them.
ANY_KEY_CONTROL
constANY_KEY_CONTROL:"anyKey"="anyKey"
The control that is actuated while any other key is held
(docs/architecture/08-input.md §3, <Keyboard>/anyKey).
ANY_STATE
constANY_STATE:"any"="any"
The name from takes for a transition that can fire from any state on its layer.
ASSET_DIAGNOSTICS_COUNTERS
constASSET_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters the assets diagnostics group publishes, in index order.
ASSET_DIAGNOSTICS_GROUP
constASSET_DIAGNOSTICS_GROUP:"assets"="assets"
The diagnostics group name (docs/architecture/15-devtools-and-diagnostics.md §3).
ASSET_MANIFEST_FORMAT
constASSET_MANIFEST_FORMAT:"ignifx.manifest"="ignifx.manifest"
The manifest format discriminator, written into assets.manifest.json.
ASSET_MANIFEST_VERSION
constASSET_MANIFEST_VERSION:1=1
The only manifest format version this build reads.
audio
constaudio: (options?) =>Extension
The @ignifx/audio extension factory.
Parameters
options?
Overrides for the audio settings section, an audio context, and the backend
factory.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({
canvas,
extensions: [audio({ buses: "audio/buses.audio.json", masterVolume: 0.8 })],
});AUDIO_ASSET_TYPE
constAUDIO_ASSET_TYPE:"audio"="audio"
The asset type audio clips are registered under.
AUDIO_BUSES_ASSET_TYPE
constAUDIO_BUSES_ASSET_TYPE:"audiobuses"="audiobuses"
The asset type bus files are registered under.
AUDIO_BUSES_FILE_EXTENSION
constAUDIO_BUSES_FILE_EXTENSION:".audio.json"=".audio.json"
The address suffix that selects the bus loader.
AUDIO_BUSES_FORMAT
constAUDIO_BUSES_FORMAT:"ignifx.audiobuses"="ignifx.audiobuses"
The format discriminator every bus file carries.
AUDIO_BUSES_FORMAT_VERSION
constAUDIO_BUSES_FORMAT_VERSION:1=1
The bus-file format version this build reads.
AUDIO_DIAGNOSTICS_COUNTERS
constAUDIO_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters the audio diagnostics group publishes, in index order.
AUDIO_DIAGNOSTICS_GROUP
constAUDIO_DIAGNOSTICS_GROUP:"audio"="audio"
The diagnostics group name (docs/architecture/15-devtools-and-diagnostics.md §3).
AUDIO_DISTANCE_MODELS
constAUDIO_DISTANCE_MODELS: readonly ["linear","inverse","exponential"]
How distance attenuates a spatial source, matching Web Audio's distanceModel
(docs/architecture/10-audio.md §3).
AUDIO_ERROR_MESSAGES
constAUDIO_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.
AUDIO_FILE_EXTENSIONS
constAUDIO_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the audio loader
(docs/architecture/10-audio.md §2).
AUDIO_PUMP_ORDER
constAUDIO_PUMP_ORDER:-400=-400
Where the audio pump sits inside PreRender.
Remarks
After physics interpolation (-500, 04-extensions.md §1) so that a source attached to an
interpolated body is heard from its display pose, and well before the render sync (900,
packages/core/src/render/render-sync-system.ts) so that nothing audio does can disturb what is
drawn. Extensions use [1001, 9999] by convention for systems that must follow every core one;
audio has to interleave with core's own ordering instead, which is what the negative number says.
AUDIO_SETTINGS_SECTION
constAUDIO_SETTINGS_SECTION:"audio"="audio"
The section name as it appears in ignifx.config.ts.
AudioErrorCode
constAudioErrorCode:object
Every diagnostic code @ignifx/audio 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
audioDisposed
readonlyaudioDisposed:"IGX-1010"
The audio service was used after the app had been disposed.
audioEngineUnavailable
readonlyaudioEngineUnavailable:"IGX-1007"
The audio engine could not be created: no Web Audio in this host.
clipDecodeFailed
readonlyclipDecodeFailed:"IGX-1008"
A clip's bytes could not be decoded into playable audio.
duplicateBusName
readonlyduplicateBusName:"IGX-1005"
Two buses in one tree declared the same name.
invalidBusFile
readonlyinvalidBusFile:"IGX-1003"
An .audio.json file is not an ignifx.audiobuses document.
invalidBusParent
readonlyinvalidBusParent:"IGX-1006"
A bus named a parent that is not declared, or the parent chain forms a cycle.
noAudioListener
readonlynoAudioListener:"IGX-1002"
A spatial source is playing and no AudioListener is enabled; logged once per world.
streamingUnavailable
readonlystreamingUnavailable:"IGX-1009"
A streaming clip was played on a backend that cannot stream (headless has no media element).
unknownBus
readonlyunknownBus:"IGX-1001"
app.audio.bus(name), or an AudioSource.bus field, named a bus the tree does not hold.
unsupportedBusFileVersion
readonlyunsupportedBusFileVersion:"IGX-1004"
An .audio.json file declares a format version this build cannot read.
Example
throw audioError(AudioErrorCode.unknownBus, "Ambience is not a registered bus.", {
context: { bus: "Ambience" },
});BILLBOARD_MODES
constBILLBOARD_MODES: readonly ["full","yAxis"]
Every way a billboard can be constrained.
BILLBOARD_ORDER
constBILLBOARD_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.
binaryAssetLoader
constbinaryAssetLoader:AssetLoader<ArrayBuffer>
Raw bytes, for .bin and .wasm addresses — the path ignifx.assets.public binaries such as
Havok's WASM take (docs/architecture/05-assets-and-loading.md §7).
BODY_TYPES
constBODY_TYPES: readonly ["dynamic","kinematic","static"]
How a body moves.
BODY_TYPES_2D
constBODY_TYPES_2D: readonly ["dynamic","kinematic","static"]
How a 2D body moves.
CANVAS_ALPHA_MODES
constCANVAS_ALPHA_MODES: readonly ["opaque","premultiplied"]
The canvas alpha modes Lite accepts, in the order the inspector lists them.
CAPSULE_2D_DIRECTIONS
constCAPSULE_2D_DIRECTIONS: readonly ["x","y"]
The axis a 2D capsule stands along.
CAPSULE_DIRECTIONS
constCAPSULE_DIRECTIONS: readonly ["x","y","z"]
The axis a capsule stands along.
CHARACTER_SHAPES_2D
constCHARACTER_SHAPES_2D: readonly ["capsule","box"]
The collision shape a 2D character controller uses.
COLLISION_EVENT_MODES
constCOLLISION_EVENT_MODES: readonly ["auto","on","off"]
Whether collision callbacks are delivered for this body.
COLLISION_EVENT_MODES_2D
constCOLLISION_EVENT_MODES_2D: readonly ["auto","on","off"]
Whether collision callbacks are delivered for this body.
COLLISION_IDENTITY_MODES
constCOLLISION_IDENTITY_MODES: readonly ["upstream","internal"]
How collision events learn which bodies took part (09-physics.md §4, ADR-0013).
COMBINE_RULES
constCOMBINE_RULES: readonly ["average","min","multiply","max"]
How two surfaces' coefficients are combined when they touch, mirroring Rapier's
CoefficientCombineRule.
CompositeKind
constCompositeKind:object
The composites a binding may declare.
Type Declaration
axis1D
readonlyaxis1D:"1DAxis"
Two buttons read as a signed axis: negative, positive.
buttonWithModifier
readonlybuttonWithModifier:"ButtonWithModifier"
A button that only counts while a modifier is held: modifier, button.
vector2D
readonlyvector2D:"2DVector"
Four buttons read as a vector2: up, down, left, right.
ControlKind
constControlKind:object
What one control produces: a pressed/released button, a signed scalar, or a two-component vector.
Type Declaration
axis
readonlyaxis:"axis"
A signed scalar, normally in [-1, 1]. Triggers report [0, 1].
button
readonlybutton:"button"
A digital or analog button; the resting value is 0 and the actuated value is 1.
vector2
readonlyvector2:"vector2"
A two-component vector, such as a stick or a pointer position.
CORE_ERROR_MESSAGES
constCORE_ERROR_MESSAGES:Readonly<Record<CoreErrorCode,string>>
The one-line message template for every CoreErrorCode. Templates name context keys in
braces ({entity}); the throwing call site substitutes the values it has and puts the same
identifiers in IgnifxError.context so production builds stay useful without the prose.
CoreErrorCode
constCoreErrorCode:object
Every diagnostic code @ignifx/core can throw, keyed by an intention-revealing name so call
sites read as prose and the compiler catches typos (coding standards §5.2 — as const objects in
place of enums).
Type Declaration
appDisposed
readonlyappDisposed:"IGX-0106"
An app was used after app.dispose() had run.
appNotReady
readonlyappNotReady:"IGX-0107"
A part of the app was reached before createApp() had finished building it.
appPropertyAlreadyDefined
readonlyappPropertyAlreadyDefined:"IGX-0401"
Two extensions defined the same app property.
assetAppDisposed
readonlyassetAppDisposed:"IGX-0503"
An asset promise outlived the app that owned it.
assetLoadAborted
readonlyassetLoadAborted:"IGX-0502"
An asset load was aborted through its AbortSignal.
assetLoadFailed
readonlyassetLoadFailed:"IGX-0505"
An asset load failed after its last retry.
assetNoLoader
readonlyassetNoLoader:"IGX-0504"
No registered loader claims the address's type or extension.
assetNotLoaded
readonlyassetNotLoaded:"IGX-0501"
An asset's value was read before the asset finished loading.
componentNotAttached
readonlycomponentNotAttached:"IGX-0206"
A component's engine-assigned state was read before the engine attached it to an entity.
componentTypeIdMissing
readonlycomponentTypeIdMissing:"IGX-0204"
A component without a typeId was serialized.
cryptoUnavailable
readonlycryptoUnavailable:"IGX-1420"
The host exposes no Web Crypto implementation.
deferredSignalWithoutScheduler
readonlydeferredSignalWithoutScheduler:"IGX-0103"
A signal handler asked for deferred delivery on a signal that has no scheduler.
destroyImmediateInCallback
readonlydestroyImmediateInCallback:"IGX-0102"
destroyImmediate() was called from inside a lifecycle callback.
duplicateAssetLoader
readonlyduplicateAssetLoader:"IGX-0506"
Two loaders were registered for the same asset type.
duplicateComponentTypeId
readonlyduplicateComponentTypeId:"IGX-0203"
Two component types were registered under the same typeId.
duplicateDiagnosticsGroup
readonlyduplicateDiagnosticsGroup:"IGX-1503"
A diagnostics counter group was registered twice.
duplicateErrorCode
readonlyduplicateErrorCode:"IGX-1501"
An error code was registered twice.
duplicateExtensionName
readonlyduplicateExtensionName:"IGX-0406"
Two extensions were registered under the same name.
duplicateLayerName
readonlyduplicateLayerName:"IGX-0304"
Two layer slots were given the same name.
entityIsNotSceneRoot
readonlyentityIsNotSceneRoot:"IGX-0309"
An operation that only accepts a scene root was given an entity that has a parent.
extensionEngineMismatch
readonlyextensionEngineMismatch:"IGX-0404"
An extension's engine range does not match the running core version.
extensionMissing
readonlyextensionMissing:"IGX-0403"
An extension declares a requires entry that was never registered.
extensionRequiresCycle
readonlyextensionRequiresCycle:"IGX-0402"
The requires graph of the registered extensions contains a cycle.
hotReloadInsideCallback
readonlyhotReloadInsideCallback:"IGX-0208"
app.hotReload.apply() was called from inside a lifecycle callback.
hotReloadSchemaChanged
readonlyhotReloadSchemaChanged:"IGX-0207"
A hot-reloaded class kept the "patch" policy while its schema shape changed.
instanceHashMismatch
readonlyinstanceHashMismatch:"IGX-0604"
A scene instance's override hash does not match the scene file it was recorded against.
invalidAssetFile
readonlyinvalidAssetFile:"IGX-0709"
An asset file does not carry the format header its loader requires.
invalidOverridePath
readonlyinvalidOverridePath:"IGX-0609"
An instance override declares a path the override grammar does not accept.
invalidRuntime
readonlyinvalidRuntime:"IGX-0702"
A runtime handle was used after disposal, or was not created by ignifx.
invalidSettings
readonlyinvalidSettings:"IGX-0408"
A project settings section did not validate against the schema its extension registered.
invalidTimeValue
readonlyinvalidTimeValue:"IGX-0108"
A Time property was set to a value outside its documented domain.
invalidTweenOptions
readonlyinvalidTweenOptions:"IGX-0109"
A app.tweens.to(...) option was outside its documented domain.
malformedErrorCode
readonlymalformedErrorCode:"IGX-1502"
An error code does not match IGX-#### in a known range.
multipleComponentsNotAllowed
readonlymultipleComponentsNotAllowed:"IGX-0202"
A second instance of a component type that does not allow multiples was added.
multipleEnvironments
readonlymultipleEnvironments:"IGX-0705"
A second Environment was enabled in one world; the most recent one wins.
mutationAfterDestroy
readonlymutationAfterDestroy:"IGX-0101"
An entity, component, or app was used after it had been destroyed or disposed.
noEnabledCamera
readonlynoEnabledCamera:"IGX-0706"
A world rendered with no enabled camera, so nothing was drawn.
nonFiniteNumber
readonlynonFiniteNumber:"IGX-0601"
A serialized number was NaN or infinite.
notASceneFile
readonlynotASceneFile:"IGX-0308"
A file handed to the scene loader does not carry the ignifx.scene format header.
parentingCycle
readonlyparentingCycle:"IGX-0306"
Reparenting an entity under its own descendant would make the scene tree cyclic.
physicsCallbackOutsideFixedStep
readonlyphysicsCallbackOutsideFixedStep:"IGX-0409"
An extension dispatched a physics callback from outside the fixed loop.
postProcessingFeatureOff
readonlypostProcessingFeatureOff:"IGX-0710"
A PostProcessStack was attached without the postProcessing rendering feature.
renderingFeatureTooLate
readonlyrenderingFeatureTooLate:"IGX-0704"
A rendering feature opt-in was requested after the render scene had been registered.
requiredComponentMissing
readonlyrequiredComponentMissing:"IGX-0201"
A component declared through requires is missing from the entity.
sceneFileInvalid
readonlysceneFileInvalid:"IGX-0608"
A scene file failed structural validation against the generated scene-file JSON Schema.
sceneInstanceCycle
readonlysceneInstanceCycle:"IGX-0302"
Instantiating a scene would place an instance inside itself.
sceneNotLoaded
readonlysceneNotLoaded:"IGX-0301"
A scene was instantiated before it had finished loading.
sceneNotReloadable
readonlysceneNotReloadable:"IGX-1506"
app.hotReload.reloadScene() was given an instance that was not built from a scene asset.
schemaOutOfRange
readonlyschemaOutOfRange:"IGX-0606"
A value had the right type but fell outside its schema field's declared value domain.
schemaTypeMismatch
readonlyschemaTypeMismatch:"IGX-0605"
A value had the wrong JavaScript or JSON type for its schema field kind.
schemaUnknownField
readonlyschemaUnknownField:"IGX-0607"
A schema declaration or a property bag named a field the schema does not declare.
screenshotNeedsRenderLoop
readonlyscreenshotNeedsRenderLoop:"IGX-0707"
A screenshot was requested with no render loop running, so no frame will ever be presented.
serviceNotRegistered
readonlyserviceNotRegistered:"IGX-0405"
ctx.require() asked for a service that no earlier extension registered.
shadowsUnsupportedForLight
readonlyshadowsUnsupportedForLight:"IGX-0703"
Shadows were requested from a light kind Babylon Lite cannot shadow.
signalHandlerThrew
readonlysignalHandlerThrew:"IGX-0104"
A signal handler threw and no handler-error reporter was installed.
simulationSceneAlreadySet
readonlysimulationSceneAlreadySet:"IGX-0410"
A second, different simulation scene was handed to a world that already has one.
stepOutsideHeadless
readonlystepOutsideHeadless:"IGX-0105"
app.step() was called while Babylon Lite's render loop was driving the frames.
storageBackendFailed
readonlystorageBackendFailed:"IGX-1425"
The storage backend failed for a reason the engine cannot classify.
storageInvalidKey
readonlystorageInvalidKey:"IGX-1422"
A storage key is empty, too long, or contains a control character.
storageInvalidNamespace
readonlystorageInvalidNamespace:"IGX-1421"
A storage namespace name is not a legal namespace segment.
storageQuotaExceeded
readonlystorageQuotaExceeded:"IGX-1424"
The storage backend refused a write because the host is out of quota or disk space.
storageValueCorrupt
readonlystorageValueCorrupt:"IGX-1426"
A stored value could not be read back; the store was damaged or written by something else.
storageValueNotSerializable
readonlystorageValueNotSerializable:"IGX-1423"
A value handed to app.storage.set has no JSON form.
tooManyLayers
readonlytooManyLayers:"IGX-0305"
The project settings declare more layer names than the 32 available slots.
transformIsNotRemovable
readonlytransformIsNotRemovable:"IGX-0205"
Transform was removed or disabled; every entity must keep exactly one enabled transform.
tweenFieldNotTweenable
readonlytweenFieldNotTweenable:"IGX-0110"
A tweened field is not a number, Vec2, Vec3, or Quat, or is not writable.
unknownComponentTypeId
readonlyunknownComponentTypeId:"IGX-0307"
A scene file names a component typeId that no extension has registered.
unknownDiagnosticsCounter
readonlyunknownDiagnosticsCounter:"IGX-1504"
A diagnostics counter name was not declared when its group was registered.
unknownLayer
readonlyunknownLayer:"IGX-0303"
A layer name that the project settings do not declare was used.
unknownSettingsSection
readonlyunknownSettingsSection:"IGX-0407"
ctx.settings() asked for a settings section that was never registered.
unreachableCase
readonlyunreachableCase:"IGX-1505"
A switch over a union reached a case the type system said was impossible.
unresolvedReference
readonlyunresolvedReference:"IGX-0602"
A serialized $entity/$component reference could not be resolved.
unsupportedFormatVersion
readonlyunsupportedFormatVersion:"IGX-0603"
A scene, prefab, or manifest declares a format version this build cannot read.
unsupportedMaterialKind
readonlyunsupportedMaterialKind:"IGX-0708"
A material file declares a family this build cannot construct.
webGpuUnavailable
readonlywebGpuUnavailable:"IGX-0701"
WebGPU is not available in the current environment.
Example
throw new IgnifxError(CoreErrorCode.mutationAfterDestroy, "The entity has been destroyed.", {
context: { entity: entity.uid },
});Remarks
Code blocks reserved for other first-party packages, which cannot import this table
(docs/architecture/00-overview.md §2): @ignifx/cli owns IGX-1401–IGX-1419; @ignifx/electron
owns IGX-1460–IGX-1499 (core's own platform codes therefore stop at IGX-1459); @ignifx/devtools
owns IGX-1550–IGX-1599 (core's own devtools-range codes stop at IGX-1549);
@ignifx/vite-plugin owns IGX-0550–IGX-0599 and IGX-0650–IGX-0699. Core allocates its
own codes from the bottom of each range and, in the platform range, from IGX-1420 upward —
which is where app.platform and app.storage live, because storage is a platform service:
the same three calls resolve to IndexedDB, a directory, or the Electron bridge depending only on
the host, so a failure is a platform failure and not a serialization or asset one.
coreExtension
constcoreExtension: (options?) =>Extension
Builds the extension createApp always puts first (docs/architecture/04-extensions.md §2
rule 1).
Parameters
options?
void
Returns
The core extension descriptor.
Example
// createApp does this for you; the list is only ever built by the kernel.
const extensions = [coreExtension(), physics(), input()];DEFAULT_ASSET_CONCURRENCY
constDEFAULT_ASSET_CONCURRENCY:6=6
The concurrency limit an unconfigured queue uses (§4).
DEFAULT_ASSET_ROOT
constDEFAULT_ASSET_ROOT:"assets"="assets"
The asset root a project gets when it configures none (§2).
DEFAULT_AUDIO_BUSES
constDEFAULT_AUDIO_BUSES: readonlystring[]
The bus tree built when a project declares no .audio.json
(docs/architecture/10-audio.md §1). Every bus after the first routes into "Master".
DEFAULT_BRDF_LUT_ADDRESS
constDEFAULT_BRDF_LUT_ADDRESS:"environments/brdf-lut.png"="environments/brdf-lut.png"
The BRDF lookup table address an Environment uses when neither it nor the project names one.
DEFAULT_CHUNK_SIZE
constDEFAULT_CHUNK_SIZE:32=32
How many cells one chunk spans by default (docs/architecture/11-2d-toolkit.md §2.5).
DEFAULT_CLIP_FPS
constDEFAULT_CLIP_FPS:12=12
The frames-per-second a clip that declares none plays at.
DEFAULT_CLIP_LENGTH
constDEFAULT_CLIP_LENGTH:1=1
How long a clip whose length nobody has declared is assumed to be, in seconds.
DEFAULT_DEVTOOLS_LOG_LIMIT
constDEFAULT_DEVTOOLS_LOG_LIMIT:500=500
How many records createDevtoolsLogSink keeps when no limit is given. Five hundred lines is about a screenful of scrollback at the Console panel's row height and costs a few tens of kilobytes.
DEFAULT_LAYER
constDEFAULT_LAYER:0=0
The slot every entity starts on, and the fallback for an unknown name in a file.
DEFAULT_MEMORY_SINK_LIMIT
constDEFAULT_MEMORY_SINK_LIMIT:200=200
How many records createMemorySink keeps when no limit is given.
DEFAULT_ORTHOGRAPHIC_SIZE
constDEFAULT_ORTHOGRAPHIC_SIZE:5=5
The half-height, in metres, a camera that declares none shows.
DEFAULT_PAUSABLE_BUSES
constDEFAULT_PAUSABLE_BUSES: readonlystring[]
The buses app.pause() pauses by default: all of them except "UI", so a pause menu can still
click (docs/architecture/10-audio.md §6).
DEFAULT_PIXELS_PER_UNIT
constDEFAULT_PIXELS_PER_UNIT:100=100
The default pixels-per-unit, matching twoD.pixelsPerUnit
(docs/architecture/11-2d-toolkit.md §1). At 100, a 32-pixel sprite is 0.32 metres wide.
DEFAULT_REFERENCE_RESOLUTION
constDEFAULT_REFERENCE_RESOLUTION:Vec2Like
The reference resolution a pixel-perfect camera fits an integer zoom to.
DEFAULT_SORTING_LAYER
constDEFAULT_SORTING_LAYER:"Default"="Default"
The sorting layer a component that names none draws on.
DEFAULT_SOUND_BUS
constDEFAULT_SOUND_BUS:"SFX"="SFX"
The bus app.audio.playOneShot and a fresh AudioSource route into.
DEFAULT_STORAGE_NAMESPACE
constDEFAULT_STORAGE_NAMESPACE:"default"="default"
The namespace app.storage itself reads and writes before namespace(name) is called.
Remarks
Every backend call carries a namespace, so the root storage needs a name of its own rather than
an empty string that each backend would have to special-case. "default" is a legal namespace
name, which means a game that writes app.storage.namespace("default") reaches the same values —
intentionally, since the two are the same store.
DEG_TO_RAD
constDEG_TO_RAD:number
Multiplier that converts degrees to radians.
DEVICE_KINDS
constDEVICE_KINDS: readonlyDeviceKind[]
Every device family, in the order app.input.devices.all reports them.
DeviceKind
constDeviceKind:object
The device families a binding path can name.
Type Declaration
gamepad
readonlygamepad:"Gamepad"
A game controller in the W3C standard mapping.
keyboard
readonlykeyboard:"Keyboard"
Physical keys, addressed by KeyboardEvent.code.
mouse
readonlymouse:"Mouse"
The mouse: three buttons, position, delta, and the wheel.
pointer
readonlypointer:"Pointer"
The unified primary pointer: mouse, pen, or the first touch.
touch
readonlytouch:"Touch"
Up to ten simultaneous touches.
virtual
readonlyvirtual:"Virtual"
A synthetic device fed by on-screen controls.
devtools
constdevtools: (options?) =>Extension
The @ignifx/devtools extension factory.
Parameters
options?
Overrides for the devtools settings section, plus the Console panel's sink.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({ canvas, extensions: [devtools({ toggleKey: "F1" })] });
app.devtools.open();DEVTOOLS_CLASS_NAMES
constDEVTOOLS_CLASS_NAMES:object
Every class name the overlay writes, so a game that wants to restyle the panels has names to target and the source has no string literals scattered through it.
Type Declaration
body
readonlybody:"ignifx-devtools-body"
The panel body under the tab strip.
button
readonlybutton:"ignifx-devtools-button"
A small push button.
canvas
readonlycanvas:"ignifx-devtools-canvas"
The timeline canvas.
heading
readonlyheading:"ignifx-devtools-heading"
A section heading inside a panel.
input
readonlyinput:"ignifx-devtools-input"
A text input, number input, or select.
label
readonlylabel:"ignifx-devtools-label"
The label half of a row.
line
readonlyline:"ignifx-devtools-line"
One console line.
node
readonlynode:"ignifx-devtools-node"
A tree row in the scene panel.
nodeSelected
readonlynodeSelected:"ignifx-devtools-node-selected"
The selected tree row.
panel
readonlypanel:"ignifx-devtools-panel"
One panel's own container.
root
readonlyroot:"ignifx-devtools"
The overlay root, docked to one edge of the canvas.
row
readonlyrow:"ignifx-devtools-row"
A label/value row.
tab
readonlytab:"ignifx-devtools-tab"
One tab button.
tabActive
readonlytabActive:"ignifx-devtools-tab-active"
The active tab button.
tabs
readonlytabs:"ignifx-devtools-tabs"
The tab strip along the top of the root.
toolbar
readonlytoolbar:"ignifx-devtools-toolbar"
A toolbar strip inside a panel.
value
readonlyvalue:"ignifx-devtools-value"
The value half of a row.
DEVTOOLS_ERROR_LIMIT
constDEVTOOLS_ERROR_LIMIT:50=50
How many app.onError reports the Console panel retains while the overlay is open. Reports that
arrive while it is closed are not retained: a closed overlay holds no subscription.
DEVTOOLS_ERROR_MESSAGES
constDEVTOOLS_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.
DEVTOOLS_HOT_RELOAD_LIMIT
constDEVTOOLS_HOT_RELOAD_LIMIT:20=20
How many app.hotReload reports the Console and Stats panels retain
(docs/architecture/15-devtools-and-diagnostics.md §5).
DEVTOOLS_LAYER_Z_INDEX
constDEVTOOLS_LAYER_Z_INDEX:1000000=1e6
The z-index the app.ui devtools layer is created at: above every layer a game is likely to
declare, so the overlay is never behind a HUD.
DEVTOOLS_LOG_LEVELS
constDEVTOOLS_LOG_LEVELS: readonlyLogLevel[]
The levels the Console panel's filter offers, lowest first.
DEVTOOLS_PANEL_NAMES
constDEVTOOLS_PANEL_NAMES: readonly ["stats","scene","inspector","assets","input","audio","physics","console","timeline"]
Every panel name, in the order 15-devtools-and-diagnostics.md §4 lists them. The panels
setting is a re-ordering — and, by omission, a filter — of this list.
DEVTOOLS_POSITIONS
constDEVTOOLS_POSITIONS: readonly ["right","left","top","bottom"]
Where the overlay is docked against the canvas.
DEVTOOLS_SAMPLE_ORDER
constDEVTOOLS_SAMPLE_ORDER:9000=9e3
The Phase.PreRender order the sampler runs at: after every renderer, 2D, UI and audio system,
and inside the [1001, 9999] band docs/architecture/04-extensions.md gives extensions.
DEVTOOLS_SETTINGS_SECTION
constDEVTOOLS_SETTINGS_SECTION:"devtools"="devtools"
The section name as it appears in ignifx.config.ts.
DEVTOOLS_STYLE_ELEMENT_ID
constDEVTOOLS_STYLE_ELEMENT_ID:"ignifx-devtools-styles"="ignifx-devtools-styles"
The id of the injected <style> element.
DEVTOOLS_UI_LAYER
constDEVTOOLS_UI_LAYER:"devtools"="devtools"
The name of the app.ui layer the overlay mounts into when @ignifx/ui is registered. A game
that wants to style or hide the overlay reaches it as app.ui.layer(DEVTOOLS_UI_LAYER).
DevtoolsErrorCode
constDevtoolsErrorCode:object
Every diagnostic code @ignifx/devtools 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
assetReloadUnsupported
readonlyassetReloadUnsupported:"IGX-1555"
The Assets panel's reload button was pressed on an asset service with no reload entry point.
duplicateExtension
readonlyduplicateExtension:"IGX-1550"
A second devtools() extension was registered on one app.
fieldWriteFailed
readonlyfieldWriteFailed:"IGX-1554"
An inspector write could not be decoded into the field's value type.
headlessNoOp
readonlyheadlessNoOp:"IGX-1551"
A DOM-only member was reached on a host with no document, and did nothing.
pickUnavailable
readonlypickUnavailable:"IGX-1557"
"Select in world" was used on an app whose renderer cannot pick.
readonlyField
readonlyreadonlyField:"IGX-1553"
An inspector write targeted a field the schema marks readonly or hidden.
sceneReloadUnsupported
readonlysceneReloadUnsupported:"IGX-1556"
reloadScenes is on but neither core nor app.hotReload can re-instantiate a scene.
unknownPanel
readonlyunknownPanel:"IGX-1552"
app.devtools.panel(name) was given a name no panel is registered under.
Example
throw devtoolsError(DevtoolsErrorCode.unknownPanel, "scene-graph is not a devtools panel.", {
context: { panel: "scene-graph" },
});EASING_NAMES
constEASING_NAMES: readonly ["linear","quadIn","quadOut","quadInOut","cubicIn","cubicOut","cubicInOut","sineInOut","backOut","elasticOut","bounceOut"]
The names EASINGS declares, in table order (coding standards §5.2 — an as const table
and the union derived from it, never an enum).
EASINGS
constEASINGS:Readonly<Record<string,EasingFunction>>
Every named easing curve, keyed by the name TweenOptions.ease accepts.
Example
const halfway = EASINGS.cubicInOut(0.5); // 0.5electron
constelectron: (options?) =>Extension
The @ignifx/electron extension factory.
Parameters
options?
The three switches in ElectronOptions; a game passes none.
Returns
The extension descriptor to pass to createApp.
Example
import { createApp } from "@ignifx/core";
import { electron } from "@ignifx/electron";
const app = await createApp({
canvas,
extensions: [physics(), input(), audio(), electron()],
});
app.desktop.isElectron; // true in a desktop build, false in a browser tabELECTRON_ERROR_MESSAGES
constELECTRON_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.
ELECTRON_STORAGE_BACKEND_NAME
constELECTRON_STORAGE_BACKEND_NAME:"electron-file"="electron-file"
The name this backend reports, as StorageBackend.name requires.
ElectronErrorCode
constElectronErrorCode:object
Every diagnostic code @ignifx/electron can throw, keyed by an intention-revealing name so call
sites read as prose and the compiler catches typos (coding standards §5.2).
Type Declaration
externalUrlRefused
readonlyexternalUrlRefused:"IGX-1464"
openExternal was handed a URL whose protocol is not on the allow-list.
hostCallFailed
readonlyhostCallFailed:"IGX-1463"
The main process refused an IPC request, or the handler threw.
hostContractIncomplete
readonlyhostContractIncomplete:"IGX-1461"
window.ignifxHost exists but is missing a method the renderer needs.
hostUnavailable
readonlyhostUnavailable:"IGX-1462"
app.desktop was used on an app whose Electron extension found no host bridge.
hostVersionMismatch
readonlyhostVersionMismatch:"IGX-1460"
window.ignifxHost exists but announces a major version this build cannot talk to.
invalidWindowOptions
readonlyinvalidWindowOptions:"IGX-1466"
createGameWindow was given options that cannot be honoured together.
protocolPathEscaped
readonlyprotocolPathEscaped:"IGX-1465"
An ignifx:// request resolved outside the directory the protocol serves.
Example
throw electronError(ElectronErrorCode.hostVersionMismatch, "The preload bridge is too old.", {
context: { host: "2.0.0", expected: "1.x" },
});EMPTY_ASSET_MANIFEST
constEMPTY_ASSET_MANIFEST:AssetManifest
The manifest an app uses until a build supplies one.
EMPTY_TILE_ID
constEMPTY_TILE_ID:0=0
The tile id that means "this cell is empty"; no tileset may claim it.
ENVIRONMENT_ASSET_TYPE
constENVIRONMENT_ASSET_TYPE:"environment"="environment"
The asset type environments are registered under.
ENVIRONMENT_FILE_EXTENSION
constENVIRONMENT_FILE_EXTENSION:".environment.json"=".environment.json"
The address suffix that selects the environment description file.
ENVIRONMENT_FILE_EXTENSIONS
constENVIRONMENT_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the environment loader.
ENVIRONMENT_FILE_FORMAT
constENVIRONMENT_FILE_FORMAT:"ignifx.environment"="ignifx.environment"
The format header an .environment.json carries
(docs/architecture/06-serialization-and-scene-format.md §6).
ENVIRONMENT_FORMAT_VERSION
constENVIRONMENT_FORMAT_VERSION:1=1
The only .environment.json formatVersion this build reads.
EPSILON
constEPSILON:number
The default tolerance for approximate float comparisons. Chosen for single-precision positions in
metres: Float32Array round-tripping loses roughly 1e-7 of relative precision, so 1e-6 is the
smallest value that does not report false differences on data that has been through the GPU.
ErrorRange
constErrorRange:object
The two-digit prefix each subsystem owns inside the IGX-#### space
(docs/architecture/15-devtools-and-diagnostics.md §1). A code is the prefix followed by a
two-digit ordinal, so rendering owns IGX-0700 through IGX-0799.
Type Declaration
assets
readonlyassets:"05"
Asset handles, loaders, and caching.
audio
readonlyaudio:"10"
Audio buses, sources, and clips.
components
readonlycomponents:"02"
Components, scripts, and their registration.
devtools
readonlydevtools:"15"
Devtools, logging, and diagnostics.
extensions
readonlyextensions:"04"
The extension host and its contract.
input
readonlyinput:"08"
Input devices, actions, and bindings.
lifecycle
readonlylifecycle:"01"
App lifecycle, phases, time, coroutines, destruction.
physics
readonlyphysics:"09"
3D physics.
platform
readonlyplatform:"14"
Platform integration (browser, Electron).
rendering
readonlyrendering:"07"
The renderer and the Babylon Lite adapter.
scenes
readonlyscenes:"03"
Scenes, scene instances, layers.
serialization
readonlyserialization:"06"
Schemas, scene/prefab JSON, references.
threeD
readonlythreeD:"12"
The 3D toolkit.
twoD
readonlytwoD:"11"
The 2D toolkit.
ui
readonlyui:"13"
The UI overlay.
Example
const code = `IGX-${ErrorRange.rendering}01` satisfies ErrorCode; // "IGX-0701"FieldKind
constFieldKind:object
Every field kind a component schema can declare
(docs/architecture/03-scripting-and-components.md §3). Declared as an as const table with a
derived union rather than an enum, which erasableSyntaxOnly bans (coding standards §5.2).
Type Declaration
array
readonlyarray:"array"
A list of values of one kind.
asset
readonlyasset:"asset"
A reference to an addressable asset.
bool
readonlybool:"bool"
A boolean toggle.
color
readonlycolor:"color"
An RGBA color.
componentRef
readonlycomponentRef:"componentRef"
A reference to a component on an entity in the same scene file.
curve
readonlycurve:"curve"
An animation curve.
custom
readonlycustom:"custom"
A value with a hand-written encoder and decoder.
entityRef
readonlyentityRef:"entityRef"
A reference to another entity in the same scene file.
enum
readonlyenum:"enum"
One of a fixed set of string values.
f32
readonlyf32:"f32"
A 32-bit-ranged floating point number.
f64
readonlyf64:"f64"
A double-precision floating point number.
i32
readonlyi32:"i32"
A signed 32-bit integer.
layerMask
readonlylayerMask:"layerMask"
A set of layer names.
map
readonlymap:"map"
A string-keyed dictionary of values of one kind.
optional
readonlyoptional:"optional"
A value that may also be null.
quat
readonlyquat:"quat"
A rotation quaternion.
record
readonlyrecord:"record"
A fixed group of named sub-fields.
str
readonlystr:"str"
A UTF-8 string.
u32
readonlyu32:"u32"
An unsigned 32-bit integer.
vec2
readonlyvec2:"vec2"
A 2D vector.
vec3
readonlyvec3:"vec3"
A 3D vector.
vec4
readonlyvec4:"vec4"
A 4D vector.
FOG_MODE_NAMES
constFOG_MODE_NAMES: readonly ["none","linear","exp","exp2"]
The as const name table behind the public union of the same name.
FONT_ASSET_TYPE
constFONT_ASSET_TYPE:"font"="font"
The asset type fonts are registered under.
FONT_FILE_EXTENSIONS
constFONT_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the font loader.
FRAME_HISTORY_LENGTH
constFRAME_HISTORY_LENGTH:300=300
How many frames of history Diagnostics keeps by default — five seconds at 60 fps, which is
what the devtools graphs plot (docs/architecture/15-devtools-and-diagnostics.md §3).
GAMEPAD_REMAPS
constGAMEPAD_REMAPS: readonlyGamepadRemap[]
The remaps this build ships. Both entries are pads that report an empty mapping string in at
least one browser and lay their buttons out differently from the standard order.
GAMEPAD_SLOTS
constGAMEPAD_SLOTS:4=4
How many gamepad slots the service tracks (docs/architecture/08-input.md §1).
HAVOK_WASM_AUTO
constHAVOK_WASM_AUTO:"auto"="auto"
The value PhysicsSettings.havokWasm carries when the address comes from the manifest.
HOST_CHANNELS
constHOST_CHANNELS:object
The IPC channel names the preload script invokes and the main process handles.
Type Declaration
dialogsShowOpen
readonlydialogsShowOpen:"ignifx:dialogs.showOpenDialog"
dialogs.showOpenDialog(options).
paths
readonlypaths:"ignifx:paths"
paths().
shellOpenExternal
readonlyshellOpenExternal:"ignifx:shell.openExternal"
shell.openExternal(url).
storageClear
readonlystorageClear:"ignifx:storage.clear"
storage.clear(namespace).
storageDelete
readonlystorageDelete:"ignifx:storage.delete"
storage.delete(namespace, key).
storageGet
readonlystorageGet:"ignifx:storage.get"
storage.get(namespace, key).
storageKeys
readonlystorageKeys:"ignifx:storage.keys"
storage.keys(namespace, prefix).
storageSet
readonlystorageSet:"ignifx:storage.set"
storage.set(namespace, key, value).
windowIsFullscreen
readonlywindowIsFullscreen:"ignifx:window.isFullscreen"
window.isFullscreen().
windowQuit
readonlywindowQuit:"ignifx:window.quit"
window.quit().
windowSetFullscreen
readonlywindowSetFullscreen:"ignifx:window.setFullscreen"
window.setFullscreen(fullscreen).
windowSetTitle
readonlywindowSetTitle:"ignifx:window.setTitle"
window.setTitle(title).
Remarks
One flat as const table rather than a nested one: the values are what both processes must agree
on literally, and a flat table is what a switch over channels can be exhaustive against
(coding standards §5.2).
HOST_CONTRACT_MAJOR
constHOST_CONTRACT_MAJOR:1=1
The major component of HOST_CONTRACT_VERSION, which is what compatibility is decided on.
HOST_CONTRACT_VERSION
constHOST_CONTRACT_VERSION:"1.0.0"="1.0.0"
The version of this contract that the preload bridge announces as window.ignifxHost.version.
Remarks
Semver over the bridge, not over the package: the renderer refuses a host whose major differs
from its own, because a preload script from a different install is the one thing a packaged app
can genuinely end up with (an asar from a previous build, a partially applied update).
HOST_GLOBAL_NAME
constHOST_GLOBAL_NAME:"ignifxHost"="ignifxHost"
The property contextBridge exposes the host under.
HOST_WINDOW_EVENT_CHANNEL
constHOST_WINDOW_EVENT_CHANNEL:"ignifx:window-event"="ignifx:window-event"
The one main-to-renderer channel: window lifecycle events, pushed rather than polled.
HUD_ANCHORS
constHUD_ANCHORS: readonly ["topLeft","top","topRight","left","center","right","bottomLeft","bottom","bottomRight"]
The nine points of a rectangle a block can be anchored to.
I18N_ASSET_TYPE
constI18N_ASSET_TYPE:"i18n"="i18n"
The asset type translation documents are registered under.
I18N_FILE_EXTENSIONS
constI18N_FILE_EXTENSIONS: readonlystring[]
The file extensions the translation loader claims.
I18N_FORMAT
constI18N_FORMAT:"ignifx.i18n"="ignifx.i18n"
The format discriminator every translation document carries.
I18N_FORMAT_VERSION
constI18N_FORMAT_VERSION:1=1
The formatVersion this build writes and is the only one it can read. Before 1.0 the number
stays 1 and an incompatible change invalidates files rather than migrating them
(CONSTITUTION.md §4.2); a file declaring anything else is rejected with IGX-1302.
IGNIFX_HOST_AUTHORITY
constIGNIFX_HOST_AUTHORITY:"app"="app"
The authority the packaged renderer is served under, so the whole origin reads
ignifx://app.
Remarks
A privileged standard scheme has a real origin, and a real origin is what makes 'self' in the
Content-Security-Policy mean "the packaged app" rather than nothing at all.
IGNIFX_ORIGIN
constIGNIFX_ORIGIN:string
The origin the packaged renderer runs on: ignifx://app.
IGNIFX_SCHEME
constIGNIFX_SCHEME:"ignifx"="ignifx"
The ignifx:// scheme the packaged renderer is served from.
input
constinput: (options?) =>Extension
The @ignifx/input extension factory.
Parameters
options?
Overrides for the input settings section, and the gamepad reader.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({
canvas,
extensions: [input({ actions: "input/default.input.json" })],
});INPUT_ACTIONS_ASSET_TYPE
constINPUT_ACTIONS_ASSET_TYPE:"inputactions"="inputactions"
The asset type name input action documents are registered under.
INPUT_ACTIONS_FILE_EXTENSIONS
constINPUT_ACTIONS_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the inputactions loader.
INPUT_ACTIONS_FORMAT
constINPUT_ACTIONS_FORMAT:"ignifx.inputactions"="ignifx.inputactions"
The format discriminator of an input actions document.
INPUT_ACTIONS_FORMAT_VERSION
constINPUT_ACTIONS_FORMAT_VERSION:1=1
The format version this build reads and writes.
INPUT_DIAGNOSTICS_COUNTERS
constINPUT_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters the input diagnostics group publishes, in index order.
INPUT_DIAGNOSTICS_GROUP
constINPUT_DIAGNOSTICS_GROUP:"input"="input"
The diagnostics group name (docs/architecture/08-input.md §9).
INPUT_ERROR_MESSAGES
constINPUT_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.
INPUT_OVERRIDES_FORMAT
constINPUT_OVERRIDES_FORMAT:"ignifx.inputoverrides"="ignifx.inputoverrides"
The format discriminator of an override document.
INPUT_OVERRIDES_FORMAT_VERSION
constINPUT_OVERRIDES_FORMAT_VERSION:1=1
The override format version this build reads and writes.
INPUT_RESOLVE_ORDER
constINPUT_RESOLVE_ORDER:-950=-950
Where the input system sits in PreUpdate. Core delivers assets at -900, so -950 puts input
first: a script woken by an asset delivered this frame already sees this frame's input.
INPUT_SETTINGS_SECTION
constINPUT_SETTINGS_SECTION:"input"="input"
The section name as it appears in ignifx.config.ts.
InputErrorCode
constInputErrorCode:object
Every diagnostic code @ignifx/input can throw, keyed by an intention-revealing name so call
sites read as prose and the compiler catches typos (coding standards §5.2).
Type Declaration
duplicateName
readonlyduplicateName:"IGX-0810"
Two actions in one map, or two maps in one asset, declared the same name.
invalidActionsFile
readonlyinvalidActionsFile:"IGX-0805"
An .input.json file is not an ignifx.inputactions document this build can read.
invalidBindingPath
readonlyinvalidBindingPath:"IGX-0803"
A binding path is malformed, or names a device or control that does not exist.
invalidOverrides
readonlyinvalidOverrides:"IGX-0808"
A saved override document is not an ignifx.inputoverrides document this build can read.
pointerLockUnavailable
readonlypointerLockUnavailable:"IGX-0809"
Pointer lock was requested on an app that has no DOM canvas to lock.
rebindInProgress
readonlyrebindInProgress:"IGX-0807"
A second interactive rebind was started while one was still listening.
unknownAction
readonlyunknownAction:"IGX-0801"
app.input.actions.get(name) found no such action in any enabled map.
unknownActionMap
readonlyunknownActionMap:"IGX-0804"
app.input.actions.map(name) found no such action map.
unknownComposite
readonlyunknownComposite:"IGX-0806"
A binding declared a composite that is not 2DVector, 1DAxis, or ButtonWithModifier.
unknownProcessor
readonlyunknownProcessor:"IGX-0802"
A binding named a processor that is not one of the five built-in ones.
Example
throw inputError(InputErrorCode.unknownAction, "No enabled action map declares jump.", {
context: { action: "jump" },
});INTERPOLATION_MODES
constINTERPOLATION_MODES: readonly ["none","interpolate"]
Whether a body's display pose is interpolated between fixed steps.
INTERPOLATION_MODES_2D
constINTERPOLATION_MODES_2D: readonly ["none","interpolate"]
Whether a body's display pose is interpolated between fixed steps.
INVALID_HANDLE
constINVALID_HANDLE:0=0
The handle value that never resolves. Allocated handles always carry a generation of at least one, so zero is unreachable and doubles as "no handle".
jsonAssetLoader
constjsonAssetLoader:AssetLoader
Parsed JSON, for .json addresses.
Remarks
The value is whatever the file contained; a loader that needs certainty about its shape validates
it with a schema (docs/architecture/06-serialization-and-scene-format.md §8). Longer suffixes
win the extension match, so registering a .scene.json loader takes those addresses away from
this one without any ordering rule.
Example
const config = app.assets.load<{ readonly hp: number }>("data/player.json");KINEMATIC_SYNC_MODES
constKINEMATIC_SYNC_MODES: readonly ["teleport","velocity"]
How a moved kinematic node reaches Havok.
LDTK_DEFAULT_INTGRID_COLLIDERS
constLDTK_DEFAULT_INTGRID_COLLIDERS:Readonly<Record<number,TileColliderDefinition>>
The default meaning of an LDtk IntGrid value, in cell-normalised top-left-origin units.
Remarks
1 is "solid" — the whole cell collides. 2 is "one-way" — the top quarter of the cell collides,
and only from above. Those two conventions cover the LDtk projects people actually ship, and
anything else is project-specific, so LdtkImportOptions.intGridColliders replaces this
table wholesale. An IntGrid value with no entry still gets a tile id and a frame; it simply does
not collide.
LDTK_INTGRID_TILESET_NAME
constLDTK_INTGRID_TILESET_NAME:"intgrid"="intgrid"
The name given to the synthetic tileset that carries IntGrid colliders.
LIGHT_TYPES
constLIGHT_TYPES: readonly ["directional","point","spot","hemispheric"]
The as const name table behind the public union of the same name.
LOD_CULLED
constLOD_CULLED:-1=-1
The level index meaning "past the last level; draw nothing".
LOD_ORDER
constLOD_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.
LOG_LEVEL_SEVERITY
constLOG_LEVEL_SEVERITY:Readonly<Record<LogThreshold,number>>
The numeric severity of each threshold. A record is written when its level's severity is greater
than or equal to the logger's threshold severity, which is why "silent" sits above "error".
LogLevel
constLogLevel:object
The severity of a log record.
Type Declaration
debug
readonlydebug:"debug"
Verbose engine tracing; off by default.
error
readonlyerror:"error"
Something failed; usually paired with an app.onError report.
info
readonlyinfo:"info"
Lifecycle milestones a developer wants to see once.
warn
readonlywarn:"warn"
Something is wrong but the frame continues.
Remarks
as const object plus derived union rather than an enum (coding standards §5.2, §5.3).
MAT4_IDENTITY
constMAT4_IDENTITY:Mat4Like
A frozen identity matrix, for the common case of "no transform". It is a plain Mat4Like
rather than a Mat4 because a Float32Array cannot be frozen — pass it to anything that
reads a matrix, and use new Mat4() when you need one you can write to.
Example
Mat4.transformPointToRef(MAT4_IDENTITY, point, out); // copies the pointMATERIAL_ALPHA_MODE_NAMES
constMATERIAL_ALPHA_MODE_NAMES: readonlyMaterialAlphaModeName[]
The alpha modes a material may declare, in the order the inspector lists them.
MATERIAL_ASSET_TYPE
constMATERIAL_ASSET_TYPE:"material"="material"
The asset type materials are registered under.
MATERIAL_FILE_EXTENSION
constMATERIAL_FILE_EXTENSION:".material.json"=".material.json"
The address suffix that selects the material loader.
MATERIAL_FILE_FORMAT
constMATERIAL_FILE_FORMAT:"ignifx.material"="ignifx.material"
The format header every .material.json carries.
MATERIAL_FORMAT_VERSION
constMATERIAL_FORMAT_VERSION:1=1
The only .material.json formatVersion this build reads.
MATERIAL_KINDS
constMATERIAL_KINDS: readonly ["pbr","standard","shader"]
The material families .material.json can declare
(docs/architecture/07-rendering.md §2.6).
MAX_LAYERS
constMAX_LAYERS:32=32
How many layer slots exist. One bit each, in a 32-bit mask.
MAX_ULID_TIME_MS
constMAX_ULID_TIME_MS:number
The largest timestamp a ULID can encode, in milliseconds since the Unix epoch. Readings beyond it are clamped rather than producing a malformed identifier.
MESH_ASSET_TYPE
constMESH_ASSET_TYPE:"mesh"="mesh"
The asset type primitives are registered under.
MODEL_ASSET_TYPE
constMODEL_ASSET_TYPE:"model"="model"
The asset type models are registered under.
MODEL_FILE_EXTENSIONS
constMODEL_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the model loader.
NAMESPACE_SEGMENT_MAX_LENGTH
constNAMESPACE_SEGMENT_MAX_LENGTH:64=64
The longest one segment of a namespace path may be.
NAV_OBSTACLE_SHAPES
constNAV_OBSTACLE_SHAPES: readonly ["box","cylinder"]
Every obstacle shape Lite's tile cache supports.
NAVIGATION_ORDER
constNAVIGATION_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.
PBR_TEXTURE_SLOTS
constPBR_TEXTURE_SLOTS: readonlystring[]
The texture slots a "pbr" material may name, in the order the loader resolves them.
Phase
constPhase:object
The ordered frame phases (docs/architecture/01-lifecycle-and-time.md §3). The ordinals are the
order the frame function walks them in, and they index the per-phase CPU timings in
FrameSample.cpuMs.
Type Declaration
EndOfFrame
readonlyEndOfFrame:0
Deferred signal deliveries and end-of-frame systems, drained at the start of the next frame.
FixedUpdate
readonlyFixedUpdate:2
The fixed-timestep simulation loop: fixedUpdate, physics, collision dispatch.
PostUpdate
readonlyPostUpdate:4
Animation, state machines, and tweens, between update and lateUpdate.
PreRender
readonlyPreRender:5
Render synchronisation: interpolation, sprite and camera sync, audio, diagnostics.
PreUpdate
readonlyPreUpdate:1
Input polling and asset delivery, before any script callback.
Update
readonlyUpdate:3
update on every enabled script, then coroutine resumption.
Remarks
EndOfFrame is ordinal 0 because the work it carries is drained at the top of the next
frame, before the clock advances; the name describes when the work was queued, the ordinal
describes when it runs.
Example
ctx.registerSystem(new SpriteSyncSystem(), { phase: Phase.PreRender, order: 100 });PHASE_COUNT
constPHASE_COUNT:6=6
How many update phases the frame loop times. The kernel owns the Phase names and their ordinals;
diagnostics only needs to know how many slots to preallocate, which keeps the two modules
independent.
PHASE_NAMES
constPHASE_NAMES: readonlystring[]
The display name of each phase, indexed by its ordinal. Used by diagnostics and error messages.
PHASES
constPHASES: readonlyPhase[]
Every phase in frame order, for loops that walk them all.
physics
constphysics: (options?) =>Extension
Builds the physics extension.
Parameters
options?
The collision-identity mode and, optionally, where Havok comes from.
Returns
The extension descriptor.
Example
const app = await createApp({ headless: true, extensions: [physics()] });PHYSICS_2D_DIAGNOSTICS_COUNTERS
constPHYSICS_2D_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters 09-physics.md §9 and 11-2d-toolkit.md §8 name for 2D.
PHYSICS_2D_DIAGNOSTICS_GROUP
constPHYSICS_2D_DIAGNOSTICS_GROUP:"physics2d"="physics2d"
The diagnostics group name.
PHYSICS_2D_ERROR_MESSAGES
constPHYSICS_2D_ERROR_MESSAGES:Readonly<Record<string,string>>
The one-line message template of every code, as ExtensionContext.registerErrorCodes wants it.
PHYSICS_2D_SETTINGS_SECTION
constPHYSICS_2D_SETTINGS_SECTION:"physics2d"="physics2d"
The section name as it appears in ignifx.config.ts.
PHYSICS_DIAGNOSTICS_COUNTERS
constPHYSICS_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters 09-physics.md §9 and the plan's diagnostics deliverable name.
PHYSICS_DIAGNOSTICS_GROUP
constPHYSICS_DIAGNOSTICS_GROUP:"physics"="physics"
The diagnostics group name.
PHYSICS_ERROR_MESSAGES
constPHYSICS_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.
PHYSICS_MATERIAL_2D_ASSET_TYPE
constPHYSICS_MATERIAL_2D_ASSET_TYPE:"physicsmaterial"="physicsmaterial"
The asset type name .physicsmaterial.json addresses resolve to.
PHYSICS_MATERIAL_2D_FILE_EXTENSION
constPHYSICS_MATERIAL_2D_FILE_EXTENSION:".physicsmaterial.json"=".physicsmaterial.json"
The address suffix that selects the loader.
PHYSICS_MATERIAL_2D_FILE_FORMAT
constPHYSICS_MATERIAL_2D_FILE_FORMAT:"ignifx.physicsmaterial"="ignifx.physicsmaterial"
The format string every physics-material document declares.
PHYSICS_MATERIAL_2D_FORMAT_VERSION
constPHYSICS_MATERIAL_2D_FORMAT_VERSION:1=1
The file format version; 1 before ignifx 1.0.
PHYSICS_MATERIAL_ASSET_TYPE
constPHYSICS_MATERIAL_ASSET_TYPE:"physicsmaterial"="physicsmaterial"
The asset type name .physicsmaterial.json addresses resolve to.
PHYSICS_MATERIAL_FILE_EXTENSION
constPHYSICS_MATERIAL_FILE_EXTENSION:".physicsmaterial.json"=".physicsmaterial.json"
The address suffix that selects the loader.
PHYSICS_MATERIAL_FILE_FORMAT
constPHYSICS_MATERIAL_FILE_FORMAT:"ignifx.physicsmaterial"="ignifx.physicsmaterial"
The format string every physics-material document declares.
PHYSICS_MATERIAL_FORMAT_VERSION
constPHYSICS_MATERIAL_FORMAT_VERSION:1=1
The file format version; 1 before ignifx 1.0.
PHYSICS_SETTINGS_SECTION
constPHYSICS_SETTINGS_SECTION:"physics"="physics"
The section name as it appears in ignifx.config.ts.
physics2d
constphysics2d: (options?) =>Extension
Builds the 2D physics extension.
Parameters
options?
Optionally, an already-instantiated Rapier module.
Returns
The extension descriptor.
Example
const app = await createApp({ headless: true, extensions: [physics2d()] });Physics2DErrorCode
constPhysics2DErrorCode:object
Every diagnostic code @ignifx/physics-2d can throw or report.
Type Declaration
bodyOnChildEntity
readonlybodyOnChildEntity:"IGX-1157"
A 2D body was built for an entity that has a parent, whose pose is not world space.
bothPhysicsExtensions
readonlybothPhysicsExtensions:"IGX-1101"
Both physics() and physics2d() are registered on one world (11-2d-toolkit.md §8).
colliderGeometryInvalid
readonlycolliderGeometryInvalid:"IGX-1156"
A collider's geometry is degenerate: too few points, or a hull Rapier refused to build.
invalidMaterialFile
readonlyinvalidMaterialFile:"IGX-1154"
A .physicsmaterial.json file is not an ignifx.physicsmaterial document this build reads.
layerOutOfRange
readonlylayerOutOfRange:"IGX-1152"
A collider's layer index is outside the sixteen Rapier's interaction groups can express.
movedStaticBody
readonlymovedStaticBody:"IGX-1151"
An entity with 2D colliders but no Rigidbody2D moved after its static body was placed.
queryBeforeStep
readonlyqueryBeforeStep:"IGX-1153"
A query ran before the first completed fixed step, so Rapier has no broadphase yet.
rapierUnavailable
readonlyrapierUnavailable:"IGX-1150"
The Rapier WebAssembly module could not be instantiated.
unknownLayer
readonlyunknownLayer:"IGX-1155"
The physics2d.collisionMatrix setting names a layer the project does not declare.
Example
throw physics2DError(Physics2DErrorCode.queryBeforeStep, "raycast() ran before the first step.", {
context: { query: "raycast" },
});PhysicsCallbackName
constPhysicsCallbackName:object
Beta
The physics callbacks an extension may deliver through ExtensionContext.dispatchScriptCallback,
named rather than numbered (docs/architecture/09-physics.md §4). The ordinals in
ScriptCallbackKind are engine plumbing and may be renumbered; these five names are the
contract @ignifx/physics is written against.
Type Declaration
onCollisionEnter
readonlyonCollisionEnter:"onCollisionEnter"
onCollisionEnter(collision).
onCollisionExit
readonlyonCollisionExit:"onCollisionExit"
onCollisionExit(collision).
onCollisionStay
readonlyonCollisionStay:"onCollisionStay"
onCollisionStay(collision).
onTriggerEnter
readonlyonTriggerEnter:"onTriggerEnter"
onTriggerEnter(trigger).
onTriggerExit
readonlyonTriggerExit:"onTriggerExit"
onTriggerExit(trigger).
Example
ctx.dispatchScriptCallback(entity, PhysicsCallbackName.onTriggerEnter, event);PhysicsErrorCode
constPhysicsErrorCode:object
Every diagnostic code @ignifx/physics can throw or report, keyed by an intention-revealing name
so call sites read as prose and the compiler catches typos (coding standards §5.2).
Type Declaration
bodyOnChildEntity
readonlybodyOnChildEntity:"IGX-0907"
A physics body was built for an entity that has a parent, whose node pose is not world space.
colliderGeometryUnavailable
readonlycolliderGeometryUnavailable:"IGX-0906"
A MeshCollider has no geometry to build a shape from.
havokUnavailable
readonlyhavokUnavailable:"IGX-0903"
The Havok WebAssembly module could not be loaded.
internalDrainUnavailable
readonlyinternalDrainUnavailable:"IGX-0908"
The ADR-0013 collision drain refused to bind because Babylon Lite's internals moved.
invalidMaterialFile
readonlyinvalidMaterialFile:"IGX-0904"
A .physicsmaterial.json file is not an ignifx.physicsmaterial document this build reads.
movedStaticBody
readonlymovedStaticBody:"IGX-0901"
An entity with colliders but no Rigidbody moved after its implicit static body was placed.
queryBeforeStep
readonlyqueryBeforeStep:"IGX-0902"
A query ran before the first completed fixed step, so Havok has no broadphase yet.
unknownLayer
readonlyunknownLayer:"IGX-0905"
The physics.collisionMatrix setting names a layer the project does not declare.
Example
throw physicsError(PhysicsErrorCode.queryBeforeStep, "raycast() ran before the first step.", {
context: { query: "raycast" },
});ProcessorKind
constProcessorKind:object
The processors a binding may declare.
Type Declaration
clamp
readonlyclamp:"clamp"
Clamps every component into a range.
deadzone
readonlydeadzone:"deadzone"
Drops actuation below min and rescales [min, max] onto [0, 1]. Radial for vectors.
invert
readonlyinvert:"invert"
Negates every component.
normalize
readonlynormalize:"normalize"
Scales a vector to unit length; clamps a scalar into [-1, 1].
scale
readonlyscale:"scale"
Multiplies the components by a per-axis factor.
PROJECTIONS
constPROJECTIONS: readonly ["perspective","orthographic"]
The as const name table behind the public union of the same name.
QUAT_IDENTITY
constQUAT_IDENTITY:QuatLike
The frozen identity rotation, (0, 0, 0, 1). Read-only: pass it anywhere a QuatLike is
wanted, and call Quat.identity() when you need one you can write to.
QUOTA_MESSAGE_PREFIX
constQUOTA_MESSAGE_PREFIX:"IGNIFX_STORAGE_QUOTA: "="IGNIFX_STORAGE_QUOTA: "
The marker a main-process quota failure is re-thrown with, so the renderer can tell IGX-1424
from IGX-1425 after the error has crossed IPC.
Remarks
Electron flattens an error thrown inside ipcMain.handle down to its message by the time it
reaches the renderer: neither a code property nor the prototype survives the trip. A prefix on
the message does, and it is the only channel available without wrapping every reply in an
envelope. It lives in the contract module because both processes have to agree on the string, and
this is the one module both of them import.
RAD_TO_DEG
constRAD_TO_DEG:number
Multiplier that converts radians to degrees.
RENDER_DIAGNOSTICS_COUNTERS
constRENDER_DIAGNOSTICS_COUNTERS: readonlystring[]
The counters the render diagnostics group publishes, in index order.
RENDER_DIAGNOSTICS_GROUP
constRENDER_DIAGNOSTICS_GROUP:"render"="render"
The render diagnostics group name (docs/architecture/15-devtools-and-diagnostics.md §3).
RENDERING_SETTINGS_SECTION
constRENDERING_SETTINGS_SECTION:"rendering"="rendering"
The name the rendering project settings section is registered under.
REQUIRED_HOST_MEMBERS
constREQUIRED_HOST_MEMBERS: readonlystring[]
The members assertHostContract requires, as "path.name" strings.
Remarks
Checked by name rather than by counting: a bridge from a newer minor version has members this build does not know about, and that is fine; a bridge missing one this build calls is not.
RESERVED_LAYER_NAMES
constRESERVED_LAYER_NAMES: readonlystring[]
The names of the eight engine-reserved slots, in slot order. They always occupy slots 0–7,
whether or not the project lists them (docs/architecture/02-scene-graph.md §7).
SCENE_ASSET_TYPE
constSCENE_ASSET_TYPE:"scene"="scene"
The asset type name the scene loader registers under.
SCENE_FILE_EXTENSIONS
constSCENE_FILE_EXTENSIONS: readonlystring[]
The file extensions the scene loader claims.
SCENE_FILE_FORMAT
constSCENE_FILE_FORMAT:"ignifx.scene"="ignifx.scene"
The format discriminator every scene and prefab file carries
(docs/architecture/06-serialization-and-scene-format.md §2). Levels (*.scene.json) and
prefabs (*.prefab.json) share it: a prefab is a scene instanced inside another scene
(ADR-0005), not a second file type.
SCENE_FORMAT_VERSION
constSCENE_FORMAT_VERSION:1=1
The formatVersion this build writes and is the only one it can read. Before 1.0 the number
stays 1 and an incompatible change invalidates files rather than migrating them
(CONSTITUTION.md §4.2); a file declaring anything else is rejected with IGX-0603.
SceneAssetToken
constSceneAssetToken:AssetTypeToken<SceneAsset>
The asset() token for a scene or prefab field. SceneAsset is an interface, so it cannot be
passed to asset() the way a class such as MeshAsset can; this token names the type instead:
class Spawner extends Script.define({ prefab: asset(SceneAssetToken) }) {
static typeId = "game/Spawner";
spawn(): void {
const value = this.prefab?.value;
if (value !== undefined) {
this.app.world.instantiate(value, { position: this.transform.position });
}
}
}In a scene file the field is written as { "$asset": "props/crate.prefab.json" }.
SchemaIssueCode
constSchemaIssueCode:object
Diagnostic codes this module reports. They live in the 06xx serialization range registered in
docs/architecture/15-devtools-and-diagnostics.md §1. Codes IGX-0601 to IGX-0604 are already
spoken for by the scene loader (docs/architecture/06-serialization-and-scene-format.md), so the
schema-level checks continue from IGX-0605.
Type Declaration
nonFiniteNumber
readonlynonFiniteNumber:"IGX-0601"
A number was NaN, Infinity, or -Infinity and therefore cannot be written to JSON.
outOfRange
readonlyoutOfRange:"IGX-0606"
A value had the right type but fell outside the field's declared value domain.
typeMismatch
readonlytypeMismatch:"IGX-0605"
A value had the wrong JavaScript or JSON type for the field kind.
unknownField
readonlyunknownField:"IGX-0607"
A property was supplied that the schema does not declare.
unresolvedReference
readonlyunresolvedReference:"IGX-0602"
An entity or component reference could not be resolved to a uid.
ScriptCallbackKind
constScriptCallbackKind:object
Every script callback, numbered. The first five are driven by the lifecycle flushes; the rest are dispatched from a phase and therefore get a sorted dispatch list.
Type Declaration
awake
readonlyawake:0
awake() — once, when the script first becomes effectively enabled.
fixedUpdate
readonlyfixedUpdate:5
fixedUpdate(dt) — once per fixed step.
lateUpdate
readonlylateUpdate:7
lateUpdate(dt) — once per frame, after animation.
onApplicationFocus
readonlyonApplicationFocus:14
onApplicationFocus(focused).
onApplicationPause
readonlyonApplicationPause:13
onApplicationPause(paused).
onCollisionEnter
readonlyonCollisionEnter:8
onCollisionEnter(collision).
onCollisionExit
readonlyonCollisionExit:10
onCollisionExit(collision).
onCollisionStay
readonlyonCollisionStay:9
onCollisionStay(collision).
onDestroy
readonlyonDestroy:4
onDestroy() — once, in the destroy flush.
onDisable
readonlyonDisable:3
onDisable() — on every transition off, including just before destruction.
onEnable
readonlyonEnable:1
onEnable() — on every transition to effectively enabled.
onTriggerEnter
readonlyonTriggerEnter:11
onTriggerEnter(trigger).
onTriggerExit
readonlyonTriggerExit:12
onTriggerExit(trigger).
start
readonlystart:2
start() — once, in flush B of the first frame the script is effectively enabled.
update
readonlyupdate:6
update(dt) — once per frame.
SORTING_LAYER_ORDER_STEP
constSORTING_LAYER_ORDER_STEP:1000=1e3
How far apart two sorting layers' Lite order values sit.
Remarks
A gap of 1000 leaves room for the per-(atlas, blend, space) sub-layers a single sorting layer expands into: one sorting layer holding sprites from twelve atlases in three blend modes still fits inside its slice without reaching the next layer's.
SPRITE_ANIMATION_ASSET_TYPE
constSPRITE_ANIMATION_ASSET_TYPE:"spriteanimation"="spriteanimation"
The asset type name the loader registers.
SPRITE_ANIMATION_FILE_EXTENSIONS
constSPRITE_ANIMATION_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the sprite-animation loader.
SPRITE_ANIMATION_FORMAT
constSPRITE_ANIMATION_FORMAT:"ignifx.spriteanimation"="ignifx.spriteanimation"
The format discriminator every .spriteanim.json document carries.
SPRITE_ANIMATION_FORMAT_VERSION
constSPRITE_ANIMATION_FORMAT_VERSION:1=1
The document version this build reads and writes.
SPRITE_ATLAS_ASSET_TYPE
constSPRITE_ATLAS_ASSET_TYPE:"spriteatlas"="spriteatlas"
The asset type name the loader registers.
SPRITE_ATLAS_FILE_EXTENSIONS
constSPRITE_ATLAS_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the sprite-atlas loader.
SPRITE_ATLAS_FORMAT
constSPRITE_ATLAS_FORMAT:"ignifx.spriteatlas"="ignifx.spriteatlas"
The format discriminator every .atlas.json document carries.
SPRITE_ATLAS_FORMAT_VERSION
constSPRITE_ATLAS_FORMAT_VERSION:1=1
The document version this build reads and writes.
SPRITE_BLEND_MODES
constSPRITE_BLEND_MODES: readonly ["alpha","premultiplied","additive","multiply","opaque"]
The blend modes SpriteRenderer.blend accepts, in the order an inspector should list them.
SPRITE_EFFECT_KINDS
constSPRITE_EFFECT_KINDS: readonly ["tint","custom"]
The built-in effects, in the order an inspector should list them.
SPRITE_FRAME_FRAGMENT_PREFIX
constSPRITE_FRAME_FRAGMENT_PREFIX:"frame:"="frame:"
The fragment prefix that addresses one frame: "sprites/hero.atlas.json#frame:idle_0".
STANDARD_TEXTURE_SLOTS
constSTANDARD_TEXTURE_SLOTS: readonlystring[]
The texture slots a "standard" material may name.
STORAGE_BACKEND_FAILED_CODE
constSTORAGE_BACKEND_FAILED_CODE:"IGX-1425"="IGX-1425"
IGX-1425 — the backend failed for any other reason.
STORAGE_KEY_MAX_LENGTH
constSTORAGE_KEY_MAX_LENGTH:512=512
The longest a storage key may be.
Remarks
512 UTF-16 code units is comfortably below the ~255 byte file-name limit once percent-encoding has expanded the key, which is why the file backend hashes nothing and truncates nothing: a key that passes this check always encodes to a name a file system accepts.
STORAGE_QUOTA_CODE
constSTORAGE_QUOTA_CODE:"IGX-1424"="IGX-1424"
IGX-1424 — the host is out of quota.
Remarks
Quoted as a literal because @ignifx/core's CoreErrorCode table is not reachable from an
extension by design (04-extensions.md §3): an extension owns its own codes and is handed
core's as documented constants.
STORAGE_VALUE_CORRUPT_CODE
constSTORAGE_VALUE_CORRUPT_CODE:"IGX-1426"="IGX-1426"
IGX-1426 — a stored value could not be read back.
SUPPORT_STATES
constSUPPORT_STATES: readonly ["unsupported","sliding","supported"]
How the character is supported by whatever is under it.
TEXT_ALIGNMENTS
constTEXT_ALIGNMENTS: readonly ["left","center","right"]
The alignments Lite's default layout supports (index.d.ts 12826-12827).
TEXT_REFRESH_HZ
constTEXT_REFRESH_HZ:10=10
How often a text panel is rewritten, in hertz — §4's "throttled" rate. A panel that declares
perFrame — the Timeline graph — ignores it.
textAssetLoader
consttextAssetLoader:AssetLoader<string>
UTF-8 text, for .txt, .md, and .csv addresses.
TEXTURE_ASSET_TYPE
constTEXTURE_ASSET_TYPE:"texture"="texture"
The asset type textures are registered under.
THIRD_PARTY_ERROR_PREFIX
constTHIRD_PARTY_ERROR_PREFIX:"9"="9"
The first digit of the range reserved for extensions published outside the @ignifx scope
(IGX-9000 through IGX-9999). First-party subsystems never allocate here.
THREE_D_ANIMATION_ORDER
constTHREE_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
constTHREE_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
constTHREE_D_SETTINGS_SECTION:"threeD"="threeD"
The section name as it appears in ignifx.config.ts.
threeD
constthreeD: (options?) =>Extension
The @ignifx/3d extension factory.
Parameters
options?
Overrides for the threeD settings section.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({
canvas,
extensions: [physics(), input(), threeD({ navigationSeed: 42 })],
});ThreeDErrorCode
constThreeDErrorCode: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
readonlycrowdFull:"IGX-1207"
A NavMeshAgent could not join its crowd because the surface's maxAgents is full.
duplicateExtension
readonlyduplicateExtension:"IGX-1213"
A second threeD() extension was registered on one app.
emptyNavMesh
readonlyemptyNavMesh:"IGX-1209"
A NavMeshSurface was baked with no source geometry, so every query fails.
invalidAnimatorFile
readonlyinvalidAnimatorFile:"IGX-1201"
A .animator.json file is not an ignifx.animator document this build can read.
invalidLodLevel
readonlyinvalidLodLevel:"IGX-1214"
A LodGroup level names a renderer that is not under the group's entity.
navigationNotReady
readonlynavigationNotReady:"IGX-1205"
A navigation query ran before the Recast plugin had finished loading, or before a bake.
navigationUnavailable
readonlynavigationUnavailable:"IGX-1206"
The Recast WebAssembly module could not be loaded at all.
noMainCamera
readonlynoMainCamera:"IGX-1211"
A rig needs the main camera and the world has none enabled.
obstaclesNotEnabled
readonlyobstaclesNotEnabled:"IGX-1208"
A NavMeshObstacle needs a surface baked with maxObstacles greater than zero.
parameterKindMismatch
readonlyparameterKindMismatch:"IGX-1204"
A parameter was written with a value of the wrong kind for its declaration.
prebakedNavMeshUnsupported
readonlyprebakedNavMeshUnsupported:"IGX-1210"
A pre-baked .navmesh.bin was named; Babylon Lite 1.27.0 cannot deserialize one.
unknownInputAction
readonlyunknownInputAction:"IGX-1212"
A controller named an input action the loaded action maps do not declare.
unknownParameter
readonlyunknownParameter:"IGX-1203"
setFloat/setInt/setBool/setTrigger named a parameter the document does not declare.
unknownState
readonlyunknownState:"IGX-1202"
Animator.play or a transition named a state the document does not declare.
Example
throw threeDError(ThreeDErrorCode.unknownState, "hero.animator.json declares no state named jump.", {
context: { asset: "hero.animator.json", state: "jump" },
});TILEMAP_ASSET_TYPE
constTILEMAP_ASSET_TYPE:"tilemap"="tilemap"
The asset type name the loader registers.
TILEMAP_FILE_EXTENSIONS
constTILEMAP_FILE_EXTENSIONS: readonlystring[]
The address suffixes that select the tilemap loader.
TILEMAP_FORMAT
constTILEMAP_FORMAT:"ignifx.tilemap"="ignifx.tilemap"
The format discriminator every .tilemap.json document carries.
TILEMAP_FORMAT_VERSION
constTILEMAP_FORMAT_VERSION:1=1
The document version this build reads and writes.
TINT_EFFECT_WGSL
constTINT_EFFECT_WGSL:"let texel = textureSample(atlasTex, atlasSamp, uv); return vec4f(texel.rgb * fx.params.rgb, texel.a * fx.params.a);"="let texel = textureSample(atlasTex, atlasSamp, uv); return vec4f(texel.rgb * fx.params.rgb, texel.a * fx.params.a);"
The WGSL body of the built-in tint effect.
Remarks
Multiplies the sampled texel by fx.params.rgb and scales its alpha by fx.params.a, which is
a per-layer tint that a per-sprite color cannot express — every sprite in the layer fades
together, in one uniform write, rather than in one instance write each.
TOUCH_SLOTS
constTOUCH_SLOTS:10=10
How many simultaneous touches Touch tracks; <Touch>/touch0 … <Touch>/touch9.
TWEEN_LOOP_FOREVER
constTWEEN_LOOP_FOREVER:-1=-1
loop: -1 means "repeat until stopped".
TWEEN_SYSTEM_ORDER
constTWEEN_SYSTEM_ORDER:-100=-100
The PostUpdate order the tween system runs at.
Remarks
-100 puts tweens before the toolkits' animation systems, which register at 0
(@ignifx/2d) and 10 (@ignifx/3d): a tween that drives an Animator parameter or a
material property is read by the animation that runs after it, in the same frame.
TWEEN_VALUE_KINDS
constTWEEN_VALUE_KINDS: readonly ["number","vec2","vec3","quat"]
The four value shapes a tween can interpolate.
TWO_D_ANIMATION_ORDER
constTWO_D_ANIMATION_ORDER:0=0
The PostUpdate order the 2D animation system runs at.
Remarks
PostUpdate is empty today — no core or extension system registers there — so 0 is the middle
of an open phase. Anything a game adds later can sit either side of it by choosing a sign.
TWO_D_ERROR_MESSAGES
constTWO_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.
TWO_D_MODES
constTWO_D_MODES: readonly ["sprite","mixed"]
Every rendering mode the 2D toolkit supports, in the order an inspector should list them
(docs/architecture/11-2d-toolkit.md §1).
TWO_D_SETTINGS_SECTION
constTWO_D_SETTINGS_SECTION:"twoD"="twoD"
The section name as it appears in ignifx.config.ts and in a scene file's settings block.
TWO_D_SYNC_ORDER
constTWO_D_SYNC_ORDER:-450=-450
The PreRender order the 2D sync system runs at.
Remarks
-450, not the -400 docs/architecture/11-2d-toolkit.md §2.2 names, because audio's pump
already holds -400. See the module's own remarks.
twoD
consttwoD: (options?) =>Extension
The @ignifx/2d extension factory.
Parameters
options?
Overrides for the twoD settings section.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({
canvas,
extensions: [twoD({ pixelsPerUnit: 16, ySort: { Default: true } })],
});TwoDErrorCode
constTwoDErrorCode:object
Every diagnostic code @ignifx/2d 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
atlasFrameNotExtruded
readonlyatlasFrameNotExtruded:"IGX-1102"
An atlas frame has no one-pixel extruded border, which a pixel-perfect camera will bleed.
duplicateExtension
readonlyduplicateExtension:"IGX-1112"
A second twoD() extension was registered on one app.
duplicateObjectFactory
readonlyduplicateObjectFactory:"IGX-1110"
app.twoD.registerTileObjectFactory was called twice for one object type.
invalidAnimationFile
readonlyinvalidAnimationFile:"IGX-1104"
A .spriteanim.json file is not an ignifx.spriteanimation document this build can read.
invalidAtlasFile
readonlyinvalidAtlasFile:"IGX-1103"
A .atlas.json file is not an ignifx.spriteatlas document this build can read.
invalidTilemapFile
readonlyinvalidTilemapFile:"IGX-1105"
A .tilemap.json file is not an ignifx.tilemap document this build can read.
missingShaderSource
readonlymissingShaderSource:"IGX-1113"
A SpriteLayerEffect declared the custom kind without a WGSL fragment body.
tileOutOfRange
readonlytileOutOfRange:"IGX-1111"
A tile coordinate is outside the tilemap layer's bounds.
unknownClip
readonlyunknownClip:"IGX-1108"
SpriteAnimator.play named a clip the animation asset does not declare.
unknownFrame
readonlyunknownFrame:"IGX-1106"
A sprite address names a frame the atlas does not declare.
unknownSortingLayer
readonlyunknownSortingLayer:"IGX-1107"
A component named a sorting layer the sortingLayers settings section does not declare.
unsupportedImport
readonlyunsupportedImport:"IGX-1109"
A tilemap importer was handed a document it cannot read, or an unsupported projection.
Example
throw twoDError(TwoDErrorCode.unknownSortingLayer, "Foreground is not a declared sorting layer.", {
context: { sortingLayer: "Foreground" },
});ui
constui: (options?) =>Extension
The @ignifx/ui extension factory.
Parameters
options?
Overrides for the ui settings section, plus the start-up translation document.
Returns
The extension descriptor to pass to createApp.
Example
const app = await createApp({
canvas,
extensions: [ui({ scaling: "fit", referenceResolution: [640, 360] })],
});UI_CLASS_NAMES
constUI_CLASS_NAMES:object
The class names the host and the helper widgets set, so a template's CSS can target them without
guessing (docs/architecture/13-ui.md §3).
Type Declaration
button
readonlybutton:"ignifx-ui-button"
A VirtualButton.
dialog
readonlydialog:"ignifx-ui-dialog"
A Dialog's outermost element.
dialogBackdrop
readonlydialogBackdrop:"ignifx-ui-dialog-backdrop"
A Dialog's backdrop.
dialogButton
readonlydialogButton:"ignifx-ui-dialog-button"
One Dialog button.
dialogButtons
readonlydialogButtons:"ignifx-ui-dialog-buttons"
A Dialog's button row.
dialogMessage
readonlydialogMessage:"ignifx-ui-dialog-message"
A Dialog's message.
dialogPanel
readonlydialogPanel:"ignifx-ui-dialog-panel"
A Dialog's panel.
dialogTitle
readonlydialogTitle:"ignifx-ui-dialog-title"
A Dialog's title.
interactive
readonlyinteractive:"ignifx-ui-interactive"
Anything that should receive pointer events; the root does not.
joystick
readonlyjoystick:"ignifx-ui-joystick"
A VirtualJoystick's outer pad.
joystickKnob
readonlyjoystickKnob:"ignifx-ui-joystick-knob"
A VirtualJoystick's knob.
layer
readonlylayer:"ignifx-ui-layer"
A named layer inside the root.
loading
readonlyloading:"ignifx-ui-loading"
A LoadingScreen's outermost element.
loadingBar
readonlyloadingBar:"ignifx-ui-loading-bar"
A LoadingScreen's progress bar.
loadingLabel
readonlyloadingLabel:"ignifx-ui-loading-label"
A LoadingScreen's label.
loadingTrack
readonlyloadingTrack:"ignifx-ui-loading-track"
A LoadingScreen's progress track.
root
readonlyroot:"ignifx-ui-root"
The overlay root.
toast
readonlytoast:"ignifx-ui-toast"
One toast.
toastStack
readonlytoastStack:"ignifx-ui-toasts"
A Toast's stack container.
UI_CSS_VARIABLES
constUI_CSS_VARIABLES:object
The CSS custom properties the root carries, so game CSS can read the safe area and the current
scale without measuring anything (docs/architecture/13-ui.md §1).
Type Declaration
safeBottom
readonlysafeBottom:"--ignifx-safe-bottom"
The bottom safe-area inset.
safeLeft
readonlysafeLeft:"--ignifx-safe-left"
The left safe-area inset.
safeRight
readonlysafeRight:"--ignifx-safe-right"
The right safe-area inset.
safeTop
readonlysafeTop:"--ignifx-safe-top"
The top safe-area inset, from env(safe-area-inset-top).
scale
readonlyscale:"--ignifx-ui-scale"
The uniform scale the root is drawn at, as a bare number.
UI_ERROR_MESSAGES
constUI_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.
UI_FOCUS_ATTRIBUTE
constUI_FOCUS_ATTRIBUTE:"data-ignifx-focus"="data-ignifx-focus"
The attribute that overrides the editability guess in either direction.
UI_LAYER_Z_STEP
constUI_LAYER_Z_STEP:10=10
The z-index step between two consecutive layers. The first declared layer sits at
UI_LAYER_Z_STEP, the second at twice that, and so on, which leaves nine free slots between any
two layers for a game that wants to interleave its own elements.
UI_SCALING_MODES
constUI_SCALING_MODES: readonly ["css","fit","dpi"]
Every scaling mode the overlay host supports, in the order an inspector should list them
(docs/architecture/13-ui.md §1).
UI_SETTINGS_SECTION
constUI_SETTINGS_SECTION:"ui"="ui"
The section name as it appears in ignifx.config.ts.
UI_STYLE_ELEMENT_ID
constUI_STYLE_ELEMENT_ID:"ignifx-ui-styles"="ignifx-ui-styles"
The id of the injected <style> element, so a second app in one document reuses it.
UI_SYNC_ORDER
constUI_SYNC_ORDER:1100=1100
The PreRender order the UI system runs at.
Remarks
After RENDER_SYNC_ORDER (900), which is the frame's camera synchronisation, and inside the
extension band. See the module's own remarks.
UiErrorCode
constUiErrorCode:object
Every diagnostic code @ignifx/ui 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
duplicateExtension
readonlyduplicateExtension:"IGX-1301"
A second ui() extension was registered on one app.
headlessNoOp
readonlyheadlessNoOp:"IGX-1307"
A DOM-only member was reached on a host with no document, and did nothing.
inputExtensionMissing
readonlyinputExtensionMissing:"IGX-1305"
A widget that needs @ignifx/input was built on an app that did not register it.
invalidLocaleFile
readonlyinvalidLocaleFile:"IGX-1302"
A .i18n.json file is not an ignifx.i18n document this build can read.
invalidMessagePattern
readonlyinvalidMessagePattern:"IGX-1304"
A message pattern could not be parsed: an unbalanced brace or an unknown argument form.
missingFont
readonlymissingFont:"IGX-1306"
A WorldText or HudText was asked to draw before its font asset was assigned.
sceneAlreadyBuilt
readonlysceneAlreadyBuilt:"IGX-1308"
A WorldText needed a scene renderable after the render scene had already been built.
unknownLocale
readonlyunknownLocale:"IGX-1303"
app.i18n.locale was set to a locale the loaded document does not declare.
Example
throw uiError(UiErrorCode.unknownLayer, "hud is not a declared UI layer.", {
context: { layer: "hud" },
});VEC2_ONE
constVEC2_ONE:Vec2Like
The frozen vector whose components are both one, (1, 1) — the identity 2D scale.
VEC2_ZERO
constVEC2_ZERO:Vec2Like
The frozen zero vector, (0, 0).
VEC3_BACKWARD
constVEC3_BACKWARD:Vec3Like
The frozen world backward direction, (0, 0, -1).
VEC3_DOWN
constVEC3_DOWN:Vec3Like
The frozen world down direction, (0, -1, 0).
VEC3_FORWARD
constVEC3_FORWARD:Vec3Like
The frozen world forward direction, (0, 0, 1). ignifx is left-handed, so forward is +Z
(ADR-0011).
VEC3_LEFT
constVEC3_LEFT:Vec3Like
The frozen world left direction, (-1, 0, 0).
VEC3_ONE
constVEC3_ONE:Vec3Like
The frozen vector whose components are all one, (1, 1, 1) — the identity scale.
VEC3_RIGHT
constVEC3_RIGHT:Vec3Like
The frozen world right direction, (1, 0, 0).
VEC3_UP
constVEC3_UP:Vec3Like
The frozen world up direction, (0, 1, 0).
VEC3_ZERO
constVEC3_ZERO:Vec3Like
The frozen zero vector, (0, 0, 0). Read-only: pass it anywhere a Vec3Like is wanted, and
call Vec3.zero when you need a vector you can write to.
VERSION
constVERSION:"0.0.0"="0.0.0"
The @ignifx/core version this build reports as app.version and as the core extension's
version (docs/architecture/04-extensions.md §1).
Remarks
The literal is "0.0.0" in the repository and is stamped by the release pipeline: Changesets
writes the real number into package.json, and the build replaces this constant with it
(coding standards §12, release.yml). Reading the version from package.json at run time is not
an option — that would be an import-time side effect and a bundler hazard
(CONSTITUTION.md §3.5).
WORLD_FORWARD
constWORLD_FORWARD:Vec3Like
Where something faces when the world has no enabled camera at all.
Functions
animatorFileSchema()
animatorFileSchema():
Schema
The ignifx.animator document schema.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
applyInit()
applyInit<
S>(target,schema,init):FieldsOf<S>
Overwrites defaults with caller-supplied values. Only names the schema declares are copied, and
a value of undefined leaves the default in place — matching the loader's rule that omitted
props take schema defaults (docs/architecture/06-serialization-and-scene-format.md §2).
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
Parameters
target
FieldsOf<S>
The field object to write into, normally the result of createDefaults.
schema
S
The schema that says which names are legal.
init
The values to apply.
Returns
FieldsOf<S>
The same target object, for chaining.
Example
const fields = applyInit(createDefaults(moverSchema), moverSchema, { speed: 12 });applyOverrides()
applyOverrides(
maps,json):void
Applies a saved override document, clearing whatever was applied before.
Parameters
maps
ReadonlyMap<string, ActionMap>
The installed action maps.
json
The document from collectOverrides.
Returns
void
Throws
IgnifxError with code IGX-0808 when the document is not an ignifx.inputoverrides
document this build can read, or names a map, action, or binding that does not exist.
applyProcessors()
applyProcessors(
chain,value,isVector):void
Runs a whole processor chain over a value, in place. Allocation-free: the chain and the value are both owned by the caller.
Parameters
chain
readonly Processor[]
The parsed processors, in application order.
value
The value to transform.
isVector
boolean
Whether the value has two meaningful components.
Returns
void
Example
const value = { x: 0.1, y: 0 };
applyProcessors(parseProcessors(["deadzone(0.15)"]), value, false);
value.x; // 0approximately()
approximately(
a,b,epsilon?):boolean
Compares two numbers with an absolute tolerance. Use this instead of === on anything that has
been through a matrix, a quaternion or a Float32Array.
Parameters
a
number
The first value.
b
number
The second value.
epsilon?
number
The largest difference still considered equal. Defaults to EPSILON.
Returns
boolean
true when the values differ by no more than epsilon. NaN is never approximately
equal to anything, including itself.
array()
array<
T>(item,defaultValue?,options?):FieldDefinition<T[]>
Declares a list field. The runtime value type is a mutable array because game code is expected
to push to it (this.waypoints.push(p)); the default is copied on every instantiation, shallowly,
so element objects supplied as defaults are shared and should be treated as immutable.
Type Parameters
T
T
The element value type, inferred from item.
Parameters
item
The field definition every element follows.
defaultValue?
readonly T[]
The list a new component starts with; defaults to empty.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<T[]>
The field definition.
Example
waypoints: array(vec3()); // Vec3Like[]asepriteFrameName()
asepriteFrameName(
raw):string
Normalises an Aseprite frame key into an identifier a clip and a #frame: fragment can name.
The rule, applied in this order:
- Drop a trailing file extension — a dot, a letter, then up to seven more alphanumerics — so
hero 0.asepriteandhero_0.pngboth lose their suffix butwalk.2does not. - Replace every run of non-alphanumeric characters with a single
_. - Trim leading and trailing
_.
Case is preserved: Hero (Idle) 0.aseprite becomes Hero_Idle_0, not hero_idle_0. A key that
normalises to nothing at all ("###.png") becomes frame.
importAsepriteAtlas and importAsepriteAnimations both run keys through this function,
which is what makes an imported clip's frame names line up with the imported atlas's.
Parameters
raw
string
The frame key as Aseprite wrote it — a hash key, or an array entry's filename.
Returns
string
The normalised frame name.
Example
asepriteFrameName("hero (idle) 0.aseprite"); // "hero_idle_0"
asepriteFrameName("hero_0.png"); // "hero_0"assertHostContract()
assertHostContract(
host):void
Checks that a bridge is one this build can talk to.
Parameters
host
The bridge found on the window.
Returns
void
Remarks
Two checks, and they fail differently on purpose. A major version mismatch (IGX-1460) means
the preload script and the renderer bundle came from different installs — a partially applied
update, a stale asar — and the message says so. A missing member (IGX-1461) means the
bridge is the right generation but incomplete, which is what a hand-written preload script that
forgot exposeIgnifxHost() and rolled its own looks like.
Throws
An IgnifxError with code IGX-1460 when the major versions differ, or IGX-1461 when a
member this build calls is absent.
Example
const host = findIgnifxHost();
if (host !== null) {
assertHostContract(host);
}assertNever()
assertNever(
value,what):never
The default branch of an exhaustive switch (coding standards §5.2). The compiler rejects the
call as soon as a new union member is left unhandled, and at runtime it throws rather than
falling through silently.
Parameters
value
never
The value the type system proved impossible.
what
string
What was being switched over, for the message.
Returns
never
Throws
IgnifxError with code IGX-1505; the function never returns.
Example
switch (level) {
case "debug":
return 10;
default:
return assertNever(level, "log level");
}assertSceneDependenciesLoaded()
assertSceneDependenciesLoaded(
asset):void
Checks that every scene a file instances — at any depth — is among the loaded dependencies, which
is what makes world.instantiate safe to be synchronous
(docs/architecture/02-scene-graph.md §2).
Parameters
asset
The scene to check.
Returns
void
Throws
IgnifxError with code IGX-0301 naming the first instanced scene that is not loaded.
asset()
asset<
A>(type,options?):FieldDefinition<AssetHandle<A> |null>
Declares a reference to an addressable asset. The runtime value is the loaded
AssetHandle, not an address: a component's asset() fields are resolved before its props
are written, so awake can already read this.mesh.value
(docs/architecture/05-assets-and-loading.md §3).
Type Parameters
A
A
The asset type the reference points at, inferred from the class.
Parameters
type
The asset class the field may point at.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<AssetHandle<A> | null>
The field definition.
Remarks
Files store the address instead — { "$asset": "models/hero.glb", "type"?: "model" }
(06-serialization-and-scene-format.md §3). Encoding reads handle.address; decoding hands that
address to the asset resolver of the ReferenceDecoder the scene loader supplies, which answers
with the handle the scene already retains. Two consequences game code sees:
- An address the resolver cannot answer decodes to
nulland reportsIGX-0602; the component keeps working with a missing asset rather than failing the whole scene. - An in-code asset — anything from
Assets.register, which includesMeshAsset.box(…)andcreateMaterialAsset(app, pbrMaterialDefinition({ … }))— lives at amemory:address that names no file, so serializing a component that holds one writesnulland reports the loss. Save the asset as a file when it has to survive a round trip.
The field does not retain the handle: the scene instance that loaded it owns the reference count and releases it on unload.
Example
class Hero extends Component.define({ clip: asset(AudioClip) }) {
static typeId = "mygame/Hero";
awake(): void {
this.clip?.value.play();
}
}assetRef()
assetRef<
T>(address,type?):AssetRef<T>
Builds an asset reference.
Type Parameters
T
T = unknown
The loaded value type the reference points at; a compile-time marker only.
Parameters
address
string
The address, fragment included.
type?
string
The asset type, when the extension does not identify it.
Returns
AssetRef<T>
A frozen reference, safe to hold as a module constant.
Example
const hero = assetRef<ModelAsset>("models/hero.glb");
const run = assetRef<AnimationClip>("models/hero.glb#animation:Run");
const handle = app.assets.load(hero);audioError()
audioError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the AudioErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Remarks
IgnifxError's code parameter is the open template type IGX-${number}, so an IGX-10##
literal from the AudioErrorCode table is accepted without an assertion.
Example
throw audioError(AudioErrorCode.unknownBus, "Ambience is not a registered bus.", {
context: { bus: "Ambience" },
hint: "Declare it in the project's .audio.json, or call app.audio.createBus.",
});audioSettingsSchema()
audioSettingsSchema():
Schema
The schema the audio section is validated against.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
bool()
bool(
defaultValue?,options?):FieldDefinition<boolean>
Declares a boolean field.
Parameters
defaultValue?
boolean
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<boolean>
The field definition.
buildControls()
buildControls(
specs): readonlyControlDescriptor[]
Assigns indices and value-array offsets to a device's control declarations.
Parameters
specs
readonly ControlSpec[]
The declarations, in the order they should be indexed.
Returns
readonly ControlDescriptor[]
The descriptors, index i describing specs[i].
Example
const controls = buildControls([
{ name: "leftStick", kind: ControlKind.vector2 },
{ name: "buttonSouth", kind: ControlKind.button },
]);
controls[1].offset; // 2 — the stick took slots 0 and 1cameraRelativeToRef()
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
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
cameraRelativeToRef(move.x, move.y, camera.transform.forward, direction);canonicalizeNumber()
canonicalizeNumber(
value):number
Rounds a number to the file format's precision: six decimal places, with -0 normalized to 0
(docs/architecture/06-serialization-and-scene-format.md §3). The rule is idempotent, so
save → load → save is byte-identical.
Parameters
value
number
The number to canonicalize.
Returns
number
The canonical form of the number.
Example
canonicalizeNumber(0.1 + 0.2); // 0.3
canonicalizeNumber(-0); // 0clamp()
clamp(
value,min,max):number
Constrains a value to an inclusive range.
Parameters
value
number
The value to constrain.
min
number
The lower bound.
max
number
The upper bound.
Returns
number
min when value is smaller, max when it is larger, otherwise value unchanged.
NaN propagates.
Example
clamp(12, 0, 10); // 10clamp01()
clamp01(
value):number
Constrains a value to the 0–1 range.
Parameters
value
number
The value to constrain.
Returns
number
The value clamped into [0, 1].
clearOverrides()
clearOverrides(
maps):void
Removes every override, returning each binding to its declared path.
Parameters
maps
ReadonlyMap<string, ActionMap>
The installed action maps.
Returns
void
collectOverrides()
collectOverrides(
maps):InputOverridesJson
Collects every override currently applied.
Parameters
maps
ReadonlyMap<string, ActionMap>
The installed action maps.
Returns
The document to persist.
collider2DFields()
collider2DFields():
Schema
The fields every 2D collider declares.
Returns
The shared field declarations, ready to spread into a collider's own schema.
colliderFields()
colliderFields():
Schema
The fields every collider declares. It is a function because a field kind is a function call and
module scope holds declarations only (CONSTITUTION.md §3.5).
Returns
The shared field declarations, ready to spread into a collider's own schema.
color()
color(
defaultValue?,options?):FieldDefinition<ColorLike>
Declares an RGBA color field. Channels are sRGB in the 0–1 range, in memory and in files alike:
conversion to linear space belongs to the renderer, not the schema
(docs/architecture/06-serialization-and-scene-format.md §3).
Parameters
defaultValue?
string | ColorLike
The starting color, either as channels or as a #rgb/#rgba/#rrggbb/
#rrggbbaa string; defaults to opaque white.
options?
Inspector and serializer metadata.
Returns
The field definition.
Throws
A TypeError when a string default is not a valid hexadecimal color.
Example
tint: color("#ffffff");componentRef()
componentRef<
C>(type,options?):FieldDefinition<C|null>
Declares a reference to a component on an entity in the same scene file.
Type Parameters
C
C
The component type the reference resolves to, inferred from the class.
Parameters
type
The component class the field may point at.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<C | null>
The field definition.
Example
follow: componentRef(Camera); // Camera | nullcompositeIsVector()
compositeIsVector(
kind):boolean
What a composite produces before processors run.
Parameters
kind
The composite.
Returns
boolean
true when the composite yields a two-component value.
compositeParts()
compositeParts(
kind): readonlystring[]
The part names one composite declares, in evaluation order.
Parameters
kind
The composite.
Returns
readonly string[]
The part names.
Example
compositeParts("2DVector"); // ["up", "down", "left", "right"]computeAnchorPlacement()
computeAnchorPlacement(
input,out):AnchorPlacement
Computes where an anchored element goes this frame.
Parameters
input
AnchorInput
The projection, the flags, and the conversion.
out
Receives the placement.
Returns
out, for chaining.
Example
const out = createAnchorPlacement();
computeAnchorPlacement(
{
screenX: 400,
screenY: 300,
inFront: true,
distance: 10,
viewWidth: 800,
viewHeight: 600,
mapping: { scaleX: 1, originX: 0, scaleY: 1, originY: 0 },
hideWhenBehindCamera: true,
clampToScreen: false,
scaleWithDistance: false,
referenceDistance: 10,
minScale: 0.5,
maxScale: 2,
},
out,
);
out.x; // 400computeHudPlacement()
computeHudPlacement(
input,out):HudPlacement
Places a block against one of the nine anchors of the render target.
Parameters
input
The anchor, the offset, the target size, and the block's size.
out
Receives the layer position.
Returns
out, for chaining.
Example
const out = { x: 0, y: 0 };
computeHudPlacement(
{
anchor: "topRight",
offsetX: -16,
offsetY: 16,
targetWidth: 800,
targetHeight: 600,
blockWidth: 100,
blockHeight: 40,
fontSize: 32,
},
out,
);
out.x; // 684 — 16 px in from the right edgecomputePivotPlacement()
computePivotPlacement(
pivot,x,y,blockWidth,blockHeight,fontSize,out):HudPlacement
Places a block around a point, with the given point of the block sitting on it.
Parameters
pivot
"topLeft" | "top" | "topRight" | "left" | "center" | "right" | "bottomLeft" | "bottom" | "bottomRight"
Which point of the block lands on the position.
x
number
The point's x, in render-target pixels.
y
number
The point's y, in render-target pixels.
blockWidth
number
The block's laid-out width.
blockHeight
number
The block's laid-out height.
fontSize
number
The em size the block was shaped at.
out
Receives the layer position.
Returns
out, for chaining.
Example
const out = { x: 0, y: 0 };
computePivotPlacement("center", 400, 300, 100, 40, 32, out);
out.x; // 350computeSceneHash()
computeSceneHash(
file):Promise<string>
The content hash of a scene file: SHA-256 over the canonical JSON text, so two saves of the same
state hash the same and an edited prefab does not
(docs/architecture/06-serialization-and-scene-format.md §2).
Parameters
file
The file to hash.
Returns
Promise<string>
The hash as sha256:<64 lowercase hex digits>.
Throws
IgnifxError with code IGX-1420 when the host exposes no Web Crypto subtle.
Example
const hash = await computeSceneHash(serializeScene(instance)); // "sha256:9f2c…"computeUiLayout()
computeUiLayout(
mode,metrics,reference):UiLayout
Computes the overlay root's size, scale, and offset for one mode and one measured canvas.
Parameters
mode
"css" | "fit" | "dpi"
The scaling mode.
metrics
The canvas's CSS and backing-store sizes.
reference
readonly number[]
The [width, height] a "fit" layout scales to; ignored by the other modes.
Returns
The layout to write onto the root.
Example
computeUiLayout("fit", { cssWidth: 800, cssHeight: 600, deviceWidth: 800, deviceHeight: 600 }, [
400, 300,
]).scale; // 2controlPath()
controlPath(
device,control):string
Builds the binding path of one control.
Parameters
device
The control's device.
control
The control.
Returns
string
The path, with the {index} segment only when the device index is not 0.
controlSlotCount()
controlSlotCount(
controls):number
How many Float32Array slots a control table needs.
Parameters
controls
readonly ControlDescriptor[]
The descriptors from buildControls.
Returns
number
The total slot count.
createAnimatorLoader()
createAnimatorLoader():
AssetLoader<AnimatorAsset>
Builds the loader for .animator.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createAnimatorLoader());createApp()
createApp(
options?):Promise<App>
Creates a game (docs/architecture/00-overview.md §1, 04-extensions.md §2).
Parameters
options?
The canvas or headless, the extensions, the project settings, and the clock.
Returns
Promise<App>
The app, ready to start.
Remarks
The whole of construction happens here: the extension list is built, sorted, and validated, every
register hook runs in order, the Lite engine and scene are created, the project settings are
frozen, and the world is built. Nothing runs a frame until app.start() (browser) or
app.step(dt) (headless).
Throws
IgnifxError with the IGX-04xx codes of 04-extensions.md §2 when the extension list
does not validate, IGX-0408/IGX-0407 when the project settings do not, and IGX-0701 when a
canvas was given but the host has no WebGPU.
Example
const app = await createApp({ headless: true, clock: createManualClock() });
const player = app.world.createEntity("Player");
player.addComponent(Mover);
app.step(1 / 60);
app.dispose();createAssetManifest()
createAssetManifest(
entries,root?):AssetManifest
Builds a manifest from a list of entries — what a test, a tool, or a hand-written config uses in place of the generated file.
Parameters
entries
readonly AssetManifestEntry[]
The addressed files.
root?
string
The asset root relative addresses resolve against. Defaults to "assets".
Returns
The manifest.
Example
const manifest = createAssetManifest([{ address: "data/x.json", url: "assets/data/x.abc123.json" }]);
const app = await createApp({ headless: true, assets: { manifest } });createAudioBusesLoader()
createAudioBusesLoader():
AssetLoader<AudioBusesAsset>
Builds the loader for .audio.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createAudioBusesLoader());createAudioClipLoader()
createAudioClipLoader(
options):AssetLoader<AudioClip>
Builds the loader for audio addresses.
Parameters
options
How to reach the app's decoder.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createAudioClipLoader({ decoder: () => service.decoder() }));createConsoleSink()
createConsoleSink(
options?):LogSink
Creates the default log sink: one console line per record, prefixed with the logger scope and routed to the console method matching the record's level.
Parameters
options?
An alternative console, for tests and for the Electron main process.
Returns
A sink for createLogger.
Example
const log = createLogger({ sink: createConsoleSink(), level: "warn" });createCryptoRandom()
createCryptoRandom():
RandomSource
Creates the production random source, backed by Web Crypto.
Returns
A source that fills buffers with crypto.getRandomValues.
Throws
IgnifxError with code IGX-1420 when the host exposes no Web Crypto implementation.
Example
const nextUid = createUlidFactory({ random: createCryptoRandom() });createDefaults()
createDefaults<
S>(schema):FieldsOf<S>
Builds the initial field object for a schema. Every value is freshly allocated by its field's
own createDefault, so two components declared from the same schema never share a mutable
default such as a vec3 or an array.
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
Parameters
schema
S
The schema to instantiate.
Returns
FieldsOf<S>
A new object holding one default per declared field.
Example
const a = createDefaults(moverSchema);
const b = createDefaults(moverSchema);
a.offset === b.offset; // false — each call allocatescreateDevtoolsLogSink()
createDevtoolsLogSink(
options?):DevtoolsLogSink
Creates the Console panel's sink.
Parameters
options?
The retention limit and the sink to tee to.
Returns
The sink, to pass to both createApp({ logSink }) and devtools({ logSink }).
Example
const sink = createDevtoolsLogSink();
sink.write({ level: "warn", scope: "physics", message: "no collider", data: [], timeMs: 0 });
sink.length; // 1createDiagnosticsGroup()
createDiagnosticsGroup(
name,counterNames):DiagnosticsGroup
Creates a counter group. Diagnostics.registerGroup is the entry point games use; this factory exists so a group can be built and tested on its own.
Parameters
name
string
The group name.
counterNames
readonly string[]
The counter names, in the order their indices are assigned.
Returns
The group.
createEnvironmentLoader()
createEnvironmentLoader():
AssetLoader<EnvironmentAsset>
Builds the loader for .env, .hdr, .dds, and .environment.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createEnvironmentLoader());createErrorCodeRegistry()
createErrorCodeRegistry():
ErrorCodeRegistry
Creates an error code registry pre-loaded with the codes @ignifx/core owns.
Returns
A registry owned by one app.
Example
const registry = createErrorCodeRegistry();
registry.register({ "IGX-9001": "The {thing} was not spawned." }, "game/spawner");
registry.describe("IGX-0701")?.message; // "WebGPU is not available in this environment."createFileStorageBackend()
createFileStorageBackend(
options):Promise<StorageBackend>
Builds a storage backend over a directory (docs/architecture/14-platform-electron.md §5).
Parameters
options
The root directory.
Returns
Promise<StorageBackend>
The backend.
Remarks
Node only: the factory loads node:fs/promises and rejects on a host that has none. It is what
createApp({ storage: { directory } }) calls, and it is exported so that tooling — ignifx bake,
a future authoritative server — can build one without an app.
Throws
IgnifxError with code IGX-1425 when the host exposes no node:fs/promises.
Example
const app = await createApp({ headless: true, storage: { directory: "./.saves" } });
await app.storage.namespace("saves").set("slot1", { level: 3 });createFontLoader()
createFontLoader():
AssetLoader<FontAsset>
Builds the loader for .ttf and .otf addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createFontLoader());createFrameSample()
createFrameSample():
FrameSample
Allocates a frame sample with every counter at zero. Call it once, outside the frame loop — the
out parameter of Diagnostics.readFrame exists so that reading history never allocates.
Returns
A zeroed sample.
Example
const sample = createFrameSample();
for (let index = 0; index < app.diagnostics.historyLength; index += 1) {
app.diagnostics.readFrame(index, sample);
graph.push(sample.rawDeltaMs);
}createInputActionsLoader()
createInputActionsLoader():
AssetLoader<InputActionsAsset>
Builds the loader for .input.json addresses.
Returns
AssetLoader<InputActionsAsset>
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createInputActionsLoader());createKeyboardDevice()
createKeyboardDevice():
InputDevice
Builds the keyboard device.
Returns
A device whose controls are the physical keys plus anyKey.
createLayerTable()
createLayerTable(
names?):LayerTable
Resolves the project's layer names into a table.
Parameters
names?
readonly string[]
The layers project settings section, in declaration order.
Returns
The resolved table.
Throws
IgnifxError with code IGX-0304 on a duplicate name, or IGX-0305 when the names do not
fit in the 32 slots.
Example
const layers = createLayerTable(["Default", "Ground", "Player", "Enemy"]);createLocaleLoader()
createLocaleLoader():
AssetLoader<LocaleAsset>
Builds the loader for .i18n.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createLocaleLoader());createLogger()
createLogger(
options):Logger
Creates the root logger of one app.
Parameters
options
The sink, and optionally the threshold, root scope, and clock.
Returns
The root logger; call Logger.child for scoped loggers.
Example
const log = createLogger({ sink: createConsoleSink(), level: "debug" });
log.child("assets").warnOnce("missing-atlas", "No atlas for sprite {id}.");createManualClock()
createManualClock(
startMs?):ManualClock
Creates a clock a test drives by hand. Headless apps take one so that realtimeSinceStartup and
waitSecondsRealtime are as deterministic as the rest of the frame
(docs/architecture/01-lifecycle-and-time.md §8).
Parameters
startMs?
number
The initial reading. Defaults to 0.
Returns
The clock, with advance and set.
Example
const clock = createManualClock(1000);
clock.advance(1000 / 60);
clock.nowMs(); // 1016.666…createMaterialAsset()
createMaterialAsset(
app,definition,textures):AssetHandle<MaterialAsset>
Builds a Lite material from a declaration and publishes it as an in-memory asset.
Parameters
app
The app whose asset service publishes it.
definition
The declaration.
textures
readonly AssetHandle<TextureAsset>[]
The texture handles the declaration's slots resolved to, in slot order.
Returns
The handle, with one holder — the caller.
Example
using red = createMaterialAsset(app, pbrMaterialDefinition({ name: "red", baseColor: { r: 1, g: 0, b: 0, a: 1 } }), []);createMaterialLoader()
createMaterialLoader():
AssetLoader<MaterialAsset>
Builds the loader for .material.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createMaterialLoader());createMemorySink()
createMemorySink(
limit?):MemorySink
Creates an in-memory ring-buffer sink.
Parameters
limit?
number
How many records to retain. Defaults to DEFAULT_MEMORY_SINK_LIMIT; values below one are clamped to one.
Returns
The sink, with the retained records readable through MemorySink.at.
Example
const sink = createMemorySink(4);
const log = createLogger({ sink, now: () => 0 });
log.warn("no atlas");
sink.at(0)?.level; // "warn"createModelLoader()
createModelLoader():
AssetLoader<ModelAsset>
Builds the loader for .glb and .gltf addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createModelLoader());createMouseDevice()
createMouseDevice():
InputDevice
Builds the mouse device.
Returns
The device behind <Mouse>/… paths.
createNavigatorGamepadReader()
createNavigatorGamepadReader():
GamepadReader|null
The reader that goes through navigator.getGamepads(), or null when the host has no Gamepad
API (Node, and browsers with the feature switched off).
Returns
GamepadReader | null
The reader, or null.
createPerformanceClock()
createPerformanceClock():
Clock
Creates the default clock: performance.now() where the host has it, Date.now() otherwise.
Returns
A clock reading the host's monotonic timer.
createPhysicsMaterial2DLoader()
createPhysicsMaterial2DLoader():
AssetLoader<PhysicsMaterial2D>
Builds the loader for .physicsmaterial.json files.
Returns
AssetLoader<PhysicsMaterial2D>
The loader, ready for ctx.registerAssetLoader.
createPhysicsMaterialLoader()
createPhysicsMaterialLoader():
AssetLoader<PhysicsMaterial>
Builds the loader for .physicsmaterial.json files.
Returns
The loader, ready for ctx.registerAssetLoader.
createPluralSelector()
createPluralSelector(
locale):PluralSelector
Builds the plural selector for a locale.
Parameters
locale
string
The BCP 47 locale tag.
Returns
A function from a number to a plural category.
Remarks
Intl.PluralRules is present in every browser and in Node, but a stripped runtime without
Intl still has to work, so the fallback is English's two-category rule.
Example
createPluralSelector("en")(1); // "one"createPointerDevice()
createPointerDevice():
InputDevice
Builds the unified pointer device: whichever of mouse, pen, or first touch acted last.
Returns
The device behind <Pointer>/… paths.
createRay()
createRay():
Ray
Creates a reusable ray at the origin pointing along +Z.
Returns
A fresh ray. Allocates — make one per call site, not per frame.
Example
const ray = createRay();
camera.screenToRay(event.offsetX, event.offsetY, ray);createSceneAsset()
createSceneAsset(
address,file,dependencies?):Promise<SceneAsset>
Builds a SceneAsset from a file that is already in memory — the shape the loader returns, and
the one tests and tools use when there is no asset service in play.
Parameters
address
string
The address the asset stands at.
file
The parsed file.
dependencies?
readonly AssetHandle<unknown>[]
Every asset the file references, already loaded.
Returns
Promise<SceneAsset>
The asset, with its content hash computed.
Example
const prefab = await createSceneAsset("prefabs/enemy.prefab.json", enemyFile, []);createSceneLoader()
createSceneLoader(
options?):AssetLoader<SceneAsset>
The AssetLoader for *.scene.json and *.prefab.json
(docs/architecture/06-serialization-and-scene-format.md §4 steps 1 and 2, ADR-0005 — one
loader for levels and prefabs).
Parameters
options?
Whether to validate.
Returns
The loader to register with ctx.registerAssetLoader.
Remarks
The loader does everything the file needs before the world sees it: parse, check the header and
the format version, validate the structure, then resolve every $asset it can find — in
settings, in every component's props, and in every instance.scene, recursively through the
scene assets those pull in. The resulting SceneAsset therefore carries a fully loaded
dependency set, which is what makes world.instantiate synchronous
(02-scene-graph.md §2).
Example
ctx.registerAssetLoader(createSceneLoader());
const level = await app.assets.loadAsync<SceneAsset>("levels/level01.scene.json");createSeededRandom()
createSeededRandom(
seed):RandomSource
Creates a deterministic random source: the same seed always produces the same byte stream.
Parameters
seed
number
Any integer; only the low 32 bits are used.
Returns
A source that fills buffers deterministically.
Remarks
The generator is Marsaglia's four-word xorshift128, seeded through a splitmix32-style
scrambler so that neighbouring seeds do not produce correlated streams. It is for tests, replays,
and procedural generation — never for anything security-sensitive.
Example
const nextUid = createUlidFactory({ random: createSeededRandom(1), now: () => 0 });
nextUid() === createUlidFactory({ random: createSeededRandom(1), now: () => 0 })(); // truecreateServiceKey()
createServiceKey<
T>(name):ServiceNameKey<T>
Creates a named service key for a service that has no class to use as a token.
Type Parameters
T
T
The service instance type the key stands for.
Parameters
name
string
A unique, human-readable name, used in IGX-0405 messages.
Returns
The key. It is a plain frozen object, so it is safe at module scope.
Example
export const StorageService: ServiceKey<Storage> = createServiceKey<Storage>("storage");
ctx.registerService(StorageService, new LocalStorage());createSpriteAnimationLoader()
createSpriteAnimationLoader():
AssetLoader<SpriteAnimationAsset>
Builds the loader for .spriteanim.json addresses.
Returns
AssetLoader<SpriteAnimationAsset>
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createSpriteAnimationLoader());createSpriteAtlasLoader()
createSpriteAtlasLoader():
AssetLoader<SpriteAtlasAsset>
Builds the loader for .atlas.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createSpriteAtlasLoader());createTextureLoader()
createTextureLoader():
AssetLoader<TextureAsset>
Builds the loader for .png, .jpg, .jpeg, .webp, .ktx2, and .basis addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createTextureLoader());createTilemapLoader()
createTilemapLoader():
AssetLoader<TilemapAsset>
Builds the loader for .tilemap.json addresses.
Returns
The loader to register with ctx.registerAssetLoader.
Example
ctx.registerAssetLoader(createTilemapLoader());createTouchDevice()
createTouchDevice():
InputDevice
Builds the touch device.
Returns
The device behind <Touch>/… paths.
createUlidFactory()
createUlidFactory(
options?): () =>string
Creates the monotonic ULID generator an app owns.
Parameters
options?
The random source and the clock.
Returns
A function producing the next ULID.
() => string
Remarks
The returned function holds the monotonic state — the last timestamp and its randomness — so that
ids created inside one millisecond still sort in creation order, exactly like the ULID
specification's monotonic mode. The state lives in the closure, never at module scope, so two apps
in one process generate independently (CONSTITUTION.md §3.5, §3.6). A clock that jumps backwards
is pinned to the last timestamp, so ids never go backwards either.
Example
const nextUid = createUlidFactory();
const a = nextUid();
const b = nextUid();
a < b; // true, even inside one millisecondcreateWebAudioBackend()
createWebAudioBackend(
context):Promise<AudioBackend>
Creates the Web Audio backend.
Parameters
context
Whether the app is headless, an audio context to build on, and the initial gain.
Returns
Promise<AudioBackend>
The backend.
Remarks
createAudioEngineAsync calls new AudioContext() when it is handed none, which throws outside a
browser — so this factory is reached only when app.isHeadless is false, or when a test supplies
its own context. Pass an OfflineAudioContext to render deterministically and faster than real
time; Lite reports such an engine as permanently "running" (lib/audio/audio-engine.js), so
there is no unlock to wait for.
Throws
IgnifxError with code IGX-1007 when this host has no Web Audio at all.
Example
const offline = new OfflineAudioContext({ numberOfChannels: 2, length: 44100, sampleRate: 44100 });
const backend = await createWebAudioBackend({ isHeadless: false, audioContext: offline, masterVolume: 1 });curve()
curve(
defaultValue?,options?):FieldDefinition<CurveValue>
Declares an animation curve field.
Parameters
defaultValue?
The curve a new component starts with; defaults to no keys.
options?
Inspector and serializer metadata.
Returns
The field definition.
Example
falloff: curve({ keys: [[0, 1, 0, 0], [1, 0, 0, 0]] });custom()
custom<
T>(codec,options?):FieldDefinition<T>
Declares a field whose JSON form is written by hand. Use it for value types the built-in kinds cannot express; the codec owns the default, the encoding, and the generated JSON Schema fragment.
Type Parameters
T
T
The runtime value type.
Parameters
codec
The default factory, serialize, deserialize, and optional jsonSchema.
options?
Inspector and serializer metadata.
Returns
The field definition.
Example
grid: custom({
createDefault: () => new Uint8Array(16),
serialize: (value) => [...value],
deserialize: (json) => Uint8Array.from(Array.isArray(json) ? json.map(Number) : []),
jsonSchema: { type: "array", items: { type: "integer" } },
});decodeProps()
decodeProps<
S>(schema,json,references):DecodeResult<FieldsOf<S>>
Decodes a component's props object. Fields the file omits take their schema default; names the
schema does not declare are reported as IGX-0607 and ignored.
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
The schema being decoded.
Parameters
schema
S
The schema to decode against.
json
The props object read from the file.
references
How to resolve uids back to entities and components.
Returns
DecodeResult<FieldsOf<S>>
The decoded field object and every problem found.
decodeTileRle()
decodeTileRle(
rle): readonlynumber[]
Expands the [count, value, …] pairs encodeTileRle produces back into a dense array.
Parameters
rle
readonly number[]
The encoded pairs.
Returns
readonly number[]
The dense tile ids.
Throws
IgnifxError with code IGX-1105 when the array has an odd length, or a run count that is
not a finite non-negative integer.
Example
decodeTileRle([2, 1, 3, 0]); // [1, 1, 0, 0, 0]decodeValue()
decodeValue<
T>(field,json,references):DecodeResult<T>
Decodes one JSON value back into a field value. Decoding never throws and never returns a broken
value: unreadable JSON yields the field's freshly built default plus an issue, so a corrupt file
degrades one field rather than failing a whole scene
(docs/architecture/06-serialization-and-scene-format.md §4).
Type Parameters
T
T
The field's value type.
Parameters
field
The field to decode against.
json
The JSON to read.
references
How to resolve uids back to entities and components.
Returns
DecodeResult<T>
The decoded value and every problem found.
Example
decodeValue(vec3(), [1, 2, 3], references); // { value: { x: 1, y: 2, z: 3 }, issues: [] }defaultAudioSettings()
defaultAudioSettings():
AudioSettings
The values used for everything a project omits.
Returns
The default audio section.
defaultDevtoolsSettings()
defaultDevtoolsSettings():
DevtoolsSettings
The values used for everything a project omits.
Returns
The default devtools section.
defaultInputSettings()
defaultInputSettings():
InputSettings
The values used for everything a project omits.
Returns
The default input section.
defaultPhysics2DSettings()
defaultPhysics2DSettings():
Physics2DSettings
The values used when a project omits the physics2d section.
Returns
A fresh defaults object.
defaultPhysicsSettings()
defaultPhysicsSettings():
PhysicsSettings
The values used when a project omits the physics section.
Returns
A fresh defaults object.
defaultRenderingSettings()
defaultRenderingSettings():
RenderingSettings
The settings a project that declares no rendering section runs with: every feature off, Lite's
own swapchain defaults, and an unclamped device pixel ratio.
Returns
A fresh, complete section. It is built on demand rather than frozen at module scope
because requiredLimits and clearColor are mutable objects a caller must not share
(CONSTITUTION.md §3.5).
Example
const defaults = defaultRenderingSettings();
defaults.features.shadows; // falsedefaultStateOf()
defaultStateOf(
definition,layer):string
The state a layer starts in.
Parameters
definition
The document.
layer
The layer.
Returns
string
The state's name.
defaultThreeDSettings()
defaultThreeDSettings():
ThreeDSettings
The values used for everything a project omits.
Returns
The default threeD section.
defaultTwoDSettings()
defaultTwoDSettings():
TwoDSettings
The values used for everything a project omits.
Returns
The default twoD section.
defaultUiSettings()
defaultUiSettings():
UiSettings
The values used for everything a project omits.
Returns
The default ui 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
The document, as authored.
address?
string
What to name in an error; defaults to "<inline>".
Returns
The complete document.
Throws
IgnifxError with code IGX-1201 when the document is not readable.
Example
const definition = defineAnimator(JSON.parse(text) as AnimatorInput, "3d/hero.animator.json");defineExtension()
defineExtension<
O>(factory): (options?) =>Extension
Wraps an extension factory so that it can be called with or without options
(docs/architecture/04-extensions.md §1). Every published extension is written this way; a game's
own extension should be too.
Type Parameters
O
O = void
The options object the factory accepts. Defaults to void for an extension that
takes none.
Parameters
factory
(options) => Extension
Builds the extension descriptor from its options, which are undefined when the
game called the factory without an argument — default them ((options = {})) or read them as optional.
Returns
A factory that may be called with no argument, in which case the options are undefined.
(options?) => Extension
Remarks
The wrapper does nothing at module import time (CONSTITUTION.md §3.5): the factory runs when the
game calls physics(), and even then only builds the descriptor — the work happens in register
and onStart.
Example
export const spawner = defineExtension<{ readonly budget?: number }>((options = {}) => ({
name: "game/spawner",
version: "1.0.0",
requires: ["@ignifx/core"],
register(ctx) {
ctx.registerService(SpawnerService, new SpawnerService(options.budget ?? 32));
},
}));
const app = await createApp({ headless: true, extensions: [spawner({ budget: 64 })] });defineInputActions()
defineInputActions(
input):InputActionsDefinition
Builds an ignifx.inputactions document in code, filling in the format header
(docs/architecture/08-input.md §3: "the same asset can be defined in code with
defineInputActions({...})").
Parameters
input
The maps, and optionally the control schemes and the header.
Returns
The document, identical to what the loader produces for the equivalent .input.json.
Example
const actions = defineInputActions({
maps: [
{
name: "Player",
actions: [{ name: "jump", type: "button", bindings: [{ path: "<Keyboard>/space" }] }],
},
],
});defineSchema()
defineSchema<
S>(fields):S
Declares a component's serialized fields. The helper is an identity function at runtime — it
returns the object it was given — but it checks every field name and, because it is generic,
preserves the exact literal type of the schema so FieldsOf can project it.
Script.define and Component.define call this before they build a base class.
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
Parameters
fields
S
The field definitions, keyed by the property name they become.
Returns
S
The same object, with its precise type preserved.
Throws
A TypeError when a field name is not identifier-like, starts with _, or collides with
a Component/Script member such as enabled or update.
Example
const moverSchema = defineSchema({
speed: f32(5, { min: 0, max: 50 }),
waypoints: array(vec3()),
});defineSpriteAnimation()
defineSpriteAnimation(
input,address?):SpriteAnimationDefinition
Fills in the defaults of an animation document and checks the invariants the animator relies on.
Parameters
input
The document, as authored or as an importer emitted it.
address?
string
What to name in an error; defaults to "<inline>".
Returns
The complete document.
Throws
IgnifxError with code IGX-1104 when the format tag, the version, or a clip is wrong.
defineSpriteAtlas()
defineSpriteAtlas(
input,address?):SpriteAtlasDefinition
Fills in the defaults of an atlas document and checks the invariants a loader relies on.
Parameters
input
The document, as authored or as an importer emitted it.
address?
string
What to name in an error; defaults to "<inline>".
Returns
The complete document.
Throws
IgnifxError with code IGX-1103 when the format tag, the version, the image address, or
a frame rectangle is wrong, or two frames share a name.
defineTilemap()
defineTilemap(
input,address?):TilemapDefinition
Fills in the defaults of a tilemap document, decodes any run-length-encoded layer, and checks the invariants the renderer and the collider rely on.
Parameters
input
The document, as authored or as an importer emitted it.
address?
string
What to name in an error; defaults to "\<inline\>".
Returns
The complete document, with every layer's tiles dense.
Throws
IgnifxError with code IGX-1105 when the format tag or version is wrong, a tile size is
not positive, a tileset's firstId is not positive, two layers share a name, a run-length array
has an odd length, or a layer's decoded tile count is not width * height.
degToRad()
degToRad(
degrees):number
Converts an angle from degrees to radians.
Parameters
degrees
number
The angle in degrees.
Returns
number
The same angle in radians.
deltaAngleDegrees()
deltaAngleDegrees(
fromDegrees,toDegrees):number
The shortest signed rotation from one angle to another, in degrees.
Parameters
fromDegrees
number
The starting angle.
toDegrees
number
The target angle.
Returns
number
The signed difference in [-180, 180).
Example
deltaAngleDegrees(350, 10); // 20, not -340describeAnimatorFormat()
describeAnimatorFormat():
SchemaDescription
Describes the ignifx.animator file format.
Returns
The record pnpm docs:schemas renders.
describeAudioBusesFormat()
describeAudioBusesFormat():
SchemaDescription
Describes the ignifx.audiobuses file format for the documentation harness
(docs/architecture/16-docs-harness-and-skill.md §3).
Returns
The description of the file's fields.
describeEnvironmentFileFormat()
describeEnvironmentFileFormat():
SchemaDescription
Describes the ignifx.environment file format
(docs/architecture/06-serialization-and-scene-format.md §6, 07-rendering.md §2.5).
Returns
The description of the top-level file fields.
describeInputActionsFormat()
describeInputActionsFormat():
SchemaDescription
Describes the ignifx.inputactions file format for the documentation harness.
Returns
The description of the top-level file fields.
describeInputSchemas()
describeInputSchemas():
Readonly<Record<string,SchemaDescription>>
Describes every component and file format this package declares, for the documentation harness.
Returns
Readonly<Record<string, SchemaDescription>>
The records, keyed by namespaced type id.
Example
describeInputSchemas()["ignifx/PlayerInput"].fields["deviceSlot"].default; // 0describeLocaleFileFormat()
describeLocaleFileFormat():
SchemaDescription
Describes the ignifx.i18n file format for the documentation harness.
Returns
The record pnpm docs:schemas renders.
describeMaterialFileFormat()
describeMaterialFileFormat():
SchemaDescription
Describes the ignifx.material file format
(docs/architecture/06-serialization-and-scene-format.md §6, 07-rendering.md §2.6).
Returns
The description of the top-level file fields.
describePhysicsMaterialFileFormat()
describePhysicsMaterialFileFormat():
SchemaDescription
Describes the ignifx.physicsmaterial file format for the documentation harness
(docs/architecture/16-docs-harness-and-skill.md §3).
Returns
The description of the top-level file fields.
describeSceneFileFormat()
describeSceneFileFormat():
SchemaDescription
The docs-harness description of the scene file format
(scripts/README.md, "Schema discovery convention"), so pnpm docs:schemas can render
references/formats/scene.md beside the component pages.
Returns
The description of the top-level file fields.
describeSchema()
describeSchema(
typeId,schema,meta?):SchemaDescription
Describes a component schema in the shape the documentation harness consumes. A package exports
a record of these keyed by typeId; pnpm docs:schemas reads it from the built entry point and
regenerates the format pages and ignifx.schemas.json from it
(scripts/README.md, docs/architecture/16-docs-harness-and-skill.md §3).
Parameters
typeId
string
The component's namespaced registration id, for example mygame/Mover.
schema
The component's declared fields.
meta?
Overrides for the title, format grouping, and summary.
Returns
The description entry.
Example
export const schemas = {
"mygame/Mover": describeSchema("mygame/Mover", moverSchema, { description: "Moves an entity." }),
};describeSchemas()
describeSchemas():
Readonly<Record<string,SchemaDescription>>
Describes every component and file format this package declares, for the documentation harness.
Returns
Readonly<Record<string, SchemaDescription>>
The records, keyed by namespaced type id.
Example
const schemas = describeSchemas();
schemas["ignifx/Camera"].fields["fov"].default; // 60describeSpriteAnimationFormat()
describeSpriteAnimationFormat():
SchemaDescription
Describes the ignifx.spriteanimation file format.
Returns
The record pnpm docs:schemas renders.
describeSpriteAtlasFormat()
describeSpriteAtlasFormat():
SchemaDescription
Describes the ignifx.spriteatlas file format.
Returns
The record pnpm docs:schemas renders.
describeTilemapFormat()
describeTilemapFormat():
SchemaDescription
Describes the ignifx.tilemap file format.
Returns
The record pnpm docs:schemas renders.
describeTwoDSchemas()
describeTwoDSchemas():
Readonly<Record<string,SchemaDescription>>
Describes every component and file format this package declares, for the documentation harness.
Returns
Readonly<Record<string, SchemaDescription>>
The records, keyed by namespaced type id.
Example
describeTwoDSchemas()["ignifx/Camera2D"].fields["orthographicSize"].default; // 5devtoolsError()
devtoolsError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the DevtoolsErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to report.
Example
throw devtoolsError(DevtoolsErrorCode.unknownPanel, "physics2d is not a devtools panel.", {
context: { panel: "physics2d" },
});devtoolsSettingsSchema()
devtoolsSettingsSchema():
Schema
The schema the devtools section is validated against.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
electronError()
electronError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the ElectronErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
throw electronError(ElectronErrorCode.externalUrlRefused, "file: links are not opened.", {
context: { url: "file:///etc/passwd" },
});encodeProps()
encodeProps<
S>(schema,props,references,issues?):JsonObject
Encodes a component's props in canonical key order. Fields the schema declares but props omits
take their default; fields marked transient are skipped.
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
The schema being encoded.
Parameters
schema
S
The schema that fixes the key order.
props
The values to encode, keyed by field name.
references
How to resolve entity and component references to uids.
issues?
An optional collector; problems are appended to it in discovery order.
Returns
The JSON object written under props in a scene file.
encodeTileRle()
encodeTileRle(
tiles): readonlynumber[]
Run-length encodes a dense tile array.
Parameters
tiles
readonly number[]
The dense tile ids.
Returns
readonly number[]
The encoded pairs; empty for an empty input.
Remarks
The layout is flat [count, value, count, value, …] pairs, read left to right, so
[1, 1, 0, 0, 0] encodes to [2, 1, 3, 0]. It is the same shape Tiled's chunk encoding and
LDtk's exports settle on, and it round-trips exactly through decodeTileRle.
Example
encodeTileRle([1, 1, 0, 0, 0]); // [2, 1, 3, 0]encodeValue()
encodeValue<
T>(field,value,references,issues?):JsonValue
Encodes one value into the JSON form the scene format defines
(docs/architecture/06-serialization-and-scene-format.md §3). Numbers are canonicalized,
vectors and colors become arrays, and references become tagged objects.
Encoding is total: it always returns valid JSON. A value that cannot be represented — a NaN, a
reference to something outside the file, a value of the wrong type — is written as null and
reported through issues. Call validateValue when you want the check without the output.
Type Parameters
T
T
The field's value type.
Parameters
field
The field to encode against.
value
T
The value to encode.
references
How to resolve entity and component references to uids.
issues?
An optional collector; problems are appended to it in discovery order.
Returns
The JSON representation.
Example
encodeValue(vec3(), { x: 1, y: 2.0000004, z: -0 }, references); // [1, 2, 0]entityRef()
entityRef<
E>(options?):FieldDefinition<E|null>
Declares a reference to another entity in the same scene file. The value is null until the
scene is fully constructed and is nulled again when the target is destroyed
(docs/architecture/03-scripting-and-components.md §3).
The entity type is supplied by the caller because Entity lives in the kernel, which is layered
above this module.
Type Parameters
E
E = unknown
The entity type the reference resolves to.
Parameters
options?
Inspector and serializer metadata.
Returns
FieldDefinition<E | null>
The field definition.
Example
target: entityRef<Entity>();enumOf()
enumOf<
T>(values,defaultValue,options?):FieldDefinition<T>
Declares a field restricted to a fixed set of string values.
Type Parameters
T
T extends string
Parameters
values
readonly T[]
Every accepted value, in the order the inspector should list them.
defaultValue
NoInfer<T>
The value a new component starts with; NoInfer keeps it out of the
inference for T, so passing a value values does not contain is a compile error as well as a
runtime one.
options?
Inspector and serializer metadata.
Returns
The field definition.
Throws
A TypeError when defaultValue is not one of values.
Example
mode: enumOf(["walk", "run"] as const, "walk");environmentDefinition()
environmentDefinition(
overrides?):EnvironmentDefinition
Fills in an environment declaration's defaults.
Parameters
overrides?
Partial<EnvironmentDefinition>
The properties the file or the caller set.
Returns
A complete declaration.
Example
environmentDefinition({ environment: "environments/studio.env", skyboxEnabled: false });f32()
f32(
defaultValue?,options?):FieldDefinition<number>
Declares a single-precision floating point field.
Parameters
defaultValue?
number
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<number>
The field definition.
Example
speed: f32(5, { min: 0, max: 50, tooltip: "Units per second" });f64()
f64(
defaultValue?,options?):FieldDefinition<number>
Declares a double-precision floating point field.
Parameters
defaultValue?
number
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<number>
The field definition.
fieldInstancesToRecord()
fieldInstancesToRecord(
fields):Readonly<Record<string,string|number|boolean>>
Flattens LDtk's [{ __identifier, __type, __value }] field instances into a plain record.
Parameters
fields
unknown
The value of a fieldInstances field, or anything else.
Returns
Readonly<Record<string, string | number | boolean>>
The flattened record; empty when fields is not a field-instance array.
Remarks
Only string, number and boolean values survive. LDtk's richer field types — points, entity
references, arrays, enum tuples — have no equivalent in the tilemap format's flat property record
and are dropped rather than stringified.
Example
fieldInstancesToRecord([{ __identifier: "facing", __type: "String", __value: "left" }]);
// { facing: "left" }findIgnifxHost()
findIgnifxHost(
scope?):IgnifxHost|null
Finds the preload bridge on a global scope.
Parameters
scope?
unknown
The global to look on; defaults to globalThis. Tests pass a fake.
Returns
IgnifxHost | null
The bridge, or null when there is none.
Remarks
The absence of a bridge is not an error: the same renderer bundle runs in a browser tab, in a
headless Node test, and in an Electron window, and only the third has one. electron() logs one
debug line and stays inert in the other two.
Example
const host = findIgnifxHost();
if (host === null) {
// a browser build
}findTileset()
findTileset(
map,tileId):TilesetDefinition|null
Resolves a global tile id to the tileset that owns it.
Parameters
map
The parsed document.
tileId
number
The global tile id.
Returns
TilesetDefinition | null
The owning tileset, or null for the empty tile and for an id no tileset claims.
Remarks
The owner is the tileset with the highest TilesetDefinition.firstId that is still less
than or equal to tileId — the rule Tiled's firstgid implies. defineTilemap sorts the
tilesets ascending, so this is a backward scan over a handful of entries.
findVirtualDevice()
findVirtualDevice(
app):VirtualDeviceLike|null
Finds app.input.devices.virtual, if @ignifx/input is registered.
Parameters
app
The running app.
Returns
VirtualDeviceLike | null
The device, or null when the input extension is not installed.
Example
const device = findVirtualDevice(app);
device?.setVector("joystick", 0, 1);formatErrorMessage()
formatErrorMessage(
code,message,context,hint,mode):string
Builds the Error.message of an IgnifxError.
Parameters
code
`IGX-${number}`
The stable diagnostic code.
message
string
The actionable development sentence.
context
Identifiers that locate the failure.
hint
string | null
A remedy sentence, or null.
mode
Whether to format for development or production.
Returns
string
The formatted message.
Remarks
Development messages read IGX-0201: Mover requires Rigidbody. [entity=01J…] Hint: add it.
Production messages read IGX-0201 [entity] — enough to look the code up in the registry and to
know which identifiers the context property carries, with no prose in the bundle.
Example
formatErrorMessage("IGX-0303", "Enemy is not a declared layer.", { layer: "Enemy" }, null, "production");
// "IGX-0303 [layer]"gamepadControlNames()
gamepadControlNames(): readonly
string[]
The gamepad control names, in index order.
Returns
readonly string[]
Every control a <Gamepad>/… path may end in.
generateUlid()
generateUlid(
random?,now?):string
Generates one ULID with fresh randomness.
Parameters
random?
Where the 80 random bits come from. Defaults to createCryptoRandom.
now?
() => number
The clock, in milliseconds since the Unix epoch. Defaults to Date.now.
Returns
string
A 26-character ULID.
Remarks
This is the stateless form: every call draws 80 new random bits, so two ids created in the same
millisecond are unordered relative to each other. Monotonic ordering needs state, and state at
module scope is forbidden (CONSTITUTION.md §3.5, §3.6) — use createUlidFactory when
ordering inside a millisecond matters, which is what an app does for entity uids.
Example
const uid = generateUlid();
isUlid(uid); // truegridAtlas()
gridAtlas(
options):SpriteAtlasDefinition
Cuts an evenly spaced sprite sheet into an ignifx.spriteatlas document.
Frames come out in reading order — left to right, then top to bottom — named
<namePrefix>_<index> with index counting from 0 across the whole sheet, so a 4×2
grid ends at tile_7. columns and rows default to as many whole cells as the image holds
(floor((imageWidth - 2·margin + spacing) / (cellWidth + spacing)), and likewise for rows) and
are clamped to that capacity when given, so an over-large explicit count never produces a frame
that falls off the image.
Parameters
options
The sheet's geometry and the frame naming.
Returns
The complete atlas document.
Remarks
namePrefix is how a grid atlas lines up with the rest of the toolkit: @ignifx/2d's Tiled
importer names a tileset's frames <tilesetName>_<index>, so passing the tileset's name
as namePrefix makes a hand-cut grid atlas addressable by exactly the names a tilemap emits.
Throws
IgnifxError with code IGX-1109 when a cell dimension is not positive, or when the
geometry yields no frames at all.
Example
const atlas = gridAtlas({
image: "2d/terrain.png",
imageWidth: 64,
imageHeight: 64,
cellWidth: 32,
cellHeight: 32,
namePrefix: "terrain",
sampling: "nearest",
});
atlas.frames.map((frame) => frame.name); // ["terrain_0", "terrain_1", "terrain_2", "terrain_3"]hostCallError()
hostCallError(
channel,error):Error
Turns a rejection that came back over IPC into an IgnifxError naming the channel.
Parameters
channel
string
The bridge member that failed, for example "storage.set".
error
unknown
What the invoke rejected with.
Returns
Error
The error to reject with.
Remarks
Electron flattens an error thrown inside ipcMain.handle to its message by the time it reaches
the renderer, so nothing but the text survives. Wrapping it keeps the original as cause and
gives the failure a code a game can branch on.
i32()
i32(
defaultValue?,options?):FieldDefinition<number>
Declares a signed 32-bit integer field. Validation rejects fractional values and values outside
the signed 32-bit range with IGX-0606.
Parameters
defaultValue?
number
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<number>
The field definition.
importAsepriteAnimations()
importAsepriteAnimations(
json,options?):SpriteAnimationDefinition
Converts an Aseprite sheet export's tags into an ignifx.spriteanimation document.
Every entry in meta.frameTags becomes one clip, named after the tag, listing the frame names
for indices from through to explicitly rather than as a range — a clip that lists names
survives an atlas being repacked in a different order.
Playback direction is baked into that list, because ignifx clips play forwards:
"forward"(and anything unrecognised) listsfrom … toin order."reverse"lists them backwards."pingpong"lists them forwards and then appends the interior frames in reverse, so a three-frame tag becomes0, 1, 2, 1— the ends are not repeated, which is what makes the clip loop seamlessly.
loop is true unless the tag's repeat is the string "1", Aseprite's "play once".
Parameters
json
unknown
The parsed Aseprite document.
options?
AsepriteAnimationImportOptions
The atlas address, the fallback rate, and a frame-naming override.
Returns
The complete animation document, already through defineSpriteAnimation.
Remarks
Aseprite stores a duration per frame, in milliseconds, while an ignifx clip carries a single
fps. A tag is therefore approximated by the mean of its frames' durations: fps is
1000 / averageDuration, rounded to three decimal places. A tag whose frames all share a
duration converts exactly; one with uneven durations does not, and the individual frames will
hold for the average instead of their authored time. Split such a tag, or even the durations out
in Aseprite, when the timing matters. When no frame in the range declares a positive duration,
options.defaultFps — itself defaulting to 12 — is used instead.
Aseprite has no frame-event concept, so no clip carries events.
Throws
IgnifxError with code IGX-1109 when the document is not an object, when
meta.frameTags is missing, is not an array, or is empty, when a tag has no name, or when
frames cannot be named because the document has no readable frames and no frameNameOf was
supplied.
Example
const animations = importAsepriteAnimations(JSON.parse(text), { atlas: "2d/hero.atlas.json" });
animations.clips[0]; // { name: "idle", frames: ["hero_0", "hero_1"], fps: 10, loop: true }importAsepriteAtlas()
importAsepriteAtlas(
json,options?):SpriteAtlasDefinition
Converts an Aseprite JSON sheet export into an ignifx.spriteatlas document.
Aseprite writes a TexturePacker-shaped document — frames as either a hash or an array,
meta.image, meta.size — plus its own meta.frameTags, meta.slices and meta.layers. The
frame keys it produces are file-ish (hero 0.aseprite, hero (idle) 0.aseprite), so every one
is put through asepriteFrameName; importAsepriteAnimations uses the same normaliser,
which is what makes the imported clips and the imported atlas agree on names.
A trimmed frame keeps its sourceSize so the loader can place the trimmed rectangle back inside
its original bounds.
Parameters
json
unknown
The parsed Aseprite document.
options?
The image override and sampling.
Returns
The complete atlas document.
Remarks
Pivots are best-effort. Aseprite has no per-frame pivot; it has slices, which carry an
optional pivot in sprite-canvas pixels relative to the slice's own bounds and apply from their
key's frame index onwards. This importer takes the slice key with the greatest frame index at
or below the frame being converted (ties going to the earlier slice in document order) and
normalises bounds + pivot against the frame's untrimmed size, clamped into [0, 1]. That is
right for the common case — one slice covering the character, authored on an untrimmed sheet —
and approximate for anything else. Frames no slice covers get the centre.
Throws
IgnifxError with code IGX-1109 when the document is not an object, when frames is
neither an object nor an array, when it is empty, when no image address can be found, or when a
frame has no rectangle.
Example
const atlas = importAsepriteAtlas(JSON.parse(text), { sampling: "nearest" });
atlas.frames[0]?.name; // "hero_idle_0", from the key "hero (idle) 0.aseprite"importLdtkLevel()
importLdtkLevel(
ldtk,options?):TilemapDefinition
Imports one level of an LDtk project.
Parameters
ldtk
unknown
The parsed .ldtk project.
options?
The level to pick, pixels-per-unit, the sorting layer, and the mappings.
Returns
The ignifx.tilemap document for that level.
Remarks
Three LDtk conventions need translating, and each is a place a naive importer goes wrong:
- Layer order is reversed. LDtk stores
layerInstancesfront-to-back — index0is the layer drawn on top. ignifx layers are back-to-front, so the list is reversed andorderInLayerfollows the reversed index. - Tile layers are sparse.
gridTilesis a list of{ px, t }placements, not a grid; the importer expands it into the dense__cWid * __cHeiarray the tilemap format wants, filling the gaps with0.tis a tile index within its tileset, so the global id istileset.firstId + t. A layer'spxOffsetX/pxOffsetYshift the grid; a dense grid has no sub-cell placement, so the offset is rounded to whole cells. - IntGrid layers are collision, not art. An
intGridCsvbecomes a layer withcollision: truewhose ids point into a synthetic, art-less tileset named LDTK_INTGRID_TILESET_NAME; see LDTK_DEFAULT_INTGRID_COLLIDERS for the value mapping and LdtkImportOptions.intGridColliders for overriding it.
A tileset's customData entries are read as JSON, and an entry that parses to an object with
solid: true gives its tile a full-cell box collider. Data that is not JSON, or that says
something else, is ignored rather than treated as an error — customData is a free-form field
and other tools put other things in it.
Per-tile flips (gridTiles[].f) are dropped, as they are in the Tiled importer: the tilemap
format has no per-cell flip yet.
Throws
IgnifxError with code IGX-1109 when the project has no levels, when
LdtkImportOptions.level names a level that is not there, or when a layer's type is not
Tiles, IntGrid or Entities; and IGX-1105 when what it decodes to is not a valid tilemap.
Example
const map = importLdtkLevel(JSON.parse(await readFile("world.ldtk", "utf8")), { level: "Cave" });importTexturePackerAtlas()
importTexturePackerAtlas(
json,options?):SpriteAtlasDefinition
Converts a TexturePacker JSON export into an ignifx.spriteatlas document.
Both of TexturePacker's JSON layouts are read and produce identical output for the same sheet:
the hash layout, whose frames is an object keyed by file name, and the array layout,
whose frames is an array of entries carrying a filename. Frame names lose their trailing file
extension (hero_0.png becomes hero_0) unless keepExtensions is set.
A frame's pivot is used as-is when the document declares one: TexturePacker already writes
pivots normalised into [0, 1] against a top-left origin, which is exactly ignifx's convention.
Frames without one get the centre. A frame marked trimmed carries its sourceSize through so
the loader can lay the trimmed rectangle back inside its original bounds.
Parameters
json
unknown
The parsed TexturePacker document.
options?
The image override, name handling, and sampling.
Returns
The complete atlas document.
Remarks
Rotated frames are rejected rather than silently drawn wrong — the sprite pipeline has no per-frame rotation flag.
spriteSourceSize's offset (x/y) has no home in SpriteFrameDefinition, which records
only the untrimmed size, so a trimmed frame whose art is not centred in its source bounds may sit
slightly off. Pack with trimming disabled, or with spriteSourceSize centred, when that matters.
Throws
IgnifxError with code IGX-1109 when the document is not an object, when frames is
neither an object nor an array, when it is empty, when no image address can be found, when a
frame has no rectangle, or when a frame is rotated.
Example
const atlas = importTexturePackerAtlas(JSON.parse(text), { image: "2d/hero.png" });
atlas.frames[0]?.name; // "hero_0"importTiledMap()
importTiledMap(
tmj,options?):TilemapDefinition
Imports a Tiled JSON map.
Parameters
tmj
unknown
The parsed .tmj document.
options?
Pixels-per-unit, the default sorting layer, and the atlas address mapping.
Returns
The ignifx.tilemap document.
Remarks
Three Tiled features are rejected outright with IGX-1109 rather than approximated: a non
orthogonal orientation, an infinite map (whose layers are chunked rather than dense), and
base64/compressed layer data (which arrives as a string). Everything else degrades quietly —
image layers and group layers are skipped, and unknown properties are carried through.
Tiled stores the horizontal, vertical and diagonal flip flags in the top three bits of every global tile id. ignifx has no per-cell flip yet, so those bits are masked off and the tile draws unflipped; without the mask a flipped tile would resolve to a nonsensical tileset.
The frame names this importer emits are <tilesetName>_<localTileIndex> — the same names
the grid-atlas generator gives the frames it cuts out of the tileset image, which is the contract
that lets TilemapRenderer look a tile's sprite up without a side table.
Throws
IgnifxError with code IGX-1109 when the document is not an orthogonal, finite,
uncompressed Tiled map, and IGX-1105 when what it decodes to is not a valid tilemap.
Example
const map = importTiledMap(JSON.parse(await readFile("cave.tmj", "utf8")), { pixelsPerUnit: 32 });inputActionsJsonSchema()
inputActionsJsonSchema():
JsonObject
The JSON Schema the Vite plugin validates .input.json files against
(docs/architecture/06-serialization-and-scene-format.md §6, §8).
Returns
The schema document.
Example
await writeFile("inputactions.schema.json", JSON.stringify(inputActionsJsonSchema(), null, 2));inputError()
inputError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the InputErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Remarks
IgnifxError's code parameter is the open template type IGX-${number}, so an IGX-08##
literal from the InputErrorCode table is accepted without an assertion.
Example
throw inputError(InputErrorCode.unknownActionMap, "UI is not a registered action map.", {
context: { map: "UI" },
});inputSettingsSchema()
inputSettingsSchema():
Schema
The schema the input section is validated against.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
instantiateScene()
instantiateScene(
world,asset,options?):SceneBuildResult
Builds the entities of a scene asset into a world — steps 3 to 6 of the loading algorithm
(docs/architecture/06-serialization-and-scene-format.md §4). It is synchronous and does no I/O:
every asset the file references is already loaded, which is what a SceneAsset guarantees.
Parameters
world
The world to build into.
asset
The scene to build.
options?
Where to attach the result, and how to treat instance hashes.
Returns
The roots, the uid table, and every recoverable problem.
Remarks
The mechanism that keeps awake honest is worth stating, because §4 step 6 and
01-lifecycle-and-time.md §4 state only the outcome. Entities are created with active: false,
so the enable transition computes "not effectively enabled" and queues nothing. Components are
attached with their schema defaults, then every component's props are decoded — that is where
entityRef and componentRef resolve, through a table that by then holds the whole scene. Only
then does a last pass write each entity's file active value in tree order, which is what queues
awake and onEnable, parents before children. Nothing observes the half-built scene, because
all of this runs in one synchronous block.
Throws
IgnifxError with code IGX-0302 on an instance cycle, IGX-0307 when the file names an
unregistered component type, and IGX-0604 when strictInstanceHashes is set and a recorded
instance hash does not match.
Example
const built = instantiateScene(world, sceneAsset, { scene: world.activeScene });
const player = built.remap.entity("01J9Z6M7E5S3A0V2Q4R8T1Y6WX");inverseLerp()
inverseLerp(
a,b,value):number
The inverse of lerp: finds the interpolant that maps a–b onto value.
Parameters
a
number
The value that maps to 0.
b
number
The value that maps to 1.
value
number
The value to locate.
Returns
number
The interpolant, clamped into [0, 1]. Returns 0 when a and b are equal.
isAssetRef()
isAssetRef(
value):value is AssetRef<unknown>
Reports whether a value is an asset reference rather than a plain address.
Parameters
value
unknown
The candidate.
Returns
value is AssetRef<unknown>
true when the value is an object with a string address.
Example
const address = isAssetRef(input) ? input.address : input;isCompatibleHostVersion()
isCompatibleHostVersion(
version):boolean
Reports whether a bridge's announced version is one this build can talk to.
Parameters
version
string
The value of window.ignifxHost.version.
Returns
boolean
true when the majors match.
Remarks
Major equality, nothing else: a bridge with a newer minor has methods this renderer does not
call, and a bridge with an older minor is caught by the per-member check in
renderer/host.ts rather than by the version string.
Example
isCompatibleHostVersion("1.4.0"); // true
isCompatibleHostVersion("2.0.0"); // falseisEditableElement()
isEditableElement(
node):boolean
Reports whether a focused node is a text-entry element, and therefore owns the keyboard.
Parameters
node
unknown
The node that just received focus, or null.
Returns
boolean
true when typing into it must stop keyboard actions from firing.
Remarks
Deliberately structural rather than instanceof HTMLInputElement: the same function then answers
for a real element in Chromium and for the fake DOM the node suite builds, and two documents in
one page (an <iframe>) do not need their constructors to match.
Example
const field = document.createElement("input");
isEditableElement(field); // true — an <input> with no type is a text fieldisFullCellSolid()
isFullCellSolid(
info,cellSize):boolean
Whether a tile's collider fills its whole cell and is not a one-way platform — the only shape the rectangle merge can absorb.
Parameters
info
The tile's collision info, in cell-local metres.
cellSize
number
The edge length of one cell, in metres.
Returns
boolean
Whether the tile is a plain, full-cell solid.
Example
isFullCellSolid({ shape: { kind: "box", x: 0, y: 0, width: 1, height: 1 }, oneWay: false, properties: {} }, 1);
// trueisIgnifxError()
isIgnifxError(
value):value is IgnifxError
Narrows an unknown value — a catch binding, a rejected promise, a signal payload — to an
IgnifxError.
Parameters
value
unknown
The value to test.
Returns
value is IgnifxError
true when the value is an ignifx error produced by this copy of @ignifx/core.
Example
app.onError.connect((report) => {
if (isIgnifxError(report.error)) {
console.warn(report.error.code, report.error.context);
}
});isSceneFileHeader()
isSceneFileHeader(
value):boolean
Reports whether a parsed JSON value carries the ignifx.scene header. It is the cheap check the
loader runs before anything else, so a .json asset handed to the wrong loader fails with
IGX-0308 rather than a confusing field error.
Parameters
value
unknown
The parsed JSON.
Returns
boolean
true when the value is an object whose format is SCENE_FILE_FORMAT.
isUlid()
isUlid(
value):boolean
Reports whether a string is a canonical ULID: 26 uppercase Crockford base32 characters whose
first character is 7 or lower, because a 48-bit timestamp cannot set the top two bits.
Parameters
value
string
The candidate identifier.
Returns
boolean
true when the string is a well-formed ULID.
Example
isUlid("01ARZ3NDEKTSV4RRFFQ69G5FAV"); // true
isUlid("01arz3ndektsv4rrffq69g5fav"); // false — ULIDs are canonically uppercaseisValidErrorCode()
isValidErrorCode(
code):code is `IGX-${number}`
Reports whether a string is a well-formed ignifx error code.
Parameters
code
string
The candidate code.
Returns
code is `IGX-${number}`
true when the code is well formed and inside an allocated range. The signature is a
type predicate, so a validated string narrows to ErrorCode without a type assertion.
Remarks
The rule has exactly two parts and the ignifx/error-code-format lint rule mirrors it:
- the string is
IGX-followed by four ASCII digits, and - the first two digits are one of the fifteen
ErrorRangeprefixes, or the first digit is THIRD_PARTY_ERROR_PREFIX (the third-party blockIGX-9000–IGX-9999).
Example
isValidErrorCode("IGX-0701"); // true — rendering
isValidErrorCode("IGX-9042"); // true — third party
isValidErrorCode("IGX-1601"); // false — no subsystem owns 16isWebGpuAvailable()
isWebGpuAvailable():
boolean
Reports whether the current environment exposes a WebGPU entry point. This is a capability probe
only: it does not request an adapter, so it never blocks and never allocates GPU resources.
ignifx is WebGPU-only (CONSTITUTION.md §1.1), so this is the gate every renderer path runs first.
Returns
boolean
true when navigator.gpu is present.
Example
if (!isWebGpuAvailable()) {
showWebGpuUnsupportedPage();
}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.
keyboardControlNames()
keyboardControlNames(): readonly
string[]
The keyboard control names, in index order. anyKey is last.
Returns
readonly string[]
The control names a <Keyboard>/… path may end in.
Example
keyboardControlNames().includes("shiftLeft"); // truekeyCodeControlNames()
keyCodeControlNames():
ReadonlyMap<string,string>
The KeyboardEvent.code to control-name table, as a map the DOM adapter resolves through once
per event.
Returns
ReadonlyMap<string, string>
The lookup, built fresh so no module holds mutable state.
layerMask()
layerMask(
defaultValue?,options?):FieldDefinition<readonlystring[]>
Declares a set of layers. Layers are stored by name, not by bit value, so renaming a layer in
project settings does not silently repoint existing files
(docs/architecture/06-serialization-and-scene-format.md §3).
The value type is a read-only array of names in Phase 1; the kernel's LayerMask class arrives
with the layer registry and will satisfy the same structural shape.
Parameters
defaultValue?
readonly string[]
The names a new component starts with; defaults to empty.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<readonly string[]>
The field definition.
Example
collidesWith: layerMask(["Default", "Enemy"]);lerp()
lerp(
a,b,t):number
Linearly interpolates between two values. The interpolant is not clamped, so values outside
[0, 1] extrapolate; wrap t in clamp01 when that is not wanted.
Parameters
a
number
The value returned at t === 0.
b
number
The value returned at t === 1.
t
number
The interpolant.
Returns
number
The interpolated value.
Example
lerp(0, 10, 0.25); // 2.5lerpAngleDegrees()
lerpAngleDegrees(
fromDegrees,toDegrees,t):number
Interpolates between two angles in degrees the short way around the circle.
Parameters
fromDegrees
number
The angle returned at t === 0.
toDegrees
number
The angle approached at t === 1.
t
number
The interpolant; not clamped, matching lerp.
Returns
number
The interpolated angle. It is not wrapped, so feeding the result back in is stable.
Example
lerpAngleDegrees(350, 10, 0.5); // 360localeFileSchema()
localeFileSchema():
Schema
The schema a translation document is described and validated against for tooling.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
Remarks
The loader validates with parseLocaleFile, which produces an actionable IGX-1302
naming the file; this schema is what pnpm docs:schemas renders and what a JSON Schema for an
editor is generated from — the split @ignifx/2d's file-schemas.ts documents.
localeJsonSchema()
localeJsonSchema():
JsonObject
The JSON Schema a tool validates a .i18n.json document against.
Returns
The JSON Schema object.
mainCamera()
mainCamera(
world):Camera|null
The camera the player is looking through.
Parameters
world
The world to look in.
Returns
Camera | null
The highest-priority enabled camera, or null when the world has none.
Example
const camera = mainCamera(this.world);mainCameraForward()
mainCameraForward(
world):Vec3Like
The main camera's forward vector.
Parameters
world
The world to look in.
Returns
The forward vector, or WORLD_FORWARD when there is no camera.
map()
map<
T>(value,options?):FieldDefinition<Record<string,T>>
Declares a string-keyed dictionary field. Keys are written in lexicographic order so that two
saves of the same state are byte-identical
(docs/architecture/06-serialization-and-scene-format.md §1).
Type Parameters
T
T
The entry value type, inferred from value.
Parameters
value
The field definition every entry's value follows.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<Record<string, T>>
The field definition.
Example
ammo: map(i32(0)); // Record<string, number>mergeTileCollisions()
mergeTileCollisions(
infoAt,options,version):TilemapCollisionData
Merges a grid of per-tile collision shapes into chunked, world-space polygons.
Parameters
infoAt
(x, y) => TileCollisionInfo
The per-cell collision info, in cell coordinates with y = 0 at the bottom.
options
The cell size, chunk size, and grid extent.
version
number
The version stamp to carry into the result; callers increment it per rebuild.
Returns
The chunked collision data.
Remarks
Coordinates. infoAt is called with cell coordinates in which y = 0 is the bottom row,
because the ignifx 2D world is +Y up; a caller reading a TilemapLayerDefinition, whose rows run
top-first, indexes it as (height - 1 - y) * width + x. Everything this function emits is world
metres relative to the tilemap's origin, so cell (x, y) spans
[x·cellSize, (x+1)·cellSize] × [y·cellSize, (y+1)·cellSize].
The merge. Each chunk is handled independently, so a later edit rebuilds one chunk rather than the map. Inside a chunk, cells that isFullCellSolid accepts go into a boolean grid and are merged in two greedy passes: first every row is cut into maximal horizontal runs, then a run extends upwards for as long as the row above holds a run with exactly the same span, which is marked consumed. Each surviving block is emitted as one counter-clockwise rectangle. It is the classic row-then-column greedy mesher: linear in cells plus a small scan per row, and optimal for rectangles while deliberately not optimal in general — an L-shape comes out as two rectangles, not one six-vertex polygon, and that is the trade the algorithm makes for being O(n).
Anything the rectangle pass cannot absorb — a partial box, a slope polygon — is emitted as its own
polygon, translated into world metres. Its winding is already counter-clockwise, because
tileCollisionInfo guarantees it.
One-way platforms. A one-way tile contributes no polygon at all; it contributes its collider's
top edge to oneWayEdges. The winding follows the same rule as a polygon: the solid material
is to the left of from → to. For a directed edge d = to − from, "left" is d rotated a
quarter turn counter-clockwise, (−dy, dx). An upward-facing platform is solid below its
surface — that is the half you cannot pass through once you have landed — so we need
(−dy, dx) = (0, −1), giving dy = 0 and dx = −1. The edge therefore runs from its right
end to its left end.
Chunks that end up with neither a polygon nor a one-way edge are omitted entirely.
Example
const data = mergeTileCollisions((x, y) => tileCollisionInfo(map, tileAt(x, y)), {
cellSize: map.cellSize,
chunkSize: 32,
width: map.width,
height: map.height,
}, 1);mouseControlNames()
mouseControlNames(): readonly
string[]
The mouse control names, in index order.
Returns
readonly string[]
leftButton, rightButton, middleButton, position, delta, scroll.
moveTowards()
moveTowards(
current,target,maxDelta):number
Moves a value towards a target without overshooting it.
Parameters
current
number
The value to move.
target
number
The value to move towards.
maxDelta
number
The largest step allowed this call; negative values move away from the target.
Returns
number
The stepped value, exactly target once the remaining distance fits in maxDelta.
Example
// frame-rate independent approach at 2 units per second
health = moveTowards(health, 100, 2 * time.deltaTime);normalisePath()
normalisePath(
path):string
Collapses . and .. segments in a /-separated path.
Parameters
path
string
The path to normalise.
Returns
string
The normalised path; leading .. segments that escape the root are dropped.
optional()
optional<
T>(inner,options?):FieldDefinition<T|null>
Declares a field that may also be null, defaulting to null (coding standards §5.5: null is
"absent value", undefined never reaches a file).
Type Parameters
T
T
The value type when present, inferred from inner.
Parameters
inner
The field definition a non-null value follows.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<T | null>
The field definition.
Example
nickname: optional(str()); // string | nullparseAudioBusesFile()
parseAudioBusesFile(
parsed,address): readonlyAudioBusDefinition[]
Parses and validates a .audio.json document.
Parameters
parsed
unknown
The parsed JSON.
address
string
The address it came from, for diagnostics.
Returns
readonly AudioBusDefinition[]
The buses, parents before children.
Throws
IgnifxError with code IGX-1003 when the header or the buses array is missing,
IGX-1004 when the format version is not readable, IGX-1005 on a duplicate name, or
IGX-1006 on a parent that is not declared earlier.
Example
const buses = parseAudioBusesFile(await ctx.fetchJson(), ctx.address);parseComposite()
parseComposite(
name):CompositeKind
Turns a composite name from a file into its kind.
Parameters
name
string
The composite field of a binding.
Returns
The kind.
Throws
IgnifxError with code IGX-0806 when no composite is spelled that way.
parseControlPath()
parseControlPath(
path):ParsedControlPath
Parses a binding path.
Parameters
path
string
The path, for example <Gamepad>{1}/dpad/up.
Returns
The device family, the device index, and the control name.
Throws
IgnifxError with code IGX-0803 when the path is malformed or names an unknown device.
Example
parseControlPath("<Keyboard>/space"); // { device: "Keyboard", deviceIndex: 0, control: "space" }parseLocaleFile()
parseLocaleFile(
value,address):LocaleDocument
Parses and validates a translation document.
Parameters
value
unknown
The parsed JSON.
address
string
The address it came from, for the error's context.
Returns
The document.
Throws
IgnifxError with code IGX-1302 when the header is missing, the version does not match,
or the file declares no locales.
Example
const document = parseLocaleFile(
{ format: "ignifx.i18n", formatVersion: 1, defaultLocale: "en", locales: { en: { ok: "OK" } } },
"ui/strings.i18n.json",
);
document.locales["en"]?.["ok"]; // "OK"parseMessage()
parseMessage(
pattern):MessagePattern
Parses one message pattern.
Parameters
pattern
string
The pattern, as written in the .i18n.json document.
Returns
The parsed nodes, or the raw text plus the reason it could not be parsed.
Example
parseMessage("{count, plural, one {# life} other {# lives}}").error; // null
parseMessage("{count, plural, one {# life}}").error; // "plural count has no other branch"parseOverridePath()
parseOverridePath(
path):OverridePath
Parses an override path.
Parameters
path
string
The path string from the file.
Returns
The parsed path.
Throws
IgnifxError with code IGX-0609 when the path does not match the grammar.
Example
parseOverridePath("01J…ROOT/components/01J…AI/props/aggression");
// { kind: "prop", entity: "01J…ROOT", component: "01J…AI", steps: ["aggression"] }parsePhysicsMaterial()
parsePhysicsMaterial(
address,document):PhysicsMaterial
Parses one ignifx.physicsmaterial document.
Parameters
address
string
The address it came from, for the diagnostic.
document
The parsed JSON.
Returns
The material.
Throws
IgnifxError with code IGX-0904 when the document is not one this build can read.
parsePhysicsMaterial2D()
parsePhysicsMaterial2D(
address,document):PhysicsMaterial2D
Parses one ignifx.physicsmaterial document into a 2D surface.
Parameters
address
string
The address it came from, for the diagnostic.
document
The parsed JSON.
Returns
The material.
Throws
IgnifxError with code IGX-1154 when the document is not one this build can read.
parseProcessor()
parseProcessor(
source):Processor
Parses one processor string.
Parameters
source
string
The processor, for example deadzone(0.15) or invert.
Returns
The parsed processor with its parameters defaulted.
Throws
IgnifxError with code IGX-0802 when the name is unknown or an argument is not a number.
Example
parseProcessor("scale(0.1)"); // { kind: "scale", first: 0.1, second: 0.1 }parseProcessors()
parseProcessors(
sources): readonlyProcessor[]
Parses a binding's whole processor list.
Parameters
sources
readonly string[]
The processor strings, in application order.
Returns
readonly Processor[]
The parsed chain.
Throws
IgnifxError with code IGX-0802 for the first unparseable entry.
parseSpriteFragment()
parseSpriteFragment(
fragment):string|null
Splits a sprite address into its atlas address and its frame name.
Parameters
fragment
string | null
The part after #, or null for a bare atlas address.
Returns
string | null
The frame name, or null when the fragment does not select a frame.
Example
parseSpriteFragment("frame:idle_0"); // "idle_0"parseWavHeader()
parseWavHeader(
bytes):WavHeader|null
Reads a RIFF/WAVE header.
Parameters
bytes
ArrayBuffer
The whole file, or at least everything up to and including the data chunk header.
Returns
WavHeader | null
The header, or null when the bytes are not a WAV this reader understands — a content
problem degrades rather than throwing (CONSTITUTION.md §3.9).
Remarks
Chunks are walked rather than assumed to be in a fixed order, because encoders routinely insert
LIST, fact, and cue chunks between fmt and data. Each chunk is padded to an even
length, which the walk honours.
Example
const header = parseWavHeader(await ctx.fetchBytes());
const seconds = header?.duration ?? null;pbrMaterialDefinition()
pbrMaterialDefinition(
overrides?):PbrMaterialDefinition
Fills in a PBR declaration's defaults, so callers name only what they mean to change.
Parameters
overrides?
Partial<Omit<PbrMaterialDefinition, "kind">>
The properties to set.
Returns
A complete declaration.
Example
pbrMaterialDefinition({ name: "gold", metallic: 1, roughness: 0.25 });physics2DError()
physics2DError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the Physics2DErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
throw physics2DError(Physics2DErrorCode.unknownLayer, "physics2d.collisionMatrix names Enemy.", {
context: { layer: "Enemy" },
});physics2DSettingsSchema()
physics2DSettingsSchema():
Schema
Builds the schema the physics2d section is validated against.
Returns
The schema.
Remarks
It is a function, not a module-level constant: every field kind is a function call, and module
scope holds declarations and immutable constants only (CONSTITUTION.md §3.5).
physicsError()
physicsError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the PhysicsErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
throw physicsError(PhysicsErrorCode.unknownLayer, "physics.collisionMatrix names Enemy.", {
context: { layer: "Enemy" },
});physicsSettingsSchema()
physicsSettingsSchema():
Schema
Builds the schema the physics section is validated against.
Returns
The schema.
Remarks
It is a function, not a module-level constant: every field kind is a function call, and module
scope holds declarations and immutable constants only (CONSTITUTION.md §3.5).
pingPong()
pingPong(
t,length):number
Bounces a value back and forth between 0 and length, the way a ping-pong animation behaves.
Parameters
t
number
The value to fold.
length
number
The positive half-period to fold into.
Returns
number
A value in [0, length] that rises then falls as t increases.
Example
pingPong(5, 4); // 3pinToDeviceSlot()
pinToDeviceSlot(
definition,slot,scheme):InputActionsDefinition
Rewrites a whole document for one player: gamepad paths pinned to a slot, and — when a scheme is named — bindings tagged with a different scheme dropped.
Parameters
definition
The document to rewrite.
slot
number
The gamepad slot gamepad paths are pinned to.
scheme
string
The control scheme to keep, or "" to keep every binding.
Returns
A new document; the input is not modified.
Example
const player2 = pinToDeviceSlot(definition, 1, "Gamepad");pivotedPositionToRef()
pivotedPositionToRef<
TOut>(anchorXPx,anchorYPx,pivot,widthPx,heightPx,rotationRadians,out):TOut
Places the pivot of a sprite at a world point by offsetting the position Lite draws it at.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
anchorXPx
number
The world anchor, in layer pixels.
anchorYPx
number
The world anchor, in layer pixels.
pivot
The pivot in [0, 1] of the frame; [0, 0] is top-left, [1, 1] bottom-right.
widthPx
number
The drawn width, in pixels.
heightPx
number
The drawn height, in pixels.
rotationRadians
number
The sprite's Lite rotation, which the offset turns with.
out
TOut
The vector to write.
Returns
TOut
out: the value to write to Sprite2DProps.positionPx.
Remarks
Lite's sprite pipeline has one pivot per layer, not per sprite or per frame: the vertex
shader reads L.pivot out of the layer uniform (lib/sprite/sprite-pipeline.js lines 25 and
264–265), and the per-frame SpriteFrame.pivot is consumed only by the billboard family
(lib/sprite/billboard-sprite.js lines 166–167). ignifx therefore keeps every layer on the
centre pivot [0.5, 0.5] and moves the sprite instead, which is what makes a per-frame pivot and
SpriteRenderer.pivotOverride work at all.
pixelMapping()
pixelMapping(
layout,metrics):UiPixelMapping
Builds the backing-store-pixel to UI-unit conversion for one layout and one canvas.
Parameters
layout
The current layout.
metrics
The canvas's CSS and backing-store sizes.
Returns
The mapping.
Example
const metrics = { cssWidth: 400, cssHeight: 300, deviceWidth: 800, deviceHeight: 600 };
const layout = computeUiLayout("css", metrics, [400, 300]);
const map = pixelMapping(layout, metrics);
map.scaleX * 800 - map.originX; // 400 — the canvas's right edge, in CSS pixelspixelsToWorldToRef()
pixelsToWorldToRef<
TOut>(xPx,yPx,pixelsPerUnit,out):TOut
Converts a Lite layer-pixel point back to world metres.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
xPx
number
The layer x, in pixels.
yPx
number
The layer y, in pixels, with +Y down.
pixelsPerUnit
number
The pixels one metre spans.
out
TOut
The vector to write.
Returns
TOut
out, in metres with +Y up.
progressFraction()
progressFraction(
progress):number
The fraction of an asset batch that is done.
Parameters
progress
The payload of app.assets.onProgress.
Returns
number
The fraction, in [0, 1].
Remarks
Bytes when the build recorded sizes, handles otherwise, and 1 for an empty batch — a loading
screen that never reaches 100% because nothing was queued is worse than one that closes at once.
Example
progressFraction({ loaded: 1, total: 4, bytesLoaded: 0, bytesTotal: 0 }); // 0.25projectOnSlopeToRef()
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
The desired direction.
normal
The ground normal.
out
TOut
Where to write the projected direction.
Returns
TOut
out, for chaining.
quat()
quat(
defaultValue?,options?):FieldDefinition<QuatLike>
Declares a rotation field.
Parameters
defaultValue?
The value a new component starts with; defaults to the identity rotation.
options?
Inspector and serializer metadata.
Returns
The field definition.
radToDeg()
radToDeg(
radians):number
Converts an angle from radians to degrees.
Parameters
radians
number
The angle in radians.
Returns
number
The same angle in degrees.
readVec2()
readVec2(
value,fallback):Vec2Like
Normalises either written form of a 2D value.
Parameters
value
Vec2Json | undefined
What the document wrote, or undefined.
fallback
What to use when the document wrote nothing.
Returns
The normalised vector.
record()
record<
S>(fields,options?):FieldDefinition<FieldsOf<S>>
Declares a fixed group of named sub-fields. Sub-fields are serialized as a nested JSON object in declaration order and validated recursively.
Type Parameters
S
S extends Readonly<Record<string, FieldDefinition<unknown>>>
The sub-schema, inferred from fields.
Parameters
fields
S
The sub-fields.
options?
Inspector and serializer metadata.
Returns
The field definition.
Example
stats: record({ hp: i32(10), armor: f32(0) }); // { hp: number; armor: number }renderMessage()
renderMessage(
pattern,params,select):string
Renders a parsed message.
Parameters
pattern
The parsed pattern.
params
The values to substitute.
select
The active locale's plural selector.
Returns
string
The rendered string.
Example
const pattern = parseMessage("{count, plural, one {# life} other {# lives}}");
renderMessage(pattern, { count: 3 }, createPluralSelector("en")); // "3 lives"repeat()
repeat(
t,length):number
Wraps a value into [0, length), the way a looping animation time behaves. Unlike % the result
is never negative.
Parameters
t
number
The value to wrap.
length
number
The positive period to wrap into.
Returns
number
The wrapped value, clamped into [0, length] so float error cannot escape the range.
Example
repeat(-1, 4); // 3resetFrameSample()
resetFrameSample(
sample):FrameSample
Zeroes every counter of a sample in place, reusing its cpuMs array.
Parameters
sample
The sample to reset.
Returns
The same sample, so it can be used as an expression.
resolveClipFrames()
resolveClipFrames(
clip,indexOf): readonlynumber[]
Resolves a clip's frame names into atlas frame indices.
Parameters
clip
The clip to resolve.
indexOf
(name) => number
Maps an atlas frame name to its index, or -1 when the atlas has no such frame.
Returns
readonly number[]
The indices in play order; empty when the clip names nothing the atlas has.
resolveEase()
resolveEase(
ease):EasingFunction|null
Resolves an ease option to the function a tween will call.
Parameters
ease
"linear" | EasingFunction | "quadIn" | "quadOut" | "quadInOut" | "cubicIn" | "cubicOut" | "cubicInOut" | "sineInOut" | "backOut" | "elasticOut" | "bounceOut" | undefined
A name from EASING_NAMES, a custom curve, or undefined for linear.
Returns
EasingFunction | null
The curve, or null when the name is not one the table declares.
Example
const curve = resolveEase("cubicOut");resolveGamepadRemap()
resolveGamepadRemap(
snapshot):GamepadRemap|null
Picks the remap for a pad, or null when the standard order applies.
Parameters
snapshot
The pad reading.
Returns
GamepadRemap | null
The remap, or null for a standard pad.
Example
resolveGamepadRemap({ id: "Pro Controller (Nintendo)", mapping: "", buttons: [], axes: [] });resolveRelative()
resolveRelative(
base,reference):string
Resolves a document-relative reference against the document's own address or URL.
Parameters
base
string
The address or URL of the document holding the reference.
reference
string
What the document wrote.
Returns
string
The resolved address or URL.
Remarks
A reference that is absolute — one of the recognised URL schemes, or one starting with / — is
returned untouched, so a project that prefers project-root addresses can write them. . and ..
segments are collapsed, and a base with no / at all is treated as a file in the root.
Example
resolveRelative("2d/hero.atlas.json", "hero.png"); // "2d/hero.png"
resolveRelative("2d/hero.atlas.json", "../shared/pal.png"); // "shared/pal.png"
resolveRelative("2d/hero.atlas.json", "/sprites/hero.png"); // "/sprites/hero.png"sceneFileJsonSchema()
sceneFileJsonSchema(
registry):JsonObject
The draft 2020-12 JSON Schema for a scene file, with components[].props narrowed per registered
component typeId (docs/architecture/06-serialization-and-scene-format.md §8). The Vite plugin
and the ignifx schemas CLI command emit this into ignifx.schemas.json, which drives
build-time validation and editor autocompletion.
Parameters
registry
The component table whose registered classes narrow props. Classes without a
schema contribute a type match with a free-form props object.
Returns
The schema document.
Example
const schema = sceneFileJsonSchema(app.world.registry);
await writeFile("ignifx.schemas.json", JSON.stringify(schema, null, 2));selectCamera()
selectCamera(
world):Camera2D|null
Picks the camera the frame draws through: the highest-priority enabled Camera2D.
Parameters
world
The world to search.
Returns
Camera2D | null
The camera, or null when the world has none enabled.
serializeComponent()
serializeComponent(
component,references?,onIssue?):SceneFileComponent
Writes one component as a file record, for tooling and tests.
Parameters
component
The component to write.
references?
How entity and component references resolve to uids.
onIssue?
(issue) => void
Receives problems found while encoding props.
Returns
The component record.
Throws
IgnifxError with code IGX-0204 when the component's class declares no typeId.
Example
expect(serializeComponent(mover).props).toEqual({ speed: 5 });serializeEntity()
serializeEntity(
entity,references?):SceneFileEntity
Writes one entity as a file record, for tooling and tests
(docs/architecture/06-serialization-and-scene-format.md §5).
Parameters
entity
The entity to write.
references?
How entity and component references resolve to uids; by default every reference resolves to the target's own uid, which is what an inspector wants.
Returns
The entity record.
Remarks
The entity is written on its own: its parent is whatever its runtime parent's uid is, its
instanced subtree is not consulted, and references to objects outside it become null.
Example
expect(serializeEntity(player).transform.position).toEqual([0, 1, 0]);serializeScene()
serializeScene(
source,options?):SceneFile
Writes a scene instance, or a set of entities, as a scene file object
(docs/architecture/06-serialization-and-scene-format.md §5).
Parameters
source
SceneInstance | readonly Entity[]
The instance to write, or the entities to write as a file's roots.
options?
Flattening, naming, and the issue collector.
Returns
The file object.
Remarks
Everything about the output is fixed so that two saves of the same state are byte-identical:
entities appear in tree order, object keys in the canonical order of §1, numbers rounded by
canonicalizeNumber, props in their schema's declaration order, and properties equal to
their default (active, static, layer, tags, enabled) omitted. Pass the result to
stringifySceneFile for the canonical text.
An entity that came from an instance entry is re-emitted as one — with overrides recomputed by
diffing its current state against the instanced scene — unless flatten is set.
Example
const text = stringifySceneFile(serializeScene(world.activeScene));sign()
sign(
value):number
The sign of a value, with zero treated as positive (matching Unity's Mathf.Sign, and unlike
Math.sign, which returns 0 and -0).
Parameters
value
number
The value to inspect.
Returns
number
-1 for negative values, 1 for positive values and for both 0 and -0, and NaN
for NaN.
sizeForZoom()
sizeForZoom(
viewportHeightPx,zoom,pixelsPerUnit):number
The inverse of zoomForSize: what half-height a zoom shows.
Parameters
viewportHeightPx
number
The viewport height, in pixels.
zoom
number
The Sprite2DView.zoom value.
pixelsPerUnit
number
The pixels one metre spans.
Returns
number
The half-height, in metres.
slopeAngleDegrees()
slopeAngleDegrees(
normal):number
The angle between a ground normal and straight up, in degrees.
Parameters
normal
The ground normal.
Returns
number
The slope angle in degrees; 0 for flat ground.
smoothStep()
smoothStep(
edge0,edge1,x):number
Smoothly interpolates between two edges with a Hermite curve (the GLSL smoothstep), easing in
and out instead of the straight ramp of lerp.
Parameters
edge0
number
The value below which the result is 0.
edge1
number
The value above which the result is 1.
x
number
The value to map.
Returns
number
A value in [0, 1]. Degenerate edges (edge0 === edge1) step from 0 to 1 at the edge.
Example
smoothStep(0, 1, 0.5); // 0.5, but with zero slope at 0 and 1snapPixel()
snapPixel(
valuePx,zoom):number
Snaps a layer-pixel coordinate to the whole-pixel grid a pixel-perfect camera draws on.
Parameters
valuePx
number
The coordinate, in layer pixels.
zoom
number
The camera's zoom; at zoom 2 the grid step is half a layer pixel.
Returns
number
The snapped coordinate.
snapZoomToInteger()
snapZoomToInteger(
zoom):number
Snaps a zoom to the nearest usable integer for a pixel-perfect camera
(docs/architecture/11-2d-toolkit.md §4).
Parameters
zoom
number
The continuous zoom zoomForSize produced.
Returns
number
The snapped zoom, always greater than zero.
Remarks
Zooms below 1 snap to the reciprocal of an integer (1/2, 1/3, …) rather than to zero, so a
camera that is pulled far out still lands on a whole-texel scale.
spawnTilemapObjects()
spawnTilemapObjects(
app,service,tilemap): readonlyEntity[]
Runs the registered factory for every object in one tilemap.
Parameters
app
The app.
service
The 2D service holding the factory registry.
tilemap
The tilemap whose objects layer to walk.
Returns
readonly Entity[]
The entities that were created, in document order.
Example
app.twoD.registerTileObjectFactory("spawn", ({ world, position }) => {
const player = world.createEntity({ name: "player" });
player.transform.position2D = new Vec2(position.x, position.y);
return player;
});spriteAnimationFileSchema()
spriteAnimationFileSchema():
Schema
The ignifx.spriteanimation document schema.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
spriteAnimationJsonSchema()
spriteAnimationJsonSchema():
JsonObject
The JSON Schema a tool validates a .spriteanim.json document against.
Returns
The JSON Schema object.
spriteAtlasFileSchema()
spriteAtlasFileSchema():
Schema
The ignifx.spriteatlas document schema.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
spriteAtlasJsonSchema()
spriteAtlasJsonSchema():
JsonObject
The JSON Schema a tool validates a .atlas.json document against.
Returns
The JSON Schema object.
spriteLayerKey()
spriteLayerKey(
sortingLayer,atlasAddress,blend,screenSpace):string
Builds the composite key two sprites must share to land in one Lite layer.
Parameters
sortingLayer
string
The sorting layer's name.
atlasAddress
string
The atlas's address.
blend
"opaque" | "premultiplied" | "alpha" | "additive" | "multiply"
The blend mode.
screenSpace
boolean
Whether the layer ignores the camera.
Returns
string
The key.
spriteRotationFromLite()
spriteRotationFromLite(
radians):number
Converts a Lite sprite rotation back to ignifx degrees.
Parameters
radians
number
The Sprite2DProps.rotation value.
Returns
number
The ignifx rotation, in degrees counter-clockwise.
spriteRotationToLite()
spriteRotationToLite(
degrees):number
Converts an ignifx rotation about +Z into the rotation Lite gives a sprite.
Parameters
degrees
number
The ignifx rotation, in degrees counter-clockwise.
Returns
number
The rotation to write to Sprite2DProps.rotation, in radians.
Remarks
Transform.rotation2D is degrees counter-clockwise in a +Y-up world. A sprite's quad is built in
Lite's +Y-down pixel space ((corner - pivot) * sizePx, then rotated), so the same visual turn is
the negated angle there. Verified against the sprite vertex shader in
@babylonjs/[email protected], lib/sprite/sprite-pipeline.js line 25.
standardMaterialDefinition()
standardMaterialDefinition(
overrides?):StandardMaterialDefinition
Fills in a Standard declaration's defaults.
Parameters
overrides?
Partial<Omit<StandardMaterialDefinition, "kind">>
The properties to set.
Returns
A complete declaration.
stickAxis()
stickAxis(
delta,length,radius,deadZone):number
Converts a raw deflection into the value written to the control.
Parameters
delta
number
The deflection along one axis, in UI units.
length
number
The deflection's length, in UI units.
radius
number
The radius at which the stick is fully deflected.
deadZone
number
The fraction of the radius below which the stick reads as centred.
Returns
number
The axis value, in -1 to 1.
Example
stickAxis(0, 0, 44, 0.15); // 0
stickAxis(44, 44, 44, 0.15); // 1str()
str(
defaultValue?,options?):FieldDefinition<string>
Declares a string field.
Parameters
defaultValue?
string
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<string>
The field definition.
stringifySceneFile()
stringifySceneFile(
file):string
Writes a scene file as the canonical UTF-8 JSON text: two-space indentation, keys in the order
the serializer built them, numbers already canonicalized by
canonicalizeNumber. Two saves of the same state produce byte-identical text
(docs/architecture/06-serialization-and-scene-format.md §1).
Parameters
file
The file object, normally from serializeScene.
Returns
string
The JSON text, without a trailing newline.
Example
stringifySceneFile(serializeScene(instance)) === stringifySceneFile(serializeScene(instance));threeDError()
threeDError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the ThreeDErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
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
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
tileCollisionInfo()
tileCollisionInfo(
map,tileId):TileCollisionInfo
Resolves a global tile id into the collision information a physics backend consumes.
Parameters
map
The parsed document.
tileId
number
The global tile id, 0 for an empty cell.
Returns
The tile's runtime collision info; a non-colliding, non-one-way default for the empty tile, for an id no tileset claims, and for a tile that declares no collider.
Remarks
This is the only place the authoring convention becomes the runtime one. A TileColliderDefinition is cell-normalised with a top-left origin and +Y down; a TileCollisionShape is cell-local metres with a bottom-left origin, +Y up and counter-clockwise winding. So:
- a box's bottom edge is
(1 - y - height) * cellSize, because the authoredymeasures the distance from the cell's top down to the box's top edge; - a polygon's points each become
(x * cellSize, (1 - y) * cellSize), and the point order is reversed, because mirroring a ring about a horizontal axis flips its winding — a clockwise editor outline is counter-clockwise once flipped only if it is also walked backwards.
Example
// A one-way platform authored as the top quarter of the cell, at cellSize 1:
tileCollisionInfo(map, 2).shape; // { kind: "box", x: 0, y: 0.75, width: 1, height: 0.25 }tiledPropertiesToRecord()
tiledPropertiesToRecord(
properties):Readonly<Record<string,string|number|boolean>>
Flattens Tiled's [{ name, type, value }] property arrays into a plain record.
Parameters
properties
unknown
The value of a Tiled properties field, or anything else.
Returns
Readonly<Record<string, string | number | boolean>>
The flattened record; empty when properties is not a Tiled property array.
Remarks
Only string, number and boolean values survive; Tiled's object and class property types
carry editor-side references that mean nothing at runtime, and are dropped rather than stringified
into something that looks meaningful but is not. color and file properties are strings in the
JSON and come through as strings.
Example
tiledPropertiesToRecord([{ name: "biome", type: "string", value: "cave" }]); // { biome: "cave" }tileFrameName()
tileFrameName(
map,tileId):string|null
The atlas frame a global tile id draws.
Parameters
map
The parsed document.
tileId
number
The global tile id.
Returns
string | null
The frame name, or null for the empty tile and for an id no tileset claims.
Example
tileFrameName(map, 1); // "hero_0"tilemapFileSchema()
tilemapFileSchema():
Schema
The ignifx.tilemap document schema.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
tilemapJsonSchema()
tilemapJsonSchema():
JsonObject
The JSON Schema a tool validates a .tilemap.json document against.
Returns
The JSON Schema object.
toJsonSchema()
toJsonSchema(
schema):JsonObject
Generates the JSON Schema (draft 2020-12) for a component's props object. The harness and the
Vite plugin assemble these into ignifx.schemas.json, which drives build-time validation and
editor autocompletion (docs/architecture/06-serialization-and-scene-format.md §8).
Parameters
schema
The schema to convert.
Returns
The object fragment describing every declared prop.
touchControlNames()
touchControlNames(): readonly
string[]
The touch control names, in index order.
Returns
readonly string[]
primaryTouch/…, touch0/… through touch9/…, and touchCount.
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
const yaw = turnTowardsDegrees(current, target, 720, dt);twoDError()
twoDError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the TwoDErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
throw twoDError(TwoDErrorCode.unknownClip, "hero.spriteanim.json declares no clip named jump.", {
context: { asset: "hero.spriteanim.json", clip: "jump" },
});twoDSettingsSchema()
twoDSettingsSchema():
Schema
The schema the twoD section is validated against, in ignifx.config.ts and in a scene file
alike.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
u32()
u32(
defaultValue?,options?):FieldDefinition<number>
Declares an unsigned 32-bit integer field. Validation rejects fractional and negative values, and
values above 4294967295, with IGX-0606.
Parameters
defaultValue?
number
The value a new component starts with.
options?
Inspector and serializer metadata.
Returns
FieldDefinition<number>
The field definition.
uiError()
uiError(
code,message,options?):IgnifxError
Builds an IgnifxError carrying one of this package's codes.
Parameters
code
The code from the UiErrorCode table.
message
string
The actionable development sentence.
options?
Context identifiers, a remedy hint, and the wrapped cause.
Returns
The error to throw or to reject with.
Example
throw uiError(UiErrorCode.unknownLocale, "fr is not a locale strings.i18n.json declares.", {
context: { locale: "fr" },
});uiSettingsSchema()
uiSettingsSchema():
Schema
The schema the ui section is validated against.
Returns
The schema, built fresh so no module holds state (CONSTITUTION.md §3.5).
validateInputActions()
validateInputActions(
value,file):InputActionsDefinition
Validates a whole ignifx.inputactions document.
Parameters
value
unknown
The parsed JSON.
file
string
The address the document came from, for error context.
Returns
The validated document.
Throws
IgnifxError with code IGX-0805 when the header is wrong or the shape is malformed.
Example
const document = validateInputActions(await ctx.fetchJson(), ctx.address);validateProps()
validateProps(
schema,props,path?): readonlySchemaIssue[]
Checks a bag of property values against a schema. Names the schema does not declare are reported
as IGX-0607; names the caller omits are legal, because omitted props take schema defaults
(docs/architecture/06-serialization-and-scene-format.md §2).
Parameters
schema
The schema to check against.
props
Readonly<Record<string, unknown>>
The values to check, keyed by field name.
path?
string
A property path prefix used when reporting issues; defaults to the empty path.
Returns
readonly SchemaIssue[]
Every problem found, in discovery order; empty when the props are valid.
validateSceneFile()
validateSceneFile(
value): readonlySceneFileIssue[]
Validates a parsed JSON value against the scene file format
(docs/architecture/06-serialization-and-scene-format.md §2).
Parameters
value
unknown
The parsed JSON.
Returns
readonly SceneFileIssue[]
Every problem found, in discovery order; empty when the value is a valid scene file.
Remarks
The checks mirror sceneFileJsonSchema clause for clause — required keys, value types,
tuple lengths, uid uniqueness, and the parent and override shapes — and are hand-written
because the engine ships no JSON Schema runtime and takes no dependency to gain one
(CONSTITUTION.md §2.3). The generated document remains the artefact the Vite plugin and editors
validate against; this is the same rule set, executable at load time.
Component props are not checked here: decodeProps already reports every field problem with
a schema issue code, per field, which is more precise than a document-level match.
Example
const issues = validateSceneFile(JSON.parse(text));
if (issues.length > 0) {
throw new IgnifxError(CoreErrorCode.sceneFileInvalid, issues[0].message);
}validateValue()
validateValue(
field,value,path?): readonlySchemaIssue[]
Checks one value against one field definition. Nothing is thrown: the result is data, and the
caller decides whether a problem is a development-time error or a logged diagnostic
(CONSTITUTION.md §3.9).
Checks performed are the value's type, finiteness for numbers, whole-number and 32-bit range for
i32/u32, min/max from the field options, enum membership, sRGB 0–1 range for colors, and
recursion into array, record, map, and optional.
Parameters
field
FieldDefinition<unknown>
The field to check against.
value
unknown
The value to check.
path?
string
A property path prefix used when reporting issues; defaults to the empty path.
Returns
readonly SchemaIssue[]
Every problem found, in discovery order; empty when the value is valid.
Example
validateValue(f32(0, { min: 0 }), -1);
// [{ path: "", code: "IGX-0606", message: "-1 is below the declared minimum 0." }]vec2()
vec2(
defaultValue?,options?):FieldDefinition<Vec2Like>
Declares a 2D vector field. The runtime value type is the structural Vec2Like, so the engine's
Vec2 class and plain object literals are both accepted.
Parameters
defaultValue?
The value a new component starts with; defaults to the origin.
options?
Inspector and serializer metadata.
Returns
The field definition.
vec3()
vec3(
defaultValue?,options?):FieldDefinition<Vec3Like>
Declares a 3D vector field.
Parameters
defaultValue?
The value a new component starts with; defaults to the origin.
options?
Inspector and serializer metadata.
Returns
The field definition.
Example
offset: vec3({ x: 0, y: 1, z: 0 });vec4()
vec4(
defaultValue?,options?):FieldDefinition<Vec4Like>
Declares a 4D vector field.
Parameters
defaultValue?
The value a new component starts with; defaults to all zeroes.
options?
Inspector and serializer metadata.
Returns
The field definition.
viewRotationToLite()
viewRotationToLite(
degrees):number
Converts a Camera2D rotation into the rotation Lite gives a view.
Parameters
degrees
number
The camera rotation, in degrees counter-clockwise.
Returns
number
The rotation to write to Sprite2DView.rotation, in radians.
Remarks
A view rotation is applied to an already-flipped world offset rather than to a sprite-local
offset, and the two flips cancel — so unlike spriteRotationToLite the sign is kept.
Verified against sprite2DWorldToScreenToRef in @babylonjs/[email protected],
lib/sprite/sprite-2d-view.js.
waitFixedUpdate()
waitFixedUpdate():
WaitInstruction
Waits until just after the next fixed step, so the coroutine sees the same world state a
fixedUpdate would.
Returns
The instruction to yield. Allocates one small object; hoist it into a field when a
loop yields it every iteration.
Example
push() {
const step = waitFixedUpdate();
for (let index = 0; index < 30; index += 1) {
this.body.addForce(this.direction);
yield step;
}
}waitSeconds()
waitSeconds(
seconds):WaitInstruction
Waits for a number of scaled seconds — time.timeScale applies, so a slow-motion effect
slows the wait too.
Parameters
seconds
number
How long to wait, in seconds.
Returns
The instruction to yield. Allocates one small object.
Example
reload() {
this.isReloading = true;
yield waitSeconds(1.5);
this.isReloading = false;
}waitSecondsRealtime()
waitSecondsRealtime(
seconds):WaitInstruction
Waits for a number of unscaled seconds — unaffected by time.timeScale, so a pause menu's
animations keep running while the game is frozen.
Parameters
seconds
number
How long to wait, in seconds of wall-clock time.
Returns
The instruction to yield. Allocates one small object.
waitUntil()
waitUntil(
predicate):WaitInstruction
Waits until a predicate becomes true. The predicate is evaluated once per frame in the
Update phase, so it must be cheap and free of side effects.
Parameters
predicate
() => boolean
Evaluated each frame; the coroutine resumes on the first true.
Returns
The instruction to yield. Allocates one small object.
Example
yield waitUntil(() => this.door.isOpen);waitWhile()
waitWhile(
predicate):WaitInstruction
Waits while a predicate stays true — the complement of waitUntil.
Parameters
predicate
() => boolean
Evaluated each frame; the coroutine resumes on the first false.
Returns
The instruction to yield. Allocates one small object.
worldToPixelsToRef()
worldToPixelsToRef<
TOut>(x,y,pixelsPerUnit,out):TOut
Converts a world point in metres to a Lite layer-pixel point.
Type Parameters
TOut
TOut extends MutableVec2
Parameters
x
number
The world x, in metres.
y
number
The world y, in metres, with +Y up.
pixelsPerUnit
number
The pixels one metre spans.
out
TOut
The vector to write.
Returns
TOut
out, in pixels with +Y down.
Example
worldToPixelsToRef(1.5, 0.5, 100, out); // out is (150, -50)wrapAngleDegrees()
wrapAngleDegrees(
degrees):number
Wraps an angle in degrees into [-180, 180), the range rotations are most readable in.
Parameters
degrees
number
The angle to wrap.
Returns
number
The equivalent angle in [-180, 180); exactly 180 wraps to -180.
Example
wrapAngleDegrees(370); // 10
wrapAngleDegrees(-190); // 170yawFromDirection()
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.
zoomForSize()
zoomForSize(
viewportHeightPx,orthographicSize,pixelsPerUnit):number
The zoom a Camera2D needs so that orthographicSize metres fill half the viewport's height
(docs/architecture/11-2d-toolkit.md §2.1).
Parameters
viewportHeightPx
number
The viewport height, in pixels.
orthographicSize
number
The camera's half-height, in metres.
pixelsPerUnit
number
The pixels one metre spans.
Returns
number
The Sprite2DView.zoom value; never zero, because Lite rejects a zero zoom.