@umicat/phaser-sdk 1.0.0

package/dist/scene/GameConfig.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Game config — top-level game settings as data.
+ *
+ * Slice 11 (Phase B.3, 2026-05-12). `public/game.json` carries the
+ * orientation / dimensions / physics defaults / controls hints that
+ * today live as TS `const` exports in `src/config.ts`. Extracting them
+ * to data lets the visual editor's eventual "Game settings" panel
+ * (Phase B.5) tweak canvas size, gravity, controls without code edits.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §3
+ *
+ * Public API:
+ *  - `loadGameConfig(path?)` — async fetch of `public/game.json`.
+ *    Resolves to `GameConfig` on success, `null` on missing file
+ *    (callers fall back to in-code defaults).
+ *
+ * Pattern in `main.ts`:
+ *
+ * ```ts
+ * import { createUmicatGame, loadGameConfig } from '@umicat/phaser-sdk';
+ *
+ * const cfg = await loadGameConfig();
+ * createUmicatGame({
+ *   orientation: cfg?.orientation ?? 'portrait',
+ *   pixelArt: cfg?.pixelArt ?? false,
+ * });
+ * ```
+ *
+ * `main.ts` needs top-level await (Vite's default target supports it).
+ */
+import { Orientation } from '../orientation.js';
+export interface GameConfig {
+    orientation?: Orientation;
+    /** Explicit canvas width — only when not using `orientation`. */
+    width?: number;
+    /** Explicit canvas height — only when not using `orientation`. */
+    height?: number;
+    /** Renders pixel-art at integer scale — matches `createUmicatGame.pixelArt`. */
+    pixelArt?: boolean;
+    /** Physics defaults applied to Arcade physics if no explicit physics options. */
+    physics?: {
+        gravity?: {
+            x?: number;
+            y?: number;
+        };
+        debug?: boolean;
+    };
+    /** Free-form controls hint surfaced to the user / editor. */
+    controls?: {
+        primary?: string;
+        fire?: string;
+        [key: string]: string | undefined;
+    };
+}
+/**
+ * Fetch the game config JSON from `public/game.json` (or a custom path).
+ * Resolves to `null` on 404 / parse error so callers can fall back to
+ * in-code defaults cleanly.
+ */
+export declare function loadGameConfig(path?: string): Promise<GameConfig | null>;

package/dist/scene/GameConfig.js

@@ -0,0 +1,50 @@
+/**
+ * Game config — top-level game settings as data.
+ *
+ * Slice 11 (Phase B.3, 2026-05-12). `public/game.json` carries the
+ * orientation / dimensions / physics defaults / controls hints that
+ * today live as TS `const` exports in `src/config.ts`. Extracting them
+ * to data lets the visual editor's eventual "Game settings" panel
+ * (Phase B.5) tweak canvas size, gravity, controls without code edits.
+ *
+ * Design: umicat-design/features/visual-editor/11-game-data-foundation.md §3
+ *
+ * Public API:
+ *  - `loadGameConfig(path?)` — async fetch of `public/game.json`.
+ *    Resolves to `GameConfig` on success, `null` on missing file
+ *    (callers fall back to in-code defaults).
+ *
+ * Pattern in `main.ts`:
+ *
+ * ```ts
+ * import { createUmicatGame, loadGameConfig } from '@umicat/phaser-sdk';
+ *
+ * const cfg = await loadGameConfig();
+ * createUmicatGame({
+ *   orientation: cfg?.orientation ?? 'portrait',
+ *   pixelArt: cfg?.pixelArt ?? false,
+ * });
+ * ```
+ *
+ * `main.ts` needs top-level await (Vite's default target supports it).
+ */
+const DEFAULT_PATH = 'game.json';
+/**
+ * Fetch the game config JSON from `public/game.json` (or a custom path).
+ * Resolves to `null` on 404 / parse error so callers can fall back to
+ * in-code defaults cleanly.
+ */
+export async function loadGameConfig(path = DEFAULT_PATH) {
+    try {
+        // Resolve relative to the page's base URL — same logic Phaser's loader uses.
+        // No leading slash so the iframe under `/preview/<id>/` works.
+        const url = path;
+        const res = await fetch(url);
+        if (!res.ok)
+            return null;
+        return (await res.json());
+    }
+    catch {
+        return null;
+    }
+}

package/dist/scene/HudRuntime.d.ts

@@ -0,0 +1,131 @@
+import Phaser from 'phaser';
+import { Anchor, AssetRecord, HudEntity, HudScene, Manifest } from './types.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * HUD runtime — slice 5.
+ *
+ * `UmicatHudScene` is a Phaser scene class that runs in parallel with the
+ * world scene, draws anchor-positioned widgets above the gameplay, and
+ * subscribes dynamic-text widgets to the game registry so they live-update
+ * when the agent's behavior code calls `this.registry.set(key, value)`.
+ *
+ * Agent contract (taught by the `hud-dynamic-binding` skill):
+ *   - Use `scene.registry.set(key, value)` to drive HUD bindings. The HUD
+ *     scene picks up the change via `registry.events.on('changedata-<key>')`.
+ *   - HUD text widgets reference the registry key via `source.binding` (flat,
+ *     at the widget root — SDK 0.3.0).
+ */
+export declare const UMICAT_HUD_SCENE_KEY = "UmicatHud";
+interface HudSceneInit {
+    /** HUD id from manifest.huds[]. */
+    hudId?: string;
+}
+/**
+ * Resolve a HUD anchor + offset against the current canvas size to a
+ * concrete pixel position. Called per widget on (a) initial spawn and (b)
+ * scale resize so widgets re-anchor when the viewport changes.
+ */
+export declare function resolveAnchor(scene: Phaser.Scene, anchor: Anchor, safeArea?: {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}): {
+    x: number;
+    y: number;
+};
+interface SpawnContext {
+    scene: Phaser.Scene;
+    registry: EntityRegistry;
+    safeArea: {
+        top: number;
+        right: number;
+        bottom: number;
+        left: number;
+    };
+    resolveAsset: (id: string) => AssetRecord;
+}
+/**
+ * Spawn a HUD widget into the scene. The returned GameObject is recorded in
+ * the entity registry so the editor + behavior code can find it by id.
+ */
+export declare function spawnHudEntity(ctx: SpawnContext, entity: HudEntity): Phaser.GameObjects.GameObject;
+/**
+ * Walk a HudScene's entities and queue Phaser loads for any image / icon
+ * assets it references. Idempotent — relies on `manifestState.requestedAssetIds`
+ * if SceneLoader's preload helpers have already touched this scene.
+ */
+export declare function preloadHudAssets(scene: Phaser.Scene, hudScene: HudScene, manifest: Manifest): void;
+/**
+ * Load and spawn a HUD scene into the given Phaser scene. Symmetric to
+ * `loadWorldScene`. Returns the parsed scene file + entity registry.
+ *
+ * Pattern (in `UmicatHudScene.create`):
+ *   const result = await loadHudScene(this, hudId);
+ *   // widgets live; agent's behavior code can subscribe to events via
+ *   // `this.events.on('hud:press', id => ...)`.
+ */
+export declare function loadHudScene(scene: Phaser.Scene, hudId: string): Promise<{
+    hudScene: HudScene;
+    registry: EntityRegistry;
+}>;
+/** Find the HUD scene's entity registry, if a HUD scene is currently active. */
+export declare function findHudRegistry(game: Phaser.Game): EntityRegistry | undefined;
+/** Find the HUD scene file from the JSON cache, if loaded. */
+export declare function findHudSceneFile(game: Phaser.Game): HudScene | undefined;
+/**
+ * Look up a HUD entity record from the cached scene file. Used by the bridge
+ * during drag (to read anchor side / current offset) and applyEdit (to
+ * resolve the new anchor when side changes).
+ */
+export declare function findHudEntity(game: Phaser.Game, entityId: string): HudEntity | undefined;
+/**
+ * Compute the canvas-pixel base position for an entity's anchor side
+ * (without offset). Used on drag-end to derive the new offset from the
+ * GameObject's final position.
+ */
+export declare function getHudAnchorBase(game: Phaser.Game, entity: HudEntity): {
+    x: number;
+    y: number;
+};
+/**
+ * Apply an editor patch to a live HUD widget. Mirrors the spawn function's
+ * logic but operates on the existing GameObject — anchor changes
+ * re-resolve position; text source changes rewire the registry subscription;
+ * visual style changes setText / setColor / etc. directly.
+ *
+ * Returns true if a known field was patched, false if nothing applied.
+ */
+export declare function applyHudPatch(game: Phaser.Game, entityId: string, patch: {
+    anchor?: {
+        side?: string;
+        offsetX?: number;
+        offsetY?: number;
+    };
+    layer?: string;
+    z?: number;
+    /**
+     * Flat render-field patch (SDK 0.3.0). Field names match the HUD entity
+     * root: `source` / `fontFamily` / `color` / `assetId` / `width` / `tint` /
+     * `label` / `fillColor` / `backgroundAssetId` / etc.
+     */
+    fields?: Record<string, unknown>;
+    role?: string | null;
+    properties?: Record<string, unknown>;
+}): boolean;
+/** Spawn a fresh HUD entity into the active HUD scene. Used by editor's create-entity path. */
+export declare function createHudEntityInScene(game: Phaser.Game, entity: HudEntity): boolean;
+/** Destroy a HUD entity. */
+export declare function deleteHudEntityFromScene(game: Phaser.Game, entityId: string): boolean;
+/**
+ * Per-game HUD scene. Auto-launched by `createUmicatGame` when the world
+ * scene's manifest entry sets `hud: '<id>'`. Renders above the world via
+ * Phaser's scene rendering order; takes input independently.
+ */
+export declare class UmicatHudScene extends Phaser.Scene {
+    private hudId;
+    constructor();
+    init(data: HudSceneInit): void;
+    create(): Promise<void>;
+}
+export {};