@unboxy/phaser-sdk 0.2.32 → 0.2.33

package/SDK-GUIDE.md

@@ -626,6 +626,181 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 **Edit mode (host-driven):** when the host (home-ui) sends `{ type: 'unboxy:setEditMode', enabled: true }` via `postMessage`, the SDK pauses every active non-Boot Phaser scene — entities stay rendered but `update`/physics/tweens stop. Sending `enabled: false` resumes. Used by the visual editor's read-only viewer in slice 1.
 
+## HUD scenes (visual editor slice 5+, since 0.2.29)
+
+A HUD scene is a separate `Phaser.Scene` that runs in parallel with the active world scene and renders anchor-positioned UI on top of it. The visual editor's `HUD` mode edits these. Five widget kinds ship today: **text**, **image**, **icon-button**, **progress-bar**, **panel**.
+
+### Manifest reference
+
+```json
+{
+  "scenes": [
+    { "id": "main", "type": "world", "file": "world/main.json", "hud": "game-hud" }
+  ],
+  "huds": [
+    { "id": "game-hud", "file": "hud/game-hud.json" }
+  ]
+}
+```
+
+When `loadWorldScene(this, sceneId)` runs, it auto-launches the `UnboxyHudScene` with the matching `hudId`. You don't call `loadHudScene` yourself — `loadWorldScene` does it for you. Multiple world scenes can reference the same HUD; editing `game-hud` updates every scene that points at it.
+
+### Scene file shape
+
+`public/scenes/hud/game-hud.json`:
+
+```json
+{
+  "schemaVersion": 1,
+  "id": "game-hud",
+  "name": "Game HUD",
+  "type": "hud",
+  "design": {
+    "designAspectRatio": "16:9",
+    "safeArea": { "top": 16, "right": 16, "bottom": 16, "left": 16 }
+  },
+  "entities": [ /* HudEntity[] */ ]
+}
+```
+
+### Anchor + offset positioning (no transform)
+
+HUD entities use a **9-grid anchor + numeric offset** instead of world coords:
+
+```json
+{
+  "id": "score-text",
+  "kind": "text",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 16 },
+  "layer": "base",
+  "visual": { "kind": "text", "source": { "mode": "static", "text": "Score: 0" } }
+}
+```
+
+`side` is one of `top-left | top | top-right | left | center | right | bottom-left | bottom | bottom-right`. The widget is anchored to that corner/edge of the canvas, then offset inward (or outward) by `offsetX/Y`. Resizing the canvas (orientation change, device rotation) re-resolves anchors automatically.
+
+`layer` is one of `base | overlay | modal` (default `base`) — controls render z-order; `modal` sits on top of `overlay` sits on top of `base`. `z` adds further ordering within a layer.
+
+### Widget reference
+
+#### `text`
+
+```json
+{
+  "kind": "text",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 16 },
+  "visual": {
+    "kind": "text",
+    "source": { "mode": "static", "text": "Hello" },
+    "fontSize": 24, "color": "#ffffff", "align": "left"
+  }
+}
+```
+
+`source` is either `{ mode: "static", text }` for a literal string OR `{ mode: "dynamic", binding, prefix?, suffix?, fallback? }` for a value read live from Phaser's game registry (see "Dynamic bindings" below).
+
+#### `image`
+
+```json
+{
+  "kind": "image",
+  "anchor": { "side": "top-right", "offsetX": -16, "offsetY": 16 },
+  "visual": { "kind": "image", "assetId": "coin-icon", "width": 32, "height": 32 }
+}
+```
+
+`assetId` resolves through `manifest.assets` exactly like world sprite entities. Optional `tint`, `alpha`, `frame` (atlas frame name or sprite-sheet index).
+
+#### `icon-button`
+
+```json
+{
+  "kind": "icon-button",
+  "anchor": { "side": "bottom-right", "offsetX": -32, "offsetY": -32 },
+  "layer": "overlay",
+  "visual": {
+    "kind": "icon-button",
+    "label": "Pause", "shape": "rounded-rect",
+    "width": 96, "height": 48,
+    "fillColor": "#3b82f6", "textColor": "#ffffff",
+    "iconAssetId": null
+  }
+}
+```
+
+Click handler is decoupled — the SDK emits a Phaser scene event `'hud:press'` with the entity id when the button is pressed. Subscribe in your gameplay code:
+
+```ts
+// In GameScene.ts (or any active scene)
+this.events.on('hud:press', (id: string) => {
+  if (id === 'pause-button') { this.scene.pause(); /* etc. */ }
+});
+```
+
+For now there's no built-in action binding (no `behavior: { type: 'pause-game' }` etc.) — you wire each button by its id explicitly. That's coming in a later slice.
+
+#### `progress-bar`
+
+```json
+{
+  "kind": "progress-bar",
+  "anchor": { "side": "top-left", "offsetX": 16, "offsetY": 50 },
+  "visual": {
+    "kind": "progress-bar",
+    "value": { "mode": "dynamic", "binding": "playerHp", "fallback": 0 },
+    "max":   { "mode": "dynamic", "binding": "playerMaxHp", "fallback": 100 },
+    "width": 200, "height": 16,
+    "fillColor": "#22c55e", "backgroundColor": "#0f172a",
+    "borderRadius": 4, "borderColor": "#ffffff", "borderWidth": 1
+  }
+}
+```
+
+`value` and `max` are independently bindable — either can be static (`{ mode: 'static', value: 100 }`) or dynamic. Bar fills from 0 → 1 as `value / max`. Subscribes to `changedata-<binding>` registry events and redraws on change.
+
+#### `panel`
+
+```json
+{
+  "kind": "panel",
+  "anchor": { "side": "center" },
+  "visual": {
+    "kind": "panel",
+    "width": 320, "height": 200,
+    "backgroundColor": "#000000", "backgroundAlpha": 0.5,
+    "borderColor": "#ffffff", "borderWidth": 1, "borderRadius": 8
+  }
+}
+```
+
+A colored rectangle with optional border + rounded corners. Use as a visual frame behind groups of HUD widgets (no children layout in v1 — child widgets are sibling entities; you align them with anchor + offset).
+
+### Dynamic bindings — driving the HUD from gameplay
+
+For values that change during play (score, HP, timer, lives), use **Phaser's game registry** as the bridge. The HUD widget references a `binding` key; gameplay code calls `this.registry.set(key, value)` and the HUD auto-refreshes.
+
+```ts
+// In GameScene.ts create():
+this.registry.set('score', 0);
+this.registry.set('playerHp', 100);
+this.registry.set('playerMaxHp', 100);
+
+// Wherever score changes:
+this.registry.set('score', this.score + 10);
+```
+
+The HUD widget's text / progress fill updates synchronously on the next frame — no manual `setText` / re-render call needed. Registry is `game.registry` under the hood, shared across all scenes.
+
+**Pick stable, lowercase keys**: `score`, `coins`, `playerHp`, `lives`, `currentLevel`, `xp`. The binding key goes into a `changedata-<key>` event name; spaces or special characters break it.
+
+**No declare ceremony**: just `set` the key. The HUD picks it up. The `unboxy.gameData` module is for *persistent* shared values (across sessions); for in-game reactive HUD, registry is the right tool.
+
+### Editor mode (for visual-editor users only)
+
+The visual editor's `World/HUD` toggle pauses the active world scene and lets the user drag widgets / edit anchor + offset / live-tune visual fields. Edits flow back to `public/scenes/hud/<id>.json` on save (Cmd+S / Edit→Play / Publish). Auto-save during editing only persists JSON to disk — no rebuild — so the iframe doesn't reload mid-edit.
+
+For game code, the editor is invisible — you write HUD scene JSON the same way regardless of whether the user uses the editor.
+
 ## Anti-patterns (don't do these)
 
 - Do **not** call `Unboxy.init()` inside a scene. Initialize at module load in `main.ts` and export the promise.
