@volter/play 0.5.212 → 0.5.213

package/README.md

@@ -2,8 +2,8 @@
 
 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.
+`external/std`. Play is the project's, as an engine's Play button is, whatever document is in front: it runs the game
+itself, on its own dev server, each player one of the game's pages, a std device, in the Game view.
 
 ## A std game
 
@@ -12,20 +12,35 @@ A project with `std.json` that depends on `@volter-ai/std-dev` is a std game (`s
 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.
+The project opens on its main level (`levels/MainLevel.tsx`, else the level last worked on), a document that stays
+the level as authored. Play, in the Game panel under every document, saves the edit Blender holds 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 (`src/game-controls.ts`). It then opens the Game view (`src/game-view.tsx`) as a tab of the editor,
+in front, 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 Game view as an iframe. Another tab in front never stops the game; Stop, or the
+Game view closed, does, and brings back the tab that was in front. The players' pages draw in the Game view's
+retained layer (`@volter/sdk/document-layer`), mounted in the workbench's container and laid over the Game view's box
+while that box is shown (hidden, and its pages throttled, while it is not), as Code-OSS keeps a webview that retains
+its context: a tab's box is parked out of the page while it is behind another, and a frame moved with it would load
+again.
+
+- **The view bar**, at the top of the Game view: Scene, Player N (each "you" or "autopilot"), and Grid (Scene and every
+  player tiled, each player's tile its whole view scaled down, as its page lays out at the view's size in every view;
+  a tile clicked opens it).
+- **Scene** is the current level (the level document in front last) live: the same level view, drawn again in the Game
+  view and put each frame on the game's running scene, read where it runs (std-dev's `GET /__std/scene`, through
+  `GET /__editor/play/std/scene`: the world the game's server runs, else the scene the viewed player's page renders, a
+  game of one player's among them) by std's node put (`contributions/std-level.document.tsx`'s `useRunningScene`,
+  `serving/std-scene-runtime.js`'s `SceneNodes`); an object the copy lacks (a character) stands as an empty of its name.
+  The level's own document stays the level as authored, beside it.
+- **Players [-][+]**, in the Game panel beside Play: how many play, the project's setting `volter.play.players` (one
+  where it is unset), which it writes to the project's settings; a running game's players join or leave to match
+  whenever the setting changes.
+- **The keys** 1 to 4 open Player N and Tab the next view, while the Game view is in front and the editor holds the
+  keyboard: in Scene, 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.
@@ -41,7 +56,7 @@ through `src/std-controls.ts` and the session's route, which holds the dev serve
 | `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 |
+| `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/3 actions through the page's own input |
 | `capture` | `capture --region play`: the viewed page's next frame, written by std's receiver |
 
 `editor.document.query` answers the editor's DOM as always and, beside it, the viewed page's labelled nodes
@@ -54,27 +69,40 @@ keeps running while the pages are paused.
 
 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 Game panel's and `cyclotron play autoplay on [<goal>]` alike, is std's own play of a goal
+(`/__std/play`), recorded and checked, on the device std's play takes where one is linked: the viewed player's page
+while the Game view is on screen, which std drives as it is and hands back to the person as the goal ends, and std's
+headless device otherwise (the editor not seen, or the Game view behind another tab; an agent's, or an arm's, also
+while no player is viewed, where the panel's waits for one). The person's
+own key or click in the page takes it over, which ends the goal there, failed, as Autoplay off does; armed while
+stopped, Autoplay plays as the run starts. One plays at a time. `play state`'s `autoplay.state` (with how the goal's
+checks went, as std said it) and the play log's `autoplay-end` say how it ended; `autoplay.report` is its report.
+Every other player is the game's bot from the start, playing the run's goal.
 
 ## The play log
 
 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
+the 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.
-
-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.
-
-One log per model document, each its latest run's; each Play replaces it, and it outlives Stop. The newest entries are
+`capture`, `script-error` (with its `phase`) and `play-stop`. A page's entry carries its trace's step as `tick`
+(std's trace format 3, `s`: sixty a game second from the trace's start, since std's live clock is the page's
+`performance.now`) and that step in seconds as `simT`; Play's own carry the run's elapsed seconds and the newest step
+heard. A page writes a trace line only as something happens on it (an input, a word said, its bot's intent; a clock
+control writes none), so its step is when it last traced, not its clock now. `play state`'s clock says which reading it
+gives (`from`): while the game is held, `std-answer`, std's exact answer to the `pause` or `step`, the same clock its
+play-log entry records; while it runs, `newest-traced-step`, the newest step the viewed player's page traced, which
+holds while that page is idle. After Stop it keeps the run's last reading and its `from`, with `running` false, so
+`play state` still says how far the run got (the panel says only that it stopped).
+
+What a room says is not in any page's trace: the room runs in the dev server's process, so its own `console.log` is on
+that server's stdout, with Vite's notices, and the exceptions Colyseus logs on its stderr, with Vite's errors and
+warnings. Of a dev server Play started, each run reads both streams from the run's start (`/__editor/play/std/output`),
+each kept apart: each stdout line is a `server-output` entry; stderr is read in blocks, a line and the indented lines
+under it, and 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 a `server-output` entry.
+
+One log, the 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.
 
@@ -82,18 +110,17 @@ the play log does.
 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 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's page half (`contributions/play.page.tsx`) registers its Game panel through editor-blender's API
+(`registerPlay`), whose bottom area shows it under every document, and below a model in its Game mode (a model's
+Animation mode is Blender's animation editors). The panel's controls are also commands (`volter.play.<verb>`), 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
+A std game's Export (the panel's button and menu; `volter.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
@@ -104,7 +131,8 @@ std prints goes to the console, and the panel says how the export stands and whe
 
 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.
+with every `.blend` under `levels/` and `prefabs/`, and each level, as a document, the main level the one it opens
+on. A project's own `editor/volter.adapter.ts` wins over it.
 
 ## A level's export
 
@@ -113,26 +141,29 @@ Blender half, std-dev's `blender/blend-to-scene.py`, is the save's own script (e
 `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
+`std level-scene <levels/name.glb>`, 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.
+and grading. std's dev server takes the level from there, its rooms reloaded by Colyseus's own dev mode. 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
+## A level's document
 
-"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`).
+A level is the document an engine opens. Each level component, `levels/<Name>Level.tsx`, is a document of its own
+(`std-level`, listed by `contributions/levels.finder.ts`), named as its component is less `Level` (`MainLevel` is Main)
+and drawn as the game draws it, by its own component and the game's own React Three Fiber, react-three-rapier and std,
+in editor-threejs's viewport (`contributions/std-level.document.tsx`; its module, `/@volter-std-scene/<source>`, is
+`serving/std-scene.ts`). Its
+source is its own code, or the `levels/<name>.blend` std's export writes it from (a Blender level's environment, canvas
+and grading drawn with it), which stays the Blender document it is authored in. Overlays draws colliders and sensors
+and signs each std marker with its name. The view edits nothing, and draws the level again as anything it depends on
+changes (`docs/adr/std-scene-view.md`). It is the level as authored, while the game runs too; the Game view's Scene is
+the same view, live.
 
 ## 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`).
+engine that is not one of the game's targets, naming `std target add` (std's guide in
+`node_modules/@volter-ai/std-dev/docs/`, "Targets").