@vgai/engine 0.2.0 → 0.3.0

package/dist/world2d/scene2d-loader.js

@@ -0,0 +1,274 @@
+import { CompositeTilemap } from '@pixi/tilemap';
+import { AnimatedSprite, Assets, BlurFilter, ColorMatrixFilter, Container, Sprite, Text, Texture, } from 'pixi.js';
+import { SceneParseError } from '../scene/parse';
+import { Scene2DSchema } from './schema/entity2d';
+const BLEND = {
+    normal: 'normal',
+    add: 'add',
+    multiply: 'multiply',
+    screen: 'screen',
+};
+function hexToNum(hex, fallback) {
+    if (!hex)
+        return fallback;
+    return Number.parseInt(hex.replace('#', ''), 16);
+}
+/** Generate N asset-light frame textures (a moving accent dot) for an AnimatedSprite. */
+function generateFrames(count, w, h, tint) {
+    const frames = [];
+    for (let i = 0; i < count; i++) {
+        const canvas = document.createElement('canvas');
+        canvas.width = w;
+        canvas.height = h;
+        const g = canvas.getContext('2d');
+        g.fillStyle = tint;
+        g.fillRect(0, 0, w, h);
+        g.fillStyle = '#10101a';
+        const t = (i / count) * Math.PI * 2;
+        g.beginPath();
+        g.arc(w / 2 + Math.cos(t) * w * 0.25, h / 2 + Math.sin(t) * h * 0.25, Math.min(w, h) * 0.18, 0, Math.PI * 2);
+        g.fill();
+        frames.push(Texture.from(canvas));
+    }
+    return frames;
+}
+function applyFilter(display, filter) {
+    if (!filter || filter === 'none')
+        return;
+    if (filter === 'blur')
+        display.filters = [new BlurFilter({ strength: 6 })];
+    else if (filter === 'desaturate') {
+        const cm = new ColorMatrixFilter();
+        cm.desaturate();
+        display.filters = [cm];
+    }
+}
+/** Instantiate a PIXI.Sprite / AnimatedSprite from authored `sprite` data. */
+async function createSprite(data) {
+    let display;
+    if (data.animationFrames && data.animationFrames > 1) {
+        const frames = generateFrames(data.animationFrames, data.width ?? 40, data.height ?? 40, data.tint ?? '#ffffff');
+        const anim = new AnimatedSprite(frames);
+        anim.animationSpeed = (data.fps ?? 8) / 60;
+        anim.play();
+        display = anim;
+    }
+    else {
+        let texture = Texture.WHITE;
+        if (data.texture) {
+            const loaded = await Assets.load(data.texture);
+            texture =
+                data.frame && loaded?.textures?.[data.frame]
+                    ? loaded.textures[data.frame]
+                    : loaded;
+        }
+        display = new Sprite(texture);
+    }
+    const [ax, ay] = data.anchor ?? [0.5, 0.5];
+    display.anchor.set(ax, ay);
+    if (data.width !== undefined)
+        display.width = data.width;
+    if (data.height !== undefined)
+        display.height = data.height;
+    if (!data.animationFrames)
+        display.tint = hexToNum(data.tint, 0xffffff);
+    if (data.alpha !== undefined)
+        display.alpha = data.alpha;
+    if (data.blendMode)
+        display.blendMode = BLEND[data.blendMode] ?? 'normal';
+    if (data.interactive) {
+        display.eventMode = 'static';
+        display.cursor = 'pointer';
+    }
+    applyFilter(display, data.filter);
+    return display;
+}
+/** Instantiate a @pixi/tilemap CompositeTilemap from authored `tilemap` data. */
+function createTilemap(data) {
+    // Generate one tile texture per palette color (asset-light).
+    const textures = data.palette.map((color) => {
+        const c = document.createElement('canvas');
+        c.width = data.tileSize;
+        c.height = data.tileSize;
+        const g = c.getContext('2d');
+        g.fillStyle = color;
+        g.fillRect(0, 0, data.tileSize, data.tileSize);
+        g.strokeStyle = 'rgba(0,0,0,0.18)';
+        g.strokeRect(0.5, 0.5, data.tileSize - 1, data.tileSize - 1);
+        return Texture.from(c);
+    });
+    const tilemap = new CompositeTilemap();
+    for (let y = 0; y < data.tiles.length; y++) {
+        const row = data.tiles[y];
+        for (let x = 0; x < row.length; x++) {
+            const tex = textures[row[x]];
+            if (tex)
+                tilemap.tile(tex, x * data.tileSize, y * data.tileSize);
+        }
+    }
+    return tilemap;
+}
+/** Instantiate a PIXI.Text from authored `text` data (world-space label). */
+function createText(data) {
+    const text = new Text({
+        text: data.text,
+        style: { fontSize: data.fontSize ?? 24, fill: data.fill ?? '#ffffff' },
+    });
+    const [ax, ay] = data.anchor ?? [0.5, 0.5];
+    text.anchor.set(ax, ay);
+    return text;
+}
+/** Map the bodyType enum to a Rapier 2D RigidBodyDesc. */
+function bodyDesc(rapier2d, type) {
+    switch (type) {
+        case 'fixed':
+            return rapier2d.RigidBodyDesc.fixed();
+        case 'kinematicVelocity':
+            return rapier2d.RigidBodyDesc.kinematicVelocityBased();
+        case 'kinematicPosition':
+            return rapier2d.RigidBodyDesc.kinematicPositionBased();
+        default:
+            return rapier2d.RigidBodyDesc.dynamic();
+    }
+}
+/** Create the Rapier 2D body + collider for an entity, register it, return the body. */
+// biome-ignore lint/complexity/noExcessiveCognitiveComplexity: one cohesive physics2d-descriptor builder; each branch maps an optional authored field to a Rapier setter
+function createPhysics2D(ctx, entity, display) {
+    const p = entity.physics2d;
+    if (!p)
+        return;
+    const { rapier2d, rapier2dWorld, physics2d } = ctx;
+    const pos = entity.transform2d?.position ?? [0, 0];
+    const rbDesc = bodyDesc(rapier2d, p.bodyType)
+        .setTranslation(pos[0], pos[1])
+        .setRotation(entity.transform2d?.rotation ?? 0);
+    if (p.linearDamping !== undefined)
+        rbDesc.setLinearDamping(p.linearDamping);
+    if (p.gravityScale !== undefined)
+        rbDesc.setGravityScale(p.gravityScale);
+    if (p.lockRotations)
+        rbDesc.lockRotations();
+    const body = rapier2dWorld.createRigidBody(rbDesc);
+    let colDesc;
+    const c = p.collider;
+    if (c.shape === 'cuboid')
+        colDesc = rapier2d.ColliderDesc.cuboid(c.halfExtents[0], c.halfExtents[1]);
+    else if (c.shape === 'ball')
+        colDesc = rapier2d.ColliderDesc.ball(c.radius);
+    else
+        colDesc = rapier2d.ColliderDesc.capsule(c.halfHeight, c.radius);
+    if (p.density !== undefined)
+        colDesc.setDensity(p.density);
+    if (p.friction !== undefined)
+        colDesc.setFriction(p.friction);
+    if (p.restitution !== undefined)
+        colDesc.setRestitution(p.restitution);
+    if (p.sensor) {
+        colDesc.setSensor(true);
+        colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);
+    }
+    else {
+        colDesc.setActiveEvents(rapier2d.ActiveEvents.COLLISION_EVENTS);
+    }
+    const collider = rapier2dWorld.createCollider(colDesc, body);
+    physics2d.add(display, body, collider);
+}
+/** Hydrate the `components` field — schema.parse + Object.assign + attach (2D analog of applyComponents).
+ *  `manager` is the unified `ComponentManager` (`ecs/component-manager.ts`), constructed
+ *  for kind `'pixijs'` — the world2d silo manager this replaced (T7.3) is deleted. */
+function applyComponents2D(registry, display, components, manager) {
+    if (!components)
+        return;
+    for (const [name, data] of Object.entries(components)) {
+        const Cls = registry[name];
+        if (!Cls)
+            throw new Error(`Unknown world2d component: "${name}"`);
+        const parsed = Cls.schema ? Cls.schema.parse(data ?? {}) : (data ?? {});
+        const instance = new Cls();
+        Object.assign(instance, parsed);
+        // T5.4: record the registry name + raw authored data — same reasoning as
+        // the 3D `applyComponents` (`scene/component-registry.ts`).
+        manager.attach(display, instance, { key: name, props: data ?? {} });
+    }
+}
+/** Apply a 2D transform to a display object. */
+function applyTransform2D(display, entity) {
+    const t = entity.transform2d;
+    if (t?.position)
+        display.position.set(t.position[0], t.position[1]);
+    if (t?.rotation !== undefined)
+        display.rotation = t.rotation;
+    if (t?.scale)
+        display.scale.set(t.scale[0], t.scale[1]);
+    const pivot = t?.pivot ?? entity.pivot;
+    if (pivot)
+        display.pivot.set(pivot[0], pivot[1]);
+    if (entity.visible === false)
+        display.visible = false;
+}
+let _autoId = 0;
+/**
+ * Load a world2d scene from authored data — the 2D analog of `loadSceneFromData`.
+ * Three passes: (1) spawn all entities (recursing into children), building an
+ * id→display map and creating Rapier 2D bodies; (2) [no joints in 2D yet];
+ * (3) `componentManager.initAll()` once everything exists.
+ *
+ * Re-validates `data` even though the fetch path (`fetchScene2DFile` in
+ * `packages/editor/src/adapter-resolver.ts`) already validates before calling
+ * in — not every caller goes through that path (test-constructed
+ * `PixiSceneConfig.sceneData` literals reach here unvalidated), so a malformed
+ * payload still throws a `SceneParseError` naming the file, not a raw
+ * `ZodError` (T4.6 convention, closing §7.1-14). `sourceName` is optional
+ * because not every caller knows the originating file path; callers that do
+ * (or gain the ability to) should thread it through for a better message.
+ */
+export async function loadScene2DFromData(data, ctx, registry, sourceName) {
+    const result = Scene2DSchema.safeParse(data);
+    if (!result.success)
+        throw new SceneParseError(result.error.issues, sourceName);
+    const scene = result.data;
+    const byId = new Map();
+    const roots = [];
+    async function spawn(entity, parent) {
+        let display;
+        if (entity.sprite)
+            display = await createSprite(entity.sprite);
+        else if (entity.text)
+            display = createText(entity.text);
+        else if (entity.tilemap)
+            display = createTilemap(entity.tilemap);
+        else
+            display = new Container();
+        display.label = entity.name;
+        const id = entity.id ?? `e2d_${_autoId++}`;
+        display.__entityId = id;
+        byId.set(id, display);
+        applyTransform2D(display, entity);
+        parent.addChild(display);
+        // Physics bodies live in world space (flat under the world container); the
+        // transform-writer drives their pose. Components attach to the display.
+        createPhysics2D(ctx, entity, display);
+        applyComponents2D(registry, display, entity.components, ctx.components);
+        if (entity.children) {
+            for (const child of entity.children)
+                await spawn(child, display);
+        }
+        return display;
+    }
+    for (const entity of scene.entities) {
+        roots.push(await spawn(entity, ctx.stage));
+    }
+    await ctx.components.initAll();
+    return {
+        roots,
+        byId,
+        dispose() {
+            for (const root of roots) {
+                root.removeFromParent();
+                root.destroy({ children: true });
+            }
+            roots.length = 0;
+            byId.clear();
+        },
+    };
+}

