@unboxy/phaser-sdk 0.2.16 → 0.2.18

package/dist/scene/spawnEntity.d.ts

@@ -0,0 +1,30 @@
+import Phaser from 'phaser';
+import { AssetRecord, WorldEntity } from './types.js';
+import { EntityRegistry } from './EntityRegistry.js';
+/**
+ * Resolves an asset id to its AssetRecord, throwing a clear error if the
+ * scene file references something the manifest doesn't know about. We
+ * surface this as an error (not a silent miss) because a missing asset
+ * means either the manifest is stale or the scene file was hand-edited
+ * — both worth catching at runtime, not skipping silently.
+ */
+export type AssetResolver = (assetId: string) => AssetRecord;
+/** Optional hook for `code-rendered` visuals. v1 throws if not provided. */
+export type RenderScriptResolver = (scriptPath: string) => ((g: Phaser.GameObjects.Graphics, params: Record<string, unknown>) => void) | undefined;
+export interface SpawnContext {
+    scene: Phaser.Scene;
+    registry: EntityRegistry;
+    resolveAsset: AssetResolver;
+    resolveRenderScript?: RenderScriptResolver;
+}
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export declare function spawnEntity(ctx: SpawnContext, entity: WorldEntity): Phaser.GameObjects.GameObject;
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export declare function parseColor(input: string): number;

package/dist/scene/spawnEntity.js

