Kiln API / kiln / App

Class: App

The game: a Koota world, resources, events, and a schedule of systems in phases. Build it with createApp(config).use(...).add(Phase, ...), then start(canvas) in the browser or step(n) headless.

Constructors

Constructor

new App(config?): App;

Parameters

Parameter	Type
config	KilnConfig

Returns

App

Properties

config

readonly config: ResolvedConfig;

---

world

readonly world: World;

---

dev

readonly dev: boolean;

---

time

readonly time: TimeState;

---

bus

readonly bus: EventBus;

---

queue

readonly queue: CommandQueue;

---

commands

readonly commands: Commands;

App-level command queue; systems share it.

---

ext

readonly ext: Record<string, any> = {};

Slots plugins attach controllers to (input, renderer, physics world...).

---

hooks

readonly hooks: object;

Lifecycle hooks for plugins.

start

start: Hook<[HTMLCanvasElement | undefined]>[];

Before Startup when the app starts in a browser. Receives the canvas.

fixedStart

fixedStart: Hook<[]>[];

Before each fixed step (render uses it to snapshot the previous transform).

fixedEnd

fixedEnd: Hook<[]>[];

After each fixed step and its commands.

frameStart

frameStart: Hook<[number, boolean]>[];

At the start of each frame, with its delta and whether it runs exactly one fixed step (step()).

frameEnd

frameEnd: Hook<[]>[];

After a frame's Update and Late phases, before Render. Recordings take their checkpoints here.

built

built: Hook<[]>[];

After the schedule is (re)built.

dispose

dispose: Hook<[]>[];

When the app is disposed.

error

error: Hook<[unknown]>[];

When a browser frame throws. The loop pauses; the browser runtime shows an overlay.

---

headless

headless: boolean = true;

True until start() runs in a browser. Render-only work skips itself when headless.

---

profile

profile: boolean = false;

Record per-system timings (the debug plugin turns this on).

---

paused

paused: boolean = false;

While true the browser loop only renders; the simulation is frozen.

---

canvas

canvas: HTMLCanvasElement | undefined;

---

frameRate

readonly frameRate: object;

Browser loop pacing. vsync: true (default) paces frames with requestAnimationFrame; false runs frames back to back (the compositor still presents at the display rate, so this measures throughput). maxFps caps frames per second in either mode; 0 means no cap. Change these at runtime; the debug panel has controls for both.

vsync

vsync: boolean = true;

maxFps

maxFps: number = 0;

---

currentPhase

currentPhase: Phase | null = null;

Accessors

pluginList

Get Signature

get pluginList(): readonly Plugin[];

Plugins used, in order.

Returns

readonly Plugin[]

---

isBooted

Get Signature

get isBooted(): boolean;

True once Startup has run.

Returns

boolean

---

isDisposed

Get Signature

get isDisposed(): boolean;

Returns

boolean

---

input

Get Signature

get input(): InputController;

Scripted and live input: app.input.script([{ frame: 10, press: 'jump' }]). Needs the input plugin.

Returns

InputController

---

resAccess

Get Signature

get resAccess(): Res;

Resource access with the same read-only rules systems get.

Returns

Res

Methods

use()

use(...plugins): this;

Adds plugins. Each plugin is used once, however many times it is passed.

Parameters

Parameter	Type
...plugins	PluginLike[]

Returns

this

---

init()

init(...items): this;

Registers resources (created with their defaults) and event types.

Parameters

Parameter	Type
...items	( | Resource<any> | EventType<any>)[]

Returns

this

---

insert()

insert<T>(r, value): this;

Sets a resource's value, replacing any existing one.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
r	Resource<T>
value	T

Returns

this

---

add()

add(phase, ...items): this;

Adds systems to a phase. Order inside the phase comes from chain() and .after()/.before().

Parameters

Parameter	Type
phase	Phase
...items	Schedulable[]

Returns

this

---

ready()

ready(): Promise<App>;

Resolves when async plugins (e.g. physics WASM) have finished.

Returns

Promise<App>

---

track()

track<T>(work): Promise<T>;

Registers background work (asset loads) that never blocks a phase. app.idle() waits for it; scenarios call it after Startup so headless runs stay deterministic.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
work	Promise<T>

Returns

Promise<T>

---

idle()

idle(): Promise<App>;

Resolves when all tracked background work (e.g. asset loads) has settled.

Returns

Promise<App>

---

resource()

resource<T>(r): T;

The live value of a resource (created on first access). Mutable: for tests and plugins.

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
r	Resource<T>

Returns

T

---

res()

res<T>(r): T;

Shorthand for app.resource(r).

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
r	Resource<T>

Returns

T

---

hasResource()

hasResource(r): boolean;

Parameters

Parameter	Type
r	Resource<any>

Returns

boolean

---

resourceList()

resourceList(): readonly Resource<any>[];

Resources created so far, in creation order.

Returns

readonly Resource<any>[]

---

build()

build(): this;

Builds and validates the schedule if anything changed. Throws errors that name the fix.

Returns

this

---

schedule()

schedule(): ReadonlyMap<Phase, BuiltPhase>;

