@volter/game-editor 0.5.65

package/package.json

@@ -0,0 +1,91 @@
+{
+  "name": "@volter/game-editor",
+  "author": "Volter AI, Inc.",
+  "version": "0.5.65",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "AGPL-3.0-only AND GPL-3.0-or-later",
+  "description": "Volter Game Editor: the game packages and Blender stitched onto the editor kit.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/volter-ai/editor.git",
+    "directory": "packages/game-editor"
+  },
+  "files": [
+    "dist",
+    "src",
+    "LICENSE",
+    "LICENSE-BLENDER",
+    "NOTICE",
+    "LICENSE-MCP",
+    "dist-node",
+    "presets.mjs",
+    "workbench",
+    "template",
+    "template-dotfiles",
+    "catalog",
+    "starter",
+    "BUNDLED_NOTICES"
+  ],
+  "scripts": {
+    "build": "vite build --config vite.config.ts",
+    "build:node": "node scripts/build-node.mjs",
+    "typecheck": "tsc -p tsconfig.node.json"
+  },
+  "vgai": {
+    "product": {
+      "entry": "./src/index.ts",
+      "displayName": "Volter Game Editor",
+      "colorTheme": "dark",
+      "workbench": {
+        "release": "game-editor-f8664703ab59-595ba7af8402-darwin-arm64",
+        "tarballSha256": "fac04a80a9745b6af25c232308faab1691ef2ecc40883cc8c9b89b42f12f8ccd"
+      }
+    }
+  },
+  "dependencies": {
+    "@volter/editor-core": "0.5.65",
+    "@volter/editor-game": "0.5.65",
+    "@volter/editor-blender": "0.1.8",
+    "@volter/blender-engine": "0.1.7",
+    "@volter/editor-project": "0.5.65",
+    "@volter/editor-sdk": "0.5.65",
+    "@volter/editor-live": "0.5.65",
+    "@volter/game-live": "0.5.65",
+    "@modelcontextprotocol/sdk": "1.30.0",
+    "@volter/game-runtime": "0.5.65",
+    "@volter/threejs-runtime": "0.5.65",
+    "undici": "7.29.1",
+    "typescript": "5.9.3",
+    "@colyseus/schema": "^4.0.14",
+    "@colyseus/sdk": "^0.17.34",
+    "@react-three/drei": "^10.7.7",
+    "@react-three/fiber": "^9.6.1",
+    "react": "~19.2.4",
+    "react-dom": "~19.2.4",
+    "three": "^0.180.0",
+    "zod": "^4.3.6",
+    "@colyseus/ws-transport": "^0.17.9",
+    "@storybook/react": "10.6.0",
+    "@types/node": "^25.3.0",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "@types/three": "^0.180.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "colyseus": "^0.17.8",
+    "storybook": "10.6.0",
+    "tsx": "^4.23.0",
+    "vite": "^6.4.3",
+    "ztrack": "^1.5.5",
+    "three-bvh-csg": "^0.0.18",
+    "three-mesh-bvh": "^0.9.12"
+  },
+  "bin": {
+    "volter-game-editor": "./dist-node/cli.js"
+  }
+}

package/presets.mjs

@@ -0,0 +1,2 @@
+// Node-executable product code, shared by the CLI and the New Project screen.
+export { declaration as default } from './dist-node/create.js';

package/src/contributions.d.ts

@@ -0,0 +1,4 @@
+declare module 'vgai:contributions/*' {
+  const contributions: readonly { readonly entryPath: string; readonly load: () => Promise<unknown> }[];
+  export default contributions;
+}

package/src/index.ts

@@ -0,0 +1,38 @@
+/**
+ * THE GAME EDITOR, COMPOSED — this file is the whole product.
+ *
+ * Thin code that stitches packages onto the editor kit and holds only what
+ * building a game needs. Three decisions, each a product's to make and nobody
+ * else's:
+ *
+ *  - WHICH PACKAGES, in mount order. `vgai:contributions/<package>` is that
+ *    package's own `package.json#vgai.contributions`, read at build time
+ *    (`@volter/editor-core/build/product-contributions`) — the product names
+ *    the package, never its modules, so a package that grows a contribution
+ *    grows this product with no edit here.
+ *  - THE LOOK. `classic` — the editor's own Graphite, which is the reference
+ *    frame every host-default shape was measured against. A DEFAULT:
+ *    `~/.vgai/settings.json`, the project's own, and its adapter's declaration
+ *    each outrank it.
+ *  - THE WORKSPACE. `game` — `@volter/editor-game`'s own workspace
+ *    contribution, which applies to a project with at least one root that
+ *    plays.
+ *
+ * `mountVgai` is what the workbench contribution reads off this module once
+ * `/__editor/served-modules` hands it this file's URL.
+ */
+
+import blender from 'vgai:contributions/@volter/editor-blender';
+import game from 'vgai:contributions/@volter/editor-game';
+import { product } from '@volter/editor-core/frame/product';
+
+export const { mountVgai } = product({
+  id: 'game-editor',
+  packages: {
+    '@volter/editor-game': game,
+    '@volter/editor-blender': blender,
+  },
+  look: 'classic',
+  workspace: 'game',
+  nativeMenus: true,
+});

