@umicat/phaser-sdk 1.0.0

package/dist/scene/types.d.ts

@@ -0,0 +1,1166 @@
+/**
+ * Scene-as-data types — visual editor foundation (slice 1).
+ *
+ * Spec: umicat-design/features/visual-editor/01-scene-data-foundation.md
+ *
+ * v1 schema (`schemaVersion: 1`) supports the entity kinds needed for the
+ * read-only scene viewer. HUD entity kinds, tilemap, trigger, and
+ * code-rendered visuals will land in later slices.
+ */
+export declare const SCHEMA_VERSION = 1;
+export type SceneType = 'world' | 'hud';
+export interface SceneRef {
+    id: string;
+    type: SceneType;
+    /** Path under `public/scenes/`, e.g. `"world/level-1-1.json"`. */
+    file: string;
+    /** Optional HUD scene id to overlay (world scenes only). Null = no HUD. */
+    hud?: string | null;
+}
+export interface HudRef {
+    id: string;
+    /** Path under `public/scenes/`, e.g. `"hud/game-hud.json"`. */
+    file: string;
+}
+/**
+ * Per-game asset table. Source of truth for asset id → Phaser textureKey
+ * resolution. The editor and runtime both read from this.
+ */
+export type AssetKind = 'image' | 'spritesheet' | 'atlas' | 'audio' | 'json';
+export interface AssetRecord {
+    /** Stable asset id used in scene files (`sprite.assetId` / `image.assetId`). */
+    id: string;
+    /** Phaser texture / cache key. May equal `id` for simple cases. */
+    textureKey: string;
+    /** Path relative to `public/`. */
+    path: string;
+    kind: AssetKind;
+    /** For `spritesheet`: Phaser SpriteSheetConfig. */
+    spriteSheetConfig?: {
+        frameWidth: number;
+        frameHeight: number;
+        margin?: number;
+        spacing?: number;
+    };
+    /**
+     * Top-level convenience fields. When the agent writes a spritesheet asset
+     * entry, it commonly puts these at the top level instead of nested in
+     * `spriteSheetConfig` — both shapes are now accepted by the loader.
+     */
+    frameWidth?: number;
+    frameHeight?: number;
+    margin?: number;
+    spacing?: number;
+    /** For `atlas`: companion atlas file path (xml or json). */
+    atlasPath?: string;
+    /** `'xml'` (Starling) or `'json'` (TexturePacker). */
+    atlasFormat?: 'xml' | 'json';
+    /**
+     * For `spritesheet`: named animation ranges. SDK auto-registers these as
+     * Phaser anims at preload, so behavior code can call
+     * `sprite.play('walk-down')` without manual `anims.create()` setup.
+     *
+     * <p>Pack import populates this from vision detection (4-direction RPG /
+     * sidescroller / multi-action layouts) or from Aseprite `frameTags`. The
+     * agent can also add/edit entries by hand when wiring a sheet asset.
+     *
+     * <p>Animation keys are scene-global in Phaser; if two sheets register
+     * the same name, the second registration is skipped with a warning.
+     * Disambiguate by namespacing the name (e.g. `cow-walk-down`) when
+     * collisions matter.
+     */
+    animations?: SheetAnimation[];
+    /** Default playback rate for `animations[]`. Defaults to 8. */
+    fps?: number;
+    /**
+     * 9-slice cut-line metadata. Two shapes accepted:
+     *
+     * - **Single image** (slice 7.5) — `NinePatchConfig` directly. Used on
+     *   `kind: 'image'` assets like a single button/panel background. All four
+     *   corner widths apply to the image as a whole.
+     * - **Per-frame on a uniform grid** (slice 7.6) — `{ perFrame: NinePatchConfig }`.
+     *   Used on `kind: 'spritesheet'` assets where every cell is its own
+     *   stretchable button/panel sharing the same corner radius (typical
+     *   itch.io UI button packs, e.g. `Square Buttons 26x26.png`). The HUD
+     *   widget references which cell to render via `backgroundFrame`.
+     *
+     * Per-cell keyed config (`{ perFrame: Record<number, NinePatchConfig> }`)
+     * is deferred to v3 per design 07 §7.9.5 — promote only when a real pack
+     * needs different corner radii on different cells.
+     */
+    ninePatch?: NinePatchConfig | NinePatchPerFrame;
+    /**
+     * Vision-detected pixel-art flag. When true, SDK applies
+     * `Phaser.Textures.FilterMode.NEAREST` to the texture after load so it
+     * renders crisp instead of bilinear-blurred. Population is per-source:
+     * pack-import sets it via vision; AI generation / manual upload / library
+     * backfill close their own gaps separately (see design doc 07 §8.4).
+     */
+    pixelArt?: boolean;
+    /**
+     * Per-asset collision body metadata (slice 8 — see design doc 09).
+     *
+     * Two shapes:
+     * - `HitboxRect` — single rect shared across every frame (top-down
+     *   characters with constant foot footprint, trees, buildings, walls).
+     * - `HitboxPerFrame` — `default` rect plus per-frame overrides indexed by
+     *   frame number. Used for melee combat where an attack-swing frame's
+     *   hitbox extends to where the tool reaches (Sprout Lands chop-the-tree
+     *   case). The SDK installs an `ANIMATION_UPDATE` listener that swaps
+     *   `body.setSize/setOffset` per frame during animation playback.
+     *
+     * v1 ships `kind: 'rect'` only. v2 adds `'circle'` as a pure forward-compat
+     * extension — see design doc 09 §9.2.1.
+     *
+     * Consumed by `applyAssetHitbox(sprite, asset)` at spawn time AND callable
+     * by behavior code after attaching a body. No-op if the sprite has no body.
+     */
+    hitbox?: HitboxRect | HitboxPerFrame;
+    /**
+     * Tileset metadata (slice 6 — see design doc 06).
+     *
+     * Present on assets used as tilemap tilesets. When set, the SDK knows
+     * the source-pixel cell size so `Phaser.Tilemap.addTilesetImage` can
+     * slice the image correctly. Phase A ships `cellSize` only; Phase C adds
+     * per-tile metadata (collision / damage / terrainTag); Phase D adds
+     * `autotile`; Phase F adds `animations`. All forward-compat — new
+     * optional sub-fields, never breaking the existing shape.
+     *
+     * Population paths:
+     * - Pack import wizard: vision-detected from uniform-grid sheets +
+     *   "looks like a tileset" heuristic. Cell size auto-filled.
+     * - Configure Tileset modal: user picks a single-image asset as a
+     *   tileset; modal prompts for cell size + persists onto this field.
+     *
+     * Note: a tileset asset typically has `kind: 'image'` (single PNG) — the
+     * `tileset` field is what marks it as "available as a tileset" in the
+     * editor's tilemap picker. Sprite-sheet assets (`kind: 'spritesheet'`)
+     * already carry frame dims via `spriteSheetConfig`; the SDK falls back
+     * to those when a layer's tileset is a spritesheet without a separate
+     * `tileset.cellSize`. See `resolveTilesetCellSize` in spawnEntity.ts.
+     */
+    tileset?: TilesetMetadata;
+    /**
+     * Asset-wide footprint anchor (slice 8 — see design doc 09 §2).
+     *
+     * Pixel within the asset's frame (top-left = 0,0) that defines where the
+     * sprite "touches the ground." SDK applies as
+     * `sprite.setOrigin(x / frameW, y / frameH)` at spawn, so `sprite.y` in
+     * world space equals the world y of the anchor pixel — perfect for ySort
+     * (`sprite.depth = sprite.y`).
+     *
+     * Typical values: character feet (e.g. `(16, 28)` on a 32×32 cell), tree
+     * trunk base, building foundation midpoint. Decorations / centered objects
+     * leave unset → Phaser default origin (0.5, 0.5) → ySort by geometric
+     * center (acceptable fallback; the scene panel surfaces a warning when
+     * ySort is on and some sprite assets lack anchor).
+     */
+    depthAnchor?: DepthAnchor;
+}
+/** Single-image 9-slice config. Pixels from each edge to the slice line. */
+export interface NinePatchConfig {
+    leftWidth: number;
+    rightWidth: number;
+    topHeight: number;
+    bottomHeight: number;
+}
+/**
+ * Per-frame 9-slice config (slice 7.6). One shared `NinePatchConfig` applied
+ * to every frame of a uniform-grid spritesheet. Covers ~95% of itch.io UI
+ * button packs, where each cell is a different button color/state but all
+ * share the same corner radius.
+ */
+export interface NinePatchPerFrame {
+    perFrame: NinePatchConfig;
+}
+/**
+ * Type guard — true when `ninePatch` is the per-frame variant. Lets call
+ * sites that only need to handle one shape stay narrow.
+ */
+export declare function isPerFrameNinePatch(np: NinePatchConfig | NinePatchPerFrame | undefined): np is NinePatchPerFrame;
+/**
+ * Rectangular hitbox in source-pixel coordinates (top-left = 0,0 within the
+ * asset's frame). Consumed by the SDK at sprite spawn time as
+ * `body.setSize(w, h)` + `body.setOffset(x, y)` when a physics body exists.
+ *
+ * v1 is the only supported `kind`. v2 adds `'circle'` (see design doc 09
+ * §9.2.1 for the full forward-compat migration story); polygon is v3+.
+ */
+export interface HitboxRect {
+    kind: 'rect';
+    /** Top-left x of the hitbox in source pixels. */
+    x: number;
+    /** Top-left y of the hitbox in source pixels. */
+    y: number;
+    w: number;
+    h: number;
+}
+/**
+ * v2 — placeholder doc only. NOT in v1 schema. When v2 adds circle, this
+ * interface lands and the `AssetRecord.hitbox` + `HitboxPerFrame.default` /
+ * `.frames` unions widen to include it. v1 backend validation whitelists
+ * `kind in ['rect']`; v2 widens the whitelist. All v1 data stays valid.
+ *
+ *   interface HitboxCircle {
+ *     kind: 'circle';
+ *     x: number;       // center x in source-pixel coords of frame 0
+ *     y: number;       // center y in source-pixel coords of frame 0
+ *     radius: number;
+ *   }
+ */
+/**
+ * Per-frame hitbox configuration. The `default` shape applies to every frame
+ * not present in `frames`; entries in `frames` override per frame index.
+ *
+ * This default+overrides model matches how combat sheets decompose — most
+ * frames share one hitbox (idle / walk / hurt at the feet), only attack-swing
+ * frames need a wider shape that reaches to where the tool / weapon visually
+ * extends. The motivating Sprout Lands case: 16-frame character sheet where
+ * frames 8–11 are an axe swing reaching ~16 pixels sideways past the foot.
+ *
+ * Discriminator: `'default' in hitbox` (HitboxRect has `kind` instead).
+ */
+export interface HitboxPerFrame {
+    default: HitboxRect;
+    /** Frame index → override shape. Frames absent fall back to `default`. */
+    frames: Record<number, HitboxRect>;
+}
+/**
+ * Type guard — true when `hitbox` is the per-frame variant. Used by SDK
+ * runtime to decide whether to install an `ANIMATION_UPDATE` listener that
+ * swaps body shape per frame.
+ *
+ * <p>Checks `default != null` (handles both `null` and `undefined`) rather
+ * than `'default' in h`. The backend stores hitboxes after a mode switch
+ * with EXPLICIT NULLS on the alternate shape's fields — `{ kind: 'rect',
+ * x, y, w, h, default: null, frames: null }` for Single mode — because
+ * OpenSearch's _update API deep-merges nested objects and would otherwise
+ * leave stale fields. `'default' in h` would return true on that shape and
+ * trip the per-frame path with a null default. The null check is the
+ * correct discriminator.
+ */
+export declare function isPerFrameHitbox(h: HitboxRect | HitboxPerFrame | undefined): h is HitboxPerFrame;
+/**
+ * Depth anchor — pixel within the asset's frame (top-left = 0,0) that defines
+ * the sprite's footprint position. The SDK applies it at spawn as
+ * `sprite.setOrigin(x / frameW, y / frameH)` so the sprite's world `y` aligns
+ * with the world position of this pixel. ySort then compares foot positions
+ * directly via `sprite.depth = sprite.y` without per-asset offset math.
+ *
+ * Asset-wide — shared across all frames of a spritesheet. Per-frame variation
+ * is not in scope (footprint position doesn't change across animations even
+ * when hitbox shape does).
+ */
+export interface DepthAnchor {
+    x: number;
+    y: number;
+}
+/**
+ * Tileset metadata for tilemap rendering (slice 6 — design doc 06).
+ *
+ * Carried on `AssetRecord.tileset`. Phase A ships the cell-size + layout
+ * fields needed to render a Phaser tilemap; later phases extend this
+ * shape additively (per-tile metadata, Wang autotile rules, animations).
+ */
+export interface TilesetMetadata {
+    /**
+     * Source-image cell size in pixels. Each cell becomes one tile in the
+     * Phaser tileset (`map.addTilesetImage(id, key, cellSize.w, cellSize.h)`).
+     * Required — without this the SDK can't slice the source image.
+     */
+    cellSize: {
+        width: number;
+        height: number;
+    };
+    /**
+     * Optional column count of the cell grid. Used by the editor's tile
+     * palette and as a sanity check during slice; derivable from
+     * `texture.width / cellSize.width` when omitted.
+     */
+    cols?: number;
+    /** Optional row count of the cell grid. See `cols`. */
+    rows?: number;
+    /**
+     * Optional margin (pixels) around the entire tileset image — pixels
+     * from the image edge before the first cell starts. Defaults to 0.
+     */
+    margin?: number;
+    /**
+     * Optional spacing (pixels) between adjacent cells. Defaults to 0.
+     */
+    spacing?: number;
+    /**
+     * Per-tile metadata keyed by tile index (0-based, row-major in the tileset
+     * image). Sparse — only tiles with non-default metadata are stored.
+     * Authored via the Tile Metadata Editor modal (right-click a cell in the
+     * tile palette). Slice 6 Phase C — design doc 06 §5.
+     *
+     * Runtime wiring:
+     *  - `solid: true` → SDK auto-flags via
+     *    `layer.setCollisionByProperty({ solid: true })` at scene load.
+     *  - other fields readable-but-not-auto-applied — game code reads via
+     *    the SDK's `getTilemapAt(scene, entityId, x, y)` helper and decides.
+     */
+    tiles?: {
+        [tileIndex: number]: TileMetadata;
+    };
+    /**
+     * Wang 4-bit autotile configuration (slice 6 Phase D — design doc 06 §7).
+     *
+     * Present when this tileset supports terrain-mode painting. Multi-terrain
+     * baseline: one tileset can carry N terrains (grass + dirt-cliff + stone),
+     * each with its own rule map (§7.5). Authored via the manual rule-map
+     * editor (Phase D.3) or auto-populated by vision on pack import (Phase
+     * D.4); SDK runtime (Phase D.2) reads `terrains[i].ruleMap` at paint time
+     * to pick the right tile index from the 4-corner bitmask.
+     */
+    autotile?: TilesetAutotile;
+    /**
+     * Animated tiles (slice 6 Phase F — design doc 06 §8). Each entry
+     * defines an animation cycle keyed on a "root" tile index. At runtime
+     * the SDK installs a per-frame update hook that swaps every painted
+     * cell whose source index === `rootTileIndex` through the animation's
+     * frame sequence, all cells synchronously (water-flow / lava-bubble /
+     * torch-flicker pattern).
+     *
+     * Painted data stores the root tile index; the SDK overlays the
+     * current-frame index at render time. On enterEdit, animated cells are
+     * reset back to root so the editor always shows the static "data"
+     * frame, not whatever was currently visible at the moment of toggle.
+     * Save paths read from the host-side draft (not the iframe's mutated
+     * tile state), so saving mid-animation is safe.
+     *
+     * Phaser's TilemapLayer does NOT auto-render Tiled `tile.animation`
+     * data — it only parses it. The SDK drives frame swaps via a scene
+     * UPDATE listener; design 06 §8.8's claim of "Phaser handles timing
+     * and rendering" was wrong (the parser stores the data on
+     * `tileset.tileData[id].animation` but no rendering code consumes it).
+     * 50-line custom impl avoids depending on the bit-rotted
+     * `phaser-animated-tiles` community plugin.
+     */
+    animations?: TilesetAnimation[];
+}
+/**
+ * One animation cycle on a tileset (slice 6 Phase F).
+ *
+ * Painted tiles whose source index equals `rootTileIndex` cycle through
+ * `frames[*].tileIndex` per their `duration` (ms). All cells animate
+ * synchronously — Sprout Lands water lake-cells all flow together.
+ * Per-cell phase offset (organic-water look) is v2.
+ *
+ * Example — Sprout Lands 4-frame water at 4fps:
+ * ```json
+ * {
+ *   "id": "water-flow",
+ *   "rootTileIndex": 12,
+ *   "frames": [
+ *     { "tileIndex": 12, "duration": 250 },
+ *     { "tileIndex": 13, "duration": 250 },
+ *     { "tileIndex": 14, "duration": 250 },
+ *     { "tileIndex": 15, "duration": 250 }
+ *   ]
+ * }
+ * ```
+ *
+ * The first frame conventionally references `rootTileIndex` so the
+ * static editor view (where animations don't run) matches frame 0 of
+ * the animation. Not enforced — the cycle starts on whichever frame the
+ * elapsed-time math lands on; users who set `frames[0].tileIndex` !==
+ * `rootTileIndex` get a visible jump when the animation starts.
+ */
+export interface TilesetAnimation {
+    /** Stable id within the tileset's `animations[]`. Used by editor UI for selection. */
+    id: string;
+    /**
+     * Tile index (0-based, row-major in the tileset image) that the user
+     * paints with. All cells painted with this index get animated.
+     */
+    rootTileIndex: number;
+    /**
+     * Frames cycled through in order, then looping. Empty frames array →
+     * SDK skips this animation (no error, just no-op).
+     */
+    frames: Array<{
+        /** Tile index to display during this frame. */
+        tileIndex: number;
+        /** Milliseconds to hold this frame before advancing. Minimum 16ms (~60fps). */
+        duration: number;
+    }>;
+}
+/**
+ * Wang autotile configuration on a tileset (slice 6 Phase D — design
+ * doc 06 §7). Multi-terrain: one tileset can drive multiple independent
+ * autotile palettes.
+ *
+ * Two modes:
+ *
+ * - **`'wang-4bit'`** (Phase D.1–D.2 baseline, design §7.1–§7.4) — 4 corner
+ *   bits per cell, max 16 ruleMap entries. Covers 9 unique edge/corner
+ *   patterns + interior; missing 6 concave/diagonal cases per §7.7. Each
+ *   terrain typically needs 9-15 tiles.
+ *
+ * - **`'wang-8bit'`** (Phase D.2.5.2, design §7.7 "blob" / Cr31
+ *   "2-edge + 2-corner") — 4 corner bits + 4 side bits per cell, max 256
+ *   ruleMap entries (~47 geometrically valid). Distinguishes patterns
+ *   the 4-bit model collapses to bm 15 (isolated 1×1, 1-wide strips,
+ *   T-intersections). Each terrain typically needs 47 tiles for full
+ *   coverage; commercial tilesets like Sprout Lands ship these.
+ */
+export interface TilesetAutotile {
+    kind: 'wang-4bit' | 'wang-8bit';
+    /**
+     * One entry per terrain this tileset supports. Order is editor-display
+     * order (also serves as the default selection in the palette).
+     */
+    terrains: WangTerrain[];
+}
+/**
+ * One Wang terrain palette inside a tileset (slice 6 Phase D).
+ *
+ * Each terrain owns a `ruleMap` from a bitmask to a tile index. The bit
+ * encoding depends on the parent `TilesetAutotile.kind`:
+ *
+ * - **`'wang-4bit'`**: bitmask is 4 bits (0..15). Bit 0 = BR corner, 1 = BL,
+ *   2 = TR, 3 = TL. So `0b1111 = 15` = interior, `0b0000 = 0` = empty.
+ *
+ * - **`'wang-8bit'`**: bitmask is 8 bits (0..255). Low 4 bits = corners
+ *   (same as 4-bit). High 4 bits = sides: bit 4 = E neighbor painted,
+ *   5 = W, 6 = S, 7 = N. So `0b00001111 = 15` = isolated 1×1 island
+ *   (all corners but no painted neighbors), `0b11111111 = 255` = full
+ *   interior. Geometrically: if a side bit is set, the 2 corners adjacent
+ *   to that side must also be set (the painted neighbor touches them).
+ *
+ * Sparse — keys without an entry mean "no tile for this configuration",
+ * and the cell stays empty when the painter resolves that bitmask. Bitmask
+ * 0 is typically absent (it's the "empty / unpainted" cell).
+ */
+export interface WangTerrain {
+    /**
+     * Stable id unique within this tileset's `autotile.terrains[]`. Layers
+     * reference this via `TilemapLayer.autotile.terrainId`. Typically the
+     * same string as `terrainTag` (e.g. `"grass"`) but kept separate so
+     * users can rename the display tag without rewriting every layer.
+     */
+    id: string;
+    /**
+     * Free-form terrain label mirroring `TileMetadata.terrainTag`. Allows
+     * behavior code to cross-reference "what terrain did the user paint
+     * here?" with per-tile gameplay metadata (movement, damage, etc.).
+     */
+    terrainTag: string;
+    /**
+     * Map from bitmask to tile index in the tileset image (0-based,
+     * row-major). Key range depends on parent kind: 0..15 for `wang-4bit`,
+     * 0..255 for `wang-8bit`. JSON wire format uses string keys (Jackson
+     * default for `Map<Integer, V>`); the SDK accepts both string and
+     * numeric keys at runtime.
+     */
+    ruleMap: {
+        [bitmask: number]: number;
+    };
+}
+/**
+ * Per-tile metadata for tilemap collision / gameplay (slice 6 Phase C —
+ * design doc 06 §5.1). All fields optional and default at runtime when
+ * undefined. Mirrors backend `TilesetMetadata.TileMetadata`.
+ */
+export interface TileMetadata {
+    /** Blocks player via Phaser's `setCollisionByProperty({ solid: true })`. */
+    solid?: boolean;
+    /** Only collides from above (jump-through platforms). v1 stores flag only. */
+    oneWay?: boolean;
+    /** `"up-left"` / `"up-right"` / undefined — slope direction. */
+    slope?: string;
+    /** HP/sec dealt when player stands on this tile. Game code reads + applies. */
+    damage?: number;
+    /** Free-form terrain label (`"grass"` / `"water"` / …) for Phase D + behavior. */
+    terrainTag?: string;
+    /** `"walk"` / `"swim"` / `"fly"` / `"block"` — movement modifier. */
+    movement?: string;
+    /** Free-form ground-type label for footstep-sound selection. */
+    groundType?: string;
+    /** Free-form user tag for game-specific logic (e.g. `"checkpoint"`). */
+    customTag?: string;
+    /**
+     * Sub-tile collision rectangles (slice 6 Phase C follow-up). N axis-
+     * aligned rects in source-pixel coords, relative to tile top-left.
+     * Multi-rect supports L / U / frame-shaped collision (wall corners,
+     * borders). When non-empty, the SDK creates one invisible Arcade static
+     * body per rect at each painted instance and disables Phaser's native
+     * cell-rect collision for those cells. When empty but `solid: true`,
+     * default Phaser cell-rect collision applies (full tile collides).
+     */
+    collisionRects?: Array<{
+        x: number;
+        y: number;
+        w: number;
+        h: number;
+    }>;
+}
+export interface SheetAnimation {
+    /** Phaser animation key — used as `sprite.play('<name>')`. */
+    name: string;
+    /** First frame index, inclusive. */
+    from: number;
+    /** Last frame index, inclusive. */
+    to: number;
+    /** When true, Phaser registers with `repeat: -1`. Defaults to true. */
+    loop?: boolean;
+    /** Override the asset-level fps for this specific animation. */
+    fps?: number;
+}
+export interface Manifest {
+    schemaVersion: number;
+    id: string;
+    title: string;
+    version: string;
+    initialScene: string;
+    scenes: SceneRef[];
+    huds: HudRef[];
+    assets: AssetRecord[];
+    /**
+     * Entity TYPE definitions for runtime spawning — slice 11, Phase B.1.
+     * Each prefab is a self-contained template: visual + physics + properties.
+     * Code spawns instances via the SDK's `spawnPrefab(scene, prefabId, x, y)`.
+     * Optional — games that have only authored static entities (no runtime
+     * spawning) can omit this field.
+     */
+    prefabs?: PrefabRecord[];
+    globals?: {
+        physics?: {
+            gravity?: {
+                x?: number;
+                y?: number;
+            };
+        };
+        world?: {
+            pixelArt?: boolean;
+        };
+    };
+}
+/**
+ * Prefab kinds — same renderable kinds as world entities. SDK 0.3.0 flattened
+ * `primitive` → `rect | circle`. (Prefabs never targeted `tilemap` / `trigger`
+ * / `group` — those are scene-authored, not runtime-spawned.)
+ */
+export type PrefabKind = 'sprite' | 'rect' | 'circle' | 'code-rendered';
+/**
+ * Arcade physics body configuration. Used by prefabs (`PrefabRecord.physics`,
+ * applied inside `spawnPrefab`) AND by authored scene entities
+ * (`WorldEntityBase.physics`, applied inside `spawnEntity`). In both cases the
+ * SDK calls `physics.add.existing` and applies these knobs to the body, so
+ * behavior code doesn't have to call `body.setSize` / `setOffset` manually.
+ *
+ * Conventions:
+ *  - `bodyW` / `bodyH` default to the visual's drawn extent (sprite
+ *    texture size, primitive width/height, or code-rendered visual.width
+ *    / visual.height — 64 if unset).
+ *  - `offsetX` / `offsetY` default to centering the body inside the
+ *    GameObject's local bounds (i.e. `(visualW - bodyW) / 2`).
+ *  - All fields are optional; pass an empty `physics: {}` to get the
+ *    default body sized to the visual.
+ */
+export interface PrefabPhysics {
+    bodyW?: number;
+    bodyH?: number;
+    offsetX?: number;
+    offsetY?: number;
+    immovable?: boolean;
+    velocityX?: number;
+    velocityY?: number;
+    collideWorldBounds?: boolean;
+    bounceX?: number;
+    bounceY?: number;
+}
+/**
+ * Entity TYPE — used as a template by `spawnPrefab` to create runtime
+ * instances. Spawn-time coordinates and per-instance overrides come from
+ * the caller; everything else is shared across all instances.
+ *
+ * Prefabs do NOT have a `transform` field — that's set per spawn.
+ * Editor live-edits to a prefab record propagate to existing instances
+ * via `umicat:editor:editPrefab` (see slice 11 §6.4).
+ *
+ * **Flat schema** (SDK 0.3.0). Prefab fields live at the top level —
+ * exactly like world entities. The shape depends on `kind`:
+ *
+ * - `kind: 'sprite'` + `{ assetId, frame?, tint?, alpha?, flipX?, flipY? }`
+ * - `kind: 'rect'` + `{ width, height, fillColor?, strokeColor?, strokeWidth?, alpha? }`
+ * - `kind: 'circle'` + `{ radius, fillColor?, strokeColor?, strokeWidth?, alpha? }`
+ * - `kind: 'code-rendered'` + `{ script, params?, width?, height? }`
+ */
+export type PrefabRecord = SpritePrefab | RectPrefab | CirclePrefab | CodeRenderedPrefab;
+export interface PrefabBase {
+    /** Stable id used by `spawnPrefab(scene, '<id>', ...)`. */
+    id: string;
+    /** Semantic tag — `registry.byRole('enemy')` lists every spawned instance. */
+    role?: string;
+    /** Physics body config applied at spawn. Omit when the prefab has no body. */
+    physics?: PrefabPhysics;
+    /** Free-form per-type data behavior code reads via `go.getData('entityProperties').<key>`. */
+    properties?: Record<string, unknown>;
+}
+export interface SpritePrefab extends PrefabBase {
+    kind: 'sprite';
+    assetId: string;
+    frame?: string | number;
+    tint?: string;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+}
+export interface RectPrefab extends PrefabBase {
+    kind: 'rect';
+    width: number;
+    height: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface CirclePrefab extends PrefabBase {
+    kind: 'circle';
+    radius: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface CodeRenderedPrefab extends PrefabBase {
+    kind: 'code-rendered';
+    script: string;
+    params?: Record<string, unknown>;
+    width?: number;
+    height?: number;
+}
+/**
+ * Wave schedule — a time-ordered sequence of spawn instructions that
+ * reference prefab ids. Models everything from a Galaga formation to a
+ * survivor game's difficulty curve.
+ *
+ * Each schedule lives in its own file under `public/waves/<id>.json`.
+ * Behavior code consumes them via `runWaveSchedule(scene, id, callbacks)`
+ * which returns a `WaveController` for game-flow operations
+ * (pause / stop / skip).
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §7
+ */
+export interface WaveScheduleRecord {
+    schemaVersion: number;
+    id: string;
+    name?: string;
+    waves: WaveRecord[];
+    /** Restart from wave 0 after the last wave's endCondition fires. */
+    loop?: boolean;
+}
+export interface WaveRecord {
+    id: string;
+    /** Wait this long after the previous wave's endCondition fires before starting. */
+    delayMs?: number;
+    spawns: SpawnInstruction[];
+    /** When this wave is considered "complete" — default `'allDead'`. */
+    endCondition?: WaveEndCondition;
+}
+/**
+ * One spawn instruction within a wave. v1 ships `point` and `formation`
+ * (with `shape: 'grid' | 'line'`) — `arc`, `v-shape`, and `random` are
+ * forward-compat'd in the wire shape but the runtime treats unknown
+ * shapes as a single `point` at the formation origin and warns.
+ */
+export type SpawnInstruction = SpawnPointInstruction | SpawnFormationInstruction;
+export interface SpawnPointInstruction {
+    kind: 'point';
+    prefabId: string;
+    x: number;
+    y: number;
+    /** Time within the wave (relative to wave start) at which to spawn. */
+    atMs: number;
+    /** Optional per-spawn overrides — same shape as `SpawnPrefabOverrides`. */
+    overrides?: Record<string, unknown>;
+}
+export interface SpawnFormationInstruction {
+    kind: 'formation';
+    prefabId: string;
+    formation: FormationRecord;
+    /** Time within the wave at which the formation starts spawning. */
+    startMs: number;
+    /** Delay between successive entity spawns inside the formation. */
+    intervalMs: number;
+    /** Optional per-spawn overrides shared by every formation member. */
+    overrides?: Record<string, unknown>;
+}
+export type FormationShape = 'grid' | 'line' | 'arc' | 'v-shape';
+export interface FormationRecord {
+    shape: FormationShape;
+    /** Grid + v-shape: number of rows. Line + arc: usually 1. */
+    rows?: number;
+    /** Grid + line + arc + v-shape: number of columns / members per row. */
+    cols?: number;
+    spacing?: {
+        x?: number;
+        y?: number;
+    };
+    /** World-coordinate top-left (grid) or center (arc) of the formation. */
+    origin?: {
+        x: number;
+        y: number;
+    };
+    /** Arc-only: radius from `origin`. */
+    radius?: number;
+    /** Arc-only: span in radians (default π). */
+    arcRadians?: number;
+}
+export type WaveEndCondition = 'allDead' | {
+    type: 'time';
+    ms: number;
+} | {
+    type: 'count';
+    killed: number;
+};
+export interface Transform {
+    x: number;
+    y: number;
+    /** Radians. */
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    depth?: number;
+}
+export type AnchorSide = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+export interface Anchor {
+    side: AnchorSide;
+    offsetX?: number;
+    offsetY?: number;
+}
+export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';
+export interface WorldEntityBase {
+    id: string;
+    /** Optional semantic tag. Behavior code keys off this. */
+    role?: string;
+    /** Free-form per-entity data the agent's behavior code reads. */
+    properties?: Record<string, unknown>;
+    transform: Transform;
+    /**
+     * Optional Arcade physics body. When set, `spawnEntity` calls
+     * `physics.add.existing` and applies the body's size / offset / immovable /
+     * velocity / bounce — the same body-level path and `PrefabPhysics` shape
+     * `spawnPrefab` uses, so authored entities and runtime instances get
+     * identical bodies. Applied for renderable entities (`sprite` / `rect` /
+     * `circle` / `code-rendered`); ignored on `group` / `tilemap` / `trigger`.
+     * Omit for entities with no body, or that wire physics in behavior code.
+     */
+    physics?: PrefabPhysics;
+}
+export interface SpriteEntity extends WorldEntityBase {
+    kind: 'sprite';
+    assetId: string;
+    /** Atlas frame name OR sprite-sheet frame index. */
+    frame?: string | number;
+    tint?: string;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+}
+export interface RectEntity extends WorldEntityBase {
+    kind: 'rect';
+    width: number;
+    height: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface CircleEntity extends WorldEntityBase {
+    kind: 'circle';
+    radius: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface CodeRenderedEntity extends WorldEntityBase {
+    kind: 'code-rendered';
+    /** Path to render script, e.g. `"src/visuals/boss-renderer.ts"`. */
+    script: string;
+    params?: Record<string, unknown>;
+    /**
+     * Optional bounds used for editor hit-testing (click + drag) and the
+     * selection rectangle. Phaser Graphics has no intrinsic size, so we set
+     * it explicitly. Defaults to 64×64 centered on the entity. The agent can
+     * override per-entity when the script draws something larger or smaller.
+     */
+    width?: number;
+    height?: number;
+}
+export interface GroupEntity extends WorldEntityBase {
+    kind: 'group';
+    /**
+     * One level of nesting in v1: a child cannot itself be a `group`.
+     * If you need deeper hierarchy, the agent should flatten via the
+     * existing transform and add a role tag for grouping queries.
+     */
+    children: NonGroupWorldEntity[];
+}
+/**
+ * Tilemap entity — slice 6.
+ *
+ * Phase A (render-only foundation, 2026-05-18): SDK reads tilemap entities
+ * and renders them as Phaser Tilemaps. One tileset per layer; per-cell
+ * `data` is a 2D array of tile indices (numeric, matching Phaser's native
+ * tile-id model). Empty layers (no `data`) fall back to the slice-3 grid
+ * sketch so unpainted tilemaps still show their bounds in the editor.
+ *
+ * Phase B adds the painter UI; Phase C adds per-tile metadata + Y-sort;
+ * Phase D adds Wang autotile resolution; Phase F adds animated tiles.
+ *
+ * Multi-tileset per layer (`tilesetIds: string[]`) is reserved in the
+ * shape for later phases but Phase A only consumes the first id.
+ */
+export interface TilemapEntity extends WorldEntityBase {
+    kind: 'tilemap';
+    /** Render-time cell size in pixels. Layer data indexes cells at this size. */
+    tileSize: {
+        width: number;
+        height: number;
+    };
+    /** Map size in cells (not pixels). */
+    size: {
+        width: number;
+        height: number;
+    };
+    layers: TilemapLayer[];
+}
+export interface TilemapLayer {
+    id: string;
+    name?: string;
+    /**
+     * Tilesets this layer can paint with. Phase A consumes the FIRST id only
+     * (single-tileset rendering); the array shape is kept so later phases
+     * can paint blended layers (grass + flowers) without a schema break.
+     */
+    tilesetIds?: string[];
+    z?: number;
+    /**
+     * 2D array of tile indices (row-major: `data[y][x]`). `null` cells are
+     * empty (not painted). Integer indices match Phaser's native tile-id
+     * scheme — the index within the tileset image, 0-based, row-major. Phase
+     * D will introduce a parallel autotile bitmask channel for Wang layers.
+     */
+    data?: Array<Array<number | null>>;
+    visible?: boolean;
+    /** Editor-only: prevents accidental painting. No runtime effect. */
+    locked?: boolean;
+    /**
+     * Wang 4-bit autotile binding (slice 6 Phase D — design doc 06 §7).
+     *
+     * When set, the painter operates in "terrain" mode on this layer: each
+     * brush stroke marks corner-vertices for `terrainId` and the SDK
+     * resolves the tile index from the tileset's `autotile.terrains[]`
+     * ruleMap on every affected cell. `terrainId` references
+     * `TilesetAutotile.terrains[].id` on the layer's first tileset.
+     *
+     * Absent (the common case) → layer is a plain stamp painter; cells
+     * carry author-chosen tile indices verbatim.
+     */
+    autotile?: {
+        terrainId: string;
+    };
+    ySort?: boolean;
+}
+export type TriggerShape = {
+    kind: 'rect';
+    width: number;
+    height: number;
+} | {
+    kind: 'circle';
+    radius: number;
+};
+/**
+ * Trigger entity — slice 3 ships a stub renderer (semi-transparent rect/circle
+ * with the design's cyan tint). Full behavior wiring (description / targets /
+ * behavior script) lands in slice 5 (03-world-editor.md §8).
+ */
+export interface TriggerEntity extends WorldEntityBase {
+    kind: 'trigger';
+    shape: TriggerShape;
+    /** User-facing label shown in Hierarchy + on canvas. */
+    description?: string;
+    /** Entity ids this trigger affects. Slice 5 wires the relationship UI. */
+    targets?: string[];
+    /** Optional path to behavior script. Slice 5 fills this in. */
+    behaviorScript?: string;
+    /** Optional preset name (open-door / damage-zone / scene-transition / spawner / heal). */
+    preset?: string;
+}
+export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
+export type WorldEntity = NonGroupWorldEntity | GroupEntity;
+/**
+ * Renderable entity kinds — those that produce a single GameObject with
+ * physics + transform. Excludes `group` (container), `tilemap` (multi-layer
+ * data), `trigger` (invisible volume).
+ */
+export type RenderableEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity;
+export interface CameraConfig {
+    /** Entity id to follow. Null = static camera. */
+    follow?: string | null;
+    smoothing?: number;
+    deadzone?: {
+        x: number;
+        y: number;
+    };
+    lookahead?: number;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    zoom?: number;
+    pixelPerfect?: boolean;
+    shakeDecay?: number;
+}
+export interface WorldSceneConfig {
+    width: number;
+    height: number;
+    background?: {
+        color?: string;
+    };
+    physics?: {
+        gravity?: {
+            x?: number;
+            y?: number;
+        };
+    };
+}
+export interface WorldScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'world';
+    world: WorldSceneConfig;
+    camera?: CameraConfig;
+    entities: WorldEntity[];
+    /**
+     * Scene-level Y-sort opt-in (slice 8 — see design doc 09 §2.2).
+     *
+     * When `true`, the SDK installs a per-frame update hook in `loadWorldScene`
+     * that walks the entity registry and sets `sprite.depth = sprite.y` so
+     * closer-to-camera sprites overlap farther ones. Default `false` —
+     * side-scrollers, single-screen arcade, and chat-only Workflow A games
+     * don't pay the per-frame cost.
+     *
+     * Two opt-out mechanisms (orthogonal, cover different intents):
+     * - `entity.transform.depth` set to a number → that constant wins, ySort
+     *   skips the entity. For "cloud always on top," "tilemap at -1000," etc.
+     * - `entity.properties.skipYSort: true` → ySort doesn't touch the entity's
+     *   depth at all. For behavior code that manages depth dynamically.
+     *
+     * Top-down RPG / farming / iso / city-builder / MOBA / 2.5D platformer
+     * are the target genres.
+     */
+    ySort?: boolean;
+    metadata?: {
+        tags?: string[];
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+}
+export type HudLayer = 'base' | 'overlay' | 'modal';
+/**
+ * Text content source — `static` is a literal string the user typed;
+ * `dynamic` reads a value from `umicat.gameData` at runtime, with optional
+ * prefix/suffix formatting. The Inspector only edits the static path; the
+ * agent flips a widget to `dynamic` via the inline AI popover when the user
+ * asks for live values ("show current score"). The variable registry +
+ * picker UX from design 04 §4.7 is intentionally NOT implemented — Umicat's
+ * thesis is users don't see "variables", agent handles bindings.
+ */
+export type HudTextSource = {
+    mode: 'static';
+    text: string;
+} | {
+    mode: 'dynamic';
+    /** Key in `umicat.gameData` whose value drives the text. */
+    binding: string;
+    prefix?: string;
+    suffix?: string;
+    /** Fallback value rendered when the binding is unset. */
+    fallback?: string;
+};
+/**
+ * A progress bar's numeric input. Static = literal number; dynamic = read
+ * from `umicat.gameData` / Phaser's game registry by key. Mirrors
+ * `HudTextSource` but for numbers (no prefix/suffix — bar is visual).
+ */
+export type HudNumberSource = {
+    mode: 'static';
+    value: number;
+} | {
+    mode: 'dynamic';
+    binding: string;
+    /** Used when the binding is unset at runtime. Defaults to 0. */
+    fallback?: number;
+};
+export type HudEntityKind = 'text' | 'image' | 'icon-button' | 'progress-bar' | 'panel';
+export interface HudEntityBase {
+    id: string;
+    /** Optional semantic tag. Behavior code keys off this. */
+    role?: string;
+    /** Free-form per-entity data the agent's behavior code reads. */
+    properties?: Record<string, unknown>;
+    anchor: Anchor;
+    /** Render layer (base < overlay < modal). Defaults to `base`. */
+    layer?: HudLayer;
+    /**
+     * Z-order within the same layer. Higher = on top. Optional; defaults to
+     * insertion order if absent.
+     */
+    z?: number;
+    /** When false, the widget is hidden at runtime. Useful for modal panels
+     *  that the agent toggles via gameData / scene events. */
+    visible?: boolean;
+}
+/**
+ * HUD text widget — renders a string at an anchor position. Source is either
+ * static (a literal) or dynamic (a key into `umicat.gameData` / Phaser's
+ * game registry). All fields flat per SDK 0.3.0.
+ */
+export interface HudTextEntity extends HudEntityBase {
+    kind: 'text';
+    source: HudTextSource;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+}
+/**
+ * HUD image widget — renders an asset by id at an anchor position. Supports
+ * single images, atlas frames, and sprite-sheet frame indexes. Optional 9-slice
+ * stretching when the referenced asset has `ninePatch` metadata.
+ */
+export interface HudImageEntity extends HudEntityBase {
+    kind: 'image';
+    assetId: string;
+    frame?: string | number;
+    /** CSS pixel size on the HUD scene's logical canvas. */
+    width?: number;
+    height?: number;
+    tint?: string;
+    alpha?: number;
+}
+/**
+ * Icon button. v1 has no built-in onPress wiring — clicks emit a Phaser
+ * scene event `hud:press` with the entity id, and the agent's behavior code
+ * subscribes (`scene.events.on('hud:press', id => ...)`). The slice-4
+ * popover is the user's path to wire one up: select the button, ✨, "pause
+ * the game when this is pressed". design 04 §6 / §7's bind-to-action +
+ * built-in-presets system is reserved for slice 5.5.
+ */
+export interface HudIconButtonEntity extends HudEntityBase {
+    kind: 'icon-button';
+    /** Optional displayed label. */
+    label?: string;
+    /** Optional icon asset shown inside the button. */
+    iconAssetId?: string;
+    /**
+     * Optional image asset rendered as the button background. When the
+     * referenced asset has `ninePatch` metadata, the SDK renders it via
+     * `phaser3-rex-plugins` NinePatch so corners stay fixed at any width/height;
+     * otherwise the image is stretched to the widget's size. When set, the
+     * colored-rect bg below (fillColor / strokeColor / shape) is ignored, and
+     * `pressedFillColor` no-ops (no fill swap on a textured bg in v1).
+     *
+     * For uniform-grid spritesheet assets with `ninePatch.perFrame` set
+     * (slice 7.6), pair this with `backgroundFrame` to pick which cell to
+     * render — common case is a button-pack sheet where every cell is a
+     * different button color/state.
+     */
+    backgroundAssetId?: string;
+    /**
+     * For uniform-grid spritesheet backgrounds (slice 7.6): index of the cell
+     * to render. Defaults to 0 when omitted. Ignored when the background asset
+     * is a single image. Mutually exclusive with `backgroundRegion` — when both
+     * are set, the SDK picks `backgroundRegion` (atlas-name lookup wins).
+     */
+    backgroundFrame?: number;
+    /**
+     * For region-atlas backgrounds (slice 10): name of the atlas frame to
+     * render. Used when the referenced asset is `kind: 'atlas'` + `atlasFormat:
+     * 'json'` — the region atlas can carry per-frame `ninePatch` metadata, in
+     * which case the SDK 9-slices each region independently. Mutually exclusive
+     * with `backgroundFrame`.
+     */
+    backgroundRegion?: string;
+    /** Button shape. Default `rounded-rect`. Ignored when backgroundAssetId is set. */
+    shape?: 'rounded-rect' | 'circle';
+    width?: number;
+    height?: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    pressedFillColor?: string;
+    textColor?: string;
+    fontSize?: number;
+}
+export interface HudProgressBarEntity extends HudEntityBase {
+    kind: 'progress-bar';
+    /** Current value source (e.g. player's HP). */
+    value: HudNumberSource;
+    /** Max value source (e.g. player's max HP). */
+    max: HudNumberSource;
+    width?: number;
+    height?: number;
+    fillColor?: string;
+    backgroundColor?: string;
+    borderColor?: string | null;
+    borderWidth?: number;
+    /** Border radius for rounded rectangles. Defaults to 0 (sharp corners). */
+    borderRadius?: number;
+}
+export interface HudPanelEntity extends HudEntityBase {
+    kind: 'panel';
+    width?: number;
+    height?: number;
+    /**
+     * Optional image asset rendered as the panel background. When the
+     * referenced asset has `ninePatch` metadata, the SDK renders it via
+     * `phaser3-rex-plugins` NinePatch so corners stay fixed at any width/height;
+     * otherwise the image is stretched to the widget's size. When set,
+     * `backgroundColor` / `backgroundAlpha` / `borderColor` / `borderWidth` are
+     * ignored — the asset image carries its own pixels.
+     */
+    backgroundAssetId?: string;
+    backgroundFrame?: number;
+    backgroundRegion?: string;
+    /** Solid fill colour. Falls back to a transparent panel if omitted. */
+    backgroundColor?: string;
+    /** Background alpha (independent of widget-level alpha). */
+    backgroundAlpha?: number;
+    borderColor?: string | null;
+    borderWidth?: number;
+    /** Border radius for the rect. Defaults to 0. */
+    borderRadius?: number;
+}
+export type HudEntity = HudTextEntity | HudImageEntity | HudIconButtonEntity | HudProgressBarEntity | HudPanelEntity;
+export interface HudScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'hud';
+    design?: {
+        /** e.g. `"16:9"`, `"9:16"`. Free-form for now; the editor uses it for the
+         *  preview-frame visualization (design 04 §2.1). v1 doesn't enforce it
+         *  at runtime — anchors resolve against the actual canvas size. */
+        designAspectRatio?: string;
+        safeArea?: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    entities: HudEntity[];
+    metadata?: WorldScene['metadata'];
+}
+export type SceneFile = WorldScene | HudScene;