@unboxy/phaser-sdk 0.2.44 → 0.2.45

package/SDK-GUIDE.md

@@ -1012,6 +1012,7 @@ footprint for characters, foundation for buildings).
 
 ## Changelog
 
+- **0.2.45** — fix: `isPerFrameHitbox` type guard tightened to check `default != null` rather than `'default' in h`. Closes a wire-shape gap from slice 8 v1.1 — the backend now writes explicit null values on the alternate shape's fields when a Hitbox PATCH switches modes (Single ↔ Per-frame), because OpenSearch's `_update` API deep-merges nested objects and would otherwise leave stale per-frame fields after a Single-mode save. Without this guard fix, the SDK's `applyAssetHitbox` would have treated the explicit-null `default: null` as "per-frame mode" via the `'in'` check and crashed when calling `applyShape(body, null)`. Pure SDK change — no API additions; only the guard's branch condition.
 - **0.2.44** — visual editor slice 8: depth + asymmetric collision. New fields `AssetRecord.hitbox` (single rect or per-frame overrides) + `AssetRecord.depthAnchor` (footprint pixel for Y-sort). New scene flag `WorldScene.ySort: boolean` (per-frame `setDepth(y)` hook). New SDK export `applyAssetHitbox(sprite, asset)` — silent no-op without metadata, dev-warn on missing body, idempotent `ANIMATION_UPDATE` listener install for per-frame variants. New type guard `isPerFrameHitbox`. Two new editor protocol messages — `unboxy:editor:assetUpdate { asset }` (broadcast hitbox/anchor edits to running iframe; re-applies to every spawned instance, no scene reload) + `unboxy:editor:setDebugOverlay { showHitboxes }` (toggle the EditorOverlayScene's per-frame hitbox + anchor draw). See "Collision + Y-sort" chapter. Pairs with: backend `PATCH /games/{id}/assets/{aid}/hitbox`, vision detection in pack import (character/tree/building/rock/decoration subjects), Hitbox Editor modal in home-ui, `asset-hitbox-physics` agent skill teaching the conditional rule.
 - **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`.

package/dist/scene/types.d.ts

@@ -205,6 +205,15 @@ export interface HitboxPerFrame {
  * Type guard — true when `hitbox` is the per-frame variant. Used by SDK
  * runtime to decide whether to install an `ANIMATION_UPDATE` listener that
  * swaps body shape per frame.
+ *
+ * <p>Checks `default != null` (handles both `null` and `undefined`) rather
+ * than `'default' in h`. The backend stores hitboxes after a mode switch
+ * with EXPLICIT NULLS on the alternate shape's fields — `{ kind: 'rect',
+ * x, y, w, h, default: null, frames: null }` for Single mode — because
+ * OpenSearch's _update API deep-merges nested objects and would otherwise
+ * leave stale fields. `'default' in h` would return true on that shape and
+ * trip the per-frame path with a null default. The null check is the
+ * correct discriminator.
  */
 export declare function isPerFrameHitbox(h: HitboxRect | HitboxPerFrame | undefined): h is HitboxPerFrame;
 /**

package/dist/scene/types.js

@@ -19,7 +19,16 @@ export function isPerFrameNinePatch(np) {
  * Type guard — true when `hitbox` is the per-frame variant. Used by SDK
  * runtime to decide whether to install an `ANIMATION_UPDATE` listener that
  * swaps body shape per frame.
+ *
+ * <p>Checks `default != null` (handles both `null` and `undefined`) rather
+ * than `'default' in h`. The backend stores hitboxes after a mode switch
+ * with EXPLICIT NULLS on the alternate shape's fields — `{ kind: 'rect',
+ * x, y, w, h, default: null, frames: null }` for Single mode — because
+ * OpenSearch's _update API deep-merges nested objects and would otherwise
+ * leave stale fields. `'default' in h` would return true on that shape and
+ * trip the per-frame path with a null default. The null check is the
+ * correct discriminator.
  */
 export function isPerFrameHitbox(h) {
-    return !!h && 'default' in h;
+    return !!h && h.default != null;
 }

package/package.json

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