@vgai/editor 0.2.0

package/template/CLAUDE.md

@@ -0,0 +1,512 @@
+# CLAUDE.md — VGAI Game Project
+
+## The acceptance bar: feature-complete, bot-proven, great-looking
+
+This project is not done at a vertical slice. It is done when the **whole
+game** — every feature in the game's maximal spec/ROADMAP, enumerated up
+front — ships, and every one of those features has a **bot-played
+acceptance criterion** proving it works on the real client (see "Autoplay
+bots" below). Two bars, non-negotiable:
+
+- **Completeness.** Write the maximal spec/ROADMAP before or alongside the
+  first line of code — every feature the game needs, not just the ones
+  that are easy or exciting. **No descopes, no "for now," no
+  vertical-slice-and-ship.** A core-only build with the rest deferred to
+  "later" is not done; it's a partial delivery wearing a done label. If
+  scope turns out to be wrong, revise the spec explicitly and say so — do
+  not quietly narrow it by shipping less.
+- **Visual quality.** "Great-looking" is a claim you DEMONSTRATE, never one
+  you assert. Every visual milestone ships a real, inspectable artifact —
+  screenshots and a gameplay video captured from the actual running client
+  (`npm run game`, not a mockup) — judged against this game's own
+  reference/style bar. "It renders" or "looks good" in prose is not proof;
+  if you can't point at the recording, it isn't shown.
+
+Both bars are proven the same way the autoplay-bot doctrine below proves
+everything else: **the bot plays the real game and the run is the
+evidence.** A skill/feature isn't complete until a bot has played it
+end-to-end and the logs/recording show it working — that's what turns
+"I built X" and "X looks great" from a claim into a demonstrated fact on
+the real product surface.
+
+## Before Writing Any Code
+
+0. **Launch the editor and keep it running.** `vgai edit` (run it in the
+   background) — the editor is the authoring surface AND the verification
+   loop: `vgai status` / `vgai play` / `vgai select` / `vgai apply-diff` and
+   the `/editor` skill all drive it. Tell the user the URL `vgai edit` prints
+   (default `http://localhost:5173`, but NOT always — see the port caveat
+   below) so they can watch the game take shape. This step applies to agents
+   too, headless or not; if part of the editor loop genuinely doesn't fit your
+   game (e.g. fully procedural world, no scene to author), say so explicitly
+   instead of silently skipping the editor.
+   **Port cross-talk caveat:** the default port (5173) is shared across every
+   vgai project on this machine. `vgai edit` will not silently retarget
+   another project's already-running editor — if a DIFFERENT project's
+   editor already holds 5173, this one starts a second instance on a fresh
+   free port instead and prints THAT url. If you (or the user) already have
+   another vgai project's editor tab open in the browser, don't assume it's
+   this project — read the printed URL/port, or pass `vgai edit --port <n>`
+   to pin a specific port for this project, so an old tab left open from a
+   different project doesn't get mistaken for this session (see the
+   `/editor` skill's CLI Reference for `--port` and `vgai sessions`).
+1. **Read an example.** A plain scaffold ships only a minimal default scene — no example content. The worked implementations (FPS, vehicle, third-person, RTS, multiplayer arena, IK, one-concept tutorials — see the Examples Catalog below) are standalone projects in the vgai monorepo's `examples/<id>/`. Scaffold one directly to read/copy its code: `npx create-vgai-project <name> --example <id>` (e.g. `--example third-person`) makes a correctly-rewritten standalone copy of that example, `vgai.game.json` and all. You can also open any of them live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>` (read-only — scaffold to keep edits). Otherwise, build gameplay from the Components section below.
+2. **Read the schema.** Scene format is defined by the engine's Zod schemas; the generated JSON Schema is `schemas/vscn.schema.json` inside the engine package (your tsconfig `paths` / vite alias points at the engine — the schema sits next to its `src/`). Read it before writing or editing any `.vscn.json` file. Wrong field names (e.g. `type` instead of `bodyType` in physics) silently break things. Do **not** author fields the runtime doesn't read: `gamepad_axis_pair`/`mouse_move` input bindings — these (like dead `.vscn` fields) **throw at parse** — the engine ships Zod schemas for every fetched asset format (`inputmap.schema.json` sits beside `vscn.schema.json` in the engine package). Discrete character animation (idle/walk/run/jump) is an XState machine + `bindXStateAnimation` in your own component code, not a `.vscn` field — see the engine's `packages/engine/src/animation/xstate-animation-binding.ts` and a scaffolded `--example third-person`'s `src/components.ts`.
+3. **Read `src/scripts/registry.ts`.** Every component used in a scene must be registered here. Unregistered components fail with "Component not found in registry".
+
+## Commands
+
+```bash
+vgai edit                # Launch the editor for this project (opens browser)
+vgai play                # Enter play mode
+                         # Play-mode (and ingest-mode) edit policy:
+                         # - LIVE-BUT-DISCARDED: gizmo transforms, rename,
+                         #   visibility, environment tuning — applied to the
+                         #   running scene, thrown away on stop.
+                         # - BLOCKED (console warning): saving (Cmd/Ctrl+S),
+                         #   structural ops (add/delete/cut/copy/paste/reparent),
+                         #   inspector edits that rebuild the object (mesh,
+                         #   material, physics, ...), undo/redo, opening files.
+                         # Nothing you change during play can leak into your
+                         # .vscn. Stop play mode to persist edits.
+vgai status              # Check editor state
+vgai apply-diff <scene.vscn.json> <patch.json> [--report]
+                         # The canonical programmatic edit op: apply a
+                         # JSON SceneDiff patch (add/remove/update/move ops +
+                         # environment/name) to a scene file. Validates the
+                         # scene, the patch, AND the result through the engine's
+                         # Zod schemas, and dereferences every asset reference
+                         # the diff introduces (existence for all; schema parse
+                         # for .mat/.prefab refs) — nothing is
+                         # written on any failure.
+                         # --report: validate + summarize only, never write.
+                         # Prefer this over hand-editing .vscn JSON in scripts.
+npm run dev              # Open the EDITOR on this project (delegates to `vgai edit .`) —
+                         # the authoring surface; press Play (or `vgai play`) to run the game
+npm run game             # Vite dev server for the STANDALONE game page (no editor) — the
+                         # ship-shaped form, for player-view testing/bots/CI, not authoring
+npm run build            # tsc + vite build
+npm run typecheck        # Type-check
+```
+
+## Project Structure
+
+```
+public/
+  scenes/          .vscn.json scene files (entities, transforms, components)
+  audio/           Audio assets
+src/
+  main.ts          Entry point — creates game runtime
+  data/            Data assets: <name>.schema.ts + emitted .schema.json + .data.json
+                   (tuning.* ships as the worked example; see src/data/README.md)
+  tools/           Project tools: <name>.tool.tsx editor panels (dock tab or
+                   inspector section) — editor-only, never bundled
+                   (example.tool.tsx + spin.tool.tsx ship; see src/tools/README.md)
+  scripts/
+    main.ts        Game setup — loads scenes, registers components, mounts the default HUD (keep .ts — its path is pinned in vgai.game.json + src/main.ts ENTRY_MODULES; see the React rule)
+    registry.ts    Component registry (GameComponent classes)
+    components/    Custom GameComponent classes
+  ui/              React HUD kit (Panel/Button/Toggle/Slider/...) + DefaultHud.tsx, mount-ui.ts
+server/
+  rooms/           Colyseus multiplayer rooms
+project.json       Project metadata (name, resolution, default scene)
+```
+
+## Key Concepts
+
+The engine has six fundamental primitives — everything you build is one of
+these, and each has exactly one home:
+
+- **Worlds** — the composition units (`vgai.game.json`): `threejs` / `react` /
+  `pixijs`, each with an `entry`; a game is one or more worlds composed by the
+  runtime and the editor alike.
+- **Scenes** — *where things are*: `.vscn.json` files in `public/scenes/`
+  defining entity hierarchies with transforms, meshes, materials, lights,
+  cameras, physics, and components. **Prefabs** (`.prefab.json`) are reusable
+  entity templates.
+- **GameComponents** — *how things behave*: per-entity classes with
+  `init`/`update`/`dispose` and a `static schema` (Zod) for per-entity config
+  (see Components below).
+- **Loop hooks** — *when things run*: per-frame system phases `input` →
+  `prePhysics` → `physics` → `postPhysics` → `gameLogic` → `animation` →
+  `preRender` → `render`, via `GameComponent.phase` or `ctx.systems.add`.
+  **Every `setup()` must return a `dispose()`** that cleans up all objects,
+  bodies, listeners, and UI.
+- **Data** — *what things are*: schema'd JSON in `src/data/`, the layer the
+  inspector (and designers, and VS Code) edit — shared/global definitions and
+  tuning, as opposed to per-entity component config. See "Tunable values → a
+  data asset" under One Canonical Way.
+- **Tools** — *how you tune it*: project-authored React panels
+  (`src/tools/*.tool.tsx`) the editor discovers automatically. Two
+  placements: `placement: 'dock'` (a ⚙ tab after the built-in bottom tabs —
+  project-global dashboards) and `placement: 'inspector'` with a
+  `match: (node, adapter) => boolean` predicate (a ⚙ section in the Inspector
+  for matching selections). Each tool file exports `tool = defineTool({...})`
+  (from `@engine/tools/define-tool`) plus a default React component; build
+  the panel from `@editor/widgets` (the editor's own widget kit + THEME
+  tokens) so it looks native. `src/tools/example.tool.tsx` (dock) and
+  `spin.tool.tsx` (inspector) ship as worked examples — both live-tune
+  `src/data/tuning.data.json` through `useData`/`writeData`
+  (`@engine/react/use-data`) and the running game follows via HMR. An
+  inspector tool can also read the selected entity's OWN component config —
+  `useSelection()` (`@engine/react/use-selection`) returns the selected node,
+  its attached components, and each component's authored config, live.
+  Tools are editor-only dev surfaces, stripped from shipped games by
+  construction: `npm run build` bundles only what `index.html` →
+  `src/main.ts` imports, and nothing in game code imports `src/tools/`.
+
+## Components
+
+All per-entity behavior is a **GameComponent class** — an OOP class with an `init`/`update`/`dispose` lifecycle. The Object3D *is* the entity (there is no ECS / no `eid`): inside a component, `this.object3D`, `this.rigidBody`, and `this.collider` are wired up for you. **Every component referenced by a scene must be registered in `src/scripts/registry.ts`** — unregistered components cause "Component not found in registry" at play time.
+
+| | GameComponent Class |
+|---|---|
+| **What** | OOP class extending `GameComponent` with lifecycle (`init`/`update`/`dispose`, optional `onTriggerEnter`/`onTriggerExit`) |
+| **Use for** | All gameplay behavior — controllers, cameras, AI, pickups, tags |
+| **Access** | `this.object3D` / `this.rigidBody` / `this.collider`; config fields from `static schema` (Zod) |
+| **Editable fields** | Declare a `static schema = z.object({...})` with `.describe()` + `.default()` — these become typed, documented widgets in the editor inspector and are validated on load |
+| **HMR** | Yes (prototype swap preserves instance state on live edit) |
+| **Reference** | `src/scripts/components/scene-camera.ts` (`SceneCamera` — declares `static phase` + `static schema`) in this project; for richer patterns, scaffold a worked example (`npx create-vgai-project <name> --example fps`, `--example vehicle`, `--example third-person`, ...) and read its `src/components.ts`; base class at `packages/engine/src/ecs/game-component.ts` |
+
+**Before creating a component:** read the reference above (or a scaffolded example's, per the "Read an example" step) and copy the pattern (`static phase`, `static schema`, `init`/`update`). Don't author ad-hoc `ctx.systems.add` closures for gameplay — they're neither editable nor hot-reloadable; reserve `systems.add` for non-gameplay infra (audio mixers, network send, etc.).
+
+**Procedural games (no scene file):** components also attach at runtime to
+code-created objects — construct the instance yourself and call
+`ctx.components.attach(object3D, instance)`; the component manager runs `init`
+and the per-frame lifecycle exactly as for scene-authored components. A fully
+procedural world (voxel terrain, roguelike floors, …) legitimately has a
+manifest world with an `entry` and **no `scene`**, and skips `.vscn` authoring
+entirely — registry registration is only *required* for components referenced
+by scene files. The editor still works on such games: play mode adopts the
+live scene graph into the hierarchy/inspector.
+
+**Registration:** `src/scripts/registry.ts` exports two maps:
+- `componentRegistry` — **all** GameComponent classes referenced by scene files (used by the loader + scene validator)
+- `gameComponents` — the same classes, for HMR
+
+**In scene JSON**, components are an object keyed by name: `"components": { "Checkpoint": {}, "MarbleController": { "forceStrength": 12 } }`. Names must match `componentRegistry` keys; field names must match the component's `static schema`. Empty `{}` for tag components (no schema).
+
+**System phases** (for `ctx.systems.add` and `GameComponent.phase`): `input` → `prePhysics` → `physics` → `postPhysics` → `gameLogic` (default) → `animation` → `preRender` → `render`
+
+## One Canonical Way Per Task
+
+For each common job there is exactly ONE recommended approach. Use it — competing paths cause ambiguity and non-determinism.
+
+- **Camera → a camera GameComponent.** Attach a component that positions/aims `ctx.camera` (the shipped patterns to copy: `FPSCamera` in a `--example fps` scaffold's `src/components.ts`, `ChaseCamera` in `--example vehicle`, `CameraTarget` in `--example third-person` — all schema-declared and driven in `preRender`). This project also registers a minimal `SceneCamera` (`src/scripts/components/scene-camera.ts` — schema-declared position + look-at target). Precedence is fixed and intentional:
+
+  `editor viewport camera < scene-defined camera < camera GameComponent`
+
+  The editor's viewport transform is only the *initial* viewpoint, so a scene-defined or component-driven camera always wins (this is why play mode uses your scene's camera, not the editor's orbit camera). Do **not** also write an ad-hoc `ctx.systems.add('preRender', ...)` camera closure — put the camera logic in the component.
+
+- **Gameplay behavior → a GameComponent.** Never an ad-hoc `ctx.systems.add` closure (those are neither editable nor hot-reloadable). Reserve `systems.add` for non-gameplay infra only (audio mixers, network send, debug overlays). See the Components section above.
+
+- **Tunable values → a data asset, never a constant.** If a designer (or you,
+  while tuning) should be able to change a value without editing game code, it
+  lives in `src/data/` as JSON governed by a Zod schema — not as a constant in
+  a component or `setup()`. Per-entity config stays in the component's
+  `static schema` (see Components); data assets are the shared/global layer:
+  feel tuning, economy numbers, tables of game definitions.
+
+  Two blessed shapes, and only these (they're what the editor's DATA tab can
+  render as real widgets): a **singleton** — one `z.object` config whose
+  fields are scalars (number/string/boolean/enum), optionally grouped one or
+  two levels deep in nested `z.object`s (the tab renders groups as sub-forms)
+  — or a **table** — `z.record(z.string(), rowSchema)` with a flat row schema,
+  rendered as a grid (this Zod version's `z.record` takes a key schema AND a
+  value schema — the single-arg `z.record(rowSchema)` shorthand from Zod 3
+  throws here). Anything the tab can't type (arrays, deep nesting, unions)
+  degrades to a raw-JSON cell that refuses invalid commits — prefer
+  flattening, or a table, when a designer should tune it. Tables also get a
+  spreadsheet-friendly bulk-edit path: the DATA tab's **Export CSV** /
+  **Import CSV** buttons round-trip the whole table (header `key,<row
+  fields>`). Import is a WHOLE-TABLE REPLACE (a row the sheet doesn't mention
+  is deleted) and ATOMIC (any cell that fails to coerce to its field's kind —
+  e.g. non-numeric text in a `number` column — writes NOTHING; fix the sheet
+  and re-import). `"$schema"` is never a CSV column; it's carried over from
+  the file automatically.
+
+  ```ts
+  // src/data/tuning.schema.ts — engineer-owned: the contract
+  import { z } from 'zod'
+  export const tuningSchema = z.object({
+    gravity: z.number().min(0).max(50).default(9.8).describe('m/s², downward'),
+  })
+  ```
+  ```jsonc
+  // src/data/tuning.data.json — designer-owned: the values
+  { "$schema": "./tuning.schema.json", "gravity": 9.8 }
+  ```
+  ```ts
+  // src/data/tuning.ts — the live handle (engine defineData, W1)
+  import { defineData } from '@engine/data/data-asset'
+  import raw from './tuning.data.json'
+  import { tuningSchema } from './tuning.schema'
+  export const tuning = defineData(tuningSchema, raw, 'src/data/tuning.data.json')
+  // ['default'] not .default: the template tsconfig's
+  // noPropertyAccessFromIndexSignature applies to Vite's ModuleNamespace
+  import.meta.hot?.accept('./tuning.data.json', (m) => tuning.hotSwap(m?.['default']))
+  ```
+  Read `tuning.get()` live where the value is used (e.g. each frame) — don't
+  copy fields out at init, or HMR edits won't reach them. `subscribe(fn)` fires
+  on every hot edit. **This project ships the pattern working**: the trio in
+  `src/data/` (`tuning.schema.ts` / emitted `tuning.schema.json` /
+  `tuning.data.json`), the handle (`src/data/tuning.ts`), and a consumer
+  (`DataSpinner` on the default scene's Box — press ▶, edit the JSON, watch it
+  change live). Add a data asset by copying that trio AND registering it in
+  `src/data/assets.ts` (the one shared list); after every schema change run
+  `npm run emit-schemas` (commits the emitted `.schema.json` so VS Code
+  validates the data file with no dev server). Rows in table-shaped assets
+  are referenced as `"file#key"` strings — declare a cross-asset field with
+  `dataRef('items')` (`@engine/data/data-ref`) instead of a bare `z.string()`:
+  the emitted schema gets a real `pattern` AND the editor's Data tab renders
+  it as a `stem#key` PICKER (a plain string still works, but has no picker
+  and doesn't survive a target-file rename in `vgai doctor`'s checks). Read
+  the referenced row with `getRef(itemsHandle, enemy.drop)` — pass the
+  TARGET's own handle, not a stem string; it resolves live off `.get()`, same
+  HMR doctrine as everything else in this file. Data assets are immutable at
+  runtime — runtime state lives in your game's own state, never written back
+  into data files. Enforcement is automatic: `npm run build` fails loud on a
+  data file that no longer matches its schema, a dangling `"file#key"` ref (or,
+  for a declared `dataRef` field, a target file that no longer exists at all),
+  or tool code reaching the shipped bundle, and `vgai doctor <folder>` runs
+  the same data checks terminal-side.
+  (The editor's Data dock tab edits these files in place, and project
+  tools (`src/tools/`, see Key Concepts) tune them live through the same
+  file-write path. WSL note: if this project lives on `/mnt/c` (drvfs — no
+  inotify), set `VGAI_WATCH_POLL=1` in the environment; the editor dev server
+  AND this project's standalone `npm run game` both honor it, and without it
+  external edits to `.data.json` never hot-reload into the running game.)
+
+- **Material → inline `material` OR `materialRef`, never both.** An entity uses one or the other: inline `material` for a one-off look, or `materialRef` pointing at a shared `.mat.json` when several entities share a material. Setting both is a hard load-time validation error (enforced by a Zod refine in the engine schema) — there is no silent precedence to memorize.
+
+## Rules
+
+- **The engine is source-linked, not copied.** `@vgai/engine` resolves as a
+  symlink back into the vgai checkout you scaffolded from (a `file:`
+  dependency plus `@engine/*` aliases into `<checkout>/packages/engine/src`).
+  The engine source is yours to read — but **editing it edits the shared
+  checkout**, instantly affecting every project scaffolded from it. A game
+  that truly needs a divergent engine forks the checkout. Your manifest's
+  `engine.version` records which engine version this project was scaffolded
+  or last upgraded against; after updating the checkout, run `vgai upgrade`
+  (report first; `--report` for report-only) to re-sync untouched template
+  files and re-pin — your own edits are never overwritten.
+  **drvfs caveat (WSL, project on /mnt/c):** npm materializes the `file:`
+  dependency as a COPY there, not a symlink — after engine changes, code that
+  resolves through `node_modules/@vgai/engine` (root scripts like
+  `emit-schemas.ts`/`validate-scenes.ts`) sees a STALE engine until you
+  refresh it: `rm -rf node_modules/@vgai/engine && npm install`. The
+  `@engine/*` tsc/vite aliases always see the live checkout and are
+  unaffected.
+- **Use engine/library APIs directly.** No wrappers around Three.js or Rapier.
+- **GameComponents are for gameplay entities only.** Static scenery, lights, and UI are plain Three.js objects.
+- **React: HUD overlay via `mountUI(ctx.uiContainer, <Component />)` (inline styles, no CSS files), OR a full react world — declare `kind: "react"` + `entry` in `vgai.game.json` and default-export a component (JSX is truth, no scene file; GameComponents can't attach to react world nodes). The UI container is reset between scene mounts — a react WORLD is the persistent-UI (title-screen shell) pattern: it lives at world scope, not scene scope.** This project ships one HUD overlay out of the box — `src/ui/DefaultHud.tsx` (ordinary props/`useState`, normal inline styling, no Scene UI `UINode`), mounted by `src/ui/mount-default-hud.tsx` and wired into `src/scripts/main.ts`'s `setup()`/`dispose()`. Edit or delete it freely; nothing else in the template depends on it. Do **not** author a `.vscn` top-level `ui` field or import `@vgai/scene-ui` for new gameplay UI — that data-language path is being retired (spec `docs/AI-NATIVE-AUTHORING-IMPLEMENTATION-SPEC.md` §9 C1/C5); use ordinary React instead.
+
+  To bridge live game state (a singleton gameplay component's score/lives/wave)
+  into the HUD, don't poll — wrap the HUD in `<GameProvider game={ctx.game!}>`
+  and read with `useGameState((g) => g.queryByComponent(MyComponent)[0]?.field)`;
+  both ship in this project's `src/ui/game-state.tsx` (a re-export of
+  `@engine/react/game-state`), and the selector re-runs at most once per frame.
+  Worked reference: the `hp-hud` example's `src/hud.tsx`.
+
+  Mounting that HUD from `src/scripts/main.ts`: keep it a `.ts` file. Its exact
+  path string is load-bearing in TWO places — `vgai.game.json`'s `entry` and the
+  `ENTRY_MODULES` key in `src/main.ts` — and only the standalone build
+  (`npm run game`) throws on a mismatch; the editor resolves the entry itself,
+  so a `.tsx` rename looks fine in `vgai edit` and breaks later. Since a `.ts`
+  file can't contain JSX, keep the JSX in a sibling `.tsx` (like hp-hud's
+  `hud.tsx`) and mount with
+  `mountUI(ctx.uiContainer, React.createElement(GameProvider, { game: ctx.game! }, React.createElement(MyHud)))`.
+- **Multiplayer → Colyseus directly.** vgai deliberately has no engine-level networking wrapper. Typed `joinOrCreate<T>` + the v0.17 Callbacks API (`onAdd`/`onChange`/`onRemove`; per-field `listen` — but see the P2P caveat below before using it); dynamic-import `@colyseus/sdk` so single-player bundles stay clean. Read live schema properties inside `onChange`; never destructure schema fields into local copies. The worked reference is `network.ts` in a `--example third-person-arena` scaffold (raw Callbacks + an ambient type mirror of the server schema; the engine's old `net/` wrapper is deleted).
+- **P2P mode (browser-hosted rooms) → write dual-target code.** Your room can
+  also run browser-hosted over WebRTC via `@vgai/p2p-colyseus`: build/serve
+  with `VGAI_P2P=1` (this project's `vite.config.ts` aliases the Colyseus
+  packages onto browser-safe compat shims only then) and launch with
+  `?net=p2p-host` / `?net=p2p-join&roomId=…`. The same room class still runs
+  on a real server (`npm run server`), so keep room + client code inside the
+  two runtimes' intersection — full rules with rationale in the engine
+  checkout's `docs/P2P-COLYSEUS-MIGRATION.md` ("Dual-Target Portability
+  Rules"); the short list:
+  - No `$.listen` in the compat layer — read root-state fields inside
+    `room.onStateChange` (use `.once(...)`, not its return value: the real
+    SDK returns an EventEmitter, the compat an unsubscribe function).
+  - No `this.clock` on the compat `Room` — drive all timing from
+    `setSimulationInterval` (tick counters for delays).
+  - Never send messages from `onJoin` (dropped under P2P) — catch-up is
+    client-initiated: register handlers, then send a `sync_req`; reply in
+    bounded batches.
+  - Keep bulky world data OUT of room state (the P2P runtime diffs the whole
+    state per client per tick) — state carries players/actors + small
+    scalars; the world is a seed + an event log sent as messages.
+  - Relay budget ~30 messages/peer/sec, 16 KB max envelope — throttle moves
+    (~10 Hz) and batch bulk sync under the cap.
+
+## Editor Control
+
+Use the `/editor` skill to control the visual editor (select entities, focus camera, play/stop, toggle display modes). The skill documents the `vgai` CLI and `@vgai/editor-sdk`.
+
+### Quick examples:
+```bash
+# Select and focus an entity after editing its scene file
+vgai select <entity-id> && vgai focus <entity-id>
+
+# Test gameplay
+vgai play
+
+# Check editor state
+vgai status
+```
+
+## Autoplay bots — testing your game in cycles
+
+The highest-leverage test harness for a vgai game is a **synthetic player**:
+a bot that plays the game the way a human does. The full doctrine and the
+evidence behind it live in the engine checkout's
+`docs/SYNTHETIC-PLAYER-DESIGN.md`; this section is the practical playbook.
+
+**The principle: synthesized input in, observable state out, no backdoors.**
+The bot presses the same virtual keys and reads the same game state a player
+sees. It never teleports the player, calls gameplay methods directly, or
+writes inventory outside a declared test fixture. To the extent the bot
+cannot cheat, every *gameplay* failure it hits is a real player-facing
+defect — a physics gap, a missing line-of-sight check, a UI-sequencing bug.
+(The bot has its own bug class too — planner/executor defects. A red run is
+a lead, not a verdict; the logs below are how you tell the buckets apart.)
+If some capability forces a compromise (e.g. headless pages have no pointer
+lock, so mouse-look may need a direct write), DECLARE it in your docs as a
+known violation — never let backdoors accumulate silently.
+
+**Actuation** — the engine's `InputManager` already ships the seam:
+- `input.setVirtualKey(code, pressed)` — synthesizes key state through the
+  real action-binding path.
+- `input.setLookStick(x, y)` — virtual look input, injected as mouse delta
+  during `poll()` (the headless-friendly alternative to pointer lock).
+Run the bot against `npm run game` (the standalone player-view page — that's
+what it's for), gated behind a query param like `?bot=1&goal=<skill>&reps=N`.
+
+**Perception** — read the game's own observable state (the same objects and
+state your HUD reads), plus a debug handle you expose on `window` for the
+harness (e.g. `__myGame = { gameState, bot }`). World queries that scan
+through terrain/content the player has never seen are X-ray — assisted
+perception. Sometimes pragmatic, but declare it.
+
+**Test in layers — never debug a pure-logic bug through the browser:**
+1. **L1 — headless logic tests.** Extract pure models (movement/physics
+   stepping, pathfinding, world rules) into functions a Node script can call
+   with no browser, no renderer. Seconds per run; this is where most bugs
+   should be found and fixed.
+2. **L2 — goal isolation.** One skill, from a fresh fixture, N repetitions,
+   under a time cap (e.g. a `bot-probe` script that boots the game page
+   headless, runs `?bot=1&goal=chop-wood&reps=3`, and greps the event log).
+   A skill isn't done until it passes ~3×3 across ≥3 world seeds/fixtures.
+3. **L3 — full mission.** The bot plays start-to-goal. Only run this when
+   the isolated skills underneath are green — otherwise every failure is
+   ambiguous.
+
+**Logs and analytics from day one — they ARE the iteration loop:**
+- **`lastFail` on every skill**: whenever a bot skill gives up, it records a
+  one-line reason with coordinates/state (`"mineBlock 4,61,-1: crosshair on
+  4,62,-1"`). A probe that ends `goal-failed` with no `lastFail` is a
+  harness bug.
+- **A trace ring buffer** (last ~60 bot decisions: step taken, expected vs
+  actual result) so a failure comes with its recent history attached.
+- **A structured event log** (`goal-passed`/`goal-failed`/`mission-complete`
+  + timestamp + position/hp), printed to console so a headless harness can
+  grep it, plus periodic screenshots if you drive via Playwright.
+- The iteration cycle is: red run → read `lastFail` + trace → reproduce at
+  the LOWEST layer that exhibits it → fix → re-run the isolation → re-run
+  the full matrix. Without the logs, step two is guesswork.
+
+**Two hard-won invariants** (each cost a debugging session to learn):
+- If your bot is a generator/coroutine stepped once per frame, every loop
+  iteration must `yield`. A loop that can re-enter without yielding (e.g.
+  "plan failed → retry") is a synchronous freeze that pins the renderer.
+- Never edit source files watched by a running dev server mid-probe — the
+  hot reload kills the run and the result is garbage either way.
+- If you drive either dev server (`vgai edit`/`npm run dev`, or `npm run
+  game`) with Playwright, use `page.goto(url, { waitUntil: 'load' })`, never
+  `'networkidle'` — the dev server keeps a live SSE/websocket/HMR
+  connection open, so the network never goes idle and `'networkidle'`
+  hangs forever.
+
+**Multiplayer without multiplayer**: N synthetic players in N headless pages
+against your Colyseus room is a real multiplayer session — same input paths,
+same netcode, no humans needed. This is the cheapest way to soak-test rooms.
+
+## Examples Catalog
+
+Nothing example-shaped ships inside this project — every example is a
+standalone project in the vgai monorepo's `examples/<id>/`, with its own
+`src/`, scenes, `vgai.game.json`, and (where multiplayer) `server/`. Get one's
+code by scaffolding it: `npx create-vgai-project <name> --example <id>` (e.g.
+`--example third-person`) — a correctly-rewritten standalone copy. Or open it
+live in the hosted editor at `https://vgai-editor.pages.dev/?project=<id>`
+(read-only; scaffold to keep edits).
+
+**Gameplay examples:**
+- `third-person` — orbit camera, WASD movement, XState animation machine, AI chase
+- `fps` — pointer lock, throwable projectiles, dynamic physics
+- `vehicle` — Rapier raycast-vehicle suspension, steering, chase camera
+- `rts` — top-down camera, box selection, navmesh crowd pathfinding
+- `third-person-arena` — multiplayer tag with AI bots: client-authoritative movement, server-authoritative game state (tag/phases); ships its own `server/`
+- `starfighter` — flight controller with schema-declared tuning fields
+- `ik` — skeletal IK (CCDIKSolver) on a code-built rig
+
+**Scene & technique showcases:**
+- `editor-tutorial` — feature-showcase scene: meshes, materials, lights, physics, particles, audio, bloom
+- `feature-scenes` — six technique scenes in one project: instancing, terrain, ocean, particles, custom water shader, HDR skybox
+- `littlest-tokyo` — GLTF model scene (Draco-compressed; ships its decoder assets)
+- `learn-joints`, `learn-matfiles`, `learn-triggers`, `learn-splines` — one-concept tutorials (physics joints, shared `.mat.json` materials, sensor triggers, spline motion)
+
+**UI / multi-world examples:**
+- `hp-hud` — React HUD reading live game state via `<GameProvider>` + `useGameState` (selectors call `g.queryByComponent(...)`) (the HUD-overlay pattern on a threejs world — for a `kind: "react"` WORLD example, see `tri-world`)
+- `tri-world` — one manifest, three world kinds side by side (threejs + pixijs + react)
+
+**Multiplayer note:** this project already ships a generic `server/` (a
+`GameRoom` in `server/rooms/`, registered in `server/rooms.ts`), but the
+Colyseus server is **not** started by `npm run dev`/`npm run game`. Run `npm run server` to
+boot it standalone — it starts `server/main.ts` on `ws://localhost:2567` and
+shuts down cleanly on Ctrl-C. Start it before connecting, or the client will
+fail to connect. (The script runs tsx against `server/tsconfig.json`, not the
+app tsconfig — `@colyseus/schema`'s legacy `@type` decorators need
+`experimentalDecorators`, which only the server tsconfig sets.) The
+`third-person-arena` example (`--example third-person-arena`) ships its own
+richer `server/` (an `ArenaRoom` with tag/phase state) in place of this
+generic one.
+
+## Scene File Format
+
+Entities in `.vscn.json` have these optional fields:
+- `id` — UUID. The **editor** generates one when it creates an entity, and the
+  runtime loader auto-generates a random one for id-less entities at load (so
+  every loaded object carries an entity descriptor and appears in the play-mode
+  hierarchy). But a random id can't be *referenced*: anything targeted from
+  elsewhere (joints, god-rays, etc.) still needs an AUTHORED id.
+- `name` — display name
+- `transform` — `{ position: [x,y,z], rotation: [x,y,z,w], scale: [x,y,z] }`
+- `mesh` — `{ type: 'box'|'sphere'|'plane'|'cylinder'|... }`
+- `material` — `{ type: 'standard'|'physical', color, metalness, roughness, ... }` (inline material)
+- `materialRef` — path to a shared `.mat.json` asset. **Mutually exclusive with `material`** — set one or the other, never both (load-time error).
+- `light` — `{ type: 'directional'|'point'|'spot'|'ambient', ... }`
+- `camera` — `{ type: 'perspective'|'orthographic', ... }`
+- `physics` — `{ bodyType: 'dynamic'|'fixed'|'kinematic', collider: { type: 'cuboid'|'ball'|'capsule', halfExtents?, radius?, friction?, restitution?, density? }, mass? }`
+
+  **Physics contracts (current):**
+  - Physics entities may be nested under transformed parents: the loader
+    composes the full parent chain and spawns the body at the WORLD
+    transform. One exception, enforced loudly: a `dynamic` body under an
+    ancestor that itself has a `dynamic`/`kinematic` body is a load error
+    (Rapier has no parent/child body relationship).
+  - Collider dimensions (`halfExtents`, `radius`) are authored in local units
+    and **scale with the entity's composed world scale** (per-axis for
+    cuboids; round colliders require uniform scale on their round axes —
+    non-uniform is a loud load error). The editor's collider gizmo renders
+    the same computed dimensions the runtime uses.
+  - Collision events fire for all scene-loaded colliders: solid-solid
+    contacts reach `ctx.collisions.onCollision`; **sensor** colliders
+    additionally dispatch `onTriggerEnter/Exit` on components.
+- `components` — `{ "ComponentName": { prop: value, ... }, ... }` (see Components section above)
+- `children` — nested entity array
+
+Scene files also carry a top-level `ui` field (React UI roots authored via the
+editor's UI edit mode); it survives undo/redo and asset moves.

package/template/LICENSE

@@ -0,0 +1,30 @@
+MIT License
+
+Copyright (c) 2026 Volter AI, Inc.
+
+This MIT license covers the vgai game-project template (this directory) — the
+starter code scaffolded into your project. It is intentionally permissive so that
+the game you build with vgai, and anything you generate from this template, is
+YOURS, free of any obligations to us. You may relicense your generated game
+under any terms you choose.
+
+(The vgai engine and tooling — everything outside this directory — are licensed
+per component: Apache-2.0 core, AGPL-3.0 editor. See the repository LICENSE.md.)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/template/emit-schemas.ts

@@ -0,0 +1,42 @@
+/**
+ * Emits `src/data/*.schema.json` from the Zod schemas — the schema-interchange
+ * step of docs/DATA-TOOLS-DESIGN.md §2.1 / D4 (in the engine checkout).
+ * The emitted artifact is committed so VS Code validates/autocompletes every
+ * `*.data.json` (via its `"$schema"` first line) with no dev server running.
+ *
+ * Also VALIDATES each asset's current `.data.json` against its schema and
+ * fails loud (the terminal half of the §6 doctor check, usable today) — a
+ * schema change that orphans existing data is caught here, not at runtime.
+ * The same list drives the BUILD-time check (`vite.config.ts` →
+ * `vgaiDataCheck`), and `vgai doctor <folder>` re-runs schema + ref
+ * validation from outside the project.
+ *
+ * Run after every schema change: `npm run emit-schemas`
+ * Register new data assets in `src/data/assets.ts` (the one shared list).
+ */
+import { readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseDataJson, toDataJsonSchema } from '@vgai/engine/data/data-asset';
+import { dataAssets } from './src/data/assets';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+
+let failed = false;
+for (const { name, schema } of dataAssets) {
+  const out = `src/data/${name}.schema.json`;
+  const data = `src/data/${name}.data.json`;
+  writeFileSync(path.join(here, out), `${JSON.stringify(toDataJsonSchema(schema), null, 2)}\n`);
+  console.log(`emit-schemas: wrote ${out}`);
+
+  // parseDataJson = the exact parse defineData runs at load (incl. the
+  // "$schema"-line strip), so this check can never disagree with runtime.
+  try {
+    parseDataJson(schema, JSON.parse(readFileSync(path.join(here, data), 'utf8')), data);
+    console.log(`emit-schemas: ${data} validates`);
+  } catch (err) {
+    failed = true;
+    console.error(String(err));
+  }
+}
+if (failed) process.exit(1);

package/template/index.html

@@ -0,0 +1,17 @@
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no, viewport-fit=cover" />
+  <title>My Game</title>
+  <style>
+    * { margin: 0; padding: 0; box-sizing: border-box; }
+    html, body { width: 100%; height: 100%; overflow: hidden; background: #000; }
+    #game-canvas { width: 100%; height: 100%; position: relative; }
+  </style>
+</head>
+<body>
+  <div id="game-canvas"></div>
+  <script type="module" src="/src/main.ts"></script>
+</body>
+</html>