@unboxy/phaser-sdk 0.2.27 → 0.2.29

package/dist/scene/HudRuntime.d.ts

@@ -0,0 +1,125 @@
+import Phaser from 'phaser';
+import { Anchor, AssetRecord, HudEntity, HudScene, Manifest } from './types.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * HUD runtime — slice 5.
+ *
+ * `UnboxyHudScene` 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>')`.
+ *   - The HUD widget JSON references the key via `visual.source.binding`.
+ */
+export declare const UNBOXY_HUD_SCENE_KEY = "UnboxyHud";
+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 `UnboxyHudScene.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;
+    visual?: 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 `createUnboxyGame` 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 UnboxyHudScene extends Phaser.Scene {
+    private hudId;
+    constructor();
+    init(data: HudSceneInit): void;
+    create(): Promise<void>;
+}
+export {};