@umicat/phaser-sdk 1.0.0

package/dist/scene/autotile.js

@@ -0,0 +1,321 @@
+/**
+ * Wang autotile runtime (slice 6 Phase D — design doc 06 §7).
+ *
+ * The user paints with a TERRAIN (e.g. "grass"); the SDK picks the actual
+ * tile index for each affected cell from the tileset's per-terrain ruleMap
+ * based on the cell's bitmask. Editing one cell can cascade to up to 8
+ * neighbors because corner vertices (and edge neighbors, in 8-bit mode)
+ * are shared.
+ *
+ * Bit convention for 4-bit corner mode (matches design doc 06 §7.3):
+ *
+ *   bit 0 = BR corner (1)
+ *   bit 1 = BL corner (2)
+ *   bit 2 = TR corner (4)
+ *   bit 3 = TL corner (8)
+ *
+ * `0b1111 = 15` = fully interior. `0b0000 = 0` = cell is empty.
+ *
+ * D.2.5.1 storage model (replaces the prior vertex grid from 0.2.122–0.2.124):
+ * source of truth is a per-CELL boolean grid of size W×H, stashed on the
+ * layer's data manager. The corner state at a vertex is derived as "any
+ * of the 4 cells touching this vertex is painted with the terrain" — same
+ * semantics as the old vertex grid (each click set 4 vertices = the 4
+ * vertices of the clicked cell), expressed at cell granularity instead.
+ *
+ * Why cell-painted instead of vertex-painted:
+ *   1. **Truly authoritative**: vertex state was a derivation of cell-paint
+ *      anyway. Storing the derivation invited drift (subtract paths on
+ *      shared vertices got tricky).
+ *   2. **Sets up 8-bit Wang (D.2.5.2)**: edge bits = "is the neighbor cell
+ *      on this side painted", which needs cell-level state. Vertex grid
+ *      couldn't express this; cell grid does it for free.
+ *
+ * Reverse-derive on first paint of a fresh layer: walk `layer.data`, mark
+ * every cell whose tile index appears in the terrain's ruleMap as painted.
+ * Tiles outside the ruleMap leave cells unmarked (assumed not part of
+ * this terrain — stamped manually, or from a different terrain). One
+ * cell-painted grid per (layer, terrain) — v1 limits a layer to one
+ * terrain so we cache a single grid keyed by `terrainId`.
+ */
+const CELL_GRID_KEY = 'unboxyAutotileCells';
+// 4-bit Wang corner bits (INCLUSIVE convention).
+// A corner bit is set iff ANY of the (up to 4) cells touching that
+// corner-vertex is painted with the terrain.
+const BIT_BR = 1;
+const BIT_BL = 2;
+const BIT_TR = 4;
+const BIT_TL = 8;
+// 8-bit Wang (STRICT / BLOB convention, design 06 §7.7 / Cr31 "2-edge +
+// 2-corner"). Only PAINTED cells render; bitmask describes the 8 neighbors
+// in terms that match how commercial blob tilesets (Sprout Lands' extended
+// block, Godot 4 "Match Corners and Sides", RPG-Maker autotile) are drawn.
+// Diagonal bits are "effective" — counted only when both adjacent
+// cardinals are also painted (Cr31 geometric constraint).
+//
+// Bit positions (clockwise from N):
+const BIT8_N = 1; // bit 0 — N cardinal neighbor painted
+const BIT8_NE = 2; // bit 1 — NE diagonal effective (N+E+NE all painted)
+const BIT8_E = 4; // bit 2 — E cardinal
+const BIT8_SE = 8; // bit 3 — SE diagonal effective
+const BIT8_S = 16; // bit 4 — S cardinal
+const BIT8_SW = 32; // bit 5 — SW diagonal effective
+const BIT8_W = 64; // bit 6 — W cardinal
+const BIT8_NW = 128; // bit 7 — NW diagonal effective
+function popCount(n) {
+    let c = 0;
+    while (n) {
+        c += n & 1;
+        n >>= 1;
+    }
+    return c;
+}
+function getCell(grid, cx, cy) {
+    if (cx < 0 || cy < 0 || cx >= grid.width || cy >= grid.height)
+        return 0;
+    return grid.data[cy * grid.width + cx];
+}
+function setCell(grid, cx, cy, v) {
+    if (cx < 0 || cy < 0 || cx >= grid.width || cy >= grid.height)
+        return;
+    grid.data[cy * grid.width + cx] = v;
+}
+/**
+ * Compute the 4-bit corner mask for cell (cx, cy). A corner bit is set
+ * iff ANY of the (up to 4) cells touching that corner is painted.
+ *
+ *   TL vertex at (cx, cy)       ← touches cells (cx-1,cy-1) (cx,cy-1) (cx-1,cy) (cx,cy)
+ *   TR vertex at (cx+1, cy)     ← touches cells (cx,cy-1) (cx+1,cy-1) (cx,cy) (cx+1,cy)
+ *   BL vertex at (cx, cy+1)     ← touches cells (cx-1,cy) (cx,cy) (cx-1,cy+1) (cx,cy+1)
+ *   BR vertex at (cx+1, cy+1)   ← touches cells (cx,cy) (cx+1,cy) (cx,cy+1) (cx+1,cy+1)
+ *
+ * Out-of-bounds cells count as "not painted" (boundary terrain is finite —
+ * the world edge is treated like a dirt neighbor).
+ */
+function bitmaskAt4(grid, cx, cy) {
+    let mask = 0;
+    if (getCell(grid, cx - 1, cy - 1) | getCell(grid, cx, cy - 1) |
+        getCell(grid, cx - 1, cy) | getCell(grid, cx, cy))
+        mask |= BIT_TL;
+    if (getCell(grid, cx, cy - 1) | getCell(grid, cx + 1, cy - 1) |
+        getCell(grid, cx, cy) | getCell(grid, cx + 1, cy))
+        mask |= BIT_TR;
+    if (getCell(grid, cx - 1, cy) | getCell(grid, cx, cy) |
+        getCell(grid, cx - 1, cy + 1) | getCell(grid, cx, cy + 1))
+        mask |= BIT_BL;
+    if (getCell(grid, cx, cy) | getCell(grid, cx + 1, cy) |
+        getCell(grid, cx, cy + 1) | getCell(grid, cx + 1, cy + 1))
+        mask |= BIT_BR;
+    return mask;
+}
+/**
+ * Compute the 8-bit Wang bitmask for cell `(cx, cy)` under the
+ * **STRICT / BLOB** convention (design 06 §7.7 / Cr31 "2-edge + 2-corner").
+ *
+ * Semantics:
+ *  - Only PAINTED cells render — unpainted cells return 0 (no tile).
+ *    This matches commercial tileset conventions (Sprout Lands extended
+ *    block, Godot 4 "Match Corners and Sides", RPG-Maker autotile).
+ *  - The bitmask describes THIS cell's 8 NEIGHBORS, not its own corners.
+ *  - Diagonal bits are "effective" — set only when the diagonal AND both
+ *    adjacent cardinals are all painted (Cr31 geometric constraint).
+ *    Reduces 256 raw combinations to 47 valid ones.
+ *
+ * Visual interpretation: a painted cell looks at its 8 neighbors. If all
+ * 8 are painted, it's a full-interior tile (bm 255). If isolated, it's a
+ * 1×1 island (bm 0). Boundary cells produce edge/corner bitmasks based
+ * on which neighbors are painted.
+ *
+ * Out-of-bounds neighbors count as "not painted" — the world edge is
+ * treated like a dirt neighbor.
+ */
+function bitmaskAt8(grid, cx, cy) {
+    if (!getCell(grid, cx, cy))
+        return 0; // unpainted cell — no tile renders
+    let mask = 0;
+    const N = getCell(grid, cx, cy - 1);
+    const E = getCell(grid, cx + 1, cy);
+    const S = getCell(grid, cx, cy + 1);
+    const W = getCell(grid, cx - 1, cy);
+    if (N)
+        mask |= BIT8_N;
+    if (E)
+        mask |= BIT8_E;
+    if (S)
+        mask |= BIT8_S;
+    if (W)
+        mask |= BIT8_W;
+    // Effective diagonals: count only when both adjacent cardinals also
+    // painted. This is the Cr31 constraint that reduces 256 → 47 valid.
+    if (N && E && getCell(grid, cx + 1, cy - 1))
+        mask |= BIT8_NE;
+    if (S && E && getCell(grid, cx + 1, cy + 1))
+        mask |= BIT8_SE;
+    if (S && W && getCell(grid, cx - 1, cy + 1))
+        mask |= BIT8_SW;
+    if (N && W && getCell(grid, cx - 1, cy - 1))
+        mask |= BIT8_NW;
+    return mask;
+}
+/**
+ * Resolve `bitmask` → tile index via the terrain's ruleMap. JSON wire
+ * format uses string keys (Jackson `Map<Integer, V>` default); in-memory
+ * authoring may use number keys. Try both. `bitmask === 0` is always
+ * "empty cell" — we don't consult the rule map.
+ */
+function tileForBitmask(terrain, bitmask) {
+    if (bitmask === 0)
+        return null;
+    const rm = terrain.ruleMap;
+    const sv = rm[String(bitmask)];
+    if (sv != null)
+        return sv;
+    const nv = rm[bitmask];
+    if (nv != null)
+        return nv;
+    return null;
+}
+/**
+ * Build the cell-painted grid by reverse-deriving from currently-painted
+ * tiles. A cell is "painted with this terrain" iff its current tile index
+ * appears anywhere in the terrain's ruleMap. Tiles outside the ruleMap
+ * (manually-stamped tiles, or tiles from a different terrain) leave the
+ * cell unmarked — that cell counts as "not in this terrain" for cascade
+ * purposes, which is correct: stamped tiles shouldn't influence wang
+ * boundary computation for the autotile terrain.
+ */
+function buildCellPaintedGrid(layer, terrain) {
+    const layerW = layer.tilemap.width;
+    const layerH = layer.tilemap.height;
+    const grid = {
+        data: new Uint8Array(layerW * layerH),
+        width: layerW,
+        height: layerH,
+        terrainId: terrain.id,
+    };
+    const ruleTiles = new Set();
+    const rm = terrain.ruleMap;
+    for (const key of Object.keys(rm)) {
+        const tileIdx = rm[key];
+        if (typeof tileIdx === 'number' && tileIdx >= 0)
+            ruleTiles.add(tileIdx);
+    }
+    layer.forEachTile((tile) => {
+        if (tile.index < 0)
+            return;
+        if (!ruleTiles.has(tile.index))
+            return;
+        setCell(grid, tile.x, tile.y, 1);
+    });
+    return grid;
+}
+function getOrBuildCellGrid(layer, terrain) {
+    const cached = layer.getData(CELL_GRID_KEY);
+    if (cached && cached.terrainId === terrain.id)
+        return cached;
+    const fresh = buildCellPaintedGrid(layer, terrain);
+    layer.setData(CELL_GRID_KEY, fresh);
+    return fresh;
+}
+/**
+ * Resolve a terrain by id from a tileset asset's autotile config. Returns
+ * null when the asset lacks autotile metadata or no terrain matches —
+ * callers typically warn + skip in that case.
+ */
+export function findTerrain(asset, terrainId) {
+    const terrains = asset?.tileset?.autotile?.terrains;
+    if (!terrains)
+        return null;
+    return terrains.find((t) => t.id === terrainId) ?? null;
+}
+/**
+ * Resolve the autotile kind (`'wang-4bit'` | `'wang-8bit'`) on a tileset
+ * asset. Defaults to `'wang-4bit'` for legacy assets where `autotile.kind`
+ * is missing (shouldn't happen with the validating backend parser, but
+ * defensive for hand-authored manifests).
+ */
+export function getAutotileKind(asset) {
+    const k = asset?.tileset?.autotile?.kind;
+    return k === 'wang-8bit' ? 'wang-8bit' : 'wang-4bit';
+}
+/**
+ * Invalidate the cached autotile state on a layer. Next autotile op
+ * rebuilds from the layer's current `data`. Call after structural
+ * mutations the grid model can't track (resize, removeLayer, tileset
+ * swap, terrain rule edits — `assetUpdate` does this automatically).
+ *
+ * Kept the old `invalidateAutotileVertices` name as an alias for
+ * back-compat with the 0.2.122–0.2.124 export surface — internal SDK
+ * code uses the new name, external consumers (none today) keep working.
+ */
+export function invalidateAutotileCells(layer) {
+    layer.setData(CELL_GRID_KEY, undefined);
+}
+/** @deprecated Renamed to `invalidateAutotileCells` (D.2.5.1). */
+export const invalidateAutotileVertices = invalidateAutotileCells;
+/**
+ * Apply a Wang autotile paint (or erase) at cell `(cellX, cellY)`.
+ *
+ * Paint mode (`mode = 'paint'`): the cell's painted-flag is set; the 3×3
+ * cell window around the click is recomputed. Each cell's new bitmask
+ * drives the tile index from `terrain.ruleMap`. Bitmask 0 (no corners) →
+ * cell becomes empty. Missing ruleMap entries are treated the same way
+ * (no tile defined → cell empty).
+ *
+ * Erase mode (`mode = 'erase'`): same flow with the cell's painted-flag
+ * cleared. Neighbors whose other corners are still terrain stay painted;
+ * cells whose bitmask drops to 0 become empty.
+ *
+ * Returns the affected cells with previous + new tile indices (one entry
+ * per cell in the 3×3 window that lies inside the layer's bounds, even
+ * if the index didn't change — the caller may dedup downstream). Cells
+ * outside the layer's bounds are silently skipped.
+ *
+ * Cheap: ~9 cell mutations + a Map lookup per cell. Cell-painted grid is
+ * stashed on the layer's data manager so subsequent calls reuse it
+ * without rebuilding from `layer.data`.
+ */
+export function applyAutotile(layer, cellX, cellY, terrain, mode, kind = 'wang-4bit') {
+    const layerW = layer.tilemap.width;
+    const layerH = layer.tilemap.height;
+    if (cellX < 0 || cellY < 0 || cellX >= layerW || cellY >= layerH) {
+        return [];
+    }
+    const grid = getOrBuildCellGrid(layer, terrain);
+    setCell(grid, cellX, cellY, mode === 'paint' ? 1 : 0);
+    // D.2.5.2 — pick bitmask function by kind. 8-bit cascade range is still
+    // 3×3 (painting cell (x,y) only changes side-bits of immediate
+    // cardinal neighbors, all within the 3×3 window).
+    const computeBitmask = kind === 'wang-8bit' ? bitmaskAt8 : bitmaskAt4;
+    const affected = [];
+    for (let dy = -1; dy <= 1; dy++) {
+        for (let dx = -1; dx <= 1; dx++) {
+            const x = cellX + dx;
+            const y = cellY + dy;
+            if (x < 0 || y < 0 || x >= layerW || y >= layerH)
+                continue;
+            const prevTile = layer.getTileAt(x, y, true);
+            const prevIndex = prevTile && prevTile.index >= 0 ? prevTile.index : -1;
+            const bitmask = computeBitmask(grid, x, y);
+            const newIndex = tileForBitmask(terrain, bitmask);
+            if (newIndex == null) {
+                if (prevIndex >= 0)
+                    layer.removeTileAt(x, y);
+                affected.push({ x, y, index: -1, prevIndex });
+            }
+            else if (newIndex !== prevIndex) {
+                layer.putTileAt(newIndex, x, y);
+                affected.push({ x, y, index: newIndex, prevIndex });
+            }
+            else {
+                affected.push({ x, y, index: newIndex, prevIndex });
+            }
+        }
+    }
+    // popCount is reserved for D.2.5.2 (8-bit Wang) where it'll be used to
+    // pick the "most-corners-filled" tile when multiple ruleMap entries
+    // resolve to the same valid bitmask. Keep the helper around so the
+    // diff to D.2.5.2 stays narrow.
+    void popCount;
+    return affected;
+}

