ignifx

What this is / when to use#

ignifx is a code-first TypeScript game engine for browsers and Electron. It renders exclusively through WebGPU via Babylon Lite (@babylonjs/lite), and it is designed for indie 2D (top-down, side-scrolling) and 3D (third-person, first-person) games. Use this skill whenever you write or modify code, scenes, or assets for an ignifx project. The engine covers the kernel (app, frame loop, entities, transforms, components, scripts, schemas, coroutines, signals, layers, math), rendering, assets, the scene/prefab format, input, 3D and 2D physics, audio, the 2D and 3D toolkits, UI, Electron, and devtools; each subsystem has its own skill (see "Adding extensions").

Environment#

Mental model#

App (createApp) ─ owns ─▶ World ─ owns ─▶ SceneInstance* ─ owns ─▶ Entity* ─ has ─▶ Transform + Component*
       │                                                                            └─ Script = Component with lifecycle callbacks
       ├─ assets  (addresses ─▶ AssetHandle<T>, reference counted)
       └─ renderer (surface, features, warm-up, picking, screenshots)

Frame: PreUpdate (asset delivery) → awake/onEnable → [fixedUpdate × N] → start → update → coroutines
       → PostUpdate → lateUpdate → destroy flush → PreRender (render sync) → render

• One obvious way per task; no globals: reach everything from this.app, this.world, this.entity.
• Units: metres, seconds, degrees. Left-handed, Y up, +Z forward. 2D is Y up with pixels-per-unit.
• Unity mapping: GameObject → Entity, MonoBehaviour → Script, prefab → instanced scene. Godot mapping: Node → Entity, PackedScene → scene asset, signal → Signal.
• Every phase runs every frame; only the fixed loop and the three script update callbacks pause.

First app#

A camera, a shadow-casting light, a ground plane, and a spinning PBR cube. createApp resolves once the WebGPU engine and every extension are ready; app.start() hands the frame loop to Babylon Lite.

