@vgai/engine 0.5.0-canary.20260719.0 → 0.5.0

package/dist/world2d/schema/sprite.js

@@ -0,0 +1,63 @@
+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');
+/** `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');

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

@@ -0,0 +1,15 @@
+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 declare const TilemapSchema: z.ZodObject<{
+    tileSize: z.ZodNumber;
+    palette: z.ZodArray<z.ZodString>;
+    tiles: z.ZodArray<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export type SceneTilemap = z.infer<typeof TilemapSchema>;
+//# sourceMappingURL=tilemap.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tilemap.d.ts","sourceRoot":"","sources":["../../../src/world2d/schema/tilemap.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB;;;;;;GAMG;AACH,eAAO,MAAM,aAAa;;;;iBAU2D,CAAC;AAEtF,MAAM,MAAM,YAAY,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/world2d/schema/tilemap.js

@@ -0,0 +1,19 @@
+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');

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

@@ -0,0 +1,20 @@
+import { z } from 'zod';
+/** 2D vector as [x, y]. The world2d analog of the 3D Vec3. */
+export declare const Vec2Schema: z.ZodTuple<[z.ZodNumber, z.ZodNumber], null>;
+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 declare const Transform2DSchema: 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>;
+export type SceneTransform2D = z.infer<typeof Transform2DSchema>;
+//# sourceMappingURL=tuples2d.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"tuples2d.d.ts","sourceRoot":"","sources":["../../../src/world2d/schema/tuples2d.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,8DAA8D;AAC9D,eAAO,MAAM,UAAU,8CAAoE,CAAC;AAE5F,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;iBAOwC,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,iBAAiB,CAAC,CAAC"}

package/dist/world2d/schema/tuples2d.js

@@ -0,0 +1,19 @@
+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]');
+/**
+ * 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)');

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

@@ -0,0 +1,16 @@
+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 declare function createPhysicsAdapter2D(physics: Physics2DRegistry): PhysicsAdapter2D;
+//# sourceMappingURL=system-adapters-2d.d.ts.map

package/dist/world2d/system-adapters-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-adapters-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/system-adapters-2d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACzC,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;GAKG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,CAAC,OAAO,EAAE,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAChD,MAAM,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;IACjC,MAAM,CAAC,OAAO,EAAE,SAAS,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/E,QAAQ,CAAC,OAAO,EAAE,SAAS,GAAG,IAAI,CAAC;CACpC;AAED,wBAAgB,sBAAsB,CAAC,OAAO,EAAE,iBAAiB,GAAG,gBAAgB,CAgCnF"}

package/dist/world2d/system-adapters-2d.js

@@ -0,0 +1,37 @@
+export function createPhysicsAdapter2D(physics) {
+    // Remember each frozen body's prior type so unfreeze restores it.
+    const frozen = new WeakMap();
+    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);
+            }
+        },
+    };
+}

package/dist/world2d/transform-writer-2d.d.ts

@@ -0,0 +1,16 @@
+import type { Physics2DRegistry } from './physics2d-registry';
+/**
+ * Build the single postPhysics transform writer for world2d — the ~5-line 2D
+ * analog of `createTransformWriter`.
+ *
+ * Rapier 2D reports `translation()` as `{x, y}` and `rotation()` as a SCALAR angle
+ * (radians), so the writeback is simply `display.position.set(x, y)` +
+ * `display.rotation = angle`. Scale is left untouched (Rapier carries no scale).
+ *
+ * Bodies are simulated in world2d pixel space directly (the surface uses a
+ * y-down, pixel-unit world), so no unit conversion is needed; parented entities
+ * are kept flat under the world container by the loader, mirroring the 3D writer's
+ * scene-root fast path.
+ */
+export declare function createTransformWriter2D(physics: Physics2DRegistry): () => void;
+//# sourceMappingURL=transform-writer-2d.d.ts.map

package/dist/world2d/transform-writer-2d.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"transform-writer-2d.d.ts","sourceRoot":"","sources":["../../src/world2d/transform-writer-2d.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,OAAO,EAAE,iBAAiB,SAC3B,IAAI,CAO1C"}

package/dist/world2d/transform-writer-2d.js

@@ -0,0 +1,22 @@
+/**
+ * Build the single postPhysics transform writer for world2d — the ~5-line 2D
+ * analog of `createTransformWriter`.
+ *
+ * Rapier 2D reports `translation()` as `{x, y}` and `rotation()` as a SCALAR angle
+ * (radians), so the writeback is simply `display.position.set(x, y)` +
+ * `display.rotation = angle`. Scale is left untouched (Rapier carries no scale).
+ *
+ * Bodies are simulated in world2d pixel space directly (the surface uses a
+ * y-down, pixel-unit world), so no unit conversion is needed; parented entities
+ * are kept flat under the world container by the loader, mirroring the 3D writer's
+ * scene-root fast path.
+ */
+export function createTransformWriter2D(physics) {
+    return function writeTransforms2D() {
+        for (const [display, { body }] of physics.entries()) {
+            const t = body.translation();
+            display.position.set(t.x, t.y);
+            display.rotation = body.rotation();
+        }
+    };
+}

