@umicat/phaser-sdk 1.0.0

package/dist/scene/Prefabs.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Prefabs — entity TYPE definitions for runtime spawning.
+ *
+ * Slice 11 (Phase B.1, 2026-05-12). Closes the editor-value gap for
+ * runtime-spawn-dominated games (shooters, runners, survivors). Today's
+ * scene-as-data only knows about *instances at positions*; prefabs add
+ * *types* — a Galaga enemy template the wave system spawns 18 instances
+ * of, all sharing one editable record in the manifest.
+ *
+ * SDK 0.3.0 flattened the schema: prefab fields (assetId / width / params /
+ * etc.) live at the top level — exactly like world entities. There is no
+ * nested `visual: { ... }` middle layer.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §6
+ *
+ * Public API:
+ *  - `spawnPrefab(scene, prefabId, x, y, overrides?)` — create and register
+ *    a runtime instance. Replaces the inline
+ *    `this.physics.add.sprite(x, y, 'tex')` pattern.
+ *  - `getPrefab(scene, prefabId)` — read the prefab record from the cached
+ *    manifest. Throws if the prefab is missing.
+ *  - `listPrefabs(scene, role?)` — enumerate prefabs, optionally filtered
+ *    by role (e.g. `listPrefabs(this, 'enemy')`).
+ */
+import Phaser from 'phaser';
+import { PrefabPhysics, PrefabRecord, Transform } from './types.js';
+import { RenderScriptResolver, AssetResolver } from './spawnEntity.js';
+/**
+ * Spawn-time overrides for a prefab. Each field is deep-merged on top of
+ * the prefab record before instantiation. Render-field overrides live at
+ * the root — same flat shape as the prefab record itself. The override
+ * type is intentionally loose (`Record<string, unknown>`) so per-kind
+ * fields (assetId on sprite, fillColor on rect/circle, params on
+ * code-rendered) can all be passed through the same channel.
+ *
+ *     spawnPrefab(this, 'enemy_grunt', x, y, {
+ *       fields: { params: { color: '#ff0066' } },  // boss recolor
+ *       properties: { hp: 30 },
+ *     });
+ */
+export interface SpawnPrefabOverrides {
+    role?: string;
+    /**
+     * Render-field overrides — deep-merged onto the prefab's render fields
+     * (assetId / tint / width / fillColor / radius / params / etc., depending
+     * on prefab.kind). Pass the same field names that live at the root of the
+     * PrefabRecord.
+     */
+    fields?: Record<string, unknown>;
+    physics?: Partial<PrefabPhysics>;
+    properties?: Record<string, unknown>;
+    /** Optional transform overrides (rotation, scale, depth — x/y come from spawn args). */
+    transform?: Partial<Omit<Transform, 'x' | 'y'>>;
+}
+export interface SpawnPrefabOptions {
+    /** Custom asset resolver. Defaults to manifest.assets lookup. */
+    resolveAsset?: AssetResolver;
+    /** Custom render-script resolver. Defaults to the global registry. */
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * Look up a prefab record by id. Reads from the cached manifest loaded
+ * by `loadWorldScene`. Throws if no manifest is cached or the id isn't
+ * declared. Use `listPrefabs(scene)` to enumerate first if the caller
+ * isn't sure what's available.
+ */
+export declare function getPrefab(scene: Phaser.Scene, prefabId: string): PrefabRecord;
+/**
+ * Enumerate prefabs in the manifest, optionally filtered by role. Returns
+ * an empty array when the manifest has no prefabs at all.
+ */
+export declare function listPrefabs(scene: Phaser.Scene, role?: string): PrefabRecord[];
+/**
+ * Spawn a runtime instance of a prefab at (x, y).
+ *
+ * Pipeline:
+ *  1. Look up the prefab in the manifest.
+ *  2. Merge `overrides` (deep) on top of the prefab record.
+ *  3. Build a synthetic `WorldEntity` carrying spawn coordinates and the
+ *     merged render / physics / properties, then call `spawnEntity` (the
+ *     same code path authored entities use) — which creates the GameObject
+ *     AND applies the physics block (`physics.add.existing` + body size /
+ *     offset / velocity / bounce / world-bounds).
+ *  4. Tag the GO with `entityPrefabId` for editor live-edit + record-keeping.
+ *  5. Register the instance with the EntityRegistry under a runtime-generated
+ *     id (format `<prefabId>#<n>`) and the prefab's role.
+ *
+ * Returns the spawned GameObject. Caller is responsible for adding it to
+ * any Phaser groups/colliders/event listeners. On `destroy()`, the SDK
+ * auto-unregisters via a Phaser DESTROY event listener.
+ */
+export declare function spawnPrefab(scene: Phaser.Scene, prefabId: string, x: number, y: number, overrides?: SpawnPrefabOverrides, options?: SpawnPrefabOptions): Phaser.GameObjects.GameObject;

package/dist/scene/Prefabs.js

@@ -0,0 +1,175 @@
+/**
+ * Prefabs — entity TYPE definitions for runtime spawning.
+ *
+ * Slice 11 (Phase B.1, 2026-05-12). Closes the editor-value gap for
+ * runtime-spawn-dominated games (shooters, runners, survivors). Today's
+ * scene-as-data only knows about *instances at positions*; prefabs add
+ * *types* — a Galaga enemy template the wave system spawns 18 instances
+ * of, all sharing one editable record in the manifest.
+ *
+ * SDK 0.3.0 flattened the schema: prefab fields (assetId / width / params /
+ * etc.) live at the top level — exactly like world entities. There is no
+ * nested `visual: { ... }` middle layer.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §6
+ *
+ * Public API:
+ *  - `spawnPrefab(scene, prefabId, x, y, overrides?)` — create and register
+ *    a runtime instance. Replaces the inline
+ *    `this.physics.add.sprite(x, y, 'tex')` pattern.
+ *  - `getPrefab(scene, prefabId)` — read the prefab record from the cached
+ *    manifest. Throws if the prefab is missing.
+ *  - `listPrefabs(scene, role?)` — enumerate prefabs, optionally filtered
+ *    by role (e.g. `listPrefabs(this, 'enemy')`).
+ */
+import Phaser from 'phaser';
+import { spawnEntity } from './spawnEntity.js';
+import { attachEntityRegistry, getEntityRegistry } from './EntityRegistry.js';
+import { getManifest } from './SceneLoader.js';
+import { resolveRenderScript } from './renderScripts.js';
+/**
+ * Look up a prefab record by id. Reads from the cached manifest loaded
+ * by `loadWorldScene`. Throws if no manifest is cached or the id isn't
+ * declared. Use `listPrefabs(scene)` to enumerate first if the caller
+ * isn't sure what's available.
+ */
+export function getPrefab(scene, prefabId) {
+    const manifest = getManifest(scene);
+    const prefab = manifest.prefabs?.find((p) => p.id === prefabId);
+    if (!prefab) {
+        throw new Error(`[umicat/prefab] no prefab with id '${prefabId}' in manifest.prefabs[] — declare it in scenes/manifest.json`);
+    }
+    return prefab;
+}
+/**
+ * Enumerate prefabs in the manifest, optionally filtered by role. Returns
+ * an empty array when the manifest has no prefabs at all.
+ */
+export function listPrefabs(scene, role) {
+    const manifest = getManifest(scene);
+    const all = manifest.prefabs ?? [];
+    return role ? all.filter((p) => p.role === role) : all;
+}
+/**
+ * Spawn a runtime instance of a prefab at (x, y).
+ *
+ * Pipeline:
+ *  1. Look up the prefab in the manifest.
+ *  2. Merge `overrides` (deep) on top of the prefab record.
+ *  3. Build a synthetic `WorldEntity` carrying spawn coordinates and the
+ *     merged render / physics / properties, then call `spawnEntity` (the
+ *     same code path authored entities use) — which creates the GameObject
+ *     AND applies the physics block (`physics.add.existing` + body size /
+ *     offset / velocity / bounce / world-bounds).
+ *  4. Tag the GO with `entityPrefabId` for editor live-edit + record-keeping.
+ *  5. Register the instance with the EntityRegistry under a runtime-generated
+ *     id (format `<prefabId>#<n>`) and the prefab's role.
+ *
+ * Returns the spawned GameObject. Caller is responsible for adding it to
+ * any Phaser groups/colliders/event listeners. On `destroy()`, the SDK
+ * auto-unregisters via a Phaser DESTROY event listener.
+ */
+export function spawnPrefab(scene, prefabId, x, y, overrides = {}, options = {}) {
+    const prefab = getPrefab(scene, prefabId);
+    const merged = mergePrefab(prefab, overrides);
+    const registry = getOrAttachRegistry(scene);
+    const instanceId = registry.nextInstanceId(prefabId);
+    const entity = prefabToEntity(merged, instanceId, x, y, overrides.transform);
+    const ctx = {
+        scene,
+        registry,
+        resolveAsset: options.resolveAsset ?? defaultAssetResolver(scene),
+        resolveRenderScript: options.resolveRenderScript ?? ((path) => resolveRenderScript(scene.game, path)),
+    };
+    // spawnEntity creates the GameObject AND applies the merged physics block
+    // (carried on the synthetic entity by `prefabToEntity`) — same body-level
+    // path authored scene entities use.
+    const go = spawnEntity(ctx, entity);
+    // Tag the GO so editor live-edit (umicat:editor:editPrefab) can find all
+    // instances of this prefab to re-apply patches.
+    go.setData('entityPrefabId', prefabId);
+    // Re-register under the runtime id (spawnEntity already registered with
+    // the same id but without prefabId). Replace to add the prefab tag.
+    registry.unregister(instanceId);
+    registry.register(instanceId, merged.role, go, prefabId);
+    // Auto-unregister on destroy so dead instances don't bloat the registry.
+    go.once(Phaser.GameObjects.Events.DESTROY, () => {
+        registry.unregister(instanceId);
+    });
+    return go;
+}
+// --- Helpers --------------------------------------------------------------
+function getOrAttachRegistry(scene) {
+    return getEntityRegistry(scene) ?? attachEntityRegistry(scene);
+}
+function defaultAssetResolver(scene) {
+    return (assetId) => {
+        const manifest = getManifest(scene);
+        const asset = manifest.assets?.find((a) => a.id === assetId);
+        if (!asset) {
+            throw new Error(`[umicat/prefab] manifest has no asset with id '${assetId}'`);
+        }
+        return asset;
+    };
+}
+/**
+ * Build a `WorldEntity` from a prefab + spawn coords. SDK 0.3.0: prefab
+ * and world-entity share the same flat shape per kind, so this is just a
+ * `{ ...prefab, id, transform }` spread — no shape transformation needed.
+ */
+function prefabToEntity(prefab, instanceId, x, y, transformOverrides) {
+    const transform = { x, y, ...transformOverrides };
+    // PrefabBase fields (id, role, physics, properties) + per-kind render fields
+    // map 1:1 onto the matching WorldEntity variant. The discriminated `kind`
+    // makes the union-narrowing work without per-kind ceremony.
+    return {
+        ...prefab,
+        id: instanceId,
+        transform,
+    };
+}
+function mergePrefab(prefab, overrides) {
+    if (!hasAny(overrides))
+        return prefab;
+    // Render-field overrides merge into the prefab root (assetId / params / etc).
+    // PrefabBase fields (physics / properties / role) merge into their own slots.
+    const base = { ...prefab };
+    if (overrides.fields) {
+        for (const [k, v] of Object.entries(overrides.fields)) {
+            base[k] = deepMerge(base[k], v);
+        }
+    }
+    if (overrides.role !== undefined)
+        base.role = overrides.role;
+    if (overrides.physics !== undefined) {
+        base.physics = deepMerge(base.physics, overrides.physics);
+    }
+    if (overrides.properties !== undefined) {
+        base.properties = { ...(prefab.properties ?? {}), ...overrides.properties };
+    }
+    return base;
+}
+function hasAny(overrides) {
+    return !!(overrides.role ||
+        overrides.fields ||
+        overrides.physics ||
+        overrides.properties ||
+        overrides.transform);
+}
+function deepMerge(base, patch) {
+    if (patch === undefined)
+        return base;
+    if (base === undefined)
+        return patch;
+    if (isPlainObject(base) && isPlainObject(patch)) {
+        const out = { ...base };
+        for (const [k, v] of Object.entries(patch)) {
+            out[k] = deepMerge(base[k], v);
+        }
+        return out;
+    }
+    return patch;
+}
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}

