@waica/engine 0.3.0

package/dist/game.js

@@ -0,0 +1,263 @@
+import * as THREE from 'three';
+import { collisionOverlap } from './collision-shape.js';
+import { resolveSceneCamera, stepSceneCamera } from './camera.js';
+import { Hitbox } from './components/hitbox.js';
+import { Entity } from './entity.js';
+import { Emitter } from './events.js';
+import { Input } from './input.js';
+import { registryEntry, spawnFromJson } from './scene.js';
+import { Stats } from './stats.js';
+import { GameUi } from './ui.js';
+/**
+ * Engine core: loop, unified 2D/3D three scene, orthographic camera,
+ * entities with components, and input. See DESIGN.md.
+ */
+export class Game {
+    scene = new THREE.Scene();
+    camera;
+    input;
+    entities = [];
+    events = new Emitter();
+    stats;
+    /** The HTML UI layer: presentation-only pieces toggled from code. */
+    ui;
+    /** Registry retained by loadScene for runtime prefab spawning. */
+    registry = null;
+    paramOverrides = {};
+    /**
+     * With false, the loop keeps rendering but runs no component updates
+     * or collisions — the editor's edit mode.
+     */
+    simulate = true;
+    // TODO(H1): migrate to WebGPURenderer (three/webgpu) with automatic WebGL2 fallback.
+    renderer;
+    resizeObserver;
+    updateFns = new Set();
+    resolution;
+    viewHeight;
+    sceneCamera = null;
+    lastTime = 0;
+    constructor(options) {
+        const { canvas, background = 0x1a1a2e, viewHeight = 10 } = options;
+        this.viewHeight = viewHeight;
+        this.resolution = options.resolution ?? null;
+        this.input = new Input(options.bindings);
+        this.stats = new Stats(options.stats);
+        this.ui = new GameUi(this.stats, () => canvas.parentElement ?? document.body);
+        this.renderer = new THREE.WebGLRenderer({ canvas, antialias: true });
+        this.renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+        this.scene.background = new THREE.Color(background);
+        this.camera = new THREE.OrthographicCamera();
+        this.camera.position.z = 10;
+        this.resize();
+        this.resizeObserver = new ResizeObserver(() => this.resize());
+        this.resizeObserver.observe(canvas);
+    }
+    /** Creates a live entity in the scene. */
+    spawn(name) {
+        const entity = new Entity(this, name);
+        this.entities.push(entity);
+        this.scene.add(entity.node);
+        return entity;
+    }
+    /** Instantiates a registered prefab after a scene has supplied the registry. */
+    spawnPrefab(prefab, options = {}) {
+        const registry = this.registry;
+        if (!registry) {
+            console.warn(`[waica] cannot spawn prefab before loadScene: "${prefab}"`);
+            return null;
+        }
+        if (!registryEntry(registry.prefabs, prefab)) {
+            console.warn(`[waica] unknown runtime prefab: "${prefab}"`);
+            return null;
+        }
+        const base = prefab.slice(prefab.lastIndexOf('/') + 1) || 'Entity';
+        const name = options.name ?? base.charAt(0).toUpperCase() + base.slice(1);
+        return spawnFromJson(this, { name, prefab, ...(options.position ? { position: options.position } : {}) }, registry);
+    }
+    /** Finds an entity by name. */
+    find(name) {
+        return this.entities.find((e) => e.name === name);
+    }
+    /** Loads persisted parameter overrides (waica.params.json). */
+    async loadParams(url) {
+        try {
+            const res = await fetch(url);
+            if (res.ok)
+                this.paramOverrides = (await res.json());
+        }
+        catch {
+            // no params file: the archetype defaults apply
+        }
+    }
+    /** Applies persisted overrides to a freshly added component. */
+    applyParamOverrides(entity, component) {
+        const Class = component.constructor;
+        const override = this.paramOverrides[entity.name]?.[Class.componentName];
+        if (override)
+            Object.assign(component, override);
+    }
+    /** Registers a function that runs once per frame. Returns the unsubscribe. */
+    onUpdate(fn) {
+        this.updateFns.add(fn);
+        return () => this.updateFns.delete(fn);
+    }
+    /**
+     * Adopts a scene's camera block: jumps to its framing and, while
+     * simulating, follows/clamps per its settings. Called by loadScene.
+     */
+    setSceneCamera(json) {
+        // No camera block: leave the camera to the host (constructor viewHeight).
+        if (!json) {
+            this.sceneCamera = null;
+            return;
+        }
+        this.sceneCamera = resolveSceneCamera(json);
+        // With a follow target the declared position is moot: start centered on
+        // the target so play begins framed like the editor shows it.
+        const followed = this.sceneCamera.follow ? this.find(this.sceneCamera.follow) : undefined;
+        const [x, y] = followed
+            ? [followed.position.x, followed.position.y]
+            : this.sceneCamera.position;
+        this.camera.position.x = x;
+        this.camera.position.y = y;
+        this.setViewHeight(this.sceneCamera.zoom);
+    }
+    start() {
+        this.renderer.setAnimationLoop((time) => this.tick(time));
+    }
+    stop() {
+        this.renderer.setAnimationLoop(null);
+    }
+    /** Internal: called by Entity.destroy(). */
+    removeEntity(entity) {
+        const i = this.entities.indexOf(entity);
+        if (i !== -1)
+            this.entities.splice(i, 1);
+    }
+    /** Visible world height (2D camera zoom). */
+    get view() {
+        return this.viewHeight;
+    }
+    setViewHeight(value) {
+        this.viewHeight = Math.min(Math.max(value, 2), 80);
+        this.resize();
+    }
+    /** Shuts the game down completely (loop, input, GPU). */
+    dispose() {
+        this.stop();
+        this.input.dispose();
+        this.resizeObserver.disconnect();
+        this.ui.dispose();
+        for (const entity of [...this.entities])
+            entity.destroy();
+        this.renderer.dispose();
+    }
+    tick(time) {
+        // Clamp dt: switching tabs or pausing doesn't fast-forward the simulation.
+        const dt = Math.min((time - this.lastTime) / 1000, 0.1);
+        this.lastTime = time;
+        if (this.simulate) {
+            for (const entity of [...this.entities]) {
+                for (const component of [...entity.components])
+                    component.onUpdate?.(dt);
+            }
+            this.dispatchCollisions();
+            this.updateSceneCamera(dt);
+        }
+        // The UI must react to the pause itself (hide until resumed).
+        this.ui.setActive(this.simulate);
+        for (const fn of this.updateFns)
+            fn(dt);
+        this.input.endFrame();
+        if (this.resolution) {
+            // Letterbox bars: clear the whole canvas, then render inside the scissor.
+            this.renderer.setScissorTest(false);
+            this.renderer.setClearColor(0x000000, 1);
+            this.renderer.clear(true, false, false);
+            this.renderer.setScissorTest(true);
+        }
+        this.renderer.render(this.scene, this.camera);
+    }
+    updateSceneCamera(dt) {
+        const cam = this.sceneCamera;
+        if (!cam)
+            return;
+        const followed = cam.follow ? this.find(cam.follow) : undefined;
+        const mover = followed?.components.find((c) => typeof c.vx === 'number');
+        const next = stepSceneCamera(cam, {
+            x: this.camera.position.x,
+            y: this.camera.position.y,
+            halfW: (this.camera.right - this.camera.left) / 2,
+            halfH: this.viewHeight / 2,
+            target: followed ? { x: followed.position.x, y: followed.position.y } : null,
+            vx: mover?.vx ?? 0,
+            dt,
+        });
+        this.camera.position.x = next.x;
+        this.camera.position.y = next.y;
+    }
+    dispatchCollisions() {
+        const boxed = this.entities.filter((e) => e.has(Hitbox));
+        for (let i = 0; i < boxed.length; i++) {
+            for (let j = i + 1; j < boxed.length; j++) {
+                const a = boxed[i];
+                const b = boxed[j];
+                if (!a?.alive || !b?.alive)
+                    continue;
+                const ha = a.get(Hitbox);
+                const hb = b.get(Hitbox);
+                if (!ha || !hb)
+                    continue;
+                const hit = collisionOverlap({
+                    x: a.position.x + ha.offsetX,
+                    y: a.position.y + ha.offsetY,
+                    width: ha.width,
+                    height: ha.height,
+                    shape: ha.shape,
+                    points: ha.points,
+                }, {
+                    x: b.position.x + hb.offsetX,
+                    y: b.position.y + hb.offsetY,
+                    width: hb.width,
+                    height: hb.height,
+                    shape: hb.shape,
+                    points: hb.points,
+                });
+                if (!hit)
+                    continue;
+                for (const c of [...a.components])
+                    c.onCollide?.(b);
+                if (!a.alive || !b.alive)
+                    continue;
+                for (const c of [...b.components])
+                    c.onCollide?.(a);
+            }
+        }
+    }
+    resize() {
+        const canvas = this.renderer.domElement;
+        const { clientWidth: w, clientHeight: h } = canvas;
+        if (w === 0 || h === 0)
+            return;
+        this.renderer.setSize(w, h, false);
+        let aspect = w / h;
+        if (this.resolution) {
+            // Fixed resolution: the largest rect with its aspect, centered (letterbox).
+            aspect = this.resolution.width / this.resolution.height;
+            const vw = Math.min(w, h * aspect);
+            const vh = vw / aspect;
+            const vx = (w - vw) / 2;
+            const vy = (h - vh) / 2;
+            this.renderer.setViewport(vx, vy, vw, vh);
+            this.renderer.setScissor(vx, vy, vw, vh);
+        }
+        const halfH = this.viewHeight / 2;
+        const halfW = halfH * aspect;
+        this.camera.left = -halfW;
+        this.camera.right = halfW;
+        this.camera.top = halfH;
+        this.camera.bottom = -halfH;
+        this.camera.updateProjectionMatrix();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,39 @@
+export { Game } from './game.js';
+export type { GameOptions, GameResolution, SpawnPrefabOptions, UpdateFn, ParamOverrides, } from './game.js';
+export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export type { SceneCameraJson, CameraLimitsJson, ResolvedSceneCamera } from './camera.js';
+export { Entity } from './entity.js';
+export { Component } from './component.js';
+export type { ComponentClass, ContactNormal, ParamSpec, SolidContact, } from './component.js';
+export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
+export type { ComponentModule } from './component-registry.js';
+export { Input, DEFAULT_BINDINGS } from './input.js';
+export type { ActionName, InputBindings } from './input.js';
+export type { ArchetypeArt, ArchetypeManifest, BrowserArchetypeManifest, EntityTemplate, } from './archetype.js';
+export { Stats } from './stats.js';
+export type { StatValue } from './stats.js';
+export { GameUi } from './ui.js';
+export { Sprite } from './components/sprite.js';
+export { Solid } from './components/solid.js';
+export { Hitbox } from './components/hitbox.js';
+export { DynamicBody } from './components/dynamic-body.js';
+export { AnimatedSprite } from './components/animated-sprite.js';
+export { aabbOverlap } from './aabb.js';
+export { resolveSolidAxis } from './solid-axis.js';
+export type { CollisionAxis, SolidAxisOptions } from './solid-axis.js';
+export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
+export type { CollisionBody, CollisionBounds, CollisionPoint, CollisionShape, } from './collision-shape.js';
+export { Emitter } from './events.js';
+export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
+export type { SceneJson, SceneEntityJson, SceneComponentJson, SceneRegistry, PrefabJson } from './scene.js';
+export { ClipPlayer } from './animation/clip-player.js';
+export type { ClipDef } from './animation/clip-player.js';
+export { sheetCell, sheetFrameCount, locateFrame } from './animation/sheet.js';
+export type { SheetGridParams, SheetCell, SheetDef } from './animation/sheet.js';
+export { resolveClip, missingClips } from './animation/contract.js';
+export type { AnimationContract } from './animation/contract.js';
+export { StateMachine, evaluateTrigger, nextTransition } from './state/state-machine.js';
+export type { StateJson, StateTransitionJson, TriggerEnv } from './state/state-machine.js';
+export { defineRole, defineStates, installArchetype, logicSet, registeredLogicSets, registeredRoles, resetRegistries, roleDefinition, } from './state/hooks.js';
+export type { ArchetypeBundle, RoleDefinition, RoleGraph, StateContext, StateHooks, StateLogic, } from './state/hooks.js';
+export * as THREE from 'three';

package/dist/index.js

@@ -0,0 +1,26 @@
+export { Game } from './game.js';
+export { CAMERA_DEFAULTS, resolveSceneCamera, stepSceneCamera } from './camera.js';
+export { Entity } from './entity.js';
+export { Component } from './component.js';
+export { collectModuleComponents, mergeRegistryComponents } from './component-registry.js';
+export { Input, DEFAULT_BINDINGS } from './input.js';
+export { Stats } from './stats.js';
+export { GameUi } from './ui.js';
+export { Sprite } from './components/sprite.js';
+export { Solid } from './components/solid.js';
+export { Hitbox } from './components/hitbox.js';
+export { DynamicBody } from './components/dynamic-body.js';
+export { AnimatedSprite } from './components/animated-sprite.js';
+export { aabbOverlap } from './aabb.js';
+export { resolveSolidAxis } from './solid-axis.js';
+export { COLLISION_SHAPES, DEFAULT_COLLISION_POLYGON, collisionBounds, collisionOverlap, collisionVertices, resolveCollisionPoints, } from './collision-shape.js';
+export { Emitter } from './events.js';
+export { loadScene, spawnFromJson, resolveEntityComponents, resolveProps } from './scene.js';
+export { ClipPlayer } from './animation/clip-player.js';
+export { sheetCell, sheetFrameCount, locateFrame } from './animation/sheet.js';
+export { resolveClip, missingClips } from './animation/contract.js';
+export { StateMachine, evaluateTrigger, nextTransition } from './state/state-machine.js';
+export { defineRole, defineStates, installArchetype, logicSet, registeredLogicSets, registeredRoles, resetRegistries, roleDefinition, } from './state/hooks.js';
+// Explicit escape hatch while our own API grows: a single source of three
+// for the whole workspace. The thesis is that three stays an implementation detail.
+export * as THREE from 'three';

package/dist/input.d.ts

@@ -0,0 +1,40 @@
+export type ActionName = string;
+/** Action → KeyboardEvent.code list. */
+export type InputBindings = Record<string, string[]>;
+/** Neutral engine baseline; archetypes own their action vocabulary. */
+export declare const DEFAULT_BINDINGS: Readonly<InputBindings>;
+/**
+ * Action-based input with archetype default bindings.
+ * v0: keyboard. TODO(H1): gamepad and touch.
+ */
+export declare class Input {
+    private readonly bindings;
+    private readonly down;
+    private readonly justDown;
+    private readonly used;
+    /** Installs exactly the action map supplied by the active archetype/project. */
+    constructor(bindings?: Readonly<InputBindings>);
+    /** Is the action held this frame? */
+    held(action: ActionName): boolean;
+    /** Was the action pressed exactly this frame? */
+    justPressed(action: ActionName): boolean;
+    /** -1..1 axis from two actions (left/right by default). */
+    axis(negative?: ActionName, positive?: ActionName): number;
+    /**
+     * Marks this frame's press of the action as spent, so consumers that
+     * honor consumption (state-machine 'input:' triggers) ignore it. One
+     * press does one thing: the press that launches a ground jump can't
+     * also fire a "key press jump" transition on the very same frame.
+     */
+    consume(action: ActionName): void;
+    /** Was this frame's press already spent by someone? */
+    consumed(action: ActionName): boolean;
+    /** Called by the Game at the end of each frame. */
+    endFrame(): void;
+    dispose(): void;
+    private isActive;
+    private releaseAll;
+    private onVisibilityChange;
+    private onKeyDown;
+    private onKeyUp;
+}

package/dist/input.js

@@ -0,0 +1,84 @@
+/** Neutral engine baseline; archetypes own their action vocabulary. */
+export const DEFAULT_BINDINGS = {};
+/**
+ * Action-based input with archetype default bindings.
+ * v0: keyboard. TODO(H1): gamepad and touch.
+ */
+export class Input {
+    bindings = new Map();
+    down = new Set();
+    justDown = new Set();
+    used = new Set();
+    /** Installs exactly the action map supplied by the active archetype/project. */
+    constructor(bindings = DEFAULT_BINDINGS) {
+        for (const [action, codes] of Object.entries(bindings)) {
+            this.bindings.set(action, new Set(codes));
+        }
+        window.addEventListener('keydown', this.onKeyDown);
+        window.addEventListener('keyup', this.onKeyUp);
+        window.addEventListener('blur', this.releaseAll);
+        document.addEventListener('visibilitychange', this.onVisibilityChange);
+    }
+    /** Is the action held this frame? */
+    held(action) {
+        return this.isActive(action, this.down);
+    }
+    /** Was the action pressed exactly this frame? */
+    justPressed(action) {
+        return this.isActive(action, this.justDown);
+    }
+    /** -1..1 axis from two actions (left/right by default). */
+    axis(negative = 'left', positive = 'right') {
+        return (this.held(positive) ? 1 : 0) - (this.held(negative) ? 1 : 0);
+    }
+    /**
+     * Marks this frame's press of the action as spent, so consumers that
+     * honor consumption (state-machine 'input:' triggers) ignore it. One
+     * press does one thing: the press that launches a ground jump can't
+     * also fire a "key press jump" transition on the very same frame.
+     */
+    consume(action) {
+        this.used.add(action);
+    }
+    /** Was this frame's press already spent by someone? */
+    consumed(action) {
+        return this.used.has(action);
+    }
+    /** Called by the Game at the end of each frame. */
+    endFrame() {
+        this.justDown.clear();
+        this.used.clear();
+    }
+    dispose() {
+        window.removeEventListener('keydown', this.onKeyDown);
+        window.removeEventListener('keyup', this.onKeyUp);
+        window.removeEventListener('blur', this.releaseAll);
+        document.removeEventListener('visibilitychange', this.onVisibilityChange);
+    }
+    isActive(action, set) {
+        const codes = this.bindings.get(action);
+        if (!codes)
+            return false;
+        for (const code of codes)
+            if (set.has(code))
+                return true;
+        return false;
+    }
+    releaseAll = () => {
+        this.down.clear();
+        this.justDown.clear();
+    };
+    onVisibilityChange = () => {
+        if (document.visibilityState === 'hidden')
+            this.releaseAll();
+    };
+    onKeyDown = (e) => {
+        if (e.repeat)
+            return;
+        this.down.add(e.code);
+        this.justDown.add(e.code);
+    };
+    onKeyUp = (e) => {
+        this.down.delete(e.code);
+    };
+}

package/dist/scene.d.ts

@@ -0,0 +1,80 @@
+import type { SceneCameraJson } from './camera.js';
+import type { ComponentClass } from './component.js';
+import type { Entity } from './entity.js';
+import type { Game } from './game.js';
+/**
+ * Waica's scene format: declarative, git-friendly data, editable by the
+ * visual editor. The scene is the source of truth; the Game is its live
+ * projection.
+ */
+export interface SceneComponentJson {
+    type: string;
+    props?: Record<string, unknown>;
+}
+export interface SceneEntityJson {
+    name: string;
+    position?: [number, number];
+    /** Prefab ref like "characters/slime", resolved against SceneRegistry.prefabs. */
+    prefab?: string;
+    /** Per-component prop overrides on top of the prefab: componentType -> propName -> value. */
+    overrides?: Record<string, Record<string, unknown>>;
+    components?: SceneComponentJson[];
+    /** Editor-only grouping label; spawning ignores it. */
+    folder?: string;
+}
+/** A reusable entity template: a typed bag of components a scene can reference. */
+export interface PrefabJson {
+    waicaPrefab: 1;
+    type: 'character' | 'object' | 'tile';
+    components: SceneComponentJson[];
+}
+export interface SceneJson {
+    waicaScene: 1 | 2 | 3;
+    /** The scene's built-in camera (v3); absent = the host keeps control. */
+    camera?: SceneCameraJson;
+    entities: SceneEntityJson[];
+    /** UI pieces (src/ui/*.html) mounted visible when the scene loads. */
+    ui?: string[];
+    /**
+     * Editor-only folder registry: keeps empty folders alive and ordered.
+     * Folders group entities in the editor's explorer; the runtime ignores them.
+     */
+    folders?: string[];
+}
+/** Which components exist and how to resolve archetype assets (waica:*). */
+export interface SceneRegistry {
+    components: Record<string, ComponentClass>;
+    /**
+     * Resolves asset URIs — "waica:dog" registry keys or project paths like
+     * "src/art/hero.png" — to loadable URLs. MUST return unknown strings
+     * unchanged: every string prop goes through it.
+     */
+    resolveAsset?: (uri: string) => string;
+    /** Prefab definitions keyed by ref ("characters/slime"). */
+    prefabs?: Record<string, PrefabJson>;
+    /** UI piece sources keyed by name ("coin-counter" → its HTML). */
+    ui?: Record<string, string>;
+}
+/**
+ * Own-property lookup. Scene JSON is data — a component or prefab named
+ * "constructor" or "toString" must read as missing, not as whatever sits
+ * on Object.prototype.
+ */
+export declare function registryEntry<T>(record: Record<string, T> | undefined, key: string): T | undefined;
+/**
+ * Runs every string prop through the registry's asset resolver (if any),
+ * recursing into arrays and plain objects — nested textures (e.g. an
+ * AnimatedSprite's extraSheets) resolve like top-level ones. Safe because
+ * resolvers return unknown strings unchanged.
+ */
+export declare function resolveProps(props: Record<string, unknown> | undefined, registry: SceneRegistry): Record<string, unknown>;
+/**
+ * Expands an entity's prefab (with its overrides) into the final component
+ * list: prefab components first, inline extras appended after. Pure — inputs
+ * are never mutated; merged components are fresh objects.
+ */
+export declare function resolveEntityComponents(entity: SceneEntityJson, prefabs?: Record<string, PrefabJson>): SceneComponentJson[];
+/** Instantiates a scene entity into the game. */
+export declare function spawnFromJson(game: Game, json: SceneEntityJson, registry: SceneRegistry): Entity;
+/** Loads a full scene into the game. */
+export declare function loadScene(game: Game, scene: SceneJson, registry: SceneRegistry): void;

package/dist/scene.js

@@ -0,0 +1,93 @@
+/**
+ * Own-property lookup. Scene JSON is data — a component or prefab named
+ * "constructor" or "toString" must read as missing, not as whatever sits
+ * on Object.prototype.
+ */
+export function registryEntry(record, key) {
+    if (!record || !Object.prototype.hasOwnProperty.call(record, key))
+        return undefined;
+    return record[key];
+}
+/**
+ * Runs every string prop through the registry's asset resolver (if any),
+ * recursing into arrays and plain objects — nested textures (e.g. an
+ * AnimatedSprite's extraSheets) resolve like top-level ones. Safe because
+ * resolvers return unknown strings unchanged.
+ */
+export function resolveProps(props, registry) {
+    if (!props)
+        return {};
+    const resolve = registry.resolveAsset;
+    if (!resolve)
+        return { ...props };
+    const walk = (value) => {
+        if (typeof value === 'string')
+            return resolve(value);
+        if (Array.isArray(value))
+            return value.map(walk);
+        if (value && typeof value === 'object' && value.constructor === Object) {
+            const out = {};
+            for (const [key, entry] of Object.entries(value))
+                out[key] = walk(entry);
+            return out;
+        }
+        return value;
+    };
+    return walk(props);
+}
+/**
+ * Expands an entity's prefab (with its overrides) into the final component
+ * list: prefab components first, inline extras appended after. Pure — inputs
+ * are never mutated; merged components are fresh objects.
+ */
+export function resolveEntityComponents(entity, prefabs) {
+    const inline = entity.components ?? [];
+    if (!entity.prefab)
+        return inline;
+    const prefab = registryEntry(prefabs, entity.prefab);
+    if (!prefab) {
+        console.warn(`[waica] unknown prefab in scene: "${entity.prefab}" (${entity.name})`);
+        return inline;
+    }
+    const fromPrefab = prefab.components.map((comp) => ({
+        type: comp.type,
+        props: { ...comp.props, ...entity.overrides?.[comp.type] },
+    }));
+    return [...fromPrefab, ...inline];
+}
+/** Instantiates a scene entity into the game. */
+export function spawnFromJson(game, json, registry) {
+    const entity = game.spawn(json.name);
+    if (json.position)
+        entity.position.set(json.position[0], json.position[1], 0);
+    for (const comp of resolveEntityComponents(json, registry.prefabs)) {
+        const Class = registryEntry(registry.components, comp.type);
+        if (!Class) {
+            console.warn(`[waica] unknown component in scene: "${comp.type}" (${json.name})`);
+            continue;
+        }
+        // The registry now carries project-owned classes, i.e. arbitrary user
+        // code. A throwing constructor or onReady costs that one component —
+        // never the rest of the scene, and never the editor hosting it.
+        try {
+            entity.add(Class, resolveProps(comp.props, registry));
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            console.error(`[waica] component "${comp.type}" failed on "${json.name}": ${message}`);
+        }
+    }
+    return entity;
+}
+/** Loads a full scene into the game. */
+export function loadScene(game, scene, registry) {
+    game.registry = registry;
+    for (const entityJson of scene.entities)
+        spawnFromJson(game, entityJson, registry);
+    // After the spawns: with a follow target, the camera starts centered on it.
+    game.setSceneCamera(scene.camera);
+    if (registry.ui)
+        game.ui.defineAll(registry.ui);
+    for (const name of scene.ui ?? [])
+        game.ui.show(name);
+}

package/dist/solid-axis.d.ts

@@ -0,0 +1,21 @@
+import { type CollisionBody } from './collision-shape.js';
+import { Solid } from './components/solid.js';
+import type { Entity } from './entity.js';
+export type CollisionAxis = 'x' | 'y';
+export interface SolidAxisOptions {
+    /** Dynamic entity whose axis position has already been moved to its target. */
+    entity: Entity;
+    axis: CollisionAxis;
+    /** Known pre-move position on this axis. */
+    previous: number;
+    /** Current world-space collision body; read again as the axis position changes. */
+    body(): CollisionBody;
+    /** Receives each nearest Solid that blocks this axis move. */
+    onContact?(solid: Solid): void;
+}
+/**
+ * Resolves one axis against scene Solids. Large displacements are split into
+ * body-sized steps so a thin wall cannot sit entirely between two samples.
+ * Returns whether a new contact blocked the move.
+ */
+export declare function resolveSolidAxis({ entity, axis, previous, body, onContact, }: SolidAxisOptions): boolean;