package/starter/cube.py

@@ -0,0 +1,81 @@
+# SPDX-License-Identifier: GPL-3.0-or-later
+#
+# THIS FILE IS GPL, AND THE REST OF YOUR PROJECT IS NOT.
+#
+# It drives `bpy`, Blender's Python API. The Blender Foundation's stated
+# position — their licence page, under "Add-ons (Python scripts)" — is that
+# the API "is an integral part of the software" and that the GPL "therefore
+# requires that such scripts (if published) are being shared under a GPL
+# compliant license". So a bpy script is a derivative work of Blender, and
+# this one is licensed GNU General Public License version 3 or later,
+# exercising Blender's own "or later".
+#
+# WHAT THIS DOES NOT TOUCH. `cube.blend` beside this file is YOURS, and so is
+# anything you export from it — glTF, GLB, renders. That is the Foundation's
+# position too, on the same page under "Your Artwork": what you make with
+# Blender is your sole property, "including the .blend files and other data
+# files Blender can write". Every other file the template gave you is MIT.
+# This licence reaches this script and nothing else.
+#
+# If you would rather not carry it: delete this file. The `.blend` is the
+# document — this is only the recorded source of how it was made — and
+# nothing in the project reads this script at runtime. If you write your own
+# bpy scripts, the Foundation's position applies to them on the same terms;
+# it is not a rule of ours and is not ours to waive, because the copyright in
+# Blender is Blender's authors'.
+#
+# Copyright 2026 Volter AI, Inc.
+
+"""The starter model — the bpy that made `cube.blend`, and its SOURCE.
+
+A model is Blender data: `cube.blend` beside this file is the document the
+editor opens, and this is the script that authored it. Run it again and you
+get the same file; edit it and re-run it, or open the `.blend` and model in
+Blender's own Edit Mode — both are authoring, and the `.blend` is the truth
+either way.
+
+Run it through the session's Blender, from this project:
+
+    npm run --silent vgai -- blender-mcp        # the transport an agent drives
+    # or, in a live editor session:
+    # editor.blender('blender-execute', { code: open('src/models/cube.py').read() })
+
+The session saves the open document about a second after the last call, so a
+script that models is a script that saves.
+
+Coordinates are metres, Z is up (Blender's), and the exporter converts to the
+game's Y-up on the way to glTF.
+"""
+
+import bpy
+
+# ONE DATABLOCK, AT THE ORIGIN. A model file holds the model, not a set: the
+# factory startup's Light and Camera belong to a scene, and a model that
+# carries them exports them too.
+for obj in list(bpy.data.objects):
+    bpy.data.objects.remove(obj, do_unlink=True)
+for mesh in list(bpy.data.meshes):
+    bpy.data.meshes.remove(mesh)
+# Materials too, or a re-run appends `Material.001` beside the one it made
+# last time and the Shader Editor shows whichever slot happens to be active.
+for material in list(bpy.data.materials):
+    bpy.data.materials.remove(material)
+
+# Blender opens on a cube; so does this. `size` is the full width, so 1.0 is
+# a 1 m box — the starter's own scale, not the factory cube's 2 m.
+bpy.ops.mesh.primitive_cube_add(size=1.0, location=(0.0, 0.0, 0.0))
+cube = bpy.context.active_object
+cube.name = "Cube"
+cube.data.name = "Cube"
+
+# AND BLENDER'S OWN DEFAULT MATERIAL, because Blender's own default cube has
+# one. Without it the Shading workspace opens on `Shader Editor · No material`
+# with nothing drawn and nothing a person can click to change that — its one
+# control, Use Nodes, correctly refuses, because this view inspects a node
+# tree and never writes one (walk 3, beat 4). `materials.new` leaves
+# `use_nodes` FALSE, which is a material the header names and the canvas still
+# cannot draw; setting it True is what builds the pair Blender builds —
+# Principled BSDF into Material Output, 2 nodes and 37 sockets.
+material = bpy.data.materials.new(name="Material")
+material.use_nodes = True
+cube.data.materials.append(material)