@@ -0,0 +1,136 @@
+/**
+ * Spawn one entity into the scene and register it. Returns the created
+ * GameObject so callers (notably `spawnEntity` itself, recursing on a
+ * group's children) can attach it to a parent container.
+ */
+export function spawnEntity(ctx, entity) {
+    let go;
+    switch (entity.kind) {
+        case 'sprite':
+            go = createSprite(ctx, entity);
+            break;
+        case 'primitive':
+            go = createPrimitive(ctx, entity);
+            break;
+        case 'group':
+            go = createGroup(ctx, entity);
+            break;
+        case 'code-rendered':
+            go = createCodeRendered(ctx, entity);
+            break;
+        case 'tilemap':
+            throw new Error(`[unboxy/scene] tilemap entity ('${entity.id}') not supported in slice 1 — see 06-tilemap.md`);
+        case 'trigger':
+            throw new Error(`[unboxy/scene] trigger entity ('${entity.id}') not supported in slice 1 — see 03-world-editor.md`);
+        default: {
+            const exhaustive = entity;
+            throw new Error(`[unboxy/scene] unknown entity kind: ${JSON.stringify(exhaustive)}`);
+        }
+    }
+    applyTransform(go, entity.transform);
+    tagGameObject(go, entity);
+    ctx.registry.register(entity.id, entity.role, go);
+    return go;
+}
+function createSprite(ctx, entity) {
+    const v = entity.visual;
+    const asset = ctx.resolveAsset(v.assetId);
+    // Phaser's add.sprite handles both plain images and atlas/spritesheet
+    // textures uniformly when given (key, frame). For plain images, frame
+    // is undefined and Phaser uses the default frame.
+    const sprite = ctx.scene.add.sprite(0, 0, asset.textureKey, v.frame);
+    if (v.tint)
+        sprite.setTint(parseColor(v.tint));
+    if (typeof v.alpha === 'number')
+        sprite.setAlpha(v.alpha);
+    if (v.flipX)
+        sprite.setFlipX(true);
+    if (v.flipY)
+        sprite.setFlipY(true);
+    return sprite;
+}
+function createPrimitive(ctx, entity) {
+    const v = entity.visual;
+    if (v.kind === 'rect')
+        return createRect(ctx, v);
+    if (v.kind === 'circle')
+        return createCircle(ctx, v);
+    const exhaustive = v;
+    throw new Error(`[unboxy/scene] unknown primitive kind: ${JSON.stringify(exhaustive)}`);
+}
+function createRect(ctx, v) {
+    const fill = v.fillColor ? parseColor(v.fillColor) : 0xffffff;
+    const rect = ctx.scene.add.rectangle(0, 0, v.width, v.height, fill);
+    if (v.strokeColor && v.strokeWidth) {
+        rect.setStrokeStyle(v.strokeWidth, parseColor(v.strokeColor));
+    }
+    if (typeof v.alpha === 'number')
+        rect.setAlpha(v.alpha);
+    return rect;
+}
+function createCircle(ctx, v) {
+    const fill = v.fillColor ? parseColor(v.fillColor) : 0xffffff;
+    const arc = ctx.scene.add.circle(0, 0, v.radius, fill);
+    if (v.strokeColor && v.strokeWidth) {
+        arc.setStrokeStyle(v.strokeWidth, parseColor(v.strokeColor));
+    }
+    if (typeof v.alpha === 'number')
+        arc.setAlpha(v.alpha);
+    return arc;
+}
+function createGroup(ctx, entity) {
+    const container = ctx.scene.add.container(0, 0);
+    for (const child of entity.children) {
+        if (child.kind === 'group') {
+            // v1 cap: groups can't nest. Surface a clear error rather than
+            // silently producing a half-attached hierarchy.
+            throw new Error(`[unboxy/scene] group '${entity.id}' has a nested group child '${child.id}' — v1 supports one level of nesting only`);
+        }
+        const childGo = spawnEntity(ctx, child);
+        container.add(childGo);
+    }
+    return container;
+}
+function createCodeRendered(ctx, entity) {
+    const render = ctx.resolveRenderScript?.(entity.visual.script);
+    if (!render) {
+        throw new Error(`[unboxy/scene] code-rendered entity '${entity.id}' references '${entity.visual.script}' but no render-script resolver was provided — render scripts land in a later slice (see 02-render-scripts.md)`);
+    }
+    const g = ctx.scene.add.graphics();
+    render(g, entity.visual.params ?? {});
+    return g;
+}
+function applyTransform(go, t) {
+    // Most game objects implement Transform; Container does too. Cast through
+    // a permissive shape so this works for sprite/rect/circle/container alike.
+    const target = go;
+    target.x = t.x;
+    target.y = t.y;
+    if (typeof t.rotation === 'number')
+        target.rotation = t.rotation;
+    if (typeof t.scaleX === 'number')
+        target.scaleX = t.scaleX;
+    if (typeof t.scaleY === 'number')
+        target.scaleY = t.scaleY;
+    if (typeof t.depth === 'number' && target.setDepth)
+        target.setDepth(t.depth);
+}
+function tagGameObject(go, entity) {
+    go.setData('entityId', entity.id);
+    if (entity.role)
+        go.setData('entityRole', entity.role);
+    if (entity.properties)
+        go.setData('entityProperties', entity.properties);
+}
+/**
+ * Accepts `'#rrggbb'`, `'rrggbb'`, or `'0xrrggbb'` and returns a number
+ * suitable for Phaser's color APIs.
+ */
+export function parseColor(input) {
+    const trimmed = input.trim();
+    if (trimmed.startsWith('#'))
+        return parseInt(trimmed.slice(1), 16);
+    if (trimmed.startsWith('0x'))
+        return parseInt(trimmed.slice(2), 16);
+    return parseInt(trimmed, 16);
+}