package/dist/world2d/types.d.ts

@@ -0,0 +1,59 @@
+import type RAPIER from '@dimforge/rapier2d-compat';
+import type { Application, Container } from 'pixi.js';
+import type { z } from 'zod';
+import type { createSystemRunner } from '../core/system-runner';
+import type { SystemPhaseName } from '../core/types';
+import type { ComponentManager } from '../ecs/component-manager';
+import type { GameComponent } from '../ecs/game-component';
+import type { Game } from '../runtime/game';
+import type { Collision2DSystem } from './collision-2d';
+import type { Physics2DRegistry } from './physics2d-registry';
+/**
+ * All world2d subsystems, passed to every world2d `setup(ctx)` and to each
+ * `GameComponent<'pixijs'>` lifecycle method — the 2D analog of `GameContext`.
+ *
+ * Raw libraries (call directly, no wrappers): `app` / `stage` (PixiJS),
+ * `rapier2dWorld` / `rapier2d` (Rapier 2D). Engine handles bridge them into the
+ * SAME phase-ordered loop the 3D path uses (`systems` is the very same
+ * `createSystemRunner`, and `PHASE_ORDER` is shared).
+ */
+export interface World2DContext {
+    /** The PixiJS application. Its renderer draws `stage`; auto-ticker is disabled. */
+    app: Application;
+    /** The world2d scene-graph root (the camera/world container under app.stage). */
+    stage: Container;
+    /** The Rapier 2D physics `World`. One shared world per world2d scene. */
+    rapier2dWorld: RAPIER.World;
+    /** The Rapier 2D module namespace (RigidBodyDesc, ColliderDesc, Vector2, …). */
+    rapier2d: typeof RAPIER;
+    /** `Container ↔ Rapier2D body/collider` registry (+ collider→entity reverse index). */
+    physics2d: Physics2DRegistry;
+    /** Rapier 2D collision/trigger event dispatcher; drained each postPhysics. */
+    collisions2d: Collision2DSystem;
+    /** Manager for all live GameComponent instances in this pixi world — the
+     *  unified `ComponentManager` (`ecs/component-manager.ts`, constructed with
+     *  `{ kind: 'pixijs' }`). The world2d-silo-only manager this replaced
+     *  (T7.3) is deleted; every 2D component attaches here, exactly like a
+     *  threejs component attaches onto its world's manager. */
+    components: ComponentManager;
+    /** The phase-ordered system runner (shared with the 3D path). */
+    systems: ReturnType<typeof createSystemRunner>;
+    /**
+     * The shared Game root when this world is mounted by a first-party host.
+     * This is the cross-world data path: a Pixi component can query gameplay
+     * components owned by a sibling Three.js world without a mirror store or a
+     * bespoke synchronization bridge.
+     */
+    game?: Game | undefined;
+}
+/** Constructor type for `GameComponent<'pixijs'>` subclasses used in a world2d
+ *  registry (carries static phase/schema) — the 2D-registry analog of
+ *  `GameComponentClass` (`ecs/game-component.ts`), narrowed to the pixijs kind
+ *  so `new Cls()` returns a properly-typed `GameComponent<'pixijs'>` without a cast. */
+export type Pixi2DComponentClass = (new () => GameComponent<'pixijs'>) & {
+    phase?: SystemPhaseName;
+    schema?: z.ZodObject<z.ZodRawShape>;
+};
+/** Component registry for world2d — a plain name→class map (the 2D analog). */
+export type Component2DRegistry = Record<string, Pixi2DComponentClass>;
+//# sourceMappingURL=types.d.ts.map