package/dist/scene/Rules.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Rules — game parameters as data.
+ *
+ * Slice 11 (Phase B.2, 2026-05-12). Free-form key-value JSON tree at
+ * `public/rules.json`, accessed via dot-notation paths
+ * (`getRule(scene, 'balance.lives', 3)`). Replaces TS `const X = ...`
+ * declarations for any value a user might want to tune — lives, score
+ * thresholds, fire cooldowns, gravity, win conditions.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §8
+ *
+ * Public API:
+ *  - `preloadRules(scene)` — queue load of `public/rules.json` in BootScene's
+ *    `preload`. Tolerant of missing file (treats as empty `{}`).
+ *  - `getRule(scene, path, fallback)` — one-shot read of a value by dot path.
+ *  - `getRules(scene)` — read the full rules tree.
+ *  - `onRuleChange(scene, path, handler)` — subscribe to editor patches.
+ *  - `patchRule(scene, path, value)` — apply an editor edit (internal use;
+ *    the EditorBridge will call this when `umicat:editor:patchRule` arrives).
+ */
+import Phaser from 'phaser';
+type RulesTree = Record<string, unknown>;
+/**
+ * Queue a load of `public/rules.json` in a Phaser scene's `preload()` —
+ * typically alongside `preloadManifest`. Missing file is tolerated:
+ * a 404 inserts an empty `{}` so subsequent `getRule` calls return
+ * fallback values cleanly.
+ */
+export declare function preloadRules(scene: Phaser.Scene): void;
+/**
+ * Read the full rules tree. Returns `{}` if rules were never loaded or
+ * the file was missing. Most callers should use `getRule(...)` for a
+ * specific path; this is for code that needs the whole tree (e.g.,
+ * displaying a debug HUD of all rules).
+ */
+export declare function getRules(scene: Phaser.Scene): RulesTree;
+/**
+ * Read a single rule by dot-notation path. Returns `fallback` if the path
+ * is unset or rules weren't loaded. The fallback's type is the return type
+ * — keep it explicit so calling code doesn't drift.
+ *
+ * Example:
+ *   const lives = getRule(this, 'balance.lives', 3);
+ *   const gravity = getRule(this, 'physics.gravity.y', 980);
+ */
+export declare function getRule<T>(scene: Phaser.Scene, path: string, fallback: T): T;
+/**
+ * Subscribe to live rule changes from the editor. Handler fires whenever:
+ *  - The exact `path` is patched.
+ *  - Any descendant of `path` is patched (subscribing to `'balance'`
+ *    fires on edits to `'balance.lives'`, `'balance.shootCooldownMs'`, etc.).
+ *
+ * Returns an unsubscribe function. Always call it on scene shutdown to
+ * avoid leaks:
+ *
+ *   const unsub = onRuleChange(this, 'balance.shootCooldownMs', (v) => {
+ *     this.shootCooldown = v as number;
+ *   });
+ *   this.events.once(Phaser.Scenes.Events.SHUTDOWN, unsub);
+ */
+export declare function onRuleChange<T>(scene: Phaser.Scene, path: string, handler: (value: T) => void): () => void;
+/**
+ * Apply an editor patch to a rule path. Updates the cache + fires every
+ * subscriber whose path is the patched path OR an ancestor of it (so a
+ * subscriber to `'balance'` sees an edit to `'balance.lives'`).
+ *
+ * Called by `EditorBridge` when the host sends
+ * `{ type: 'umicat:editor:patchRule', path, value }`. Direct use from
+ * game code is allowed but unusual — rules are typically read-only at
+ * runtime; the source of truth is the JSON file + editor edits.
+ */
+export declare function patchRule(scene: Phaser.Scene, path: string, value: unknown): void;
+export {};

