@vgai/engine 0.4.1 → 0.5.0-canary.20260719.0

package/src/world2d/scene2d-loader.ts

@@ -1,5 +1,6 @@
 import type RAPIER from '@dimforge/rapier2d-compat';
 import { CompositeTilemap } from '@pixi/tilemap';
+import type { Ticker } from 'pixi.js';
 import {
   AnimatedSprite,
   Assets,
@@ -12,6 +13,12 @@ import {
 } from 'pixi.js';
 import type { ComponentManager } from '../ecs/component-manager';
 import { SceneParseError } from '../scene/parse';
+import {
+  assertMovingPhysicsParent2D,
+  computePhysicsPose2D,
+  scaleCollider2D,
+} from './physics2d-transform';
+import { resolveScene2DEntityIds } from './scene2d-identity';
 import { type Entity2D, type Scene2DFile, Scene2DSchema } from './schema/entity2d';
 import type { SceneSprite, SceneText2D } from './schema/sprite';
 import type { SceneTilemap } from './schema/tilemap';
@@ -24,37 +31,39 @@ const BLEND: Record<string, 'normal' | 'add' | 'multiply' | 'screen'> = {
   screen: 'screen',
 };
 
+// Pixi implements Sprite width/height by mutating native scale. Keep that
+// implementation scale separate from authored transform2d.scale so the visual
+// and its pixel-authored collider compose the same way.
+const spriteBaseScales = new WeakMap<Container, readonly [number, number]>();
+const tilemapTextures = new WeakMap<CompositeTilemap, readonly Texture[]>();
+
+/** Native atlas sub-textures retained for source-backed tile painting. */
+export function getSceneTilemapTextures2D(display: Container): readonly Texture[] | null {
+  return display instanceof CompositeTilemap ? (tilemapTextures.get(display) ?? null) : null;
+}
+
+/** Refresh the native Sprite sizing scale after an authoring operation writes
+ * `display.width`/`height` from new source dimensions. The next authored
+ * transform application multiplies this base by transform2d.scale exactly once. */
+export function captureSceneSpriteBaseScale2D(
+  display: Container,
+  axes: { x: boolean; y: boolean } = { x: true, y: true },
+  authoredScale: readonly [number, number] = [1, 1],
+): void {
+  const previous = spriteBaseScales.get(display) ?? [display.scale.x, display.scale.y];
+  const authoredSignX = authoredScale[0] < 0 ? -1 : 1;
+  const authoredSignY = authoredScale[1] < 0 ? -1 : 1;
+  spriteBaseScales.set(display, [
+    axes.x ? display.scale.x * authoredSignX : previous[0],
+    axes.y ? display.scale.y * authoredSignY : previous[1],
+  ]);
+}
+
 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 })];
@@ -65,36 +74,30 @@ function applyFilter(display: Sprite | AnimatedSprite, filter: string | undefine
   }
 }
 
-/** 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);
+type LoadedSpriteAsset = Texture & {
+  animations?: Record<string, Texture[]>;
+  textures?: Record<string, Texture>;
+};
+
+function createAnimatedSprite(data: SceneSprite, loaded: LoadedSpriteAsset): AnimatedSprite {
+  const frames = loaded.animations?.[data.animation!];
+  if (!frames?.length) {
+    throw new Error(`Spritesheet "${data.texture}" does not contain animation "${data.animation}"`);
   }
+  const display = new AnimatedSprite({ autoUpdate: false, textures: frames });
+  display.animationSpeed = (data.fps ?? 8) / 60;
+  display.loop = data.loop ?? true;
+  display.play();
+  return display;
+}
+
+function applySpriteAppearance(display: Sprite | AnimatedSprite, data: SceneSprite): void {
   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);
+  captureSceneSpriteBaseScale2D(display);
+  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) {
@@ -102,29 +105,51 @@ async function createSprite(data: SceneSprite): Promise<Sprite | AnimatedSprite>
     display.cursor = 'pointer';
   }
   applyFilter(display, data.filter);
+}
+
+function resolveStaticSpriteTexture(
+  data: SceneSprite,
+  loaded: LoadedSpriteAsset | undefined,
+): Texture {
+  if (!loaded) return Texture.WHITE;
+  if (!data.frame) return loaded as Texture;
+  const frame = loaded.textures?.[data.frame];
+  if (!frame) {
+    throw new Error(`Spritesheet "${data.texture}" does not contain frame "${data.frame}"`);
+  }
+  return frame;
+}
+
+/** Instantiate a PIXI.Sprite / AnimatedSprite from authored `sprite` data. */
+async function createSprite(data: SceneSprite): Promise<Sprite | AnimatedSprite> {
+  const loaded = data.texture
+    ? ((await Assets.load(data.texture)) as LoadedSpriteAsset)
+    : undefined;
+  const display = data.animation
+    ? createAnimatedSprite(data, loaded!)
+    : new Sprite(resolveStaticSpriteTexture(data, loaded));
+  applySpriteAppearance(display, data);
   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);