package/dist/scene/renderScripts.d.ts

@@ -0,0 +1,53 @@
+import Phaser from 'phaser';
+/**
+ * Render-script module shape — slice 3.5.
+ *
+ * Spec: `umicat-design/features/visual-editor/02-render-scripts.md`.
+ *
+ * A `code-rendered` entity references a render script by path. The script's
+ * `render` is a **pure function** that draws into a Phaser Graphics object
+ * given a parameters object. The function:
+ *
+ *   - Calls `g.clear()` first (idempotent re-renders).
+ *   - Has no time/random dependency (motion is in tween system, not here).
+ *   - Holds no module state.
+ *
+ * Optional exports the editor / SDK uses if present:
+ *
+ *   - `defaultParams` — used as a starting point for new entities.
+ *   - `paramSchema`   — drives the Inspector's auto-generated UI (slice 4+).
+ *
+ * The script registry is built by the template (`import.meta.glob`), passed
+ * to `createUmicatGame({ renderScripts })`, and resolved by path string at
+ * spawn time. Path strings in scene files match the registry keys exactly:
+ * usually `src/visuals/<name>.ts`.
+ */
+export interface RenderScriptModule<P extends Record<string, unknown> = Record<string, unknown>> {
+    render: (g: Phaser.GameObjects.Graphics, params: P) => void;
+    defaultParams?: P;
+    paramSchema?: unknown;
+}
+/**
+ * Stash a render-script registry on the Phaser game so `loadWorldScene` /
+ * `EditorBridge.applyEdit` can find it without explicit plumbing.
+ *
+ * The map's keys are absolute paths matching what scene files reference
+ * (e.g. `src/visuals/coin.ts`). Templates that build via `import.meta.glob`
+ * commonly produce relative keys like `./visuals/coin.ts`; the resolver
+ * normalises trailing slashes / leading `./` so both shapes work.
+ */
+export declare function setRenderScriptRegistry(game: Phaser.Game, scripts: Record<string, RenderScriptModule>): void;
+export declare function getRenderScriptRegistry(game: Phaser.Game): Record<string, RenderScriptModule> | undefined;
+/**
+ * Returns the `render` function for a script path, or undefined if no
+ * matching module is registered. The matcher is forgiving:
+ *
+ *   - exact match (`src/visuals/coin.ts`)
+ *   - leading `./` stripped (`./visuals/coin.ts` matches `src/visuals/coin.ts`)
+ *   - filename-only fallback so renames in the registry that drop the
+ *     `src/` prefix still resolve.
+ *
+ * The forgiveness lets templates use whatever import.meta.glob shape they
+ * find natural without forcing a one-true-key convention.
+ */
+export declare function resolveRenderScript(game: Phaser.Game, scriptPath: string): ((g: Phaser.GameObjects.Graphics, params: Record<string, unknown>) => void) | undefined;