package/dist/world2d/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/world2d/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,2BAA2B,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,SAAS,CAAC;AACtD,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AACjE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,iBAAiB,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAE9D;;;;;;;;GAQG;AACH,MAAM,WAAW,cAAc;IAC7B,mFAAmF;IACnF,GAAG,EAAE,WAAW,CAAC;IACjB,iFAAiF;IACjF,KAAK,EAAE,SAAS,CAAC;IACjB,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAC,KAAK,CAAC;IAC5B,gFAAgF;IAChF,QAAQ,EAAE,OAAO,MAAM,CAAC;IACxB,uFAAuF;IACvF,SAAS,EAAE,iBAAiB,CAAC;IAC7B,8EAA8E;IAC9E,YAAY,EAAE,iBAAiB,CAAC;IAChC;;;;+DAI2D;IAC3D,UAAU,EAAE,gBAAgB,CAAC;IAC7B,iEAAiE;IACjE,OAAO,EAAE,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC;IAC/C;;;;;OAKG;IACH,IAAI,CAAC,EAAE,IAAI,GAAG,SAAS,CAAC;CACzB;AAED;;;wFAGwF;AACxF,MAAM,MAAM,oBAAoB,GAAG,CAAC,UAAU,aAAa,CAAC,QAAQ,CAAC,CAAC,GAAG;IACvE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,MAAM,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC;CACrC,CAAC;AAEF,+EAA+E;AAC/E,MAAM,MAAM,mBAAmB,GAAG,MAAM,CAAC,MAAM,EAAE,oBAAoB,CAAC,CAAC"}

package/dist/world2d/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -2,7 +2,7 @@
   "name": "@vgai/engine",
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
-  "version": "0.5.0-canary.20260719.0",
+  "version": "0.5.0",
   "description": "Readable TypeScript game engine and universal host for Three.js, PixiJS, and React games.",
   "keywords": ["game-engine", "three.js", "pixijs", "react", "ai-agents"],
   "type": "module",

package/schemas/vgai-game.schema.json

@@ -403,6 +403,69 @@
           "maximum": 9007199254740991
         }
       }
+    },
+    "learn": {
+      "description": "Optional learner-facing metadata (FT-5) — set on shipped example projects so the gallery/wizard/Learn-catalog registries can be generated from the manifest itself",
+      "type": "object",
+      "properties": {
+        "kind": {
+          "type": "string",
+          "enum": [
+            "starter",
+            "feature",
+            "sample-game",
+            "lesson-companion"
+          ],
+          "description": "Content kind in the FTUE taxonomy (§3): starter (minimal per-genre starting point), feature (demonstrates a subsystem), sample-game (complete game as an architectural reference), lesson-companion (exists to back a Learn-site lesson)"
+        },
+        "title": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Learner-facing display title (gallery card headline)"
+        },
+        "summary": {
+          "type": "string",
+          "minLength": 1,
+          "description": "One-sentence learner-facing summary (gallery card body)"
+        },
+        "difficulty": {
+          "type": "string",
+          "enum": [
+            "beginner",
+            "intermediate",
+            "advanced"
+          ],
+          "description": "Learner-facing difficulty rating"
+        },
+        "features": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*$"
+          },
+          "description": "Short kebab-case feature tags used as gallery/catalog filter facets"
+        },
+        "thumbnail": {
+          "description": "Optional thumbnail image reference (engine-repo-relative, e.g. docs/example-screenshots/<id>/<shot>.png; generated per FT-11, never hand-made)",
+          "type": "string"
+        },
+        "preview": {
+          "description": "Optional short preview video/loop reference (generated per FT-11)",
+          "type": "string"
+        },
+        "lesson": {
+          "description": "Optional Learn-site lesson URL that teaches this project 1:1 (e.g. https://vgai-learn.pages.dev/quick-starts/joints/)",
+          "type": "string"
+        }
+      },
+      "required": [
+        "kind",
+        "title",
+        "summary",
+        "difficulty",
+        "features"
+      ],
+      "additionalProperties": false
     }
   },
   "required": [

package/src/manifest/load.ts

@@ -18,6 +18,7 @@ import {
   type GameManifest,
   GameManifestSchema,
   type IngestStrategy,
+  type LearnMetadata,
   type RootAdapter,
   type Tier,
 } from './schema';
@@ -132,6 +133,11 @@ export interface ResolvedGameManifest {
         readonly maxTriangles?: number | undefined;
       }
     | undefined;
+  /** FT-5 (docs/FTUE-LEARN-SYSTEM-DESIGN.md §3) — learner-facing metadata on
+   *  shipped example projects; read by the editor server's registry surface
+   *  (`GET /__editor/examples`, packages/editor/server/editor-server.ts) to
+   *  generate the gallery/wizard/Learn-catalog registries. */
+  readonly learn: LearnMetadata | undefined;
 }
 
 // ---------------------------------------------------------------------------
@@ -441,5 +447,6 @@ export function loadGameManifest(raw: unknown): ResolvedGameManifest {
     debug: manifest.debug,
     determinism: manifest.determinism,
     budget: manifest.budget,
+    learn: manifest.learn,
   };
 }

package/src/manifest/schema.ts

@@ -315,6 +315,60 @@ export const AdapterRootSchema = z
   .strict();
 export type AdapterRoot = z.infer<typeof AdapterRootSchema>;
 
