---
url: /api/kiln/classes/App.md
---
[Kiln API](../../index.md) / [kiln](../index.md) / 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

```ts
new App(config?): App;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `config` | [`KilnConfig`](../interfaces/KilnConfig.md) |

#### Returns

`App`

## Properties

### config

```ts
readonly config: ResolvedConfig;
```

***

### world

```ts
readonly world: World;
```

***

### dev

```ts
readonly dev: boolean;
```

***

### time

```ts
readonly time: TimeState;
```

***

### bus

```ts
readonly bus: EventBus;
```

***

### queue

```ts
readonly queue: CommandQueue;
```

***

### commands

```ts
readonly commands: Commands;
```

App-level command queue; systems share it.

***

### ext

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

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

***

### hooks

```ts
readonly hooks: object;
```

Lifecycle hooks for plugins.

#### start

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

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

#### fixedStart

```ts
fixedStart: Hook<[]>[];
```

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

#### fixedEnd

```ts
fixedEnd: Hook<[]>[];
```

After each fixed step and its commands.

#### frameStart

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

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

#### frameEnd

```ts
frameEnd: Hook<[]>[];
```

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

#### built

```ts
built: Hook<[]>[];
```

After the schedule is (re)built.

#### dispose

```ts
dispose: Hook<[]>[];
```

When the app is disposed.

#### error

```ts
error: Hook<[unknown]>[];
```

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

***

### headless

```ts
headless: boolean = true;
```

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

***

### profile

```ts
profile: boolean = false;
```

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

***

### paused

```ts
paused: boolean = false;
```

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

***

### canvas

```ts
canvas: HTMLCanvasElement | undefined;
```

***

### frameRate

```ts
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

```ts
vsync: boolean = true;
```

#### maxFps

```ts
maxFps: number = 0;
```

***

### currentPhase

```ts
currentPhase: Phase | null = null;
```

## Accessors

### pluginList

#### Get Signature

```ts
get pluginList(): readonly Plugin[];
```

Plugins used, in order.

##### Returns

readonly [`Plugin`](../interfaces/Plugin.md)\[]

***

### isBooted

#### Get Signature

```ts
get isBooted(): boolean;
```

True once Startup has run.

##### Returns

`boolean`

***

### isDisposed

#### Get Signature

```ts
get isDisposed(): boolean;
```

##### Returns

`boolean`

***

### input

#### Get Signature

```ts
get input(): InputController;
```

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

##### Returns

[`InputController`](../interfaces/InputController.md)

***

### resAccess

#### Get Signature

```ts
get resAccess(): Res;
```

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

##### Returns

[`Res`](../interfaces/Res.md)

## Methods

### use()

```ts
use(...plugins): this;
```

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`plugins` | [`PluginLike`](../type-aliases/PluginLike.md)\[] |

#### Returns

`this`

***

### init()

```ts
init(...items): this;
```

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`items` | ( | [`Resource`](../interfaces/Resource.md)<`any`> | [`EventType`](../interfaces/EventType.md)<`any`>)\[] |

#### Returns

`this`

***

### insert()

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

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

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Resource`](../interfaces/Resource.md)<`T`> |
| `value` | `T` |

#### Returns

`this`

***

### add()

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

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `phase` | [`Phase`](../interfaces/Phase.md) |
| ...`items` | [`Schedulable`](../type-aliases/Schedulable.md)\[] |

#### Returns

`this`

***

### ready()

```ts
ready(): Promise<App>;
```

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

#### Returns

`Promise`<`App`>

***

### track()

```ts
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()

```ts
idle(): Promise<App>;
```

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

#### Returns

`Promise`<`App`>

***

### resource()

```ts
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`](../interfaces/Resource.md)<`T`> |

#### Returns

`T`

***

### res()

```ts
res<T>(r): T;
```

Shorthand for app.resource(r).

#### Type Parameters