package/dist/scene/types.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Scene-as-data types — visual editor foundation (slice 1).
+ *
+ * Spec: unboxy-design/features/visual-editor/01-scene-data-foundation.md
+ *
+ * v1 schema (`schemaVersion: 1`) supports the entity kinds needed for the
+ * read-only scene viewer. HUD entity kinds, tilemap, trigger, and
+ * code-rendered visuals will land in later slices.
+ */
+export declare const SCHEMA_VERSION = 1;
+export type SceneType = 'world' | 'hud';
+export interface SceneRef {
+    id: string;
+    type: SceneType;
+    /** Path under `public/scenes/`, e.g. `"world/level-1-1.json"`. */
+    file: string;
+    /** Optional HUD scene id to overlay (world scenes only). Null = no HUD. */
+    hud?: string | null;
+}
+export interface HudRef {
+    id: string;
+    /** Path under `public/scenes/`, e.g. `"hud/game-hud.json"`. */
+    file: string;
+}
+/**
+ * Per-game asset table. Source of truth for asset id → Phaser textureKey
+ * resolution. The editor and runtime both read from this.
+ */
+export type AssetKind = 'image' | 'spritesheet' | 'atlas' | 'audio' | 'json';
+export interface AssetRecord {
+    /** Stable asset id used in scene files (`visual.assetId`). */
+    id: string;
+    /** Phaser texture / cache key. May equal `id` for simple cases. */
+    textureKey: string;
+    /** Path relative to `public/`. */
+    path: string;
+    kind: AssetKind;
+    /** For `spritesheet`: Phaser SpriteSheetConfig. */
+    spriteSheetConfig?: {
+        frameWidth: number;
+        frameHeight: number;
+        margin?: number;
+        spacing?: number;
+    };
+    /** For `atlas`: companion atlas file path (xml or json). */
+    atlasPath?: string;
+    /** `'xml'` (Starling) or `'json'` (TexturePacker). */
+    atlasFormat?: 'xml' | 'json';
+}
+export interface Manifest {
+    schemaVersion: number;
+    id: string;
+    title: string;
+    version: string;
+    initialScene: string;
+    scenes: SceneRef[];
+    huds: HudRef[];
+    assets: AssetRecord[];
+    globals?: {
+        physics?: {
+            gravity?: {
+                x?: number;
+                y?: number;
+            };
+        };
+        world?: {
+            pixelArt?: boolean;
+        };
+    };
+}
+export interface Transform {
+    x: number;
+    y: number;
+    /** Radians. */
+    rotation?: number;
+    scaleX?: number;
+    scaleY?: number;
+    depth?: number;
+}
+export type AnchorSide = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+export interface Anchor {
+    side: AnchorSide;
+    offsetX?: number;
+    offsetY?: number;
+}
+export interface SpriteVisual {
+    kind: 'sprite';
+    assetId: string;
+    /** Atlas frame name OR sprite-sheet frame index. */
+    frame?: string | number;
+    tint?: string;
+    alpha?: number;
+    flipX?: boolean;
+    flipY?: boolean;
+}
+export interface PrimitiveRectVisual {
+    kind: 'rect';
+    width: number;
+    height: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export interface PrimitiveCircleVisual {
+    kind: 'circle';
+    radius: number;
+    fillColor?: string;
+    strokeColor?: string | null;
+    strokeWidth?: number;
+    alpha?: number;
+}
+export type PrimitiveVisual = PrimitiveRectVisual | PrimitiveCircleVisual;
+export interface CodeRenderedVisual {
+    kind: 'code-rendered';
+    /** Path to render script, e.g. `"src/visuals/boss-renderer.ts"`. */
+    script: string;
+    params?: Record<string, unknown>;
+}
+export type WorldVisual = SpriteVisual | PrimitiveVisual | CodeRenderedVisual;
+export type WorldEntityKind = 'sprite' | 'primitive' | 'code-rendered' | 'group' | 'tilemap' | 'trigger';
+export interface WorldEntityBase {
+    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>;
+    transform: Transform;
+}
+export interface SpriteEntity extends WorldEntityBase {
+    kind: 'sprite';
+    visual: SpriteVisual;
+}
+export interface PrimitiveEntity extends WorldEntityBase {
+    kind: 'primitive';
+    visual: PrimitiveVisual;
+}
+export interface CodeRenderedEntity extends WorldEntityBase {
+    kind: 'code-rendered';
+    visual: CodeRenderedVisual;
+}
+export interface GroupEntity extends WorldEntityBase {
+    kind: 'group';
+    /**
+     * One level of nesting in v1: a child cannot itself be a `group`.
+     * If you need deeper hierarchy, the agent should flatten via the
+     * existing transform and add a role tag for grouping queries.
+     */
+    children: NonGroupWorldEntity[];
+}
+/**
+ * v1 placeholder — schema slot reserved so future slices can layer in
+ * tilemap/trigger without a schemaVersion bump. Loader currently throws
+ * on these kinds so an unmigrated game can't silently render nothing.
+ */
+export interface TilemapEntity extends WorldEntityBase {
+    kind: 'tilemap';
+    /** Opaque tilemap payload — defined in `06-tilemap.md`. */
+    data: unknown;
+}
+export interface TriggerEntity extends WorldEntityBase {
+    kind: 'trigger';
+    /** Opaque trigger payload — defined in `03-world-editor.md`. */
+    data: unknown;
+}
+export type NonGroupWorldEntity = SpriteEntity | PrimitiveEntity | CodeRenderedEntity | TilemapEntity | TriggerEntity;
+export type WorldEntity = NonGroupWorldEntity | GroupEntity;
+export interface CameraConfig {
+    /** Entity id to follow. Null = static camera. */
+    follow?: string | null;
+    smoothing?: number;
+    deadzone?: {
+        x: number;
+        y: number;
+    };
+    lookahead?: number;
+    bounds?: {
+        x: number;
+        y: number;
+        width: number;
+        height: number;
+    };
+    zoom?: number;
+    pixelPerfect?: boolean;
+    shakeDecay?: number;
+}
+export interface WorldSceneConfig {
+    width: number;
+    height: number;
+    background?: {
+        color?: string;
+    };
+    physics?: {
+        gravity?: {
+            x?: number;
+            y?: number;
+        };
+    };
+}
+export interface WorldScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'world';
+    world: WorldSceneConfig;
+    camera?: CameraConfig;
+    entities: WorldEntity[];
+    metadata?: {
+        tags?: string[];
+        author?: string;
+        createdAt?: string;
+        updatedAt?: string;
+    };
+}
+/**
+ * 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.
+ */
+export interface HudScene {
+    schemaVersion: number;
+    id: string;
+    name: string;
+    type: 'hud';
+    design?: {
+        designAspectRatio?: string;
+        safeArea?: {
+            top: number;
+            right: number;
+            bottom: number;
+            left: number;
+        };
+    };
+    entities: unknown[];
+    metadata?: WorldScene['metadata'];
+}
+export type SceneFile = WorldScene | HudScene;