+/** Instantiate a @pixi/tilemap CompositeTilemap from a native Pixi atlas. */
+async function createTilemap(data: SceneTilemap): Promise<CompositeTilemap> {
+  const loaded = (await Assets.load(data.texture)) as LoadedSpriteAsset;
+  const textures = data.frames.map((frame) => {
+    const texture = loaded.textures?.[frame];
+    if (!texture) {
+      throw new Error(`Spritesheet "${data.texture}" does not contain tile frame "${frame}"`);
+    }
+    return texture;
   });
   const tilemap = new CompositeTilemap();
+  tilemapTextures.set(tilemap, textures);
   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);
+      const index = row[x]!;
+      if (index === -1) continue;
+      tilemap.tile(textures[index]!, x * data.tileSize, y * data.tileSize);
     }
   }
   return tilemap;
@@ -155,28 +180,62 @@ function bodyDesc(rapier2d: typeof RAPIER, type: string): RAPIER.RigidBodyDesc {
   }
 }
 
-/** 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 {
+interface MovingPhysicsAncestor2D {
+  bodyType: string;
+  name: string;
+}
+
+function entityLabel(entity: Entity2D): string {
+  return entity.id ? `${entity.name} (id: "${entity.id}")` : entity.name;
+}
+
+function isMovingBodyType(bodyType: string): boolean {
+  return bodyType !== 'fixed';
+}
+
+/** Create the Rapier 2D body + collider for an entity and register it. */
+function createPhysics2D(
+  ctx: World2DContext,
+  entity: Entity2D,
+  display: Container,
+  movingAncestor: MovingPhysicsAncestor2D | undefined,
+): void {
   const p = entity.physics2d;
   if (!p) return;
   const { rapier2d, rapier2dWorld, physics2d } = ctx;
-  const pos = entity.transform2d?.position ?? [0, 0];
+  const label = entityLabel(entity);
+  if (movingAncestor) {
+    throw new Error(
+      `world2d physics entity "${label}" has a "${p.bodyType}" body nested under ` +
+        `"${movingAncestor.name}", which has a moving "${movingAncestor.bodyType}" body. ` +
+        'Rapier has no parent/child body relationship, so a moving ancestor cannot carry ' +
+        'another physics body. Move the nested body out of that hierarchy or make the ' +
+        'ancestor fixed.',
+    );
+  }
+  if (isMovingBodyType(p.bodyType)) assertMovingPhysicsParent2D(display, ctx.stage, label);
+  const pose = computePhysicsPose2D(entity, display, ctx.stage, label);
+  const colliderShape = scaleCollider2D(p.collider, pose.scale, label);
 
   const rbDesc = bodyDesc(rapier2d, p.bodyType)
-    .setTranslation(pos[0], pos[1])
-    .setRotation(entity.transform2d?.rotation ?? 0);
+    .setTranslation(pose.position[0], pose.position[1])
+    .setRotation(pose.rotation);
   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 (colliderShape.shape === 'cuboid') {
+    colDesc = rapier2d.ColliderDesc.cuboid(
+      colliderShape.halfExtents[0],
+      colliderShape.halfExtents[1],
+    );
+  } else if (colliderShape.shape === 'ball') {
+    colDesc = rapier2d.ColliderDesc.ball(colliderShape.radius);
+  } else {
+    colDesc = rapier2d.ColliderDesc.capsule(colliderShape.halfHeight, colliderShape.radius);
+  }
 
   if (p.density !== undefined) colDesc.setDensity(p.density);
   if (p.friction !== undefined) colDesc.setFriction(p.friction);
@@ -214,89 +273,98 @@ function applyComponents2D(
   }
 }
 