package/dist/world2d/schema/entity2d.d.ts

@@ -0,0 +1,102 @@
+import { z } from 'zod';
+/**
+ * A world2d entity — the 2D analog of the 3D `SceneEntity`. The SAME engine model
+ * (named components validated against a registry, a tree of children) reused; the
+ * sections (`sprite`/`text`/`physics2d`/`transform2d`) name engine-owned data, NOT
+ * `PIXI.Sprite`. `surface` defaults to 'world2d' for entities in a Scene2D file.
+ */
+declare const Entity2DBase: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    name: z.ZodString;
+    surface: z.ZodOptional<z.ZodEnum<{
+        world2d: "world2d";
+        world3d: "world3d";
+    }>>;
+    visible: z.ZodOptional<z.ZodBoolean>;
+    locked: z.ZodOptional<z.ZodBoolean>;
+    tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    transform2d: z.ZodOptional<z.ZodObject<{
+        position: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        rotation: z.ZodOptional<z.ZodNumber>;
+        scale: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        pivot: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    pivot: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    sprite: z.ZodOptional<z.ZodObject<{
+        texture: z.ZodOptional<z.ZodString>;
+        frame: z.ZodOptional<z.ZodString>;
+        anchor: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+        tint: z.ZodOptional<z.ZodString>;
+        alpha: z.ZodOptional<z.ZodNumber>;
+        width: z.ZodOptional<z.ZodNumber>;
+        height: z.ZodOptional<z.ZodNumber>;
+        blendMode: z.ZodOptional<z.ZodEnum<{
+            normal: "normal";
+            screen: "screen";
+            add: "add";
+            multiply: "multiply";
+        }>>;
+        interactive: z.ZodOptional<z.ZodBoolean>;
+        filter: z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            blur: "blur";
+            desaturate: "desaturate";
+        }>>;
+        animationFrames: z.ZodOptional<z.ZodNumber>;
+        fps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strip>>;
+    text: z.ZodOptional<z.ZodObject<{
+        text: z.ZodString;
+        fontSize: z.ZodOptional<z.ZodNumber>;
+        fill: z.ZodOptional<z.ZodString>;
+        anchor: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    }, z.core.$strip>>;
+    tilemap: z.ZodOptional<z.ZodObject<{
+        tileSize: z.ZodNumber;
+        palette: z.ZodArray<z.ZodString>;
+        tiles: z.ZodArray<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>>;
+    physics2d: z.ZodOptional<z.ZodObject<{
+        bodyType: z.ZodEnum<{
+            fixed: "fixed";
+            dynamic: "dynamic";
+            kinematicVelocity: "kinematicVelocity";
+            kinematicPosition: "kinematicPosition";
+        }>;
+        collider: z.ZodDiscriminatedUnion<[z.ZodObject<{
+            shape: z.ZodLiteral<"cuboid">;
+            halfExtents: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+        }, z.core.$strip>, z.ZodObject<{
+            shape: z.ZodLiteral<"ball">;
+            radius: z.ZodNumber;
+        }, z.core.$strip>, z.ZodObject<{
+            shape: z.ZodLiteral<"capsule">;
+            halfHeight: z.ZodNumber;
+            radius: z.ZodNumber;
+        }, z.core.$strip>], "shape">;
+        sensor: z.ZodOptional<z.ZodBoolean>;
+        density: z.ZodOptional<z.ZodNumber>;
+        friction: z.ZodOptional<z.ZodNumber>;
+        restitution: z.ZodOptional<z.ZodNumber>;
+        linearDamping: z.ZodOptional<z.ZodNumber>;
+        gravityScale: z.ZodOptional<z.ZodNumber>;
+        lockRotations: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    components: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodNumber, z.ZodString, z.ZodBoolean]>, z.ZodArray<z.ZodNumber>, z.ZodArray<z.ZodString>, z.ZodArray<z.ZodBoolean>]>>>>;
+}, z.core.$strip>;
+export type Entity2D = z.infer<typeof Entity2DBase> & {
+    children?: Entity2D[] | undefined;
+};
+export declare const Entity2DSchema: z.ZodType<Entity2D>;
+/** A world2d scene file — the 2D analog of `.vscn.json` (`.scn2d.json`). */
+export declare const Scene2DSchema: z.ZodObject<{
+    version: z.ZodOptional<z.ZodNumber>;
+    name: z.ZodOptional<z.ZodString>;
+    surface: z.ZodOptional<z.ZodLiteral<"world2d">>;
+    gravity: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    background: z.ZodOptional<z.ZodString>;
+    entities: z.ZodArray<z.ZodType<Entity2D, unknown, z.core.$ZodTypeInternals<Entity2D, unknown>>>;
+}, z.core.$strip>;
+export type Scene2DFile = z.infer<typeof Scene2DSchema>;
+export {};
+//# sourceMappingURL=entity2d.d.ts.map