| Type Parameter |
| ------ |
| `T` |

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Resource`](../interfaces/Resource.md)<`T`> |

#### Returns

`T`

***

### hasResource()

```ts
hasResource(r): boolean;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `r` | [`Resource`](../interfaces/Resource.md)<`any`> |

#### Returns

`boolean`

***

### resourceList()

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

Resources created so far, in creation order.

#### Returns

readonly [`Resource`](../interfaces/Resource.md)<`any`>\[]

***

### build()

```ts
build(): this;
```

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

#### Returns

`this`

***

### schedule()

```ts
schedule(): ReadonlyMap<Phase, BuiltPhase>;
```

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

#### Returns

`ReadonlyMap`<[`Phase`](../interfaces/Phase.md), `BuiltPhase`>

***

### systemsIn()

```ts
systemsIn(phase): readonly CompiledSystem[];
```

Compiled systems in run order for a phase.

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `phase` | [`Phase`](../interfaces/Phase.md) |

#### Returns

readonly `CompiledSystem`\[]

***

### replaceSystem()

```ts
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`](../interfaces/System.md) |
| `newSystem` | [`System`](../interfaces/System.md) |

#### Returns

`boolean`

***

### boot()

```ts
boot(): this;
```

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

#### Returns

`this`

***

### step()

```ts
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()

```ts
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()

```ts
flush(): void;
```

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

#### Returns

`void`

***

### start()

```ts
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()

```ts
render(): this;
```

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

#### Returns

`this`

***

### dispose()

```ts
dispose(): void;
```

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

#### Returns

`void`

***

### spawn()

#### Call Signature

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

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

##### Type Parameters

| Type Parameter |
| ------ |
| `P` |

##### Parameters

| Parameter | Type |
| ------ | ------ |
| `prefab` | [`Prefab`](../interfaces/Prefab.md)<`P`> |
| ...`params` | `P` *extends* `void` ? \[] : \[`P`] |

##### Returns

`Entity`

#### Call Signature

```ts
spawn(...traits): Entity;
```

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

##### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`traits` | `ConfigurableTrait`\[] |

##### Returns

`Entity`

***

### despawn()

```ts
despawn(entity): void;
```

Despawns immediately (tests and tools).

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `entity` | `Entity` |

#### Returns

`void`

***

### get()

```ts
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()

```ts
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()

```ts
has(entity, trait): boolean;
```

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `entity` | `Entity` |
| `trait` | `Trait` |

#### Returns

`boolean`

***

### query()

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

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| ...`params` | [`QueryParam`](../type-aliases/QueryParam.md)\[] |

#### Returns

readonly `Entity`\[]

***

### emit()

```ts
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`](../interfaces/EventType.md)<`T`> |
| ...`data` | `T` *extends* `void` ? \[] : \[`T`] |

#### Returns

`void`

***

### events()

```ts
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`](../interfaces/EventType.md)<`T`> |

#### Returns

readonly `T`\[]

***

### snapshot()

```ts
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`](../interfaces/SnapshotOptions.md) |

#### Returns

[`Snapshot`](../interfaces/Snapshot.md)

***

### diff()

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

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

#### Parameters

| Parameter | Type | Default value |
| ------ | ------ | ------ |
| `a` | [`Snapshot`](../interfaces/Snapshot.md) | `undefined` |
| `b` | [`Snapshot`](../interfaces/Snapshot.md) | `undefined` |
| `epsilon` | `number` | `0` |

#### Returns

[`SnapshotDiff`](../interfaces/SnapshotDiff.md)

***

### restore()

```ts
restore(snapshot): object;
```

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

#### Parameters

| Parameter | Type |
| ------ | ------ |
| `snapshot` | [`Snapshot`](../interfaces/Snapshot.md) |

#### Returns

`object`

##### missingTraits

```ts
missingTraits: string[];
```

***

### describe()

```ts
describe(): AppDescription;
```

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

#### Returns

[`AppDescription`](../interfaces/AppDescription.md)