+// ---------------------------------------------------------------------------
+// Learn metadata (FT-5, docs/FTUE-LEARN-SYSTEM-DESIGN.md §3)
+// ---------------------------------------------------------------------------
+
+export const LearnKindSchema = z
+  .enum(['starter', 'feature', 'sample-game', 'lesson-companion'])
+  .describe(
+    'Content kind in the FTUE taxonomy (§3): starter (minimal per-genre starting point), ' +
+      'feature (demonstrates a subsystem), sample-game (complete game as an architectural ' +
+      'reference), lesson-companion (exists to back a Learn-site lesson)',
+  );
+export type LearnKind = z.infer<typeof LearnKindSchema>;
+
+export const LearnDifficultySchema = z
+  .enum(['beginner', 'intermediate', 'advanced'])
+  .describe('Learner-facing difficulty rating');
+export type LearnDifficulty = z.infer<typeof LearnDifficultySchema>;
+
+export const LearnMetadataSchema = z
+  .object({
+    kind: LearnKindSchema,
+    title: z.string().min(1).describe('Learner-facing display title (gallery card headline)'),
+    summary: z.string().min(1).describe('One-sentence learner-facing summary (gallery card body)'),
+    difficulty: LearnDifficultySchema,
+    features: z
+      .array(z.string().regex(/^[a-z0-9]+(-[a-z0-9]+)*$/, 'features tags must be kebab-case'))
+      .describe('Short kebab-case feature tags used as gallery/catalog filter facets'),
+    thumbnail: z
+      .string()
+      .optional()
+      .describe(
+        'Optional thumbnail image reference (engine-repo-relative, e.g. ' +
+          'docs/example-screenshots/<id>/<shot>.png; generated per FT-11, never hand-made)',
+      ),
+    preview: z
+      .string()
+      .optional()
+      .describe('Optional short preview video/loop reference (generated per FT-11)'),
+    lesson: z
+      .string()
+      .optional()
+      .describe(
+        'Optional Learn-site lesson URL that teaches this project 1:1 ' +
+          '(e.g. https://vgai-learn.pages.dev/quick-starts/joints/)',
+      ),
+  })
+  .strict()
+  .describe(
+    'Learner-facing metadata (FT-5, docs/FTUE-LEARN-SYSTEM-DESIGN.md §3) — powers the example ' +
+      'gallery, New Project wizard, and Learn-site catalog. Registries are generated from this ' +
+      'block; there is no parallel hand-edited catalog.',
+  );
+export type LearnMetadata = z.infer<typeof LearnMetadataSchema>;
+
 // ---------------------------------------------------------------------------
 // Game manifest (vgai.game.json)
 // ---------------------------------------------------------------------------
@@ -540,6 +594,10 @@ export const GameManifestSchema = z
           'profiler and fails (nonzero exit) when any metric here is exceeded. Only ' +
           'headlessly-measurable metrics are budgetable; real GPU frame time is not (SwiftShader).',
       ),
+    learn: LearnMetadataSchema.optional().describe(
+      'Optional learner-facing metadata (FT-5) — set on shipped example projects so the ' +
+        'gallery/wizard/Learn-catalog registries can be generated from the manifest itself',
+    ),
   })
   .strict()
   .describe('Game manifest (vgai.game.json) — the complete v2 project configuration');

package/src/world3d-react/r3f-adapter.tsx

@@ -258,14 +258,14 @@ export function createR3FAdapter(options: CreateR3FAdapterOptions): GameAdapter
 
       return {
         kind: 'threejs',
-        // Fiber's REAL `THREE.Scene`/`THREE.Camera` — `three` identity is
-        // deduped to the host's single instance by the project's Vite
-        // config (see this file's header comment), so these pass the
-        // editor's `instanceof THREE.Scene` / `instanceof THREE.Camera`
-        // gates unmodified (design acceptance gate 3). `state.camera`'s
-        // type (`Camera = (OrthographicCamera | PerspectiveCamera) & {
-        // manual?: boolean }`) is a structural subtype of `THREE.Camera`, so
-        // no cast is needed.
+        // Fiber's REAL `THREE.Scene`/`THREE.Camera`. Checkout development
+        // dedupes `three`; a registry-installed project and the prebundled
+        // editor can legitimately have distinct constructor identities, so
+        // editor boundaries recognize Three's stable structural brands
+        // (`isScene`, `isCamera`) rather than relying only on `instanceof`.
+        // `state.camera`'s type (`Camera = (OrthographicCamera |
+        // PerspectiveCamera) & { manual?: boolean }`) is a structural subtype
+        // of `THREE.Camera`, so no cast is needed.
         scene: state.scene,
         camera: state.camera,
         drivesOwnLoop: false,