-/** Apply a 2D transform to a display object. */
-function applyTransform2D(display: Container, entity: Entity2D): void {
+/** Apply authored entity state to its live Pixi object. Exported so the source
+ * authoring adapter uses exactly the loader's Sprite-size/scale composition. */
+export function applySceneEntityTransform2D(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 authoredScale = t?.scale ?? [1, 1];
+  let baseScale = spriteBaseScales.get(display);
+  if (!baseScale) {
+    baseScale = entity.sprite ? [display.scale.x, display.scale.y] : [1, 1];
+    if (entity.sprite) spriteBaseScales.set(display, baseScale);
+  }
+  display.scale.set(baseScale[0] * authoredScale[0], baseScale[1] * authoredScale[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>;
+  /** Advance authored AnimatedSprites through Pixi's native update method from the engine loop. */
+  updateAnimations(dt: number): void;
   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,
+type SpawnHook = (
+  entity: Entity2D,
+  display: Container,
+  movingAncestor: MovingPhysicsAncestor2D | undefined,
+) => void;
+
+async function spawnScene2DVisuals(
+  scene: Scene2DFile,
+  stage: Container,
+  onSpawn?: SpawnHook,
 ): 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 animatedSprites: AnimatedSprite[] = [];
   const roots: Container[] = [];
+  const ids = resolveScene2DEntityIds(scene);
 
-  async function spawn(entity: Entity2D, parent: Container): Promise<Container> {
+  async function spawn(
+    entity: Entity2D,
+    parent: Container,
+    path: readonly number[],
+    movingAncestor?: MovingPhysicsAncestor2D,
+  ): 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 if (entity.tilemap) display = await createTilemap(entity.tilemap);
     else display = new Container();
+    if (display instanceof AnimatedSprite) animatedSprites.push(display);
 
     display.label = entity.name;
-    const id = entity.id ?? `e2d_${_autoId++}`;
+    // Authored ids are canonical. The path fallback is deterministic across
+    // edit-mode reloads, unlike the old process-global counter, while keeping
+    // id optional for existing source documents.
+    const id = ids.get(entity)!;
     (display as Container & { __entityId?: string }).__entityId = id;
     byId.set(id, display);
 
-    applyTransform2D(display, entity);
+    applySceneEntityTransform2D(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);
+    onSpawn?.(entity, display, movingAncestor);
 
     if (entity.children) {
-      for (const child of entity.children) await spawn(child, display);
+      const childMovingAncestor =
+        entity.physics2d && isMovingBodyType(entity.physics2d.bodyType)
+          ? { bodyType: entity.physics2d.bodyType, name: entityLabel(entity) }
+          : movingAncestor;
+      for (let index = 0; index < entity.children.length; index++) {
+        await spawn(entity.children[index]!, display, [...path, index], childMovingAncestor);
+      }
     }
     return display;
   }
 
-  for (const entity of scene.entities) {
-    roots.push(await spawn(entity, ctx.stage));
+  for (let index = 0; index < scene.entities.length; index++) {
+    roots.push(await spawn(scene.entities[index]!, stage, [index]));
   }
 
-  await ctx.components.initAll();
-
   return {
     roots,
     byId,
+    updateAnimations(dt) {
+      const ticker = { deltaTime: dt * 60 } as Ticker;
+      for (const display of animatedSprites) display.update(ticker);
+    },
     dispose() {
       for (const root of roots) {
         root.removeFromParent();
@@ -304,6 +372,62 @@ export async function loadScene2DFromData(
       }
       roots.length = 0;
       byId.clear();
+      animatedSprites.length = 0;
     },
   };
 }
+
+/**
+ * Instantiate only authored Pixi display objects. This is the editor's
+ * stopped-mode preview seam: no component construction/init, Rapier bodies,
+ * input manager, systems, or gameplay loop are created.
+ */
+export async function loadScene2DVisualsFromData(
+  data: Scene2DFile,
+  stage: Container,
+  sourceName?: string,
+): Promise<Scene2DInstance> {
+  const result = Scene2DSchema.safeParse(data);
+  if (!result.success) throw new SceneParseError(result.error.issues, sourceName);
+  return spawnScene2DVisuals(result.data, stage);
+}
+
+/**
+ * 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 instance = await spawnScene2DVisuals(
+    scene,
+    ctx.stage,
+    (entity, display, movingAncestor) => {
+      // Rapier bodies live in world space. The loader composes the Pixi parent
+      // chain at spawn; the post-physics writer converts the simulated pose back
+      // to parent-local display coordinates.
+      createPhysics2D(ctx, entity, display, movingAncestor);
+      applyComponents2D(registry, display, entity.components, ctx.components);
+    },
+  );
+
+  await ctx.components.initAll();
+  return instance;
+}

package/src/world2d/schema/entity2d.ts

@@ -36,10 +36,7 @@ const Entity2DBase = z.object({
   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.',
-    ),
+    .describe('Prevent selection and editing in the native 2D scene editor'),
   tags: z
     .array(z.string())
     .optional()
@@ -66,11 +63,9 @@ 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
+    // T4.1: two 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).
+    // which ARE read — `scene-query.ts` for `tags`):
     //   - `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
@@ -78,15 +73,6 @@ export const Entity2DSchema: z.ZodType<Entity2D> = z.lazy(() =>
     //     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,
@@ -116,30 +102,62 @@ export const Scene2DSchema = z
     name: z
       .string()
       .optional()
+      .describe('Scene name shown in the native 2D document hierarchy and inspector'),
+    surface: z.literal('world2d').optional().describe("Render surface. Always 'world2d'"),
+    gravity: Vec2Schema.optional().describe(
+      'World gravity [x, y] in px/s^2. Default [0, 9.8 * pixelsPerMeter] ([0, 980] at the default scale)',
+    ),
+    pixelsPerMeter: z
+      .number()
+      .positive()
+      .optional()
       .describe(
-        'Scene name. REJECTED at parse (T4.1): declared but has no runtime reader — authoring ' +
-          'this field throws. Do not author.',
+        'Authored pixels per physics meter. Configures native Rapier World.lengthUnit and scales default gravity. Default 100',
       ),
-    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.
+  // Duplicate authored ids are rejected at the document boundary so source
+  // history and editor selection always address one stable native Container.
   .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'],
+    const authoredIds = new Map<string, Array<string | number>>();
+    const visit = (entities: Entity2D[], parentPath: Array<string | number>): void => {
+      entities.forEach((entity, index) => {
+        const entityPath = [...parentPath, index];
+        if (entity.id !== undefined) {
+          const idPath = [...entityPath, 'id'];
+          const firstPath = authoredIds.get(entity.id);
+          if (firstPath) {
+            ctx.addIssue({
+              code: z.ZodIssueCode.custom,
+              message:
+                `Duplicate world2d entity id "${entity.id}"; first authored at ` +
+                firstPath.join('.'),
+              path: idPath,
+            });
+          } else {
+            authoredIds.set(entity.id, idPath);
+          }
+        }
+        if (entity.children) visit(entity.children, [...entityPath, 'children']);
       });
-    }
+    };
+    visit(scene.entities, ['entities']);
   })
   .describe('A world2d scene (PixiJS render surface)');
 
 export type Scene2DFile = z.infer<typeof Scene2DSchema>;
+
+/** A copy-on-instantiate reusable native 2D entity subtree. This is a
+ * separate format from Three's `.prefab.json`: its root is an `Entity2D`, and
+ * insertion assigns fresh scene identities instead of creating a linked
+ * override layer. */
+export const Entity2DAssetSchema = z
+  .object({
+    version: z.literal(1).describe('2D entity asset format version'),
+    name: z.string().describe('Reusable 2D entity asset display name'),
+    root: Entity2DSchema.describe('Native Entity2D subtree copied into a Scene2D document'),
+  })
+  .describe('A reusable native 2D entity asset (.entity2d.json)');
+
+export type Entity2DAsset = z.infer<typeof Entity2DAssetSchema>;

package/src/world2d/schema/physics2d.ts

@@ -5,7 +5,7 @@ import { Vec2Schema } from './tuples2d';
 export const Collider2DSchema = z
   .discriminatedUnion('shape', [
     z.object({
-      shape: z.literal('cuboid').describe('Axis-aligned box collider'),
+      shape: z.literal('cuboid').describe('Box collider aligned to the rigid-body rotation'),
       halfExtents: Vec2Schema.describe('Half-width and half-height [hx, hy] in pixels'),
     }),
     z.object({
@@ -30,8 +30,19 @@ 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'),
+      .describe(
+        'Rapier 2D rigid-body type. A body of any type nested below a dynamic or kinematic ' +
+          'body is rejected: Rapier has no parent/child body relationship. Nesting below a ' +
+          'fixed or physics-less transformed parent is supported for fixed bodies. Dynamic ' +
+          'and kinematic bodies additionally require a conformal parent chain (uniform scale ' +
+          'plus rotation/reflection), because later body rotation cannot round-trip through ' +
+          'non-uniform parent scale without shearing the Pixi visual.',
+      ),
+    collider: Collider2DSchema.describe(
+      'Collider shape attached to the body. Its pose and dimensions use the composed parent ' +
+        'transform at spawn. Cuboids support non-uniform scale; ball/capsule colliders reject ' +
+        'non-uniform scale because Rapier cannot represent an ellipse.',
+    ),
     sensor: z
       .boolean()
       .optional()