package/dist/scene/types.js

@@ -0,0 +1,10 @@
+/**
+ * Scene-as-data types — visual editor foundation (slice 1).
+ *
+ * Spec: unboxy-design/features/visual-editor/01-scene-data-foundation.md
+ *
+ * v1 schema (`schemaVersion: 1`) supports the entity kinds needed for the
+ * read-only scene viewer. HUD entity kinds, tilemap, trigger, and
+ * code-rendered visuals will land in later slices.
+ */
+export const SCHEMA_VERSION = 1;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@unboxy/phaser-sdk",
-  "version": "0.2.16",
+  "version": "0.2.18",
   "description": "Unboxy Phaser 3 SDK — game infrastructure for the Unboxy platform",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -11,7 +11,8 @@
   "scripts": {
     "build": "tsc",
     "test": "npm run build && node --test scripts/test-chat-facade.mjs",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build && [ \"$UNBOXY_PUBLISH_VIA_SCRIPT\" = \"1\" ] || (echo '\\nERROR: do not run `npm publish` directly. Use ./publish.sh instead — it gates on the template-sync checklist.\\nSee CLAUDE.md \"Template sync — do not skip\".\\n' >&2 && exit 1)",
+    "release": "./publish.sh"
   },
   "dependencies": {
     "colyseus.js": "^0.16.0"