@unboxy/phaser-sdk 0.2.27 → 0.2.29

package/dist/scene/SceneLoader.js

@@ -187,6 +187,15 @@ export async function loadWorldScene(scene, sceneId, options = {}) {
         spawnEntity(ctx, entity);
     // Configure camera.
     applyCamera(scene, sceneFile, registry);
+    // Auto-launch the HUD scene attached to this world (slice 5). Imported
+    // lazily to avoid pulling HudRuntime into worlds that don't need it.
+    if (ref.hud) {
+        const { UNBOXY_HUD_SCENE_KEY } = await import('./HudRuntime.js');
+        if (scene.scene.isActive(UNBOXY_HUD_SCENE_KEY)) {
+            scene.scene.stop(UNBOXY_HUD_SCENE_KEY);
+        }
+        scene.scene.launch(UNBOXY_HUD_SCENE_KEY, { hudId: ref.hud });
+    }
     return { sceneFile, registry };
 }
 async function loadSceneJson(scene, ref) {

package/dist/scene/types.d.ts

@@ -260,17 +260,114 @@ export interface WorldScene {
         updatedAt?: string;
     };
 }
+export type HudLayer = 'base' | 'overlay' | 'modal';
 /**
- * HUD scene schema slot — v1 reserves the shape for slice 5. The loader
- * throws if it encounters one in slice 1; the type lives here so the
- * manifest's `huds[]` list is well-typed.
+ * Text content source — `static` is a literal string the user typed;
+ * `dynamic` reads a value from `unboxy.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 — Unboxy's
+ * thesis is users don't see "variables", agent handles bindings.
  */
+export type HudTextSource = {
+    mode: 'static';
+    text: string;
+} | {
+    mode: 'dynamic';
+    /** Key in `unboxy.gameData` whose value drives the text. */
+    binding: string;
+    prefix?: string;
+    suffix?: string;
+    /** Fallback value rendered when the binding is unset. */
+    fallback?: string;
+};
+export interface HudTextVisual {
+    kind: 'text';
+    source: HudTextSource;
+    fontFamily?: string;
+    fontSize?: number;
+    color?: string;
+    align?: 'left' | 'center' | 'right';
+}
+export interface HudImageVisual {
+    kind: 'image';
+    assetId: string;
+    /** Atlas frame name OR sprite-sheet frame index. */
+    frame?: string | number;
+    /** CSS pixel size on the HUD scene's logical canvas. */
+    width?: number;
+    height?: number;
+    tint?: string;
+    alpha?: number;
+}
+export interface HudIconButtonVisual {
+    kind: 'icon-button';
+    /** Optional displayed label. */
+    label?: string;
+    /** Optional icon asset shown inside the button. */
+    iconAssetId?: string;
+    /** Button shape. Default `rounded-rect`. */
+    shape?: 'rounded-rect' | 'circle';
+    width?: number;
+    height?: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    pressedFillColor?: string;
+    textColor?: string;
+    fontSize?: number;
+}
+export type HudVisual = HudTextVisual | HudImageVisual | HudIconButtonVisual;
+export type HudEntityKind = 'text' | 'image' | 'icon-button';
+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;
+}
+export interface HudTextEntity extends HudEntityBase {
+    kind: 'text';
+    visual: HudTextVisual;
+}
+export interface HudImageEntity extends HudEntityBase {
+    kind: 'image';
+    visual: HudImageVisual;
+}
+/**
+ * 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';
+    visual: HudIconButtonVisual;
+}
+export type HudEntity = HudTextEntity | HudImageEntity | HudIconButtonEntity;
 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;
@@ -279,7 +376,7 @@ export interface HudScene {
             left: number;
         };
     };
-    entities: unknown[];
+    entities: HudEntity[];
     metadata?: WorldScene['metadata'];
 }
 export type SceneFile = WorldScene | HudScene;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.27",
+  "version": "0.2.29",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",