package/dist/scene/renderScripts.js

@@ -0,0 +1,67 @@
+const REGISTRY_KEY = '__unboxyRenderScriptRegistry';
+/**
+ * Stash a render-script registry on the Phaser game so `loadWorldScene` /
+ * `EditorBridge.applyEdit` can find it without explicit plumbing.
+ *
+ * The map's keys are absolute paths matching what scene files reference
+ * (e.g. `src/visuals/coin.ts`). Templates that build via `import.meta.glob`
+ * commonly produce relative keys like `./visuals/coin.ts`; the resolver
+ * normalises trailing slashes / leading `./` so both shapes work.
+ */
+export function setRenderScriptRegistry(game, scripts) {
+    const bag = game;
+    bag[REGISTRY_KEY] = scripts;
+}
+export function getRenderScriptRegistry(game) {
+    const bag = game;
+    return bag[REGISTRY_KEY];
+}
+/**
+ * Returns the `render` function for a script path, or undefined if no
+ * matching module is registered. The matcher is forgiving:
+ *
+ *   - exact match (`src/visuals/coin.ts`)
+ *   - leading `./` stripped (`./visuals/coin.ts` matches `src/visuals/coin.ts`)
+ *   - filename-only fallback so renames in the registry that drop the
+ *     `src/` prefix still resolve.
+ *
+ * The forgiveness lets templates use whatever import.meta.glob shape they
+ * find natural without forcing a one-true-key convention.
+ */
+export function resolveRenderScript(game, scriptPath) {
+    const registry = getRenderScriptRegistry(game);
+    if (!registry)
+        return undefined;
+    // Direct hit.
+    if (registry[scriptPath])
+        return registry[scriptPath].render;
+    // Try common normalisations.
+    const candidates = candidateKeys(scriptPath);
+    for (const c of candidates) {
+        if (registry[c])
+            return registry[c].render;
+    }
+    // Filename-only fallback.
+    const filename = scriptPath.split('/').pop();
+    if (filename) {
+        for (const key of Object.keys(registry)) {
+            if (key.endsWith('/' + filename) || key === filename) {
+                return registry[key].render;
+            }
+        }
+    }
+    return undefined;
+}
+function candidateKeys(scriptPath) {
+    const out = [];
+    const trimmed = scriptPath.replace(/^\.\//, '');
+    out.push(trimmed);
+    // src/visuals/coin.ts → ./visuals/coin.ts
+    if (trimmed.startsWith('src/'))
+        out.push('./' + trimmed.slice(4));
+    // visuals/coin.ts → src/visuals/coin.ts
+    if (!trimmed.startsWith('src/') && !trimmed.startsWith('./')) {
+        out.push('src/' + trimmed);
+    }
+    return out;
+}

package/dist/scene/spawnEntity.d.ts

@@ -0,0 +1,201 @@
+import Phaser from 'phaser';
+import { AssetRecord, TileMetadata, WorldEntity } from './types.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * Resolves an asset id to its AssetRecord, throwing a clear error if the
+ * scene file references something the manifest doesn't know about. We
+ * surface this as an error (not a silent miss) because a missing asset
+ * means either the manifest is stale or the scene file was hand-edited
+ * — both worth catching at runtime, not skipping silently.
+ */
+export type AssetResolver = (assetId: string) => AssetRecord;
+/** Optional hook for `code-rendered` visuals. v1 throws if not provided. */
+export type RenderScriptResolver = (scriptPath: string) => ((g: Phaser.GameObjects.Graphics, params: Record<string, unknown>) => void) | undefined;
+export interface SpawnContext {
+    scene: Phaser.Scene;
+    registry: EntityRegistry;
+    resolveAsset: AssetResolver;
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export declare function spawnEntity(ctx: SpawnContext, entity: WorldEntity): Phaser.GameObjects.GameObject;
+/**
+ * Read the auto-tracker's recorded draw extent and set editor hit-area
+ * data on the GameObject. Falls back to declared `visual.width/height`
+ * (centered on transform) when nothing was tracked (script didn't call
+ * any tracked methods, or called them through unwrapped paths).
+ *
+ * Exported so EditorBridge can call it after a re-render too —
+ * applyCodeRenderedParamsPatch reads new params, calls render again,
+ * then this updates the hit area to the new draw extent.
+ */
+export declare function applyTrackedHitArea(g: Phaser.GameObjects.Graphics, fallbackW: number, fallbackH: number): void;
+/**
+ * Slice 6 Phase C — wire per-tile metadata onto a Phaser tileset + layer.
+ *
+ * Sources `asset.tileset.tiles` (sparse map keyed by tile index) and:
+ *   1. Replaces `tileset.tileProperties` so any FUTURE `putTileAt` call
+ *      auto-stamps the new tile's `properties` from the lookup. Phaser
+ *      reads `tileset.tileProperties[index]` at tile-creation time.
+ *   2. Walks existing tiles via `layer.forEachTile` and refreshes each
+ *      tile's `properties` — needed for tiles that were already painted
+ *      before this fn ran (initial scene load, or `assetUpdate` replay).
+ *   3. Calls `layer.setCollisionByProperty({ solid: true })` so any tile
+ *      whose `properties.solid === true` participates in Arcade collision.
+ *      Idempotent + safe to call when no tile is solid (no-op).
+ *
+ * Exported because `EditorBridge.applyTilemapStructureOp` (addLayer) and
+ * `EditorBridge.handleAssetUpdate` both need to re-arm collision wiring
+ * without going through the full scene load. SDK 0.2.115+.
+ */
+export declare function applyTilesetTileMetadata(tileset: Phaser.Tilemaps.Tileset, layer: Phaser.Tilemaps.TilemapLayer, asset: AssetRecord): void;
+/**
+ * Arm tile animations on this layer — Phase F (slice 6 — design doc 06 §8).
+ *
+ * Reads `asset.tileset.animations[]`, finds every painted cell whose source
+ * index matches an animation's `rootTileIndex`, installs a per-frame UPDATE
+ * listener that swaps each cell's `tile.index` to the current frame.
+ * All cells with the same root animate in lockstep (Sprout Lands water
+ * lake-cells flow together).
+ *
+ * Idempotent — re-calling tears down the prior listener and re-scans. Used
+ * by:
+ *  - `createTilemap` at scene boot (initial arm)
+ *  - `EditorBridge.handleAssetUpdate` (when Animation Editor saves)
+ *  - `EditorBridge.applyTilemapStructureOp addLayer` (new layer arm)
+ *  - any subsequent paint op (host's `handleEditTilemap` re-runs metadata)
+ *
+ * Edit-mode caveat: scenes are `setActive(false)` in edit mode → scene
+ * UPDATE doesn't fire → the swap handler stays dormant → animated cells
+ * stay on whatever frame they were on when edit was entered. To keep edit
+ * mode showing the static "data" view, `EditorBridge.enterEdit` calls
+ * `resetTilesetAnimationsToRoot` which walks all animated cells + sets
+ * them back to root. exitEdit → next UPDATE tick re-applies current frame.
+ *
+ * Save-path safety: the iframe's mutated `tile.index` per frame doesn't
+ * leak into the host's draft state (home-ui keeps its own copy in
+ * `useEditorDraft`'s baseline + commands). Mid-animation Cmd+S saves the
+ * root indices, not the displayed frame.
+ *
+ * Phaser API note: Phaser 3 parses Tiled's `tile.animation` field into
+ * `tileset.tileData[id].animation` but its TilemapLayer renderer does NOT
+ * consume it. The community `phaser-animated-tiles` plugin bridges that
+ * gap but has been bit-rotted since 3.80. This is a 50-line custom impl
+ * that does the swap directly — same algorithm, no external dep.
+ */
+export declare function applyTilesetAnimations(layer: Phaser.Tilemaps.TilemapLayer, asset: AssetRecord): void;
+/**
+ * Reset every animated cell on a tilemap container to its root tile index.
+ * Called by `EditorBridge.enterEdit` so animated cells show the static
+ * authored frame in the editor, not whatever was currently visible at the
+ * moment the user toggled into edit mode. exitEdit doesn't need a paired
+ * call — the next UPDATE tick after scenes resume swaps each cell back to
+ * its current animation frame.
+ */
+export declare function resetTilesetAnimationsToRoot(container: Phaser.GameObjects.Container): void;
+/**
+ * Wire collision between `target` (a sprite, group, or anything with a
+ * physics body) and all collision surfaces of a tilemap entity — both
+ * the layer's native cell-rect collision AND any sub-tile static bodies
+ * authored via the Tile Metadata Editor's collision-shape mode.
+ *
+ * The one-call alternative to:
+ * ```ts
+ * scene.physics.add.collider(player, layer);
+ * scene.physics.add.collider(player, layer.getData('unboxySubTileStaticGroup'));
+ * ```
+ *
+ * Behavior code in a typical game:
+ * ```ts
+ * import { addTilemapCollider } from '@umicat/phaser-sdk';
+ * create() {
+ *   // ... spawn player ...
+ *   addTilemapCollider(this, 'world', this.player);
+ * }
+ * ```
+ *
+ * Returns the created Collider instances so callers can `.destroy()` them
+ * if needed (e.g. on level transition).
+ */
+export declare function addTilemapCollider(scene: Phaser.Scene, entityId: string, target: Phaser.Types.Physics.Arcade.ArcadeColliderType, callback?: Phaser.Types.Physics.Arcade.ArcadePhysicsCallback): Phaser.Physics.Arcade.Collider[];
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export declare function parseColor(input: string): number;
+/**
+ * Apply the asset's `hitbox` metadata to a sprite's physics body.
+ *
+ * Called automatically at spawn from `createSprite`; ALSO callable by
+ * behavior code that attaches a body later (e.g. the agent's physics skill
+ * does `scene.physics.add.existing(sprite); applyAssetHitbox(sprite, asset);`).
+ *
+ * Semantics:
+ * - **No-op (silent)** when `asset.hitbox` is unset — that's the chat-only
+ *   path (primitives, AI-gen images without vision metadata). Workflow A
+ *   in design doc 09 §4.4 is unaffected.
+ * - **Dev-warn (NOT throw)** when called on a sprite without a physics body.
+ *   The most likely agent mistake is calling this BEFORE
+ *   `scene.physics.add.existing(sprite)`; the warning surfaces in the
+ *   iframe console for the agent's post-turn diagnostic loop.
+ * - **Per-frame variant** installs an `ANIMATION_UPDATE` listener that
+ *   swaps `body.setSize/setOffset` on every frame change during anim
+ *   playback. Listener is idempotent — calling `applyAssetHitbox` twice
+ *   on the same sprite tears down the prior listener before installing a
+ *   new one (handles asset hot-reload + Inspector live-edits).
+ *
+ * Caveat: per-frame swap fires on `Phaser.Animations.Events.ANIMATION_UPDATE`
+ * only, which means manual `sprite.setFrame(idx)` calls outside of animation
+ * playback do NOT swap the body. v1 accepts this — combat sheets are
+ * animation-driven. A `setFrame` wrapper is a v2 candidate.
+ */
+export declare function applyAssetHitbox(sprite: Phaser.GameObjects.Sprite, asset: AssetRecord): void;
+/**
+ * Result of a `getTilemapAt` query. `metadata` holds the authored per-tile
+ * metadata for the matching tile (collision flags, damage, terrain tag,
+ * etc.); empty object when the tile is painted but has no metadata.
+ */
+export interface TilemapHit {
+    /** Which layer of the tilemap entity holds the tile. */
+    layerId: string;
+    /** The tile's 0-based row-major index in the tileset image. */
+    tileIndex: number;
+    /** Per-tile metadata (collision + gameplay fields). Empty if unset. */
+    metadata: TileMetadata;
+    /** Tile column inside the layer (0-based). */
+    tileX: number;
+    /** Tile row inside the layer (0-based). */
+    tileY: number;
+}
+/**
+ * Look up the painted tile at a world coordinate inside a tilemap entity.
+ *
+ * Slice 6 Phase C (design doc 06 §5.2). Returns null when:
+ *   - the entity doesn't exist / isn't a tilemap;
+ *   - no layer in the tilemap has a painted (non-empty) tile at that
+ *     world coord;
+ *   - the world coord is outside every layer's bounds.
+ *
+ * Layer scan order (when `options.layerId` is omitted) is top-down — the
+ * layer with the highest `z` is queried first, matching the visual stack.
+ * Pass `options.layerId` to scope to one layer (e.g. for a "ground type"
+ * lookup on the floor layer specifically).
+ *
+ * Behavior-code use:
+ * ```ts
+ * const hit = getTilemapAt(this, 'world', player.x, player.y);
+ * if (hit?.metadata.damage) player.hp -= hit.metadata.damage * dt;
+ * if (hit?.metadata.movement === 'swim') player.speed *= 0.5;
+ * ```
+ *
+ * Per-frame perf: each layer query is a constant-time `worldToTileXY` +
+ * `getTileAt` Phaser call. Safe for `update()` loops at typical layer
+ * counts (1–4 layers per tilemap).
+ */
+export declare function getTilemapAt(scene: Phaser.Scene, entityId: string, worldX: number, worldY: number, options?: {
+    layerId?: string;
+}): TilemapHit | null;