package/dist/scene/Rules.js

@@ -0,0 +1,164 @@
+/**
+ * Rules — game parameters as data.
+ *
+ * Slice 11 (Phase B.2, 2026-05-12). Free-form key-value JSON tree at
+ * `public/rules.json`, accessed via dot-notation paths
+ * (`getRule(scene, 'balance.lives', 3)`). Replaces TS `const X = ...`
+ * declarations for any value a user might want to tune — lives, score
+ * thresholds, fire cooldowns, gravity, win conditions.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §8
+ *
+ * Public API:
+ *  - `preloadRules(scene)` — queue load of `public/rules.json` in BootScene's
+ *    `preload`. Tolerant of missing file (treats as empty `{}`).
+ *  - `getRule(scene, path, fallback)` — one-shot read of a value by dot path.
+ *  - `getRules(scene)` — read the full rules tree.
+ *  - `onRuleChange(scene, path, handler)` — subscribe to editor patches.
+ *  - `patchRule(scene, path, value)` — apply an editor edit (internal use;
+ *    the EditorBridge will call this when `umicat:editor:patchRule` arrives).
+ */
+import Phaser from 'phaser';
+const RULES_PATH = 'rules.json';
+const RULES_CACHE_KEY = 'umicat:rules';
+const SUBSCRIBERS_KEY = '__unboxyRulesSubscribers';
+/**
+ * Queue a load of `public/rules.json` in a Phaser scene's `preload()` —
+ * typically alongside `preloadManifest`. Missing file is tolerated:
+ * a 404 inserts an empty `{}` so subsequent `getRule` calls return
+ * fallback values cleanly.
+ */
+export function preloadRules(scene) {
+    if (scene.cache.json.exists(RULES_CACHE_KEY))
+        return;
+    // Phaser fires FILE_LOAD_ERROR on 404; we install a single-shot listener
+    // that injects an empty cache entry so downstream `getRule` calls don't
+    // throw "rules not loaded". The listener removes itself after firing once.
+    const onError = (file) => {
+        if (file.key !== RULES_CACHE_KEY)
+            return;
+        if (!scene.cache.json.exists(RULES_CACHE_KEY)) {
+            scene.cache.json.add(RULES_CACHE_KEY, {});
+        }
+        scene.load.off(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+    };
+    scene.load.on(Phaser.Loader.Events.FILE_LOAD_ERROR, onError);
+    scene.load.json(RULES_CACHE_KEY, RULES_PATH);
+}
+/**
+ * Read the full rules tree. Returns `{}` if rules were never loaded or
+ * the file was missing. Most callers should use `getRule(...)` for a
+ * specific path; this is for code that needs the whole tree (e.g.,
+ * displaying a debug HUD of all rules).
+ */
+export function getRules(scene) {
+    const cached = scene.cache.json.get(RULES_CACHE_KEY);
+    return cached ?? {};
+}
+/**
+ * Read a single rule by dot-notation path. Returns `fallback` if the path
+ * is unset or rules weren't loaded. The fallback's type is the return type
+ * — keep it explicit so calling code doesn't drift.
+ *
+ * Example:
+ *   const lives = getRule(this, 'balance.lives', 3);
+ *   const gravity = getRule(this, 'physics.gravity.y', 980);
+ */
+export function getRule(scene, path, fallback) {
+    const v = readPath(getRules(scene), path);
+    return v === undefined ? fallback : v;
+}
+/**
+ * Subscribe to live rule changes from the editor. Handler fires whenever:
+ *  - The exact `path` is patched.
+ *  - Any descendant of `path` is patched (subscribing to `'balance'`
+ *    fires on edits to `'balance.lives'`, `'balance.shootCooldownMs'`, etc.).
+ *
+ * Returns an unsubscribe function. Always call it on scene shutdown to
+ * avoid leaks:
+ *
+ *   const unsub = onRuleChange(this, 'balance.shootCooldownMs', (v) => {
+ *     this.shootCooldown = v as number;
+ *   });
+ *   this.events.once(Phaser.Scenes.Events.SHUTDOWN, unsub);
+ */
+export function onRuleChange(scene, path, handler) {
+    const subs = getOrCreateSubscribers(scene);
+    const set = subs.get(path) ?? new Set();
+    const wrapped = (v) => handler(v);
+    set.add(wrapped);
+    subs.set(path, set);
+    return () => {
+        set.delete(wrapped);
+        if (set.size === 0)
+            subs.delete(path);
+    };
+}
+/**
+ * Apply an editor patch to a rule path. Updates the cache + fires every
+ * subscriber whose path is the patched path OR an ancestor of it (so a
+ * subscriber to `'balance'` sees an edit to `'balance.lives'`).
+ *
+ * Called by `EditorBridge` when the host sends
+ * `{ type: 'umicat:editor:patchRule', path, value }`. Direct use from
+ * game code is allowed but unusual — rules are typically read-only at
+ * runtime; the source of truth is the JSON file + editor edits.
+ */
+export function patchRule(scene, path, value) {
+    const rules = getRules(scene);
+    writePath(rules, path, value);
+    // Re-add to the cache so subsequent reads see the patched tree. Phaser's
+    // JSON cache stores by reference, so the in-place mutation already affects
+    // reads — but `add` calls invalidate the right internal flags too.
+    scene.cache.json.add(RULES_CACHE_KEY, rules);
+    const subs = getSubscribers(scene);
+    if (!subs)
+        return;
+    for (const [subPath, set] of subs) {
+        if (subPath === path || path === subPath || path.startsWith(subPath + '.') || subPath.startsWith(path + '.')) {
+            const v = readPath(rules, subPath);
+            set.forEach((h) => h(v));
+        }
+    }
+}
+// --- Internals ------------------------------------------------------------
+function getSubscribers(scene) {
+    const game = scene.game;
+    return game[SUBSCRIBERS_KEY];
+}
+function getOrCreateSubscribers(scene) {
+    const game = scene.game;
+    let subs = game[SUBSCRIBERS_KEY];
+    if (!subs) {
+        subs = new Map();
+        game[SUBSCRIBERS_KEY] = subs;
+    }
+    return subs;
+}
+function readPath(obj, path) {
+    if (!path)
+        return obj;
+    const parts = path.split('.');
+    let cur = obj;
+    for (const p of parts) {
+        if (cur === null || typeof cur !== 'object')
+            return undefined;
+        cur = cur[p];
+        if (cur === undefined)
+            return undefined;
+    }
+    return cur;
+}
+function writePath(obj, path, value) {
+    const parts = path.split('.');
+    let cur = obj;
+    for (let i = 0; i < parts.length - 1; i++) {
+        const p = parts[i];
+        const existing = cur[p];
+        if (typeof existing !== 'object' || existing === null || Array.isArray(existing)) {
+            cur[p] = {};
+        }
+        cur = cur[p];
+    }
+    cur[parts[parts.length - 1]] = value;
+}

package/dist/scene/SceneLoader.d.ts

@@ -0,0 +1,118 @@
+import Phaser from 'phaser';
+import { Manifest, SceneFile, WorldScene } from './types.js';
+import { RenderScriptResolver } from './spawnEntity.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * Where scene files live in the workspace and at runtime. The Vite build
+ * copies `public/` to the served root, so paths are origin-relative
+ * (`scenes/manifest.json`). No leading slash — the iframe is sometimes
+ * served under a sub-path (`/preview/:gameId/`).
+ */
+export declare const SCENES_BASE = "scenes/";
+export declare const MANIFEST_PATH = "scenes/manifest.json";
+/**
+ * Fetches the manifest via Phaser's loader. Must be called from a Phaser
+ * scene's `preload()` since it queues a load request. Subsequent calls
+ * (e.g. on scene transitions) hit the Phaser JSON cache.
+ *
+ * Resolves once Phaser fires `complete` for the load batch — callers
+ * typically await this in `create()` after `this.load.start()` is done.
+ */
+export declare function preloadManifest(scene: Phaser.Scene): void;
+/**
+ * Read the manifest from Phaser's JSON cache. Throws if `preloadManifest`
+ * hasn't completed first.
+ */
+export declare function getManifest(scene: Phaser.Scene): Manifest;
+/**
+ * Walk a scene file's entities and queue Phaser loads for any assets that
+ * aren't already in the texture cache. Caller is responsible for awaiting
+ * the loader (`scene.load.once('complete', ...)` or do it in `preload()`).
+ *
+ * Idempotent across scenes — once an asset is loaded, switching to another
+ * scene that uses it is free.
+ */
+export declare function preloadSceneAssets(scene: Phaser.Scene, sceneFile: SceneFile, manifest: Manifest): void;
+/**
+ * Walk every `kind=spritesheet` asset in the manifest and register each one's
+ * `animations[]` as a Phaser animation, so behavior code can call
+ * `sprite.play('walk-down')` directly. Idempotent — uses `scene.anims.exists()`
+ * to skip duplicates (Phaser's anims.create throws otherwise).
+ *
+ * <p>Animation keys are scene-global. Two sheets registering the same name
+ * (e.g. two characters both with `walk-down`) → first wins, second logs a
+ * warning. Sheets that need disambiguation should namespace their keys
+ * (e.g. `cow:walk-down`) at metadata time.
+ */
+/**
+ * Walk every asset in the manifest and apply `Phaser.Textures.FilterMode.NEAREST`
+ * to each `pixelArt: true` entry's loaded texture. Without this, pixel-art
+ * sprites render bilinear-blurred — visible immediately on imported character
+ * sheets when the agent hasn't manually set Phaser game config's `pixelArt`.
+ *
+ * <p>Idempotent: setFilter is safe to call multiple times. Skip silently when
+ * a texture isn't loaded yet (next call after that asset is requested will
+ * pick it up). Wrap in try/catch so a single bad asset doesn't block the rest
+ * of scene init.
+ *
+ * <p>Per-asset NEAREST closes the visible blur gap; the game-wide flag
+ * (`Phaser.Game.config.pixelArt` + `camera.setRoundPixels`) is a separate
+ * concern (framebuffer-stretch crispness, perf) deferred to a follow-up.
+ */
+export declare function applyPixelArtFilters(scene: Phaser.Scene, manifest: Manifest): void;
+/**
+ * Look up per-frame 9-slice metadata for an atlas-format asset. Returns the
+ * `NinePatchConfig` declared inline on the named frame in the atlas JSON, or
+ * `undefined` if the asset isn't an atlas, the cache miss happened, or the
+ * frame has no `ninePatch` entry (plain stretched draw).
+ */
+export declare function getAtlasFrameNinePatch(scene: Phaser.Scene, textureKey: string, frameName: string): {
+    leftWidth: number;
+    rightWidth: number;
+    topHeight: number;
+    bottomHeight: number;
+} | undefined;
+export interface LoadWorldSceneOptions {
+    /**
+     * Optional render-script resolver for `code-rendered` entities. When
+     * absent, the loader throws on code-rendered entities (slice 1).
+     */
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * Suspend the scene's update/physics/tween processing while async work
+ * runs inside `create()`. Phaser does not await an async `create()` —
+ * the scene transitions to RUNNING as soon as the call returns its
+ * Promise, and `update()` starts ticking on the next frame regardless of
+ * whether the awaited load has settled. Without this guard, any
+ * `update()` code that reads class fields populated AFTER the await
+ * (e.g. `this.player.body`) crashes on frame 1 with
+ * `Cannot read properties of undefined (reading 'body')`.
+ *
+ * Idempotent: if the scene is already paused (e.g. the editor has
+ * paused everything via `setupEditorModeListener`), we leave it that
+ * way and the returned release is a no-op.
+ */
+export declare function suspendSceneUpdates(scene: Phaser.Scene): () => void;
+/**
+ * One-shot async loader: fetch scene JSON (if not already cached), lazy
+ * preload its assets, spawn entities, configure camera, and return the
+ * EntityRegistry. Idempotent re-loads of the same scene id reuse the
+ * Phaser JSON cache.
+ *
+ * Phaser's update loop is suspended for the duration of the await so
+ * `update()` can safely read fields the agent assigns AFTER `await
+ * loadWorldScene(...)` — no manual `if (!this.player) return;` guard
+ * required.
+ *
+ * Pattern (in `GameScene.create()`):
+ *
+ * ```ts
+ * const result = await loadWorldScene(this, sceneId);
+ * // entities live; behavior code can use result.registry.byRole('player')
+ * ```
+ */
+export declare function loadWorldScene(scene: Phaser.Scene, sceneId: string, options?: LoadWorldSceneOptions): Promise<{
+    sceneFile: WorldScene;
+    registry: EntityRegistry;
+}>;