The built schedule: each phase's systems in run order.

Returns

ReadonlyMap<Phase, BuiltPhase>

---

systemsIn()

systemsIn(phase): readonly CompiledSystem[];

Compiled systems in run order for a phase.

Parameters

Parameter	Type
phase	Phase

Returns

readonly CompiledSystem[]

---

replaceSystem()

replaceSystem(oldSystem, newSystem): boolean;

Swaps one system for another in place, keeping the world. Used by hot reload ('keep'). The schedule is re-validated first; on error the old system stays.

Parameters

Parameter	Type
oldSystem	System
newSystem	System

Returns

boolean

---

boot()

boot(): this;

Builds the schedule and runs Startup once. step() and start() call this for you.

Returns

this

---

step()

step(n?): this;

Advances exactly n frames of one fixed step each, with no renderer. Deterministic for a given seed and input script. Events emitted during the call are readable with app.events(E).

Parameters

Parameter	Type	Default value
n	number	1

Returns

this

---

tick()

tick(dt, exact?): this;

Runs one variable-dt frame: input, 0..N fixed steps, update, late, render. With exact, the frame runs exactly one fixed step as step() does (replays use it for frames stepped that way).

Parameters

Parameter	Type	Default value
dt	number	undefined
exact	boolean	false

Returns

this

---

flush()

flush(): void;

Applies queued commands now. Runs automatically at every phase boundary.

Returns

void

---

start()

start(canvas?, options?): Promise<App>;

Starts the browser loop: runs plugin start hooks (renderer, input devices), Startup, then a requestAnimationFrame loop. Pass { loop: false } to drive frames yourself (kiln shot does), { startup: false } to skip Startup (when restoring a snapshot).

Parameters

Parameter	Type
canvas?	HTMLCanvasElement
options?	{ loop?: boolean; startup?: boolean; }
options.loop?	boolean
options.startup?	boolean

Returns

Promise<App>

---

render()

render(): this;

Renders one frame now without advancing the simulation. Needs a started app.

Returns

this

---

dispose()

dispose(): void;

Stops the loop and frees the world. The app can't be used afterwards.

Returns

void

---

spawn()

Call Signature

spawn<P>(prefab, ...params): Entity;

Spawns immediately (tests and tools). Systems use commands.spawn.

Type Parameters

Type Parameter
P

Parameters

Parameter	Type
prefab	Prefab<P>
...params	P extends void ? [] : [P]

Returns

Entity

Call Signature

spawn(...traits): Entity;

Spawns immediately (tests and tools). Systems use commands.spawn.

Parameters

Parameter	Type
...traits	ConfigurableTrait[]

Returns

Entity

---

despawn()

despawn(entity): void;

Despawns immediately (tests and tools).

Parameters

Parameter	Type
entity	Entity

Returns

void

---

get()

get<T>(entity, trait): TraitRecord<T> | undefined;

A trait's current value on an entity, or undefined.

Type Parameters

Type Parameter
T extends Trait

Parameters

Parameter	Type
entity	Entity
trait	T

Returns

TraitRecord<T> | undefined

---

set()

set<T>(
   entity, 
   trait, 
   value
): void;

Sets fields of a trait on an entity (tests and tools).

Type Parameters

Type Parameter
T extends Trait

Parameters

Parameter	Type
entity	Entity
trait	T
value	Partial<TraitRecord<T>>

Returns

void

---

has()

has(entity, trait): boolean;

Parameters

Parameter	Type
entity	Entity
trait	Trait

Returns

boolean

---

query()

query(...params): readonly Entity[];

Entities matching a query. Mut() and change filters are accepted and ignored.

Parameters

Parameter	Type
...params	QueryParam[]

Returns

readonly Entity[]

---

emit()

emit<T>(e, ...data): void;

Emits an event from outside a system (tests, DOM callbacks).

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
e	EventType<T>
...data	T extends void ? [] : [T]

Returns

void

---

events()

events<T>(e): readonly T[];

Every event of this type emitted during the last app.step() call (or browser frame).

Type Parameters

Type Parameter
T

Parameters

Parameter	Type
e	EventType<T>

Returns

readonly T[]

---

snapshot()

snapshot(options?): Snapshot;

The world as JSON: app.snapshot({ traits: [Transform, Health] }). With no traits, every JSON-friendly trait on every entity. Add resources: [Score] or resources: true.

Parameters

Parameter	Type
options?	SnapshotOptions

Returns

Snapshot

---

diff()

diff(
   a, 
   b, 
   epsilon?
): SnapshotDiff;

Field-level changes between two snapshots. Numbers within epsilon count as equal.

Parameters

Parameter	Type	Default value
a	Snapshot	undefined
b	Snapshot	undefined
epsilon	number	0

Returns

SnapshotDiff

---

restore()

restore(snapshot): object;

Replaces all entities (and listed resources) with a snapshot's. Traits match by name.

Parameters

Parameter	Type
snapshot	Snapshot

Returns

object

missingTraits

missingTraits: string[];

---

describe()

describe(): AppDescription;

The built app as data: phases, systems with reads/writes/order, traits, resources, events.

Returns

AppDescription