@vgai/engine 0.2.0

package/src/world2d/scene2d-loader.ts

@@ -0,0 +1,308 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import { CompositeTilemap } from '@pixi/tilemap';
+import {
+  AnimatedSprite,
+  Assets,
+  BlurFilter,
+  ColorMatrixFilter,
+  Container,
+  Sprite,
+  Text,
+  Texture,
+} from 'pixi.js';
+import type { ComponentManager } from '../ecs/component-manager';
+import { SceneParseError } from '../scene/parse';
+import { type Entity2D, type Scene2DFile, Scene2DSchema } from './schema/entity2d';
+import type { SceneSprite, SceneText2D } from './schema/sprite';
+import type { SceneTilemap } from './schema/tilemap';
+import type { Component2DRegistry, World2DContext } from './types';
+
+const BLEND: Record<string, 'normal' | 'add' | 'multiply' | 'screen'> = {
+  normal: 'normal',
+  add: 'add',
+  multiply: 'multiply',
+  screen: 'screen',
+};
+
+function hexToNum(hex: string | undefined, fallback: number): number {
+  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: number, w: number, h: number, tint: string): Texture[] {
+  const frames: Texture[] = [];
+  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: Sprite | AnimatedSprite, filter: string | undefined): void {
+  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: SceneSprite): Promise<Sprite | AnimatedSprite> {
+  let display: Sprite | AnimatedSprite;
+  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 = Texture.WHITE;
+    if (data.texture) {
+      const loaded = await Assets.load(data.texture);
+      texture =
+        data.frame && loaded?.textures?.[data.frame]
+          ? loaded.textures[data.frame]
+          : (loaded as Texture);
+    }
+    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: SceneTilemap): CompositeTilemap {
+  // 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: SceneText2D): Text {
+  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: typeof RAPIER, type: string): RAPIER.RigidBodyDesc {
+  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: World2DContext, entity: Entity2D, display: Container): void {
+  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: RAPIER.ColliderDesc;
+  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: Component2DRegistry,
+  display: Container,
+  components: Record<string, Record<string, unknown>> | undefined,
+  manager: ComponentManager,
+): void {
+  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: Container, entity: Entity2D): void {
+  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;
+
+/** A loaded world2d scene instance: the root display objects + an update/dispose. */
+export interface Scene2DInstance {
+  roots: Container[];
+  /** id → display object map for editor/lookup (the 2D analog of the loader's entity map). */
+  byId: Map<string, Container>;
+  dispose(): void;
+}
+
+/**
+ * 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: Scene2DFile,
+  ctx: World2DContext,
+  registry: Component2DRegistry,
+  sourceName?: string,
+): Promise<Scene2DInstance> {
+  const result = Scene2DSchema.safeParse(data);
+  if (!result.success) throw new SceneParseError(result.error.issues, sourceName);
+  const scene = result.data;
+  const byId = new Map<string, Container>();
+  const roots: Container[] = [];
+
+  async function spawn(entity: Entity2D, parent: Container): Promise<Container> {
+    let display: Container;
+    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 as Container & { __entityId?: string }).__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/src/world2d/schema/entity2d.ts

@@ -0,0 +1,145 @@
+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 type Entity2D = z.infer<typeof Entity2DBase> & {
+  children?: Entity2D[] | undefined;
+};
+
+export const Entity2DSchema: z.ZodType<Entity2D> = 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'],
+        });
+      }
+    }),
+) as z.ZodType<Entity2D>;
+
+/** 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)');
+
+export type Scene2DFile = z.infer<typeof Scene2DSchema>;

package/src/world2d/schema/physics2d.ts

@@ -0,0 +1,53 @@
+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)');
+
+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 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)');
+
+export type ScenePhysics2D = z.infer<typeof Physics2DSchema>;

package/src/world2d/schema/sprite.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+import { Vec2Schema } from './tuples2d';
+
+/**
+ * `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 const SpriteSchema = z
+  .object({
+    texture: z
+      .string()
+      .optional()
+      .describe(
+        'Texture asset URL (loaded via PIXI.Assets). Omit for a tintable 1x1 white texture',
+      ),
+    frame: z
+      .string()
+      .optional()
+      .describe('Spritesheet frame/sub-texture name when `texture` is a spritesheet atlas'),
+    anchor: Vec2Schema.optional().describe('Normalized anchor [x, y] (0..1). Default [0.5, 0.5]'),
+    tint: z
+      .string()
+      .optional()
+      .describe("Tint color as hex string (e.g. '#ff8800'). Default white"),
+    alpha: z.number().min(0).max(1).optional().describe('Opacity 0..1. Default 1'),
+    width: z
+      .number()
+      .optional()
+      .describe('Explicit display width in pixels (overrides texture size)'),
+    height: z
+      .number()
+      .optional()
+      .describe('Explicit display height in pixels (overrides texture size)'),
+    blendMode: z
+      .enum(['normal', 'add', 'multiply', 'screen'])
+      .optional()
+      .describe('PixiJS blend mode. Default normal'),
+    interactive: z
+      .boolean()
+      .optional()
+      .describe('Enable federated pointer events (eventMode=static) so this sprite can be picked'),
+    filter: z
+      .enum(['none', 'blur', 'desaturate'])
+      .optional()
+      .describe('Apply a PixiJS filter (BlurFilter / ColorMatrix desaturate). Default none'),
+    animationFrames: z
+      .number()
+      .int()
+      .optional()
+      .describe('If set, build an AnimatedSprite cycling N generated tinted frames'),
+    fps: z.number().optional().describe('AnimatedSprite playback speed in frames/sec. Default 8'),
+  })
+  .describe('2D sprite appearance (world2d). Instantiated as a PIXI.Sprite or AnimatedSprite');
+
+export type SceneSprite = z.infer<typeof SpriteSchema>;
+
+/** `text` authored section — a world-space PIXI.Text label (world-space UI). */
+export const Text2DSchema = z
+  .object({
+    text: z.string().describe('The string to display'),
+    fontSize: z.number().optional().describe('Font size in pixels. Default 24'),
+    fill: z.string().optional().describe("Text color as hex string. Default '#ffffff'"),
+    anchor: Vec2Schema.optional().describe('Normalized anchor [x, y] (0..1). Default [0.5, 0.5]'),
+  })
+  .describe('2D world-space text label (world2d). Instantiated as a PIXI.Text');
+
+export type SceneText2D = z.infer<typeof Text2DSchema>;

package/src/world2d/schema/tilemap.ts

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+
+/**
+ * `tilemap` authored section — engine-owned 2D tilemap data (NOT a CompositeTilemap),
+ * instantiated to a `@pixi/tilemap` CompositeTilemap by the 2D spawn path. Asset-light:
+ * a `palette` of hex colors generates one tile texture each, and `tiles` is a row-major
+ * grid of palette indices. A real tileset texture/Tiled `.tmj` import is the natural
+ * extension (per the spec's optional Tiled note).
+ */
+export const TilemapSchema = z
+  .object({
+    tileSize: z.number().describe('Tile width/height in pixels'),
+    palette: z
+      .array(z.string())
+      .describe('Hex colors; one generated tile texture per entry (index → color)'),
+    tiles: z
+      .array(z.array(z.number().int()))
+      .describe('Row-major grid of palette indices (each row is an array of tile indices)'),
+  })
+  .describe('2D tilemap (world2d). Instantiated as a @pixi/tilemap CompositeTilemap');
+
+export type SceneTilemap = z.infer<typeof TilemapSchema>;

package/src/world2d/schema/tuples2d.ts

@@ -0,0 +1,25 @@
+import { z } from 'zod';
+
+/** 2D vector as [x, y]. The world2d analog of the 3D Vec3. */
+export const Vec2Schema = z.tuple([z.number(), z.number()]).describe('2D vector as [x, y]');
+
+export type Vec2 = z.infer<typeof Vec2Schema>;
+
+/**
+ * 2D local transform — the world2d analog of the 3D TransformSchema.
+ *
+ * Orientation is a single scalar `rotation` (radians, about the screen Z axis),
+ * NOT a quaternion: PixiJS display objects rotate in the plane. The runtime/editor
+ * neutral `Transform` tuple (position[3]/quaternion[4]/scale[3]) maps onto this as
+ * z = 0 and rotation about Z (see PIXI-WORLD2D-MAXIMAL-SPEC model-transform2d-section).
+ */
+export const Transform2DSchema = z
+  .object({
+    position: Vec2Schema.optional().describe('Local position [x, y] in world2d pixels'),
+    rotation: z.number().optional().describe('Rotation in radians about the Z axis. Default 0'),
+    scale: Vec2Schema.optional().describe('Scale per axis [x, y]. Default [1, 1]'),
+    pivot: Vec2Schema.optional().describe('Local pivot point [x, y] (center of rotation/scale)'),
+  })
+  .describe('2D local transform relative to parent (world2d surface)');
+
+export type SceneTransform2D = z.infer<typeof Transform2DSchema>;

package/src/world2d/system-adapters-2d.ts

@@ -0,0 +1,49 @@
+import type { Container } from 'pixi.js';
+import type { Physics2DRegistry } from './physics2d-registry';
+
+/**
+ * PhysicsAdapter2D — the world2d analog of the 3D PhysicsAdapter (rapier-physics-adapter).
+ * Lets the editor coordinate editing of a Rapier-2D-driven entity WITHOUT owning the
+ * simulation: report transform ownership, then freeze → commit → unfreeze so a drag
+ * sticks instead of being stomped by the next physics step.
+ */
+export interface PhysicsAdapter2D {
+  ownerOf(display: Container): 'physics' | 'none';
+  freeze(display: Container): void;
+  commit(display: Container, position: [number, number], rotation: number): void;
+  unfreeze(display: Container): void;
+}
+
+export function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapter2D {
+  // Remember each frozen body's prior type so unfreeze restores it.
+  const frozen = new WeakMap<Container, number>();
+  return {
+    ownerOf(display) {
+      const refs = physics.get(display);
+      if (!refs) return 'none';
+      return refs.body.isDynamic() || refs.body.isKinematic() ? 'physics' : 'none';
+    },
+    freeze(display) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      frozen.set(display, refs.body.bodyType());
+      // Kinematic-position bodies hold a pose without being driven by forces.
+      refs.body.setBodyType(2 /* KinematicPositionBased */, true);
+    },
+    commit(display, position, rotation) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      refs.body.setTranslation({ x: position[0], y: position[1] }, true);
+      refs.body.setRotation(rotation, true);
+    },
+    unfreeze(display) {
+      const refs = physics.get(display);
+      if (!refs) return;
+      const prior = frozen.get(display);
+      if (prior !== undefined) {
+        refs.body.setBodyType(prior, true);
+        frozen.delete(display);
+      }
+    },
+  };
+}