package/template/.agents/references/project-manual.md

@@ -0,0 +1,341 @@
+# Detailed VGAI game project reference
+
+This is the procedural reference behind the compact project `AGENTS.md`
+router. Load only the section the current decision needs. The source files
+named here are the examples an agent should copy; no hidden generator or
+registry supplies their semantics.
+
+## Contents
+
+- [Starting a game](#starting-a-game)
+- [Roadmap and journal](#roadmap-and-journal)
+- [Source architecture](#source-architecture)
+- [Playable slices](#playable-slices)
+- [The resident QA tester](#the-resident-qa-tester)
+- [Studio surfaces](#studio-surfaces)
+- [Analytics and gameplay sessions](#analytics-and-gameplay-sessions)
+- [Game data](#game-data)
+- [UI roots](#ui-roots)
+- [Capabilities and assets](#capabilities-and-assets)
+- [Multiplayer](#multiplayer)
+- [Live verification](#live-verification)
+
+## Starting a game
+
+Read the brief, create the first `ROADMAP.md` arc, inspect
+`vgai.project.json`, then start the editor immediately:
+
+```bash
+npm run dev
+```
+
+Tell the user the printed URL in the first visible message and keep that
+session running. The editor is where the source is observed and verified;
+source edits remain ordinary file edits. `npm run dev:standalone` serves only
+an exported build and is not a development bypass.
+
+## Roadmap and journal
+
+`ROADMAP.md` is the only game-level tracker. Its first entry is the complete
+playable prototype from the brief, not one task per mechanic, UI, tool, or
+test. Later entries are only major features of comparable scope. Each entry
+has one `status:` and one `Summary:`; do not add acceptance criteria yet.
+`ztrack check` verifies this shape.
+
+`DEVLOG.md` is not another tracker. Add one entry when a coherent feature arc
+finishes, covering what changed, why, important decisions, the live playtest
+outcome, and what remains. Link only evidence you inspected. Copy selected
+screenshots into `media/screenshots/` and selected short clips into
+`media/clips/`; bounded `.vgai/` history is working material, not a permanent
+journal attachment.
+
+## Source architecture
+
+Read `vgai.project.json` and `src/main.ts` first. Every manifest root has one
+adapter and lifecycle. Its entry is the source document: TSX for a Three or
+Canvas root, JSX for a DOM root. Do not call `createRoot`, `hydrateRoot`, or
+`ReactDOM.render` inside a root component; host mounting belongs to the
+adapter boundary.
+
+The neutral Three starter demonstrates the complete taxonomy:
+
+```text
+src/world.tsx                         thin persistent root + scene swap slot
+src/scenes/MainScene.tsx              complete replaceable composition
+src/prefabs/HeroBox.tsx               independently placeable object
+src/prefabs/HeroBox.stories.tsx       Content registration/design state
+src/components/environment/Ground.tsx non-placeable support assembly
+```
+
+Preserve the meanings when replacing the starter content:
+
+- A scene composes environment, prefabs, and cameras. It is not a Content
+  prefab and does not hide independent repeated entities inside scenery.
+- A prefab is a thing a designer selects, places, duplicates, or reuses as one
+  piece. It accepts ordinary `ThreeElements[...]` props, forwards them to one
+  native outer root, has meaningful node names, and ships a colocated story
+  naming it as `meta.component`.
+- Construction pieces that only make sense as part of a prefab stay inside
+  that owner. Do not create a prefab per primitive.
+- Supporting components are non-placeable implementation: sky, atmosphere,
+  a one-per-scene floor assembly, a light rig. They belong under
+  `src/components/` and do not receive hollow stories.
+- A character is the rigged humanoid-generator asset path, never a stack of
+  capsules and boxes.
+
+`check-idioms` makes the objective edges loud: E10 for a prefab without its
+story, E11 for scene-folder misclassification, E9 for R3F authoring warnings,
+and W10 when a Three project has no registered prefab at all. W10 is a prompt,
+not a claim that fully procedural games are impossible; record and suppress a
+genuine exception with a reason.
+
+The world node is the entity. Behavior on an R3F root is an ordinary React
+component using `useFrame`; physics is ordinary `@react-three/rapier` JSX.
+Use the ecosystem library directly. No mirror tree, gameplay registry, or
+vgai phase vocabulary belongs in game code.
+
+## Playable slices
+
+Ship one vertical slice at a time. A mechanic slice includes all of:
+
+- the player-visible behavior;
+- the rendering/HUD required to read it;
+- an ordinary exported state readout beside the mechanic;
+- an ordinary exported setup function when reaching a QA situation costs
+  roughly more than 30 seconds of honest play;
+- a tester behavior that exercises the mechanic through normal input;
+- any game-specific Tester/Data/Analytics presentation the slice earns;
+- a live playtest, reviewed visual evidence, and a commit.
+
+The exported function is the debug door. There is no command registry:
+
+```ts
+// src/sim/cooling.ts
+export function readCooling() {
+  return { temperature, capacity, throttled };
+}
+
+export function setupHeatSpike() {
+  // Arrange the expensive precondition only. Do not perform the behavior
+  // the tester is meant to exercise.
+}
+```
+
+The developer reaches that exact running module from the session:
+
+```js
+game.run(async ({ modules }) => {
+  const cooling = await modules('src/sim/cooling.ts');
+  cooling.setupHeatSpike();
+  return cooling.readCooling();
+})
+```
+
+Do not press the player's controls from the developer REPL in a realtime game.
+The developer arranges and observes; the resident tester holds the controller
+at simulation speed. A genuinely turn-paced action is the narrow exception
+where developer-paced input can still be honest.
+
+## The resident QA tester
+
+The tester is ordinary game code under `src/bot/`, not an LLM service and not
+gameplay automation that belongs to the shipped player's economy. It is the QA
+person holding this game instance's controller.
+
+The starter demonstrates the mechanics without standardizing the game's
+vocabulary:
+
+- `src/input.ts` is the game's own input store. Human key bindings and virtual
+  tester actuation merge into the same action reads.
+- `src/bot/behaviors.ts` is the game-specific repertoire. Replace the starter
+  `sweep` with intent-level goals named for real outcomes and grow it with
+  every mechanic.
+- `src/bot/tester-station.ts` exports `hireTester`, `describeTester`, and the
+  sim-tick stepper.
+- `src/bot/bot-station.ts` exports status plus pause, resume, abort, and
+  handoff controls.
+- `src/bot/QaTester.tsx` is the thin frame hook that steps the tester before
+  gameplay reads input.
+
+A tester behavior actuates only `ctx.hands` and reads the game's own state. It
+never teleports, buys resources directly, or calls setup functions. A setup
+function may establish the hard-to-reach state before the goal begins; the
+goal must still play the behavior under judgment normally.
+
+Handoff releases virtual input and returns the controller to the human.
+Pause, refusal, a goal that completes within one paint, blockers, and terminal
+outcomes must all narrate themselves on the Tester surface and in the play
+log.
+
+## Studio surfaces
+
+`src/contributions/` contains this game's editor panels. Contributions are ordinary
+TSX discovered by filename (`*.inspector.tsx`, `*.document.tsx`,
+`*.utility.tsx`, `*.analytics.tsx`). They export a contribution `point`, a
+`title`, and a default React component. There is no registry, declaration API,
+generated form, command vocabulary, or required section layout.
+
+Live contributions read the running mount through
+`src/contributions/use-game-modules.ts`. Never directly import a live gameplay module
+from a contribution; that would create a second module instance under the
+editor importer. Hand-type the narrow slice the surface uses and call the
+same exported functions the developer reaches through `game.run`.
+
+The `studio` addition (`game-editor create <name> --with studio`, or `--template full`)
+brings three unfinished surfaces. No other preset does, because nothing a
+project inherits may error and these three throw until they are rewritten:
+
+- Tester is the live QA cockpit: controller ownership, repertoire, current
+  goal mind and outcome, controls, setup cheats, and live judgment readings.
+- Data edits the game's authored content and mechanic parameters.
+- Analytics shows game-specific charts and metrics from the selected recorded
+  Gameplay Session, using the editor's existing playback controls.
+
+All three stubs emit `VGAI_STUB_UNIMPLEMENTED`, which makes the live console and
+`check-idioms` report remaining work. Rewrite the files whole in the game's
+vocabulary.
+
+## Analytics and gameplay sessions
+
+One Play interval is one durable Gameplay Session. The editor writes
+`logs/play-*.jsonl`, including lifecycle rows and structured game events. A
+WebM recording is also captured by CLI Play. The log itself is the session catalog, so
+sessions survive Stop and editor reload without a second manifest.
+
+`workspace.analytics` has a shared host shell: session selector, real-time
+scrub rail, current elapsed time, and optional video hover preview. The game's
+`analytics.analytics.tsx` is only the body. It receives a stable Gameplay
+Session store and deliberately receives no live `play` handle, so charts
+cannot accidentally depend on ephemeral simulation state.
+
+In a React component, `useDebugEmit` from `@volter/game-runtime/react/world-state`
+returns the event callback: `const emit = useDebugEmit()`. Call
+`emit('gem-collected', { count })` in the mechanic's collection handler; the
+editor stamps and records it. Build charts from the selected log at the shared cursor.
+
+Record motion while Play runs:
+
+```bash
+npm run --silent vgai -- eval 'return editor.recording.start({ fps: 30 })'
+# direct tester goals and advance with game.waitSimTime(...)
+npm run --silent vgai -- eval 'return editor.recording.stop()'
+```
+
+Recordings are standard WebM files under `.vgai/recordings/`. Use ordinary
+`ffprobe`/`ffmpeg` to inspect and trim them.
+
+## Game data
+
+Game rules and content are plain typed TS literals under `src/data/`, named
+for the mechanic or content they describe:
+
+```ts
+// src/data/cooling.ts
+export const cooling = {
+  baseCapacity: 120,
+  throttleAt: 86,
+} as const;
+
+export type Cooling = typeof cooling;
+```
+
+Mechanics import the literal directly. TypeScript is the schema; Vite HMR is
+the edit transport. There is no engine data format, handle, emitted schema, or
+runtime parse layer. Put derived calculations beside the data as plain
+functions, then render the useful derived columns/graphs in the Data
+contribution. A table too large to balance by hand should be generated from a
+small set of authored parameters; the generated table is build output.
+
+## UI roots
+
+A player HUD is a `dom` root in `vgai.project.json`, default-exporting an
+ordinary React component. It reads the project's own React context/store and
+uses normal React subscriptions. Do not mount a second React root from project
+code, and do not use Drei `Html` for a HUD—it is absent from clean composite
+captures.
+
+The host owns root mounting. `src/main.ts` registers the root adapters and the
+manifest supplies root identity/entry. The source component itself stays free
+of vgai runtime context.
+
+## Capabilities and assets
+
+Capabilities are optional standard libraries copied into the project. Before
+writing reusable plumbing, list what already exists:
+
+```bash
+npm run --silent vgai -- add
+npm run --silent vgai -- add <id>
+```
+
+The copied source under `src/lib/` is project-owned and editable. Use its
+native library API; do not wrap Three, Rapier, Pixi, React, Colyseus, or XState
+behind another programming model.
+
+For 3D, 2D, animation, humanoid, environment, or generated assets, load the
+matching `.agents/skills/vgai-*` skill before acting. The 3D asset floor is a
+named prefab component, a colocated story, named nodes, and inspected visual
+evidence. Provider generation must go through the provider-native skill and
+`ctx.projectOutputs.write(...)`; never spend funds by calling a provider ad
+hoc.
+
+Repeatable creative sequences are flat scripts under
+`scripts/<task>/steps/`, with a README at each meaningful step and
+intermediates under `.vgai/tmp/<task>/`. Helpers under `src/lib/<domain>/` are
+only for reusable, purely mechanical operations—not workflow runners,
+registries, or auto-judges.
+
+## Multiplayer
+
+Call Colyseus directly with typed rooms and the callbacks API. Dynamically
+import the client so single-player bundles remain clean. A multiplayer seat is
+a person; in the editor it lives in one full game instance with its own
+resident tester or a human handoff.
+
+Use one editor, not extra browser tabs or synthetic clients:
+
+```js
+await editor.instances(['host', 'guest'])
+const host = game.instance('host')
+const guest = game.instance('guest')
+```
+
+Address each instance explicitly, load its running tester module, and direct
+its tester toward the seat's goal. Keyboard focus, the Inspector's currently
+viewed instance, and the instance addressed by code are separate; never assume
+a human click retargeted the developer wire.
+
+## Live verification
+
+After every slice:
+
+```bash
+npm run check-idioms
+npm run typecheck
+npm run validate
+npm run validate-manifest
+npm run --silent vgai -- status
+```
+
+Then verify through the live editor-owned session:
+
+1. Enter Play and wait for the full mount acknowledgement.
+2. Arrange one situation through exported setup functions.
+3. Direct the resident tester toward an intent-level goal.
+4. Advance with `game.waitSimTime({ simSeconds })`; never use wall-clock
+   sleeps, rAF loops, or synthetic keyboard events.
+5. Read module state and `logs/play-*.jsonl`, one observation at a time.
+6. Look at the visible result and capture a legible screenshot. Exercise the
+   face control itself when validating a visible button.
+7. Repeat for the few varied situations that could expose the slice.
+8. Inspect hierarchy and Content: prefabs appear as prefabs, repeated
+   primitives are collapsed under their owner, and independent entities are
+   not hidden in scenery.
+9. `npm run --silent vgai -- console` must be silent. Any unresolved warning/error is
+   remaining work or must be explicitly acknowledged with an honest reason.
+10. Commit the verified slice immediately. When the arc finishes, update
+    `DEVLOG.md` with the judged result and reviewed media.
+
+Do not add automated tests, specs, or committed autoplay routes to a game
+project. The live interactive playtest is the approved proof; its play log is
+the receipt.

package/template/.agents/skills/editor/SKILL.md

@@ -0,0 +1,53 @@
+---
+name: editor
+description: Launch, control, inspect, and verify a VGAI game through its live visual editor. Use for editor sessions, Play mode, selection, hierarchy or inspector work, screenshots, status, logs, restart after setup changes, or the live playtest loop.
+---
+
+# Control the VGAI editor
+
+## Open the observable session
+
+1. Run `npm run dev` from the game project. Let it auto-open unless the run is
+   genuinely unattended CI.
+2. Tell the user the printed editor URL and keep the process running.
+3. Run `npm run --silent vgai -- status`; require `connected: true` before treating the
+   response as live state. A running server without a browser tab only has a
+   cached snapshot.
+4. Use Play mode for user-visible game runs. The standalone page
+   (`npm run dev:standalone`) serves EXPORTED builds only — until the game is
+   exported it refuses to mount, so the editor is the one surface for a game
+   in development.
+
+Always invoke the scaffold-pinned CLI as `npm run --silent vgai -- <verb>`. Never use
+a bare global `vgai` command, which may come from a different checkout.
+
+## Verify the loop
+
+- Use `play`, `stop`, `status`, and `screenshot` to observe work — selection,
+  focus, and panels go through the eval door (`npx volter-game-editor eval
+  'editor.select("<id>")'` / `editor.focus()` / `editor.showPanel(...)`);
+  edit project source directly when that is the simplest authoring path.
+- Use `restart` after init-time registrations, listeners, resources, or
+  ownership changes. Ordinary component HMR does not rerun `init()`. Its ack
+  IS the readiness guarantee (relay up, tab attached, play running); a
+  failure names the next step.
+- Playtest LIVE from first playability: exported setup functions arrange the
+  situation, the resident tester is hired through its running module, and the
+  event log is read on an interval while the run is redirected until
+  satisfied. The play log is the receipt.
+- Read persisted Play logs and visible pixels as well as state. Screenshots
+  must make the result being claimed legible.
+- **Every `npx volter-game-editor play` records video automatically** — the ack prints the
+  recording path (`.vgai/recordings/play-latest.webm`, replaced by the next
+  play; `npx volter-game-editor play --record <name>` keeps a clip forever), play auto-stops
+  after 2 idle minutes, and stopping finalizes the WebM. A claim about
+  MOTION (an effect, an animation, a stutter, anything that lives between
+  frames) is judged from that clip: find the moment via the play log's
+  event timestamps against the recording's start time, then examine at
+  least 10 frames within a ≤5-second span around it. `npx volter-game-editor screenshot`
+  while play is running refuses and points at the clip; screenshots are for
+  static states.
+
+Read [references/editor-control.md](references/editor-control.md) when exact
+CLI verbs, connection behavior, E2E exit codes, SDK methods, or worked command
+sequences are needed.

package/template/.agents/skills/editor/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Control the VGAI Editor"
+  short_description: "Operate and inspect the live VGAI editor"
+  default_prompt: "Use $editor to open, control, inspect, and verify this game in the VGAI editor."