@volter/play 0.5.211 → 0.5.213

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,169 @@
 # 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 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
+
+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.
+
+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.
+- 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/3 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.
+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.
 
-## 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 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`. 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.
 
-```ts
-play.autoplay(({ dt, simT, tick, keys }) => {
-  // the game's own decision, from its own state
-  return car.speed < 20 ? ['ArrowUp'] : [];
-});
+```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
 ```
 
-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.
-
 ## 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 })`.
+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.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/` 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
+
+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-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 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 document
+
+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 in
+`node_modules/@volter-ai/std-dev/docs/`, "Targets").