@@ -638,6 +813,17 @@ The `scene-data-architecture` agent skill has the full guidance. The `scene-data
 
 ## Changelog
 
+- **0.2.33** — docs: HUD scenes chapter added to this guide (covers slice-5 widget kinds, anchor model, dynamic bindings via `scene.registry`, `hud:press` event). Existing workspaces pick this up via `npm update @unboxy/phaser-sdk`.
+- **0.2.32** — fix: 9-grid anchor side change in the visual editor moved container-based widgets (icon-button, progress-bar, panel) far from the new corner. `applyHudPatch` now re-applies the origin shift that compensates for containers having no `setOrigin`.
+- **0.2.31** — fix: progress-bar and panel widgets drew their Graphics rect from `(0, 0)` instead of centered, so the visual was offset by `(w/2, h/2)` from the editor's selection rect. Both now draw centered.
+- **0.2.30** — added HUD `progress-bar` and `panel` widgets (visual editor slice 5.5). progress-bar supports independent static/dynamic `value` and `max` bindings; panel is a colored rectangle with optional border + rounded corners. New types: `HudProgressBarVisual`, `HudPanelVisual`, `HudNumberSource`. See "HUD scenes" chapter above.
+- **0.2.29** — added HUD scene runtime (visual editor slice 5). New module `src/scene/HudRuntime.ts` exporting `UnboxyHudScene`, `loadHudScene`, `spawnHudEntity`, `resolveAnchor`. Three v1 widget kinds: `text` (static or dynamic), `image`, `icon-button`. Auto-launched by `loadWorldScene` when `manifest.scenes[].hud` is set. Dynamic bindings hook into Phaser's game registry. Editor protocol gains `unboxy:editor:setEditMode { mode: 'world' \| 'hud' }`. See "HUD scenes" chapter above.
+- **0.2.28** — fix: `EditorBridge.computeScreenRect` was multiplying by `Phaser.Scale.ScaleManager.displayScale.x` which is `gameSize / canvasBoundsSize` (the inverse of what the variable name suggests), so coords ballooned out of the iframe. Now measures CSS-to-logical scale directly via `canvas.getBoundingClientRect()`.
+- **0.2.27** — added `EditorSelectionRectMessage` (visual editor slice 4 — inline AI popover). SDK posts `unboxy:editor:selectionRect { entityId, rect }` on selection change / drag-end / pan-zoom; rect is in iframe-relative pixels. Used by home-ui to anchor a floating ✨ button next to the selected entity for entity-scoped AI prompts.
+- **0.2.26** — fix: tilemap entities couldn't be selected in the editor. `spawnEntity` for `tilemap` now sets explicit hit-test bounds (Phaser Graphics has no intrinsic size).
+- **0.2.25** — fix: Backspace / Delete in the editor didn't remove selected entities once focus was inside the iframe. The overlay scene now catches bare Backspace/Delete and posts `action: 'delete'` to the host.
+- **0.2.24** — fix: re-dragging an already-in-manifest asset spawned an unrendered entity. `createEntity` resolver now falls back to the cached `manifest.json` when the host omits `manifestAsset`.
+- **0.2.23** — fix: code-rendered entities couldn't be selected/dragged in the editor. `spawnEntity` now sets explicit Graphics size (Phaser Graphics returns 0×0 from `getBounds()` otherwise). Schema gains optional `visual.width` / `visual.height`.
 - **0.2.22** — render-script registry wired (visual editor slice 3.5). `createUnboxyGame` accepts a new `renderScripts: Record<path, RenderScriptModule>` option; templates build it via `import.meta.glob('./visuals/*.ts', { eager: true })`. `loadWorldScene` falls back to that registry when no explicit `resolveRenderScript` is passed, so games don't have to plumb it through every scene call. Missing scripts no longer crash the scene boot — `spawnEntity` renders a clear orange-bordered "?" placeholder instead and tags the GameObject with `renderScriptMissing` for debug. `applyEdit` now handles `visual.params` patches on `code-rendered` entities by re-calling render with merged params (live editor preview as you tune in the Inspector). New exports: `RenderScriptModule`, `setRenderScriptRegistry`, `getRenderScriptRegistry`, `resolveRenderScript`. Pairs with the `phaser-render-script` agent skill which teaches the pure-function contract.
 - **0.2.21** — visual editor slice 3 (drag-to-place). Formalized trigger + tilemap entity data shapes (TriggerEntity now has `shape: rect|circle`, `description`, `targets[]`; TilemapEntity has `tileSize`, `size`, `layers[]`). spawnEntity renders both as placeholders (trigger = semi-transparent cyan rect/circle, tilemap = translucent grid sketch — full features ship in slices 5+6). New protocol: `unboxy:editor:createEntity { entity, manifestAsset? }` (host-side drag-to-place spawns entity at world coord; lazy-loads asset texture if needed) + `unboxy:editor:deleteEntity { entityId }` (Backspace + undo of create). `sceneLoaded` now also carries the manifest snapshot so home-ui can mutate the asset table when a new asset gets dropped on the canvas.
 - **0.2.20** — added editor shortcut forwarding (Cmd+Z/Y/S land in iframe when canvas focused; SDK posts back to host via `unboxy:editor:shortcut`). Without this, native shortcuts didn't reach the host's keydown listener after the user clicked the canvas.

package/package.json

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