@volter/cyclotron 0.5.212 → 0.5.213

package/README.md

@@ -35,7 +35,9 @@ and Chat ready. Later launches reopen that starter and preserve your edits.
 
 ## Game and Animation
 
-The Game | Animation switch at the left of the bottom panel's header chooses what that panel is for.
+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
@@ -70,14 +72,14 @@ Run from the project folder with `npx --no-install cyclotron <command>`;
 
 | Command | What it does |
 | --- | --- |
-| `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 a Blender file (`levels/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). 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. |
+| `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: 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 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 level's game, and the clock: simulation `time`, `tick`, `paused`, `speed`). 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; `restart` begins the game again with its level read afresh. 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 [<goal>]` plays the goal with the game's bot in std's headless play, out of view, to its end, and `autoplay off` ends it (the Game panel's Autoplay drives the player in view); the state's `autoplay` says `{ on, available, by, armed, driver, state, why }`, `state` being the headless play's (`<goal>: playing`, `achieved` or `failed — why`) 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.model-play.pause')`, `…('volter.model-play.speed', { speed: 2 })`. |
+| `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. |
@@ -87,7 +89,9 @@ Run from the project folder with `npx --no-install cyclotron <command>`;
 
 ## 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