@volter/cyclotron 0.5.211 → 0.5.213

package/LICENSE

@@ -1,9 +1,8 @@
                                   NOTICE
 
 `packages/cyclotron` is licensed under the GNU Affero General Public License,
-version 3 only, whose text follows. The capability distribution that is copied
-into users' games is not part of this package: it is
-`packages/game-editor/catalog/project-source/`, licensed MIT.
+version 3 only, whose text follows. Component-specific licenses and attribution
+are preserved in this package's NOTICE and companion license files.
 
 --------------------------------------------------------------------------
 

package/LICENSE-BLENDER

@@ -29,18 +29,19 @@ ARTWORK is not.
   provenance file and emits `blender.icons.json`.
 
   The remaining 149 glyphs are our own drawings in Blender's idiom, and
-  `contributions/blender.palette.json` is a transcription of Blender's default
-  theme colours. Neither the traced paths nor anything derived from them may
-  be copied into an Apache-2.0 or MIT part of this repository —
+  `@volter/editor-blender`'s `themes/blender.json` is a transcription of
+  Blender's default theme colours. Neither the traced paths nor anything derived
+  from them may be copied into an Apache-2.0 or MIT part of this repository —
   `packages/editor`'s own icon set included.
 
   ONE SOURCE FILE FOLLOWS BLENDER'S OWN CODE.
 
-  `contributions/blender-pose.ts` evaluates a pose as Blender does, and is
-  written from Blender's source: its damped-track constraint follows
-  `damptrack_do_transform` statement by statement, and its NLA stack, channel
-  blending, bone matrices and F-Curve evaluation follow the Blender functions
-  its header names. It is a derivative work of GPL-2.0-or-later code and,
+  `contributions/blender-pose.ts` places the NLA's strips as Blender does, and
+  is written from Blender's source: which strip a frame falls on, the action
+  frame it shows, its influence (one keyed influence F-Curve evaluated as
+  `fcurve_eval_keyframes` does) and where the active action sits follow the
+  Blender functions its header names. The pose itself is three.js's
+  (`blender-mixer-pose.ts`, the package's own licence). It is a derivative work of GPL-2.0-or-later code and,
   exercising Blender's "or later", is conveyed under the GNU General Public
   License, version 3 or later, not the AGPL. The file says so in its header.
   It may not be copied into an Apache-2.0 or MIT part of this repository.

package/NOTICE

@@ -9,11 +9,16 @@ The workbench and engine source/distribution reviews remain separate.
 
 The launcher helpers and modeling starter were transferred from the AGPL-3.0-only
 CLI and editor packages of volter-ai/volter-engine. Workbench contributions were
-transferred from its model-editor package. Provenance is recorded in editor-product.json and
-editor-workbench.json in the repository provenance directory.
+transferred from its model-editor package. The source revision is
+cf9cb8e22dd7ae5709ed0dd8a46dd6f16d1e4945.
+
+node/project-upgrade.ts, moved here from @volter/sdk's src/session/ because only this package imports it
+(docs/adr/sdk-plugin-api.md, decisions 1 and 4), is Volter AI, Inc.'s own work and is AGPL-3.0-only
+here, as product source. The @volter/sdk releases that carried it remain Apache-2.0.
 
 The Blender MCP transport and tool declarations were transferred from the
-AGPL-3.0-only CLI at the revision in provenance/editor-product.json.
+AGPL-3.0-only CLI at revision
+cf9cb8e22dd7ae5709ed0dd8a46dd6f16d1e4945.
 
 BlenderMCP tool descriptions and prompt follow ahujasid/blender-mcp,
 copyright (c) 2025 Siddharth Ahuja, MIT. The permission notice is included

package/README.md

@@ -3,16 +3,19 @@
 A free, open-source game editor by videogame.ai, built from Blender 5.2 compiled to WebAssembly, Code-OSS, three.js, TypeScript and React.
 
 ```bash
-npx @volter/cyclotron create my-race --template playable
+npx @volter/cyclotron create my-models
 ```
 
-The starter game is Canyon Comet: a three-lap kart race against five rivals through a desert
-canyon, with its Blender scene, the bpy scripts that built it, a TypeScript play script and a
-React HUD.
+The example game is Canyon Comet: a three-lap kart race against five rivals through a desert
+canyon, a volter-ai/std game with its Blender level, the bpy scripts that built it, its race
+in its room, a React HUD and win and lose bots. It is made from a checkout of
+[volter-ai/editor](https://github.com/volter-ai/editor) with the std it pins
+(`node packages/cyclotron/dist-node/cli.js create my-race --example canyon-comet`): an
+installed Cyclotron carries no std yet.
 
-Node.js 24. Without it, the one-line install at
+Node.js 26.8.1 or later. Without it, the one-line install at
 [cyclotron.videogame.ai](https://cyclotron.videogame.ai/#install) sets up everything and opens
-the same starter game.
+the editor.
 
 For a model, run `npx @volter/cyclotron` without arguments. It opens the current
 project, or prepares `~/Documents/Volter Models/Untitled Model` with a saved cube
@@ -26,25 +29,25 @@ and Chat ready. Later launches reopen that starter and preserve your edits.
 | --- | --- |
 | Editor shell | VS Code (Code-OSS) |
 | Rendering | three.js |
-| Gameplay | TypeScript — `src/models/canyon.play.ts` |
-| UI | React — `src/ui/` |
+| Gameplay | volter-ai/std — three.js, React Three Fiber, Rapier and Colyseus, in TypeScript |
+| UI | React — the game's `client/` |
 | 3D modelling | Blender 5.2 compiled to WebAssembly |
 
 ## Game and Animation
 
-The Game | Animation switch at the left of the bottom panel's header chooses what that panel is for.
-**Game** (the default for a model with a `*.play.ts` beside its `.blend`) shows the Game
-panel: Play / Stop, Pause / Resume, Step one tick, Restart, speed (0.25× to 4×) and the
-game's clock — simulation time and tick. Beside them, the **Autoplay** toggle lets the game's
-own bot drive (a play script offers one with `play.autoplay(controller)`), with a line saying
-who is driving, and the play log as it is written, filterable by kind. Autoplay is off at every
-Play and Restart, and any key or click in the game hands control back to you. A bot exists
-only once the game runs, so the panel says "Available once the game is running" while stopped
-(pressing Autoplay then arms it for the next Play) and "No autoplay — this game doesn't
-provide a bot" for a game without one. **Animation** (the default otherwise) shows Blender's
+The bottom panel is the Game panel under every document; below a model, the Game | Animation switch at the left of
+its header chooses what that panel is for. Play runs the game in the Game view, a tab that opens in front, with each
+player's page and Scene, the level live; any other tab can come in front while it runs.
+**Game** shows the Game panel: Play / Stop, Pause / Resume, Step, Restart, speed (0.25× to 4×)
+and the game's clock as std answers it. Pause, step and speed hold every player's page; a room on
+the game's dev server keeps running, as Colyseus cannot pause a room. Beside them, the
+**Autoplay** toggle lets the game's own bot (its `autopilot/` program, std's) drive the player in
+view toward one of its goals, with a line saying who is driving, and the play log as it is
+written, filterable by kind. Any key or click in the player's page hands control back to you;
+pressed while stopped, Autoplay arms the next Play. **Animation** shows Blender's
 animation editors: the Timeline, the Dope Sheet's Action Editor (pick the clip an armature
-plays) and the NLA editor. Switching to Animation leaves a running game running, and the
-editors then show what it animates, read-only. Each model keeps your choice for the session.
+plays) and the NLA editor. Switching to Animation leaves a running game running. Each model keeps your choice for
+the session.
 
 ## Your agent
 
