@volter/play 0.5.210 → 0.5.212

package/NOTICE

@@ -4,9 +4,9 @@ This package is developed in the public volter-ai/editor repository and is
 Volter AI, Inc.'s own work. It was first published under AGPL-3.0-only and is
 licensed under Apache-2.0 from this notice on. The owner's words are "the
 runtime should be apache, the editor is agpl"; that this package is runtime
-(the play-script API a game's gameplay is written against) is the reading
-recorded as ruling D336 on board task t_b315eb39 and in COMMERCIAL.md at the
-repository root. LICENSE contains the Apache-2.0 text.
+is the reading recorded as ruling D336 on board task t_b315eb39 and in
+COMMERCIAL.md at the repository root. LICENSE contains the Apache-2.0 text.
 
-A play script is written against `src/play-script.ts`. The package imports
-`@volter/sdk` (Apache-2.0), three and React, and nothing of Blender.
+The package imports `@volter/sdk` (Apache-2.0), three and React, and nothing of Blender. A game it plays is a
+volter-ai/std game (Apache-2.0; the Blender scripts std ships are GPL-3.0-or-later), whose packages are the game's own
+dependencies: this package runs the game's own commands and pages and carries none of std's code.

package/README.md

@@ -1,185 +1,138 @@
 # Play
 
-Play scripts on detached model documents. Play (the Game panel's, in Cyclotron) runs
-`src/models/<name>.play.ts` beside `src/models/<name>.blend` on a detached copy
-of the model; the model, its selection and its history stand as they were, and
-Stop returns to them. The script's default export is called once with the play
-context (`ModelPlayContext`, `src/play-script.ts`) and answers the game:
-
-```ts
-import type { ModelPlayContext, ModelPlayGame } from '@volter/play/play-script';
-
-export default (play: ModelPlayContext): ModelPlayGame => {
-  const player = play.find('Player')!;
-  let checkpoint = false;
-  return {
-    update(dt) {
-      player.position.y += dt;
-      if (!checkpoint && player.position.y > 10) {
-        checkpoint = true;
-        play.tint('Checkpoint.Pad', '#2bff6b');
-        play.log('checkpoint', { stage: 2, at: player.position });
-      }
-    },
-  };
-};
-```
+A Cyclotron game is a [volter-ai/std](https://github.com/volter-ai/std) game: three.js, React Three Fiber, Rapier and
+Colyseus, used as their own docs describe them, with std adding only what they lack. This repository pins std as
+`external/std`. Play runs the game itself, on its own dev server: each player is one of the game's pages, a std device,
+standing in the model document's stage.
+
+## A std game
+
+A project with `std.json` that depends on `@volter-ai/std-dev` is a std game (`src/std-game.ts` asks the session,
+`serving/std-dev.ts`). `cyclotron create --template game` makes one with std's own `std new`; `cyclotron add-play`
+runs `std new` into an existing project and moves its `src/models/*.blend` into `levels/`. Either installs the game's
+dependencies with pnpm, as std's README does; the editor hears `std.json` arrive and needs no reload.
+
+Pressing Play on a level saves its `.blend` first (editor-blender's `modelDocument.flush`) and waits for std's export of
+it (`src/std-level.ts`), so the game plays the current edit. Play then starts the game's dev server where none runs
+(`npm run dev -- --no-open`, owned by the session and ended with it), finds it by the record std writes in Vite's
+cacheDir (`node_modules/.vite/std-dev.json`, whose token stays in the session), and stands each player in the stage
+as an iframe.
+
+- **The view bar**, over the viewport: Edit, Player N (each "you" or "autopilot"), Grid (Edit and every player tiled,
+  each player's tile its whole view scaled down, as its page lays out at the stage's size in every view; a tile clicked
+  opens it) and Players [-][+], each one a client joining or leaving. Edit brings the level's own area
+  back, live for editing, while the game runs on.
+- **The keys** 1 to 4 open Player N, Tab the next view and Escape Edit (Escape in Edit stops the game), whenever the
+  editor holds the keyboard: in Edit, in Grid, or after a press on the view bar. A viewed player's page holds the
+  keyboard, and its keys, 1 to 4 included, are the game's, as Unity's Multiplayer Play Mode and Unreal's Play In
+  Editor treat a focused game window.
+- **Each player's page** is told apart by the slot its address names (`?slot=<run>-<n>`), which its trace's first
+  line says; a page that loads again is found again by it. A player whose page never joins is taken out, and its
+  failure stands.
+- Play, Stop and Restart load, unload and reload the pages.
+
+## std's device controls
+
+Every word Play says to a player's page is one of std's device controls (`POST /__std/devices/<id>/control`), sent
+through `src/std-controls.ts` and the session's route, which holds the dev server's token:
+
+| Control | What Play uses it for |
+| --- | --- |
+| `clock` (`pause`, `resume`, `step`, `speed`) | The Game panel's pause, step and speed, sent to every joined player's page; the panel shows the clock std answers |
+| `autoplay`, `manual` | Who drives the viewed player: its bot, with its slot and goal, or the person |
+| `inspect` | `editor.inspect` while a player is in view: the page's live three.js objects and labelled screen nodes |
+| `act` | `editor.document.key` with no selector, and `editor.document.click('role=<role>[name="<name>"]')` (the page's labelled node pressed at its middle), while a player is in view: std-driver/2 actions through the page's own input |
+| `capture` | `capture --region play`: the viewed page's next frame, written by std's receiver |
 
-## The play log
+`editor.document.query` answers the editor's DOM as always and, beside it, the viewed page's labelled nodes
+(`framed`; `@volter/sdk/framed-document-driver`). A refusal is std's own answer, shown with its words.
 
-`play.log(kind, facts?)` writes one entry, stamped with `simT` (seconds of
-simulation since Play started, the sum of the `dt`s given to `update`) and
-`tick` (the update in progress). Facts are snapshotted as JSON when logged. `simT` and `tick` are the Game panel's
-clock: they stand still while paused and run at the speed (see Time below). The
-runner adds `play-start`, `play-restart` (`{ speed }`, right after a Restart's
-`play-start`), `script-reload` (`{ reason: 'saved' | 'dependency-deleted', path }`),
-`script-error` (`{ phase, message }`), `tint-unsupported` (`{ object, material, why }`),
-`tint-unknown-object` (`{ object, call }`, once per name: `tint` or `setOpacity` was given a
-name the model has none of, and did nothing), `autoplay-on` / `autoplay-off`
-(`{ by: 'panel' | 'cli' | 'takeover' | 'script' }`, see Autoplay below),
-`autoplay-unavailable` (`{ why }`, when a script's first update has run and it registered no
-bot; once per run, and again only if a bot came and went),
-`pause`, `resume`, `step` (`{ dt }`, one per stepped update), `speed`
-(`{ speed, from }` on a change; `{ speed }` at a start that is not 1×) and
-`play-stop` (`{ reason }`). Log transitions rather than every frame. Logging
-never throws and never changes timing or state; a script's `log`, `tint` and
-`setOpacity` do nothing once it has been replaced or Play has stopped.
-
-Each model document keeps its own log; a read takes the active Play's unless it
-names a document. The newest 5000 entries are kept (older ones are counted as
-`dropped`), each entry's facts up to 2048 characters of JSON. Play from a fresh
-copy, and Restart, empty the document's log; a script reload does not, and the log stays readable after Stop until the
-next Play. `console.log` does not reach the session's console feed (only
-warnings and errors do); the play log does.
+The clock holds the pages. A room on the dev server runs on: Colyseus has no pause for a room, so a timer a room runs
+keeps running while the pages are paused.
 
-```sh
-cyclotron play-log                     # every kept entry, one per line
-cyclotron play-log --kind death        # one kind
-cyclotron play-log --since 12.5 --json # entries at or after simT 12.5, as JSON
-cyclotron play-log --document <id>     # another model document's log
-cyclotron eval "(await editor.modelPlayLog({ kind: 'death' })).entries"
-```
+## Autoplay
 
-## Recolouring the copy
-
-`play.tint(object, color)` draws an object (a name, or what `find` answered)
-and every mesh under it in `color`; an emitting surface glows in it, and an
-image texture is multiplied by it. `play.setOpacity(object, opacity)` fades it.
-`null` returns the authored look. Other objects wearing the same Blender
-material are not affected.
-
-Use these instead of editing materials directly: a presented mesh's `material`
-is an array with one `MeshPhysicalMaterial` per Blender material slot, shared by
-every object with that material; the presenter re-assigns those slots whenever
-it re-applies shading; `clone()` drops its shader hooks; and a node graph that
-drives Base Color or Alpha ignores `color` and `opacity`. A tinted or faded
-object wears copies of its own slots that draw the material's constant inputs
-(so a node graph's other inputs are not drawn while it does), and keeps them
-across a script reload. An object with a material the document cannot copy
-(one the script made itself) is left as it is, and the log says so once with
-`tint-unsupported`.
+The game's bot is its own program, `autopilot/index.ts`, whose goals are named by words (std's `autopilot({ goals })`).
+Play lists them from the session's route `/__editor/play/std/goals`, which loads that program in Node as std does.
+The Game panel's Autoplay turns the viewed player's bot on with the goal the panel picks, and armed while stopped turns
+it on as the run starts; the person's own key or click in its page takes over. `cyclotron play autoplay on [<goal>]` is
+std's own headless play of that goal (`/__std/play`): its bot pages, out of view, play the goal to its end whether or not
+the editor is seen, the viewed player and the panel's goal untouched, and `play state`'s `autoplay.state` and the play
+log's `autoplay-end` say how it ended. Every other player is a bot from the start.
 
-## Autoplay
+## The play log
 
-A game offers its bot; the editor decides whether it drives.
+Each player's page traces its run (std's trace, `build/runs/<run>/<page>.jsonl`), and the run reads each trace into
+the document's play log, each entry tagged with its player's slot (`source: 'script'`). Play adds its own entries
+(`source: 'play'`): `play-start`, `running`, `player-joined`, `player-page-loaded`, `player-left`, `view`,
+`autoplay-on` and `autoplay-off` (with `by`), `pause`, `resume`, `step` and `speed` (each with the clock std answered),
+`capture`, `script-error` (with its `phase`) and `play-stop`. Entries carry the run's clock as std last answered it.
 
-```ts
-play.autoplay(({ dt, simT, tick, keys }) => {
-  // the game's own decision, from its own state
-  return car.speed < 20 ? ['ArrowUp'] : [];
-});
-```
+A room's exceptions are not in any page's trace: Colyseus logs them on the dev server's error output (stderr), with
+Vite's errors and warnings. Of a dev server Play started, each run reads that output from the run's start
+(`/__editor/play/std/errors`) in blocks, a line and the indented lines under it: a block that names an `Error` or
+carries a stack is a `script-error` with the phase `server` and an error in the console, once by its first line; any
+other is a `server-output` entry.
 
-The controller is a plain function. While autoplay is on it is called before each `update`
-with that update's `dt`, `simT` and `tick` (the stamps that update's log entries carry) and
-`keys`, the keys the person holds; it returns the `KeyboardEvent.code` keys the bot holds for
-that update (any iterable, or nothing). The runner merges them into `play.keys`, so the bot
-drives through the script's own input code exactly as a person does. One bot per script:
-registering again replaces it, `play.autoplay(null)` withdraws it, and it goes with the script
-on a reload or Stop. The bot is called only inside the editor's Play runner; a game run
-anywhere else never drives itself.
-
-Whether it drives is the editor's:
-
-- Autoplay is **off** whenever Play starts or restarts.
-- Only the Game panel's **Autoplay** toggle, `cyclotron play autoplay on|off` or
-  `await editor.command('volter.model-play.autoplay', { on: true })` turn it on (or off).
-- **A bot exists only while the game runs**: `play.autoplay` is called by the play script, so
-  a stopped game (or one still starting) has none, and neither has a running script that never
-  registers one. The panel says which, in words beside the toggle — "Available once the game is
-  running" or "No autoplay — this game doesn't provide a bot" — and `on` is refused with the
-  same reason, which `play state` also gives as `autoplay.why`.
-- **Arming.** Pressed while stopped, the panel's Autoplay arms the next start: autoplay turns
-  on (`by: 'panel'`) as soon as that run's script has run its first update with a bot, and the
-  arm is dropped if it offers none. A person's key or click in the game before then drops it
-  too (`autoplay-off` with `{ by: 'takeover', armed: true }`): the person always wins. Only an
-  explicit arm carries over; Stop, and closing the model, drop it.
-- **The person always wins.** A new key press the game would hear, or a pointer pressed in the
-  game's area (the HUD included), turns autoplay off before that key reaches `play.keys`, and
-  the panel reads "You're driving" until someone switches the bot on again. Synthetic keys and
-  clicks (`editor.document.key`, `click`) count as a person's: they are how an agent plays by
-  hand. A key repeat is not a new press; keys typed in a text field, or while the game's surface
-  does not hold the keyboard, are not the game's and do not take over.
-- A bot that throws turns autoplay off (`by: 'script'`, with a `script-error` of phase
-  `autoplay`), as does a reload whose script offers no bot.
-
-Each change is a play-log entry, `autoplay-on` or `autoplay-off`, with `by`.
-
-## Time
-
-`update(dt)` is the only clock a play script is given, and the editor decides it:
-
-| Control | What the script sees |
-| --- | --- |
-| Playing at 1× | One `update` per drawn frame, `dt` = the frame's seconds (at most 0.1). |
-| Speed 0.25× – 4× | `dt` scaled by the speed. A scaled frame longer than 0.1 s is split into equal updates, so no single `dt` exceeds 0.1. |
-| Pause | No `update` at all. The copy, the camera and the HUD hold the last frame. |
-| Step (while paused) | One `update` with `dt` = 1/60. |
-| Restart | The run begins again on a fresh detached copy, the clock at zero, without the camera's fly-in. |
-
-A script that reads the page's own clock (`performance.now()`, `Date.now()`) instead of
-summing `dt` is outside the reach of pause and speed.
-
-The run's clock — simulation time (the sum of the `dt`s handed to the script) and tick (the
-number of updates) — is kept per document beside whether it plays (`src/model-play.ts`).
-Speed is kept for the page's life; pause and the clock reset on every Play.
-When the run plays but no game runs — the script failed to start, or threw — the clock's
-`failure` says why (the Game panel shows it in place of "Playing"); a save of the script
-retries, and the next running game clears it.
+One log per model document, each its latest run's; each Play replaces it, and it outlives Stop. The newest entries are
+kept in a bounded ring (older ones counted as `dropped`). `console.log` does not reach the session's console feed;
+the play log does.
+
+```sh
+cyclotron play-log                     # every kept entry, one per line
+cyclotron play-log --kind coin         # one kind
+cyclotron play-log --since 12.5 --json # entries at or after 12.5 s, as JSON
+cyclotron play-log --document <id>     # another model document's log
+```
 
 ## Controls
 
-The tool registers the `model` document Play extension
-(`@volter/sdk/kit/document-play-extension`). Beside Play and Stop it offers:
-
-- `transport` — `setPaused`, `step`, `setSpeed`, `restart`, the `clock` and its own
-  subscription, the offered `speeds`, and the restart `generation` the document keys its
-  detached copy on.
-- `transport.autoplay(documentId)` and `transport.setAutoplay(documentId, on, by)` — the bot's
-  switch: `{ on, available, by, armed }`, announced through `subscribeClock`;
-  `transport.armAutoplay(documentId, armed)` arms it, while stopped, for the next start.
-- `log` — `tail(documentId, last, kind?)` (the newest entries and every kind the run wrote) and
-  `subscribe`, which the Game panel draws live.
-- `scriptPath(sourcePath)` and `hasScript(sourcePath)` — where a model's play script goes and
-  whether it exists, so a layout can open a model with a script as a game.
-
-In Cyclotron these are drawn by the Game panel (`@volter/editor-blender`): the Game /
-Animation switch at the left of the bottom area's header puts it there in place of the Timeline. The panel's controls
-are also commands, `volter.model-play.<verb>`, so an agent drives the same run the person
-sees:
-
-| Command | Arguments |
-| --- | --- |
-| `volter.model-play.state` | — |
-| `volter.model-play.play` / `stop` | — (`play` also switches the document to Game mode) |
-| `volter.model-play.pause` / `resume` | — |
-| `volter.model-play.step` | `{ count?: 1–600 }`, while paused |
-| `volter.model-play.speed` | `{ speed: 0.25 \| 0.5 \| 1 \| 2 \| 4 }` |
-| `volter.model-play.restart` | — |
-| `volter.model-play.mode` | `{ mode?: 'game' \| 'animation' }` |
-| `volter.model-play.autoplay` | `{ on: boolean }` — the game's bot drives, or the person does |
-
-Each takes an optional `document` (the model document's id) and otherwise acts on the model
-document on screen; each answers with the panel's state. From the shell:
-`cyclotron play pause`; under `eval`:
-`await editor.command('volter.model-play.speed', { speed: 0.5 })`.
+The model document's Play is registered through editor-blender's API (`registerModelPlay`) from play's page half
+(`contributions/play.page.tsx`), and drawn by play's Game panel in the bottom area. The panel's controls are also
+commands, so an agent drives the same run the person sees: `cyclotron play play|stop|pause|resume|restart`,
+`play step [count]`, `play speed <0.25|0.5|1|2|4>`, `play mode [game|animation]` and `play autoplay on [<goal>]|off`,
+each answering with the panel's state.
+
+A std game's Export (the panel's button and menu; `volter.model-play.export { target, add? }` under `eval`) builds the
+game for the web (`std build`, into `dist/`) or exports it to an engine (`std export --target <engine>`). An engine not
+yet one of the game's targets is offered as "Add Roblox and export", which adds it first (`std target add <engine>`: its
+package installed, its `std.json` settings and its scripts); the verb refuses one unless `add` is true. A game is built
+for an engine only once someone asks for it, as an engine's editor builds for a platform once it is chosen. Each line
+std prints goes to the console, and the panel says how the export stands and where it is.
+
+## A std game's editor
+
+A std game carries no editor code. Play supplies its adapter (`src/std-game-adapter.ts`, declared in
+`contributes.volter.projectAdapters` for a project with `std.json`): Blender's layout, keymap and properties inspector,
+with every `.blend` under `levels/` as a document. A project's own `editor/volter.adapter.ts` wins over it.
+
+## A level's export
+
+Each save of a level's `.blend` (`levels/**/*.blend`) runs std's level export, its two halves as std states them. The
+Blender half, std-dev's `blender/blend-to-scene.py`, is the save's own script (editor-blender's
+`modelDocument.setSaveScript`): it runs in the save's turn, on the very scene that save wrote, and the save's answer
+carries the files it wrote (`levels/<name>.glb`, its description, a copied sky image, a baked `<name>.view.cube`).
+Then, one save after another, those files are carried into the project and the Node half,
+`std level <levels/name.glb> --description <levels/name.level.json>`, runs in the game's folder at the session route
+`/__editor/play/std/level`, by the game's own std, and writes `<Name>Level.tsx`, `<name>.canvas.ts`, the environment
+and grading. std's dev server takes the level by its own hot reload. Both halves' output is the console's
+(`std-level`); a half that fails is an error there.
+
+The game's `prefabs/` folder is a Blender asset library named Prefabs whose import method is Link
+(editor-blender's `setAssetLibrary`), so a prefab dragged from it is linked, not appended.
+
+## A level's Scene view
+
+"Play: Open Scene View" (`volter.std-scene { level? }`) opens the std level whose `.blend` was active last, or the
+`levels/<name>.blend` it names, drawn as the game draws it: its generated component, its environment, its canvas's tone
+mapping and shadows and its view transform, with the game's own React Three Fiber, react-three-rapier and std, in
+editor-threejs's viewport (`contributions/std-scene.document.tsx`; its module, `/@volter-std-scene/<levels/name.blend>`,
+is `serving/std-scene.ts`). Overlays draws colliders and sensors and signs each std marker with its name. The view edits
+nothing: the `.blend` is the level's source, and the view draws the level again as each save exports it
+(`docs/adr/std-scene-view.md`).
+
+## Outside the editor
+
+`cyclotron export web|roblox|unreal` runs the game's own `std build` or `std export --target <engine>`, which refuses an
+engine that is not one of the game's targets, naming `std target add` (std's guide,
+`node_modules/@volter-ai/std-dev/docs/03-targets.md`).