import {  Camera,  Light,  MeshAsset,  MeshRenderer,  Script,  createApp,  createMaterialAsset,  f32,  pbrMaterialDefinition,} from "@ignifx/core";import type { ScriptCallbacks } from "@ignifx/core";class Spinner extends Script.define({ speed: f32(90) }) implements ScriptCallbacks {  static typeId = "demo/Spinner"; // `speed` is a serialized field, degrees per second  update(dt: number): void {    this.transform.rotate({ x: 0, y: this.speed * dt, z: 0 });  }}const canvas = document.querySelector("canvas");if (!(canvas instanceof HTMLCanvasElement)) {  throw new Error("ignifx needs a <canvas> element on the page.");}// Shadows are a Babylon Lite opt-in, declared before the scene is registered (IGX-0704).const app = await createApp({ canvas, settings: { rendering: { features: { shadows: true } } } });app.registerComponents([Spinner]);const eye = app.world.createEntity("Main Camera");eye.transform.localPosition.set(0, 2.5, -4.5);eye.transform.lookAt({ x: 0, y: 0.6, z: 0 });eye.addComponent(Camera, { fov: 55, far: 100 });const sun = app.world.createEntity("Sun");sun.transform.localPosition.set(3, 6, -2);sun.transform.lookAt({ x: 0, y: 0, z: 0 });const light = sun.addComponent(Light, { type: "directional", intensity: 3 });light.shadows.enabled = true;const ground = app.world.createEntity("Ground");ground.addComponent(MeshRenderer, {  mesh: MeshAsset.ground(app, { width: 20, height: 20 }),  castShadows: false,});const ember = createMaterialAsset(  app,  pbrMaterialDefinition({ name: "ember", baseColor: { r: 0.93, g: 0.42, b: 0.16, a: 1 }, roughness: 0.35 }),  [],);const cube = app.world.createEntity("Cube");cube.transform.localPosition.set(0, 0.65, 0);cube.addComponent(MeshRenderer, { mesh: MeshAsset.box(app, { size: 1.3 }), materials: [ember] });cube.addComponent(Spinner, { speed: 120 });await app.start();

Without a GPU — how tests and tools run it — createApp({ headless: true, clock: createManualClock() }), then app.step(1 / 60) per frame and app.dispose(); the extensions example below is exactly that shape. Pump frames rather than stepping a big delta (app.step(dt) is clamped by time.maximumDeltaTime, 0.1 s), and expect one IGX-0706 warning from a world with no Camera — harmless headless, and logLevel: "error" silences it.

Adding extensions#

Extensions register in createApp({ extensions }); each adds an app.<name> service, scripts, asset types, and a settings section, and has a subsystem skill with the detail. Everything below is also re-exported from ignifx. Headless apps drive input with simulate and advance audio playback by the frame delta, so both are testable without a device.

import { audio, AudioSource, createApp, defineInputActions, input } from "ignifx";const app = await createApp({ headless: true, extensions: [input(), audio()] });const jump = { name: "jump", bindings: [{ path: "<Keyboard>/space" }] };app.input.loadActions(defineInputActions({ maps: [{ name: "Player", actions: [jump] }] }));// A clip comes from `app.assets.load<AudioClip>("sfx/jump.wav")`, awaited before `start()` so it// settles without a frame; it is left out here because this block is executed by the docs harness.const source = app.world.createEntity("Player").addComponent(AudioSource, { bus: "SFX" });await app.start();app.input.simulate({ "<Keyboard>/space": 1 });app.step(1 / 60); // the source awakes; `jump.wasPressedThisFrame` now holds for this whole framesource.play({ volume: 0.8 }); // in a browser, queued (not lost) while app.audio.state is "locked"app.audio.bus("SFX").volume = 0.5;

Core APIs#

createApp(options?): Promise<App>#

App#

app.events carries onSceneLoaded, onSceneUnloaded, onDeviceLost ({ reason, message }), onDeviceRecovered, and onDeviceRecoveryFailed. Connect with { owner: this } from a script.

Entity#

World adds createEntity(name?, options?), getEntity(uid), getEntityByHandle(handle), findByName, findAllByName, findByTag, components(Type), activeScene, scenes, layers, registry, mainCamera, raycastRender(ray, options?), the scene API below, and the onEntityCreated/onEntityDestroyed/onSceneLoaded/onSceneUnloaded signals.

Transform#

Rendering components#

Fields and defaults: references/formats/components.md; how they behave: references/concepts/rendering.md.

Camera methods: screenToRay(x, y), worldToScreen(point, out), screenToWorldPoint, viewportToWorldPoint, getViewMatrix(out), getProjectionMatrix(out).

Meshes and materials in code#

There is no mesh file format: geometry is a primitive built in code or part of a ModelAsset. An in-code asset cannot be serialized into a scene file (IGX-0602).

app.assets#

Full page: references/concepts/assets.md.

AssetHandle<T>: address, type, state, value (IGX-0501 unless loaded), promise, progress, error, refCount, retain(), release(), [Symbol.dispose](), onReplaced. LoadOptions: signal, priority, type, onProgress. Every load needs one release, and while the app runs, loads deliver in PreUpdate (state flips next frame); before app.start() they settle at once, so preload, await, then start.

An asset(TypeToken) schema field holds the loaded handle; the file stores { "$asset": "<address>" }. The scene loader resolves every reference before writing props, so awake can read this.mesh.value, and the field never owns the reference count.

Scenes and prefabs#

A prefab and a level are one format, ignifx.scene (ADR-0005). SceneInstance carries uid, name, roots, isLoaded, persistent, settings, asset, remap, onUnloading. A file cannot name a code-built primitive — see references/formats/scene.md.

app.renderer and the rendering settings#

surface (the canvas, null headless), pixelRatio, resolutionScale, setSize(w, h) (OffscreenCanvas only), features, requireFeature(name), warmUp(materials), pickAsync(x, y, options?), captureScreenshot(), drawCalls, gpuFrameTimeMs, profileTasks, taskTimings().

The rendering section is read once, at createApp: features (shadows, postProcessing, skeletons, boneControl, stencil, lightmaps, materialPlugins, asyncPipelines, deviceLostRecovery — all false by default and refused after start with IGX-0704), msaaSamples (1 or 4, default 4), alphaMode, srgb, format, maxDevicePixelRatio, useHighPrecisionMatrix, useFloatingOrigin, requiredLimits, clearColor (a colour object; a Camera.clearColor beats an Environment.clearColor, which beats this), brdfLut (DEFAULT_BRDF_LUT_ADDRESS). There is no powerPreference. The assets section takes root, preload, concurrency, gcDelay, retries.

Script callbacks and their timing#

Callbacks are not members of Script; implement the ones you need, optionally with implements ScriptCallbacks for signature checking.

Statics (static typeId, requires, allowMultiple, executionOrder, updateWhenPaused) and callbacks are written plainly with no override: they are not members of Component/Script; the class-token types match them structurally (ComponentStatics, ScriptStatics) and the registry applies the defaults.

Schema kinds#

Declared with Script.define({...}) / Component.define({...}). Every kind takes FieldOptions last (min, max, step, tooltip, group, hidden, readonly, transient).

Time (app.time)#

Signal<T>#

connect(handler, options?) returns a Disconnect; ConnectOptions is { once?, deferred?, owner? }. emit(value) is synchronous unless the connection is deferred (delivery moves to the next EndOfFrame; a standalone signal throws IGX-0103). disconnect(handler), clear(), connectionCount, owner. Always pass owner: this from a script.

Coroutines#

startCoroutine(routine) / stopCoroutine(handle) / stopAllCoroutines() on a Script, plus the app.coroutines host. A Coroutine is Generator<CoroutineYield, void, unknown>.

defineExtension#

import { Phase, defineExtension } from "@ignifx/core";import type { Extension, ExtensionContext } from "@ignifx/core";export const demo: (options?: void) => Extension = defineExtension<void>(() => ({  name: "game/demo",  version: "1.0.0",  engine: ">=0.1.0 <1.0.0",  requires: ["@ignifx/core"],  register(ctx: ExtensionContext): void {    ctx.requireRenderingFeature("skeletons");    ctx.registerSystem({ name: "game/demo.tick" }, { phase: Phase.Update, order: 1001 });  },}));

ExtensionContext offers app, log, registerComponent(s), registerSystem, registerService, defineAppProperty, registerSettings, settings, require, tryGet, registerAssetType, registerAssetLoader, requireRenderingFeature, registerErrorCodes, and onDispose. Registration errors: IGX-0402 (requires cycle), IGX-0403 (missing), IGX-0404 (engine range), IGX-0406 (duplicate name), IGX-0401 (app property defined twice).

Errors#

Misuse throws IgnifxError with a stable code, a context record, and a hint; isIgnifxError narrows an unknown. AssetLoadError adds address and url. Codes are IGX-####, where the first two digits are the area.

CoreErrorCode names every kernel code; CORE_ERROR_MESSAGES holds the templates. Runtime failures inside callbacks, coroutines, systems, extensions, and the asset pipeline reach app.onError as an ErrorReport rather than being thrown at the caller.

Recipes#

All sixteen — tweens, saves, rebinding, tilemaps, physics queries, the third-person camera rig, devtools counters — are indexed in references/recipes/README.md.

File formats#

assets.manifest.json (format ignifx.manifest, version 1) and the .meta.json sidecar are documented in @ignifx/vite-plugin's README.md, together with virtual:ignifx/manifest and virtual:ignifx/scripts.

Gotchas (top 18)#

1. Rendering features are declared before app.start(). shadows, postProcessing, skeletons, stencil, deviceLostRecovery and the rest are false by default and refused afterwards with IGX-0704. Set settings.rendering.features, or call ctx.requireRenderingFeature(name) from an extension. postProcessing is the one people forget: a PostProcessStack without it logs IGX-0710 and does nothing.
2. A mesh added at runtime appears a few frames late. Spike S2.2 measured 3 extra frames for a cold material family against 0–2 for a warmed one. app.start() warms the boot preload group; use app.renderer.warmUp(materials) for anything loaded later (ADR-0014).
3. One Environment per world (a second logs IGX-0705), point and hemispheric lights cast no shadows (IGX-0703), and a world with no enabled camera renders nothing (IGX-0706).
4. Assets are delivered in PreUpdate once the app runs. A load requested in update is ready on the next frame at the earliest, and handle.value throws IGX-0501 until then. In a headless test that has called app.start(), nothing settles until you app.step(); await loads before start() instead, where they settle as they finish.
5. Pair every load with a release. Handles are shared and reference-counted; using works. An asset() field is not a holder — the scene instance that loaded the asset releases it.
6. active = false hides, destroy() removes. Lite disposes a mesh removed from its last scene, permanently — never unhook Lite objects to hide something.
7. fixedUpdate runs 0…N times per frame. Integrate with its dt argument, never with app.time.deltaTime. And no async lifecycle callbacks: use a coroutine.
8. .lite escape hatches are unstable. app.lite, world.lite, transform.lite, asset.lite expose Babylon Lite objects with no stability guarantee; ask for a first-class API.
9. WebGPU only, no fallback. Probe with isWebGpuAvailable(); createApp({ canvas }) rejects with IGX-0701 when no adapter is available.
10. Degrees in the public API; world getters allocate. A radian API carries a Rad suffix, and transform.position/.forward/… allocate — use positionToRef(out) in hot paths.
11. Browsers start audio locked. app.audio.state is "locked" until a user gesture or app.audio.unlock(); plays made before then are queued, not lost. Headless apps are never locked.
12. Physics needs a completed fixed step and, by default, has no collision identities. Queries throw IGX-0902 before the first step; collision.other is null unless physics({ collisionIdentities: "internal" }) is on, so triggers are the default gameplay mechanism; MeshCollider needs a GPU app.
13. 2D physics filters by the project's first sixteen layers only. Rapier's interaction groups are 16 bits; a 2D collider on a higher layer logs IGX-1152 and falls back to layer 0. Queries throw IGX-1153 before the first fixed step, as in 3D.
14. twoD.pixelsPerUnit is 100 by default, so a 32-px sprite is 0.32 m; set it to your art's pixel size (16, 32) or everything looks tiny. 2D is +Y up in metres; the adapter flips into Lite's pixel space.
15. A click on UI never reaches gameplay, but a drag does. Input reads pointerdown from the canvas and the overlay is its sibling, while pointermove/pointerup come from the window — so the UI host sets app.input.uiHasPointer during such a drag and pointing-device actions read as released. Pointer positions are backing-store pixels, the space pickAsync and worldToScreen use. Only text fields set app.input.uiHasFocus. WorldText must exist before app.start() (IGX-1308); spawn WorldText2D mid-game instead.
16. Two Models of one .glb cannot be animated independently. Lite binds an animation group to one manager and a cloned skinned mesh shares the template's skeleton, so a second Animator is refused the clips (reported on app.onError). Load the .glb under a second address for a second animated character.
17. A sandboxed Electron preload cannot be an ES module. An .mjs preload leaves window.ignifxHost undefined with no error at all; build desktop/preload.ts as CommonJS (index.cjs). Device-loss recovery needs shadows.technique = "esm"; PCF shadow maps do not survive a lost device.
18. Hot reload "patch" keeps state and skips every lifecycle callback. Change a field layout and write static hotReload = "recreate", or the engine re-creates anyway with an IGX-0207 warning; wire it with acceptHotReload(app) from virtual:ignifx/scripts.

The full list, with error codes, is in references/gotchas.md.

Deprecated (current window)#

None (pre-1.0: no deprecation window; breaking changes are listed in the changelog).

Where to look next#

docs/migrations/ exists only after 1.0.