@umicat/phaser-sdk 1.0.0

package/dist/scene/Waves.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Wave schedules — time-ordered spawn sequences as data.
+ *
+ * Slice 11 (Phase B.4, 2026-05-12). Each schedule lives in
+ * `public/waves/<id>.json` as a `WaveScheduleRecord`. Behavior code calls
+ * `runWaveSchedule(scene, id, callbacks)` to drive enemy waves / formations /
+ * staged spawns without hand-implementing wave loops.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §7
+ *
+ * Public API:
+ *  - `loadWaveSchedule(scene, id)` — async fetch via Phaser's loader. Cached.
+ *  - `runWaveSchedule(scene, id, callbacks)` — start a schedule; returns a
+ *    `WaveController` (pause / resume / skipTo / stop).
+ *
+ * Wave end conditions:
+ *  - `'allDead'` (default) — waits until every spawned instance from this
+ *    wave has been destroyed.
+ *  - `{ type: 'time', ms }` — fixed duration from wave start.
+ *  - `{ type: 'count', killed }` — wait until N spawned instances destroyed.
+ */
+import Phaser from 'phaser';
+import { WaveRecord, WaveScheduleRecord } from './types.js';
+export interface SpawnInstance {
+    /** Prefab id requested by the schedule. */
+    prefabId: string;
+    /** World coordinate where the spawn should land. */
+    x: number;
+    y: number;
+    /** Wave id the spawn belongs to (for logging / per-wave logic). */
+    waveId: string;
+    /** Zero-based index of the wave within the schedule. */
+    waveIndex: number;
+    /** Per-spawn overrides from the schedule (deep-merged into the prefab). */
+    overrides?: Record<string, unknown>;
+}
+export interface WaveCallbacks {
+    /**
+     * Called for every spawn. Caller spawns the instance (typically via
+     * `spawnPrefab`) and returns the GameObject so the controller can
+     * track it for `endCondition: 'allDead'` / `{ type: 'count', killed }`.
+     * Return `void` if you don't want lifecycle tracking (rare).
+     */
+    onSpawn: (instance: SpawnInstance) => Phaser.GameObjects.GameObject | void;
+    onWaveStart?: (waveIndex: number, wave: WaveRecord) => void;
+    onWaveEnd?: (waveIndex: number, wave: WaveRecord) => void;
+    onScheduleEnd?: () => void;
+}
+export interface WaveController {
+    /** Pause all pending timers + advance checks. Idempotent. */
+    pause(): void;
+    /** Resume after pause. Idempotent if not paused. */
+    resume(): void;
+    /** Jump to the wave at `index` (0-based). Cancels in-flight spawns of current wave. */
+    skipTo(index: number): void;
+    /** Stop the schedule. Fires `onScheduleEnd`. Controller is dead after this. */
+    stop(): void;
+    /** Zero-based index of the wave currently spawning / waiting on. */
+    currentWaveIndex(): number;
+    /** `true` after the schedule fully completes (no more waves, no loop). */
+    isComplete(): boolean;
+}
+/**
+ * Fetch a wave schedule via Phaser's JSON loader. Cached per scene cache
+ * — re-calling with the same id returns the cached record immediately.
+ */
+export declare function loadWaveSchedule(scene: Phaser.Scene, scheduleId: string): Promise<WaveScheduleRecord>;
+/**
+ * Start a wave schedule. Returns a `WaveController` immediately; the
+ * schedule loads asynchronously and starts as soon as the file is in
+ * cache. Use this in `GameScene.create()`:
+ *
+ * ```ts
+ * const wc = runWaveSchedule(this, 'stage-1', {
+ *   onSpawn: ({ prefabId, x, y, overrides }) => {
+ *     const go = spawnPrefab(this, prefabId, x, y, overrides);
+ *     this.enemies.add(go);
+ *     return go;
+ *   },
+ *   onWaveStart: (i) => this.events.emit('hudWave', i + 1),
+ *   onScheduleEnd: () => this.scene.start('VictoryScene'),
+ * });
+ * ```
+ */
+export declare function runWaveSchedule(scene: Phaser.Scene, scheduleId: string, callbacks: WaveCallbacks): WaveController;

package/dist/scene/Waves.js