package/dist/world2d/schema/entity2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity2d.d.ts","sourceRoot":"","sources":["../../../src/world2d/schema/entity2d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAiBxB;;;;;GAKG;AACH,QAAA,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;iBAmChB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,GAAG;IACpD,QAAQ,CAAC,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC;CACnC,CAAC;AAEF,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,OAAO,CAAC,QAAQ,CA6CvB,CAAC;AAEzB,4EAA4E;AAC5E,eAAO,MAAM,aAAa;;;;;;;iBA8B4B,CAAC;AAEvD,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/world2d/schema/entity2d.js

@@ -0,0 +1,119 @@
+import { z } from 'zod';
+import { Physics2DSchema } from './physics2d';
+import { SpriteSchema, Text2DSchema } from './sprite';
+import { TilemapSchema } from './tilemap';
+import { Transform2DSchema, Vec2Schema } from './tuples2d';
+/** Component data: same shape as the 3D ComponentsSchema (scalars + scalar arrays). */
+const ComponentScalarSchema = z.union([z.number(), z.string(), z.boolean()]);
+const ComponentValueSchema = z.union([
+    ComponentScalarSchema,
+    z.array(z.number()),
+    z.array(z.string()),
+    z.array(z.boolean()),
+]);
+const ComponentDataSchema = z.record(z.string(), ComponentValueSchema);
+const ComponentsSchema = z.record(z.string(), ComponentDataSchema);
+/**
+ * A world2d entity — the 2D analog of the 3D `SceneEntity`. The SAME engine model
+ * (named components validated against a registry, a tree of children) reused; the
+ * sections (`sprite`/`text`/`physics2d`/`transform2d`) name engine-owned data, NOT
+ * `PIXI.Sprite`. `surface` defaults to 'world2d' for entities in a Scene2D file.
+ */
+const Entity2DBase = z.object({
+    id: z.string().optional().describe('Unique entity ID. Auto-generated if omitted'),
+    name: z.string().describe('Human-readable entity name (shown in hierarchy panel)'),
+    surface: z
+        .enum(['world2d', 'world3d'])
+        .optional()
+        .describe("Render surface that instantiates this entity. Default 'world2d' in a Scene2D file. The " +
+        "'world3d' value is REJECTED at parse (T4.1): declared but has no runtime reader — " +
+        "authoring surface: 'world3d' throws. Do not author it ('world2d', the default, is fine)."),
+    visible: z.boolean().optional().describe('Whether the entity and its children are rendered'),
+    locked: z
+        .boolean()
+        .optional()
+        .describe('Prevent selection and editing in the scene editor. REJECTED at parse (T4.1): declared ' +
+        'but has no runtime reader — authoring this field throws. Do not author.'),
+    tags: z
+        .array(z.string())
+        .optional()
+        .describe('Arbitrary string tags for runtime queries. REJECTED at parse (T4.1): declared but has no ' +
+        'runtime reader — authoring this field throws. Do not author.'),
+    transform2d: Transform2DSchema.optional().describe('Local 2D transform relative to parent'),
+    pivot: Vec2Schema.optional().describe('Local-space pivot point [x, y]'),
+    sprite: SpriteSchema.optional().describe('2D sprite appearance'),
+    text: Text2DSchema.optional().describe('World-space text label'),
+    tilemap: TilemapSchema.optional().describe('2D tilemap (CompositeTilemap)'),
+    physics2d: Physics2DSchema.optional().describe('2D physics rigid body + collider'),
+    components: ComponentsSchema.optional().describe('User-defined components (validated against the world2d component registry)'),
+});
+export const Entity2DSchema = z.lazy(() => Entity2DBase.extend({
+    children: z.array(Entity2DSchema).optional().describe('Child entities'),
+})
+    // T4.1: three fields are authored/typed but have no runtime reader in
+    // `scene2d-loader.ts`'s `spawn()` (unlike their 3D `SceneEntity` siblings,
+    // which ARE read — editor selection-locking for `locked`, `scene-query.ts`
+    // for `tags`):
+    //   - `locked` — spawn() never checks it (no 2D editor selection-lock yet).
+    //   - `tags` — never copied onto userData; no 2D equivalent of scene-query.ts.
+    //   - `surface: 'world3d'` — spawn() always instantiates as world2d
+    //     regardless of this field's value, so a 'world3d' entity is silently
+    //     spawned into the 2D world anyway. ('world2d', the default, is a
+    //     harmless no-op and is not flagged.)
+    // Loud load errors until readers exist — see T4.1.
+    .superRefine((entity, ctx) => {
+    if (entity.locked !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `world2d entity "${entity.name}": \`locked\` is authored but not implemented — ` +
+                'scene2d-loader.ts has no 2D editor selection-lock reader yet. See T4.1.',
+            path: ['locked'],
+        });
+    }
+    if (entity.tags !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `world2d entity "${entity.name}": \`tags\` is authored but not implemented — ` +
+                'no 2D equivalent of scene-query.ts reads it yet. See T4.1.',
+            path: ['tags'],
+        });
+    }
+    if (entity.surface === 'world3d') {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `world2d entity "${entity.name}": \`surface: 'world3d'\` is authored but not ` +
+                'implemented — spawn() always instantiates entities as world2d regardless of this ' +
+                'field, so a world3d entity would be silently spawned into the 2D world. See T4.1.',
+            path: ['surface'],
+        });
+    }
+}));
+/** A world2d scene file — the 2D analog of `.vscn.json` (`.scn2d.json`). */
+export const Scene2DSchema = z
+    .object({
+    version: z.number().optional().describe('Scene format version'),
+    name: z
+        .string()
+        .optional()
+        .describe('Scene name. REJECTED at parse (T4.1): declared but has no runtime reader — authoring ' +
+        'this field throws. Do not author.'),
+    surface: z.literal('world2d').optional().describe("Render surface. Always 'world2d'"),
+    gravity: Vec2Schema.optional().describe('World gravity [x, y] in px/s^2. Default [0, 980]'),
+    background: z.string().optional().describe("Background color hex string. Default '#10101a'"),
+    entities: z.array(Entity2DSchema).describe('Root entities of the world2d scene'),
+})
+    // T4.1: `name` is authored/typed but has no runtime reader anywhere (unlike
+    // `SceneFile.name`/`PrefabFile.name`, which the editor reads via
+    // `editor-store.ts`'s `sceneName` getter/setter) — no 2D scene-name display
+    // exists yet. Loud load error until a reader exists — see T4.1.
+    .superRefine((scene, ctx) => {
+    if (scene.name !== undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: '`name` is authored but not implemented — no runtime reader displays/consumes a ' +
+                'world2d scene name yet (unlike SceneFile.name). See T4.1.',
+            path: ['name'],
+        });
+    }
+})
+    .describe('A world2d scene (PixiJS render surface)');