@@ -55,12 +58,12 @@ editors then show what it animates, read-only. Each model keeps your choice for
   assets; `CLAUDE.md` imports the same instructions. For a new game, the agent
   matches a static 3D scene and React UI screenshot to the visual reference
   before implementing gameplay, including framing, palette and color management.
-- New projects include `tsconfig.json` before the editor opens, ready for TypeScript play scripts and React UI source.
+- New projects include `tsconfig.json` before the editor opens, ready for TypeScript games and React UI source.
 - From the project folder, `npx --no-install cyclotron chat status`,
   `chat send "your prompt"`, and `chat stop` control the same conversation visible
-  in the editor. `send` requests a native Chat submission; its
-  `submissionConfirmed: false` receipt does not confirm a started turn.
-  Status reports busy state and pending requests.
+  in the editor. `send` submits through the native Chat and reports in
+  `submissionConfirmed` whether that conversation's turn started; during a running
+  turn the prompt is steered into it, answered `queued`, which confirms nothing. Status reports busy state and pending requests.
 
 ## Commands
 
@@ -69,20 +72,26 @@ Run from the project folder with `npx --no-install cyclotron <command>`;
 
 | Command | What it does |
 | --- | --- |
-| `create <folder> [--template models\|playable]` | A new project. |
-| `upgrade [version]` | Moves the project's `@volter` packages and its engine pin to one release (default: latest). From a project on any earlier version, run it as `npx @volter/cyclotron@latest upgrade` (a plain `npx @volter/cyclotron` runs the project's own older version). Prints what changed and what to run next. |
-| `add-play [folder]` | Makes a `models` project playable: adds the Play and React UI dependencies, the manifest's UI root and resolution, the adapter's `regionIncludes.ui`, and — when the project has no `*.play.ts` yet — a first play script for the project's own model (its default `.blend`, or its only one): `<model>.play.ts` moves the model's first object with the arrow keys or WASD and offers Autoplay a `wander` behaviour, `game-state.ts` beside it holds what it publishes, and `src/ui/game.tsx` draws that over Play. It does not copy Canyon Comet, the `playable` template's game. Never overwrites a file; prints what it added, what it left and the next step (`npm install` when dependencies changed, then reload the editor). |
+| `create <folder> [--template models\|game\|film \| --example canyon-comet]` | A new project. `game` is a volter-ai/std game made by std's `std new`, its level laid out in code (`levels/MainLevel.tsx`) with its ground a Blender model (`prefabs/ground/ground.blend`); `--example canyon-comet` is the example game, Canyon Comet; `film` is a short film as files (`film.json`, the story, the script, the shot list, takes, boards, music, graphics and the cut), with the skills its agent follows; `npm run check` validates them with no editor open. |
+| `upgrade [version]` | Moves the project's `@volter` packages and its engine pin to one release (default: latest), and a std game's std packages onto the std this Cyclotron pins (std's own `std upgrade` packs them again). From a project on any earlier version, run it as `npx @volter/cyclotron@latest upgrade` (a plain `npx @volter/cyclotron` runs the project's own older version). Prints what changed and what to run next. |
+| `add-play [folder]` | Makes this project a volter-ai/std game: runs std's `std new` into it, moves its `src/models/*.blend` into `levels/`, and installs the game's dependencies with pnpm. Refuses a file std would write that the project already has; needs no reload. |
 | `status` \| `console` | The editor's state, and its unresolved console entries. Entries print to stderr; the command exits 1 only for an unresolved **error** — warnings alone exit 0. `eval` ends by the same rule. |
 | `eval <JavaScript>` \| `eval --list` | Runs code against the live editor; `--list` prints what is in scope and a few common tasks. |
 | `camera --position x,y,z --target x,y,z [--fov n]` | Poses the current document's viewport camera. Coordinates are Blender's: metres, Z up (the command converts them to the stage's Y up). `--fov` is the vertical field of view in degrees. |
-| `capture [--region document\|play\|page] [--name words] [--out file.png [--force]]` | Saves what the person sees as a PNG and prints its path (default `.volter/captures/[<name>-]<region>-<time>.png`). The editor shows the picture in its corner for a few seconds, captioned with `--name` when given. `document` is the active document with its overlays; `play` is the live Play frame with its UI. `--out` refuses to replace an existing file unless `--force` is given. |
-| `play [state]` \| `play play\|stop\|pause\|resume\|restart` \| `play step [count]` \| `play speed <0.25\|0.5\|1\|2\|4>` \| `play mode [game\|animation]` \| `play autoplay on\|off` | The Game panel's controls, for the model document on screen, and its state as JSON afterwards (`mode`, `playing`, the play script, and the clock: simulation `time`, `tick`, `paused`, `speed`). Pause stops the script's `update` calls; `step` runs one 1/60 s update of a paused game; speed scales the `dt` the script is handed; `restart` begins again on a fresh copy of the model. A control lands on the next drawn frame, so `play state` reads its effect. `play` and `restart` switch the document to Game mode. `autoplay on` lets the game's bot drive until a person presses a key or clicks in the game; the state's `autoplay` says `{ on, available, by, armed, driver, why }`, `why` being the reason there is no bot to switch (stopped or not yet running, or no bot), which a refused `autoplay on` prints too. Under `eval` the same commands are `await editor.command('volter.model-play.pause')`, `…('volter.model-play.speed', { speed: 2 })`. |
+| `capture [--region document\|play\|page] [--name words] [--out file.png [--force]]` | Saves what the person sees as a PNG and prints its path (default `.volter/captures/[<name>-]<region>-<time>.png`). The editor shows the picture in its corner for a few seconds, captioned with `--name` when given. `document` is the active document with its overlays; `play` is the live Play frame: a std game's player, its game with its HUD, as its page captures itself. `--out` refuses to replace an existing file unless `--force` is given. |
+| `play [state]` \| `play play\|stop\|pause\|resume\|restart` \| `play step [count]` \| `play speed <0.25\|0.5\|1\|2\|4>` \| `play players [1-8]` \| `play mode [game\|animation]` \| `play autoplay on\|off` | The Game panel's controls, for the project's game whatever document is in front, and its state as JSON afterwards (`mode`, `playing`, the game's script, and the clock: `time`, `tick`, `from`, `paused`, `speed`; held, `from` is `std-answer` and `time` and `tick` are std's exact answer to the pause or step, `tick` its frame; running, `from` is `newest-traced-step` and `tick` is the newest step the viewed player's page traced, sixty a game second, `time` that step in seconds, which holds while that page traces nothing). Pause stops the game's updates; `step` runs one 1/60 s update of a paused game; speed scales the time the game is handed; `players` is how many players a std game's Play starts, yours and a bot for each other: the project's `volter.play.players`, which it sets (one unless set; a running game's players join or leave to match); `restart` begins the game again with its level read afresh. A control lands on the next drawn frame, so `play state` reads its effect: a pause's or step's clock exactly. `play` opens the Game view and `stop` closes it; `play mode` is a model's Game or Animation. `autoplay on [<goal>]` plays the goal with the game's bot in std's own play, to its end, on the viewed player's page while the Game view is on screen and out of view on std's headless device while it is not, and `autoplay off` ends it, as the Game panel's Autoplay does; the state's `autoplay` says `{ on, driving, available, armed, driver, state, report, why }`, `on` while std's play of a goal plays wherever it plays and `driving` while it drives the player in view, `state` being std's play's (`<goal>: playing`, `achieved` or `failed — why`, `headless ` before it out of view, then how the goal's checks went as std said it: `· checks of <goal>: 2 passed (…)`, `· …: 1 of 2 failed (…)` or `· …: none ran (…)`; the report's `checks.verdict` is `none`, `passed` or `failed`), `report` its report's file, and `why` the reason there is no bot to switch (stopped or not yet running, or no bot), which a refused `autoplay on` prints too. Under `eval` the same commands are `await editor.command('volter.play.pause')`, `…('volter.play.speed', { speed: 2 })`. |
 | `screenshot [<target>]` | The active document's render, or a model file or entity staged on its own. |
+| `export component <file.blend> [--force]` | Exports a component `.blend` with Blender's own glTF exporter, in the editor's Blender, as `.volter/export/components/<name>.glb`: Y-up, every action as an animation, `Notes` and `References` left out (the component format Play reads, `packages/play/README.md`). A manifest beside it (`<name>.json`) records the `.blend`'s and the file's SHA-256 and the exporter's version and settings; an unchanged `.blend` is not exported again unless `--force` is given. The editor opens the file and returns to the document it was showing. |
+| `export level <file.blend> [--force]` | Exports a level `.blend` as `.volter/export/levels/<name>.glb`: its own objects, a placement marker for each linked component (`extras.component`, `extras.action`, `extras.tint`, visibility) and its timeline as one scene animation plus `extras.timeline` (RFC 0007 §2–3). Then exports, or confirms current, every component its markers name. |
+| `export web\|roblox\|unreal [folder]` | Exports a std game by its own std in its folder, as the Game panel's Export does: `web` is its `std build` (its page and its room's server, into `dist/`); an engine is its `std export --target <engine>`, which refuses an engine that is not one of the game's targets, naming `std target add <engine>` (a game is built for an engine only once it is added). |
+| `render-movie --out <file>.webm [--composition <story>] [--from <marker\|frame>] [--to <marker\|frame>] [--width <px>]` | Renders the scene's Timeline through Blender's VOLTER_THREE engine and encodes a WebM in the editor tab, with the scene's sound (its sound strips and speakers) mixed in sync as an Opus track. Uses the scene's frame range, frame rate, camera cuts and resolution unless overridden. `--composition` renders a UI story that reads `useMovieFrame()` and declares `parameters.volter.movie`, frame by frame; `--from` and `--to` are then its frames. |
 | `chat status` \| `chat send "<prompt>"` \| `chat stop` | The editor's Chat conversation. |
 
 ## The editor's address
 
-`edit` prints `http://editor-<id>.localhost:<port>/?project=<name>`: each project has its own
+`edit` prints `http://editor-<id>.localhost:<port>/?project=<name>&tkn=<token>` (`tkn` is the project's connection
+token, which the page's first load keeps in a cookie; the editor refuses a request that carries neither, and its
+session also refuses one whose Host is not one of its own): each project has its own
 host (a stable hash of its folder), and `http://127.0.0.1:<port>/` redirects there. A tool that
 drives the editor in a browser should bind that printed host and reuse its tab. Binding
 `127.0.0.1:<port>` opens a fresh tab each time, the editor yields the previous one, and tabs pile