@@ -0,0 +1,365 @@
+/**
+ * Wave schedules — time-ordered spawn sequences as data.
+ *
+ * Slice 11 (Phase B.4, 2026-05-12). Each schedule lives in
+ * `public/waves/<id>.json` as a `WaveScheduleRecord`. Behavior code calls
+ * `runWaveSchedule(scene, id, callbacks)` to drive enemy waves / formations /
+ * staged spawns without hand-implementing wave loops.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §7
+ *
+ * Public API:
+ *  - `loadWaveSchedule(scene, id)` — async fetch via Phaser's loader. Cached.
+ *  - `runWaveSchedule(scene, id, callbacks)` — start a schedule; returns a
+ *    `WaveController` (pause / resume / skipTo / stop).
+ *
+ * Wave end conditions:
+ *  - `'allDead'` (default) — waits until every spawned instance from this
+ *    wave has been destroyed.
+ *  - `{ type: 'time', ms }` — fixed duration from wave start.
+ *  - `{ type: 'count', killed }` — wait until N spawned instances destroyed.
+ */
+import Phaser from 'phaser';
+const WAVE_CACHE_PREFIX = 'umicat:wave:';
+/**
+ * Fetch a wave schedule via Phaser's JSON loader. Cached per scene cache
+ * — re-calling with the same id returns the cached record immediately.
+ */
+export function loadWaveSchedule(scene, scheduleId) {
+    const cacheKey = `${WAVE_CACHE_PREFIX}${scheduleId}`;
+    if (scene.cache.json.exists(cacheKey)) {
+        return Promise.resolve(scene.cache.json.get(cacheKey));
+    }
+    return new Promise((resolve, reject) => {
+        scene.load.once(Phaser.Loader.Events.COMPLETE, () => {
+            const record = scene.cache.json.get(cacheKey);
+            if (!record) {
+                reject(new Error(`[umicat/waves] schedule '${scheduleId}' loaded but cache is empty`));
+                return;
+            }
+            resolve(record);
+        });
+        scene.load.once(Phaser.Loader.Events.FILE_LOAD_ERROR, (file) => {
+            if (file.key === cacheKey) {
+                reject(new Error(`[umicat/waves] failed to load wave schedule '${scheduleId}' — check public/waves/${scheduleId}.json exists`));
+            }
+        });
+        scene.load.json(cacheKey, `waves/${scheduleId}.json`);
+        scene.load.start();
+    });
+}
+/**
+ * Start a wave schedule. Returns a `WaveController` immediately; the
+ * schedule loads asynchronously and starts as soon as the file is in
+ * cache. Use this in `GameScene.create()`:
+ *
+ * ```ts
+ * const wc = runWaveSchedule(this, 'stage-1', {
+ *   onSpawn: ({ prefabId, x, y, overrides }) => {
+ *     const go = spawnPrefab(this, prefabId, x, y, overrides);
+ *     this.enemies.add(go);
+ *     return go;
+ *   },
+ *   onWaveStart: (i) => this.events.emit('hudWave', i + 1),
+ *   onScheduleEnd: () => this.scene.start('VictoryScene'),
+ * });
+ * ```
+ */
+export function runWaveSchedule(scene, scheduleId, callbacks) {
+    const controller = new WaveControllerImpl(scene, callbacks);
+    loadWaveSchedule(scene, scheduleId)
+        .then((record) => controller.start(record))
+        .catch((err) => {
+        // eslint-disable-next-line no-console
+        console.warn('[umicat/waves]', err);
+    });
+    return controller;
+}
+// --- Internals ------------------------------------------------------------
+class WaveControllerImpl {
+    constructor(scene, callbacks) {
+        this.scene = scene;
+        this.callbacks = callbacks;
+        this.record = null;
+        this.waveIndex = 0;
+        this.paused = false;
+        this.stopped = false;
+        this.complete = false;
+        /** Active TimerEvents we need to cancel on pause / skip / stop. */
+        this.timers = new Set();
+        /** GameObjects spawned in the current wave — tracked for endCondition. */
+        this.aliveInWave = new Set();
+        /** Count of GameObjects destroyed in the current wave (for `count` end condition). */
+        this.killedInWave = 0;
+        /** Wave-start timestamp (for `time` end condition). */
+        this.waveStartedAtMs = 0;
+        /** Polling timer for endCondition checks. */
+        this.endCheckTimer = null;
+        // Stop the schedule if the scene shuts down — frees all timers.
+        scene.events.once(Phaser.Scenes.Events.SHUTDOWN, () => this.stop());
+    }
+    start(record) {
+        if (this.stopped)
+            return;
+        this.record = record;
+        this.runWave(0);
+    }
+    currentWaveIndex() {
+        return this.waveIndex;
+    }
+    isComplete() {
+        return this.complete;
+    }
+    pause() {
+        if (this.paused || this.stopped)
+            return;
+        this.paused = true;
+        this.scene.time.paused = false; // we manage our own timers; don't pause the whole scene clock
+        for (const t of this.timers)
+            t.paused = true;
+        if (this.endCheckTimer)
+            this.endCheckTimer.paused = true;
+    }
+    resume() {
+        if (!this.paused || this.stopped)
+            return;
+        this.paused = false;
+        for (const t of this.timers)
+            t.paused = false;
+        if (this.endCheckTimer)
+            this.endCheckTimer.paused = false;
+    }
+    skipTo(index) {
+        if (this.stopped || !this.record)
+            return;
+        this.cancelTimers();
+        this.aliveInWave.clear();
+        this.killedInWave = 0;
+        this.runWave(Math.max(0, Math.min(index, this.record.waves.length)));
+    }
+    stop() {
+        if (this.stopped)
+            return;
+        this.stopped = true;
+        this.cancelTimers();
+        this.aliveInWave.clear();
+        this.complete = true;
+        this.callbacks.onScheduleEnd?.();
+    }
+    // ---- Wave lifecycle ------------------------------------------------------
+    runWave(index) {
+        if (this.stopped || !this.record)
+            return;
+        // Beyond the last wave — loop or end.
+        if (index >= this.record.waves.length) {
+            if (this.record.loop) {
+                this.runWave(0);
+            }
+            else {
+                this.complete = true;
+                this.callbacks.onScheduleEnd?.();
+            }
+            return;
+        }
+        const wave = this.record.waves[index];
+        this.waveIndex = index;
+        const startWave = () => {
+            if (this.stopped)
+                return;
+            this.waveStartedAtMs = this.scene.time.now;
+            this.killedInWave = 0;
+            this.aliveInWave.clear();
+            this.callbacks.onWaveStart?.(index, wave);
+            this.scheduleSpawns(wave, index);
+            this.armEndConditionCheck(wave, index);
+        };
+        if (wave.delayMs && wave.delayMs > 0) {
+            this.addTimer(wave.delayMs, startWave);
+        }
+        else {
+            startWave();
+        }
+    }
+    scheduleSpawns(wave, waveIndex) {
+        for (const ins of wave.spawns) {
+            switch (ins.kind) {
+                case 'point':
+                    this.schedulePoint(ins, wave, waveIndex);
+                    break;
+                case 'formation':
+                    this.scheduleFormation(ins, wave, waveIndex);
+                    break;
+                default: {
+                    // Unknown kind — log + skip rather than crash. v1 ships point + formation;
+                    // future kinds (`random`, ...) wire here.
+                    // eslint-disable-next-line no-console
+                    console.warn('[umicat/waves] unknown spawn kind:', ins.kind);
+                }
+            }
+        }
+    }
+    schedulePoint(ins, wave, waveIndex) {
+        this.addTimer(ins.atMs ?? 0, () => {
+            this.doSpawn({
+                prefabId: ins.prefabId,
+                x: ins.x,
+                y: ins.y,
+                waveId: wave.id,
+                waveIndex,
+                overrides: ins.overrides,
+            });
+        });
+    }
+    scheduleFormation(ins, wave, waveIndex) {
+        const positions = expandFormation(ins);
+        for (let i = 0; i < positions.length; i++) {
+            const [x, y] = positions[i];
+            const at = ins.startMs + i * (ins.intervalMs ?? 0);
+            this.addTimer(at, () => {
+                this.doSpawn({
+                    prefabId: ins.prefabId,
+                    x,
+                    y,
+                    waveId: wave.id,
+                    waveIndex,
+                    overrides: ins.overrides,
+                });
+            });
+        }
+    }
+    doSpawn(instance) {
+        if (this.stopped)
+            return;
+        const go = this.callbacks.onSpawn(instance);
+        if (!go)
+            return;
+        this.aliveInWave.add(go);
+        go.once(Phaser.GameObjects.Events.DESTROY, () => {
+            this.aliveInWave.delete(go);
+            this.killedInWave++;
+        });
+    }
+    armEndConditionCheck(wave, waveIndex) {
+        const end = wave.endCondition ?? 'allDead';
+        const tick = () => {
+            if (this.stopped || this.paused)
+                return;
+            if (this.shouldEndWave(end)) {
+                this.endWave(wave, waveIndex);
+            }
+        };
+        // Poll once per 100ms. Light enough at any reasonable wave count;
+        // simpler than per-destroy event aggregation across all end-conditions.
+        this.endCheckTimer = this.scene.time.addEvent({
+            delay: 100,
+            loop: true,
+            callback: tick,
+        });
+    }
+    shouldEndWave(end) {
+        if (end === 'allDead') {
+            // Wait until every scheduled spawn has fired AND every spawned instance
+            // is gone. While the schedule still has pending timer callbacks, alive
+            // can be 0 transiently — guard with the timer count.
+            const pendingTimers = pendingSpawnTimers(this.timers);
+            return pendingTimers === 0 && this.aliveInWave.size === 0;
+        }
+        if (end.type === 'time') {
+            return this.scene.time.now - this.waveStartedAtMs >= end.ms;
+        }
+        if (end.type === 'count') {
+            return this.killedInWave >= end.killed;
+        }
+        return false;
+    }
+    endWave(wave, waveIndex) {
+        if (this.endCheckTimer) {
+            this.endCheckTimer.remove(false);
+            this.endCheckTimer = null;
+        }
+        this.callbacks.onWaveEnd?.(waveIndex, wave);
+        this.cancelTimers();
+        this.runWave(waveIndex + 1);
+    }
+    // ---- Timer plumbing ------------------------------------------------------
+    addTimer(delay, callback) {
+        const t = this.scene.time.addEvent({
+            delay: Math.max(0, delay),
+            callback: () => {
+                this.timers.delete(t);
+                callback();
+            },
+        });
+        this.timers.add(t);
+    }
+    cancelTimers() {
+        for (const t of this.timers)
+            t.remove(false);
+        this.timers.clear();
+        if (this.endCheckTimer) {
+            this.endCheckTimer.remove(false);
+            this.endCheckTimer = null;
+        }
+    }
+}
+/** Count of `addTimer` events that haven't fired yet. */
+function pendingSpawnTimers(timers) {
+    let n = 0;
+    for (const t of timers)
+        if (!t.hasDispatched)
+            n++;
+    return n;
+}
+/**
+ * Expand a formation record into a list of [x, y] positions. v1 ships
+ * `grid` and `line`; `arc` and `v-shape` are forward-compat'd but expand
+ * to a single point at the origin with a warn.
+ */
+function expandFormation(ins) {
+    const f = ins.formation;
+    const rows = Math.max(1, f.rows ?? 1);
+    const cols = Math.max(1, f.cols ?? 1);
+    const sx = f.spacing?.x ?? 0;
+    const sy = f.spacing?.y ?? 0;
+    const ox = f.origin?.x ?? 0;
+    const oy = f.origin?.y ?? 0;
+    const positions = [];
+    if (f.shape === 'grid') {
+        for (let r = 0; r < rows; r++) {
+            for (let c = 0; c < cols; c++) {
+                positions.push([ox + c * sx, oy + r * sy]);
+            }
+        }
+        return positions;
+    }
+    if (f.shape === 'line') {
+        for (let c = 0; c < cols; c++) {
+            positions.push([ox + c * sx, oy]);
+        }
+        return positions;
+    }
+    if (f.shape === 'v-shape') {
+        // simple v: rows = depth, cols = members per side; falls back to grid
+        // when ambiguous. v1 minimum: one row, cols members in a V centered on origin.
+        const half = Math.floor(cols / 2);
+        for (let c = 0; c < cols; c++) {
+            const dx = (c - half) * sx;
+            const dy = Math.abs(c - half) * sy;
+            positions.push([ox + dx, oy + dy]);
+        }
+        return positions;
+    }
+    if (f.shape === 'arc') {
+        const r = f.radius ?? 0;
+        const span = f.arcRadians ?? Math.PI;
+        for (let c = 0; c < cols; c++) {
+            const t = cols === 1 ? 0.5 : c / (cols - 1);
+            const theta = -span / 2 + t * span;
+            positions.push([ox + r * Math.sin(theta), oy + r * (1 - Math.cos(theta))]);
+        }
+        return positions;
+    }
+    // eslint-disable-next-line no-console
+    console.warn(`[umicat/waves] unknown formation shape '${f.shape}'; spawning single point at origin`);
+    return [[ox, oy]];
+}