package/dist/world2d/schema/physics2d.d.ts

@@ -0,0 +1,46 @@
+import { z } from 'zod';
+/** A single 2D collider shape (Rapier 2D). Cuboid takes 2 half-extents; ball a radius. */
+export declare const Collider2DSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    shape: z.ZodLiteral<"cuboid">;
+    halfExtents: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+}, z.core.$strip>, z.ZodObject<{
+    shape: z.ZodLiteral<"ball">;
+    radius: z.ZodNumber;
+}, z.core.$strip>, z.ZodObject<{
+    shape: z.ZodLiteral<"capsule">;
+    halfHeight: z.ZodNumber;
+    radius: z.ZodNumber;
+}, z.core.$strip>], "shape">;
+export type SceneCollider2D = z.infer<typeof Collider2DSchema>;
+/**
+ * `physics2d` authored section — engine-owned 2D physics data, instantiated as a
+ * Rapier 2D RigidBody + Collider. The world2d analog of the 3D `physics` section.
+ */
+export declare const Physics2DSchema: z.ZodObject<{
+    bodyType: z.ZodEnum<{
+        fixed: "fixed";
+        dynamic: "dynamic";
+        kinematicVelocity: "kinematicVelocity";
+        kinematicPosition: "kinematicPosition";
+    }>;
+    collider: z.ZodDiscriminatedUnion<[z.ZodObject<{
+        shape: z.ZodLiteral<"cuboid">;
+        halfExtents: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+    }, z.core.$strip>, z.ZodObject<{
+        shape: z.ZodLiteral<"ball">;
+        radius: z.ZodNumber;
+    }, z.core.$strip>, z.ZodObject<{
+        shape: z.ZodLiteral<"capsule">;
+        halfHeight: z.ZodNumber;
+        radius: z.ZodNumber;
+    }, z.core.$strip>], "shape">;
+    sensor: z.ZodOptional<z.ZodBoolean>;
+    density: z.ZodOptional<z.ZodNumber>;
+    friction: z.ZodOptional<z.ZodNumber>;
+    restitution: z.ZodOptional<z.ZodNumber>;
+    linearDamping: z.ZodOptional<z.ZodNumber>;
+    gravityScale: z.ZodOptional<z.ZodNumber>;
+    lockRotations: z.ZodOptional<z.ZodBoolean>;
+}, z.core.$strip>;
+export type ScenePhysics2D = z.infer<typeof Physics2DSchema>;
+//# sourceMappingURL=physics2d.d.ts.map

