@umicat/phaser-sdk 1.0.7 → 1.0.8

package/dist/index.d.ts

@@ -39,5 +39,5 @@ export { setupEditorBridge } from './editor/EditorBridge.js';
 export { EditorOverlayScene, EDITOR_OVERLAY_KEY } from './editor/EditorOverlayScene.js';
 export type { EditorEntityPatch, EditorEnterMessage, EditorExitMessage, EditorGetSceneMessage, EditorApplyEditMessage, EditorSetSelectionMessage, EditorPanZoomMessage, EditorHostToSdkMessage, EditorSceneLoadedMessage, EditorSelectionPickedMessage, EditorDragEndMessage, EditorShortcutMessage, EditorCreateEntityMessage, EditorDeleteEntityMessage, EditorSetEditModeMessage, EditorSelectionRectMessage, EditorSdkToHostMessage, } from './protocol.js';
 export { SCHEMA_VERSION, isPerFrameNinePatch, isPerFrameHitbox, } from './scene/types.js';
-export type { Manifest, ManifestGroup, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } from './scene/types.js';
+export type { Manifest, ManifestGroup, SceneRef, HudRef, AssetRecord, AssetKind, SceneType, SceneFile, WorldScene, HudScene, WorldSceneConfig, CameraConfig, WorldEntity, WorldEntityKind, NonGroupWorldEntity, RenderableEntity, SpriteEntity, RectEntity, CircleEntity, CodeRenderedEntity, GroupEntity, TilemapEntity, TilemapLayer, TilesetMetadata, TileMetadata, TilesetAutotile, TilesetAnimation, WangTerrain, TriggerEntity, PrefabRefEntity, TriggerShape, HudEntity, HudEntityKind, HudEntityBase, HudTextEntity, HudImageEntity, HudIconButtonEntity, HudProgressBarEntity, HudPanelEntity, HudTextSource, HudNumberSource, HudLayer, Transform, Anchor, AnchorSide, NinePatchConfig, NinePatchPerFrame, HitboxRect, HitboxPerFrame, DepthAnchor, } from './scene/types.js';
 export { PROTOCOL_VERSION, type HelloMessage, type InitMessage, type RpcRequestMessage, type RpcResultOk, type RpcResultError, type HostToSdkMessage, type SdkToHostMessage, type RpcErrorPayload, type RpcMethod, type SavesGetParams, type SavesGetResult, type SavesSetParams, type SavesSetResult, type SavesDeleteParams, type SavesDeleteResult, type SavesListResult, type GameDataGetParams, type GameDataGetResult, type GameDataSetParams, type GameDataSetResult, type GameDataDeleteParams, type GameDataDeleteResult, type GameDataListResult, type RealtimeGetTokenParams, type RealtimeGetTokenResult, } from './protocol.js';

package/dist/scene/SceneLoader.js

@@ -78,7 +78,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
     if (sceneFile.type !== 'world')
         return; // HUD slice will add its own walker
     const state = getOrInitState(scene, manifest);
-    const ids = collectAssetIds(sceneFile.entities);
+    const ids = collectAssetIds(sceneFile.entities, manifest);
     for (const id of ids) {
         if (state.requestedAssetIds.has(id))
             continue;
@@ -98,7 +98,7 @@ export function preloadSceneAssets(scene, sceneFile, manifest) {
         state.requestedAssetIds.add(id);
     }
 }