package/dist/scene/autotile.d.ts

@@ -0,0 +1,103 @@
+/**
+ * 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`.
+ */
+import type Phaser from 'phaser';
+import type { AssetRecord, WangTerrain } from './types.js';
+/**
+ * One cell mutated by an autotile cascade. `prevIndex === -1` means the
+ * cell was empty before; `index === -1` means the cell is empty after.
+ * Callers emit these as the `previousCells` array on `tilemapEdited` so
+ * undo can restore the prior state in one shot.
+ */
+export interface AutotileAffectedCell {
+    x: number;
+    y: number;
+    index: number;
+    prevIndex: number;
+}
+/**
+ * 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 declare function findTerrain(asset: AssetRecord | null | undefined, terrainId: string): WangTerrain | 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 declare function getAutotileKind(asset: AssetRecord | null | undefined): 'wang-4bit' | 'wang-8bit';
+/**
+ * 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 declare function invalidateAutotileCells(layer: Phaser.Tilemaps.TilemapLayer): void;
+/** @deprecated Renamed to `invalidateAutotileCells` (D.2.5.1). */
+export declare const invalidateAutotileVertices: typeof 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 declare function applyAutotile(layer: Phaser.Tilemaps.TilemapLayer, cellX: number, cellY: number, terrain: WangTerrain, mode: 'paint' | 'erase', kind?: 'wang-4bit' | 'wang-8bit'): AutotileAffectedCell[];