package/dist/world2d/schema/physics2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"physics2d.d.ts","sourceRoot":"","sources":["../../../src/world2d/schema/physics2d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,0FAA0F;AAC1F,eAAO,MAAM,gBAAgB;;;;;;;;;;4BAgBe,CAAC;AAE7C,MAAM,MAAM,eAAe,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,gBAAgB,CAAC,CAAC;AAE/D;;;GAGG;AACH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;iBAsBwC,CAAC;AAErE,MAAM,MAAM,cAAc,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,eAAe,CAAC,CAAC"}

package/dist/world2d/schema/physics2d.js

@@ -0,0 +1,45 @@
+import { z } from 'zod';
+import { Vec2Schema } from './tuples2d';
+/** A single 2D collider shape (Rapier 2D). Cuboid takes 2 half-extents; ball a radius. */
+export const Collider2DSchema = z
+    .discriminatedUnion('shape', [
+    z.object({
+        shape: z.literal('cuboid').describe('Axis-aligned box collider'),
+        halfExtents: Vec2Schema.describe('Half-width and half-height [hx, hy] in pixels'),
+    }),
+    z.object({
+        shape: z.literal('ball').describe('Circle collider'),
+        radius: z.number().describe('Radius in pixels'),
+    }),
+    z.object({
+        shape: z.literal('capsule').describe('Capsule collider (vertical)'),
+        halfHeight: z.number().describe('Half the straight segment length'),
+        radius: z.number().describe('Cap radius'),
+    }),
+])
+    .describe('2D collider shape (Rapier 2D)');
+/**
+ * `physics2d` authored section — engine-owned 2D physics data, instantiated as a
+ * Rapier 2D RigidBody + Collider. The world2d analog of the 3D `physics` section.
+ */
+export const Physics2DSchema = z
+    .object({
+    bodyType: z
+        .enum(['dynamic', 'fixed', 'kinematicVelocity', 'kinematicPosition'])
+        .describe('Rapier 2D rigid-body type'),
+    collider: Collider2DSchema.describe('Collider shape attached to the body'),
+    sensor: z
+        .boolean()
+        .optional()
+        .describe('If true, a sensor (trigger) collider — overlaps fire onTriggerEnter/Exit, no solid response'),
+    density: z.number().optional().describe('Collider density (drives mass). Default 1'),
+    friction: z.number().optional().describe('Coefficient of friction. Default 0.5'),
+    restitution: z.number().optional().describe('Bounciness 0..1. Default 0'),
+    linearDamping: z.number().optional().describe('Linear velocity damping. Default 0'),
+    gravityScale: z.number().optional().describe('Per-body gravity multiplier. Default 1'),
+    lockRotations: z
+        .boolean()
+        .optional()
+        .describe('Lock the body so it cannot rotate. Default false'),
+})
+    .describe('2D physics rigid body + collider (world2d, Rapier 2D)');