-function collectAssetIds(entities) {
+function collectAssetIds(entities, manifest) {
     const ids = new Set();
     function walk(e) {
         if (e.kind === 'sprite') {
@@ -119,6 +119,14 @@ function collectAssetIds(entities) {
                     ids.add(id);
             }
         }
+        else if (e.kind === 'prefab-ref') {
+            // Authored prefab instance — preload whatever the prefab's visual
+            // references (sprite prefabs carry an assetId at the record root).
+            const prefab = manifest?.prefabs?.find((p) => p.id === e.prefabId);
+            const assetId = prefab?.assetId;
+            if (typeof assetId === 'string')
+                ids.add(assetId);
+        }
         // rect / circle / code-rendered / trigger don't reference assets.
     }
     for (const e of entities)

package/dist/scene/spawnEntity.js

@@ -30,6 +30,14 @@ export function spawnEntity(ctx, entity) {
         case 'trigger':
             go = createTriggerStub(ctx, entity);
             break;
+        case 'prefab-ref':
+            // Authored prefab INSTANCE (editor "Convert to Type" / drag-from-Types,
+            // 2026-06-12). Resolve the prefab record, build a synthetic entity at
+            // this instance's transform, and recurse — the inner call creates the
+            // GameObject, applies the prefab's physics, tags, and registers under
+            // THIS entity's id. We then re-tag kind + prefabId below.
+            go = createPrefabRefInstance(ctx, entity);
+            break;
         default: {
             const exhaustive = entity;
             throw new Error(`[umicat/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
@@ -38,9 +46,71 @@ export function spawnEntity(ctx, entity) {
     applyTransform(go, entity.transform);
     tagGameObject(go, entity);
     applyEntityPhysicsIfDeclared(ctx.scene, go, entity);
+    if (entity.kind === 'prefab-ref') {
+        // Tag for editor live-edit: `umicat:editor:editPrefab` walks instances
+        // via this data key, and canvas clicks route to the Prefab inspector
+        // (editing one instance = editing the type). Registry re-registers with
+        // the prefabId so byPrefabId() finds authored instances too.
+        go.setData('entityPrefabId', entity.prefabId);
+        ctx.registry.unregister(entity.id);
+        ctx.registry.register(entity.id, entity.role ?? prefabRoleOf(ctx.scene, entity.prefabId), go, entity.prefabId);
+        return go;
+    }
     ctx.registry.register(entity.id, entity.role, go);
     return go;
 }
+/**
+ * Read a prefab record straight from the cached manifest. Deliberately NOT
+ * importing SceneLoader's getManifest — that module imports this one, and
+ * keeping the read inline avoids the import cycle.
+ */
+function lookupPrefab(scene, prefabId) {
+    const manifest = scene.cache.json.get('umicat:manifest');
+    const prefab = manifest?.prefabs?.find((p) => p.id === prefabId);
+    return prefab ?? null;
+}
+function prefabRoleOf(scene, prefabId) {
+    const prefab = lookupPrefab(scene, prefabId);
+    return prefab?.role ?? undefined;
+}
+function createPrefabRefInstance(ctx, entity) {
+    const prefab = lookupPrefab(ctx.scene, entity.prefabId);
+    if (!prefab) {
+        console.warn(`[umicat/scene] prefab-ref '${entity.id}' references prefab '${entity.prefabId}' but the manifest has no such prefab; rendering placeholder`);
+        return createMissingPlaceholder(ctx.scene, `prefab: ${entity.prefabId}?`);
+    }
+    // Synthetic entity = prefab fields + this instance's id/transform. Instance
+    // role/properties override the prefab's when set (per-instance variance
+    // without breaking the type link).
+    const synthetic = {
+        ...prefab,
+        id: entity.id,
+        transform: entity.transform,
+        ...(entity.role !== undefined ? { role: entity.role } : {}),
+        ...(entity.properties !== undefined
+            ? { properties: { ...(prefab.properties ?? {}), ...entity.properties } }
+            : {}),
+    };
+    if (synthetic.kind === 'prefab-ref') {
+        // A prefab record can never be kind prefab-ref, but guard against a
+        // hand-edited manifest producing infinite recursion.
+        console.warn(`[umicat/scene] prefab '${entity.prefabId}' has invalid kind 'prefab-ref'`);
+        return createMissingPlaceholder(ctx.scene, `prefab: ${entity.prefabId}?`);
+    }
+    return spawnEntity(ctx, synthetic);
+}
+/** Magenta-bordered "?" placeholder — same soft-fail pattern as missing assets. */
+function createMissingPlaceholder(scene, label) {
+    const g = scene.add.graphics();
+    g.lineStyle(2, 0xff00ff, 1);
+    g.strokeRect(-32, -32, 64, 64);
+    g.lineBetween(-32, -32, 32, 32);
+    g.lineBetween(-32, 32, 32, -32);
+    g.setData('editorHitWidth', 64);
+    g.setData('editorHitHeight', 64);
+    void label;
+    return g;
+}
 /**
  * Apply a scene entity's optional `physics` block. Only renderable entity
  * kinds (sprite / rect / circle / code-rendered) carry a body — they mirror

package/dist/scene/types.d.ts

@@ -753,7 +753,7 @@ export interface Anchor {
     offsetX?: number;
     offsetY?: number;
 }
-export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';
+export type WorldEntityKind = 'sprite' | 'rect' | 'circle' | 'code-rendered' | 'group' | 'tilemap' | 'trigger' | 'prefab-ref';
 export interface WorldEntityBase {
     id: string;
     /** Optional semantic tag. Behavior code keys off this. */
@@ -913,7 +913,23 @@ export interface TriggerEntity extends WorldEntityBase {
     /** Optional preset name (open-door / damage-zone / scene-transition / spawner / heal). */
     preset?: string;
 }
-export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
+/**
+ * Authored INSTANCE of a prefab — the Figma component/instance model
+ * brought to scene data (editor "Convert to Type" + drag-from-Types,
+ * 2026-06-12). The scene stores only "which type + where"; every render /
+ * physics / properties field comes from the prefab record at spawn time,
+ * so editing the prefab updates every placed instance across all scenes.
+ *
+ * Unlike `spawnPrefab` runtime instances (`<prefabId>#<n>` ids, created by
+ * behavior code), prefab-refs are scene-file entities: they appear in the
+ * editor Hierarchy, are draggable (transform lives here), and persist.
+ * `role` defaults to the prefab's role; an explicit role here overrides.
+ */
+export interface PrefabRefEntity extends WorldEntityBase {
+    kind: 'prefab-ref';
+    prefabId: string;
+}
+export type NonGroupWorldEntity = SpriteEntity | RectEntity | CircleEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity | PrefabRefEntity;
 export type WorldEntity = NonGroupWorldEntity | GroupEntity;
 /**
  * Renderable entity kinds — those that produce a single GameObject with

package/package.json

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