package/dist/world2d/schema/sprite.d.ts

@@ -0,0 +1,42 @@
+import { z } from 'zod';
+/**
+ * `sprite` authored section — engine-owned 2D sprite data, NOT a `PIXI.Sprite`.
+ *
+ * Per ARCHITECTURE.md §Render Surfaces: authored data says `sprite`, and a runtime
+ * adapter instantiates it onto the appropriate backend (here, a `PIXI.Sprite` on
+ * the world2d surface). A 1x1 white texture is used when `texture` is omitted, so a
+ * tinted rectangle sprite needs no asset.
+ */
+export declare const SpriteSchema: z.ZodObject<{
+    texture: z.ZodOptional<z.ZodString>;
+    frame: z.ZodOptional<z.ZodString>;
+    anchor: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+    tint: z.ZodOptional<z.ZodString>;
+    alpha: z.ZodOptional<z.ZodNumber>;
+    width: z.ZodOptional<z.ZodNumber>;
+    height: z.ZodOptional<z.ZodNumber>;
+    blendMode: z.ZodOptional<z.ZodEnum<{
+        normal: "normal";
+        screen: "screen";
+        add: "add";
+        multiply: "multiply";
+    }>>;
+    interactive: z.ZodOptional<z.ZodBoolean>;
+    filter: z.ZodOptional<z.ZodEnum<{
+        none: "none";
+        blur: "blur";
+        desaturate: "desaturate";
+    }>>;
+    animationFrames: z.ZodOptional<z.ZodNumber>;
+    fps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+export type SceneSprite = z.infer<typeof SpriteSchema>;
+/** `text` authored section — a world-space PIXI.Text label (world-space UI). */
+export declare const Text2DSchema: z.ZodObject<{
+    text: z.ZodString;
+    fontSize: z.ZodOptional<z.ZodNumber>;
+    fill: z.ZodOptional<z.ZodString>;
+    anchor: z.ZodOptional<z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>>;
+}, z.core.$strip>;
+export type SceneText2D = z.infer<typeof Text2DSchema>;
+//# sourceMappingURL=sprite.d.ts.map

package/dist/world2d/schema/sprite.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sprite.d.ts","sourceRoot":"","sources":["../../../src/world2d/schema/sprite.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;iBA6CqE,CAAC;AAE/F,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAEvD,gFAAgF;AAChF,eAAO,MAAM,YAAY;;;;;iBAOsD,CAAC;AAEhF,MAAM,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC"}