@volter/cyclotron 0.5.211 → 0.5.213

package/starter/AGENTS.md

@@ -15,9 +15,8 @@ Your first minute:
 1. Say in Chat, in a sentence or two, what you are going to build.
 2. Open the document you will work in and frame it:
    `npx --no-install cyclotron camera --position x,y,z --target x,y,z`
-   (Blender metres, Z up). For a game in a models-only project, run
-   `npx --no-install cyclotron add-play` first, then `npm install`,
-   and reload the editor once as `add-play` says, before your first build step.
+   (Blender metres, Z up). For a game in a project with no `std.json`, run
+   `npx --no-install cyclotron add-play` first (Working games, below).
 3. Put the plan beside the work (`Build Notes`, below) with the current step.
 4. Check what the person sees: `npx --no-install cyclotron capture --region document`.
 
@@ -44,11 +43,12 @@ but keep it short between visible steps. Throughout:
   Blender Text data-block named `Build Notes` with a fake user, and keep a
   readable copy beside the work as Text objects in a `Notes` collection (a
   text buffer alone is not visible in the viewport). Include the current step,
-  pending steps, and verified completed steps with their times; update both at
+  pending steps, and verified completed steps; update both at
   real milestones and preserve them across rebuilds and reopening. Keep notes
-  out of the intended shot, renders, exports and gameplay, and verify that in
-  the actual output (`hide_render` alone does not exclude an object from every
-  path).
+  out of the intended shot, renders, exports and gameplay: disable the `Notes`
+  collection in renders (`collection.hide_render = True`), which keeps them on
+  screen and, in a std game, out of the level std exports. Verify that in the
+  actual output.
 - Check what they actually see in captures: framing, the reference and the
   notes visible together before the first substantial build and again before
   each substantial step, and text legible at normal size (adjust its size,
@@ -71,30 +71,24 @@ Replace unused scaffold placeholders as the requested result calls for.
   and the intended viewpoints; add cameras when the requested shot needs them.
   A game-like reference can describe a static scene. Implement playable behavior
   when the user asks for a working game or interactive mechanics.
-- **A level and its pieces:** the level's `.blend` is the environment
-  (terrain, mountains, rocks, scatter). Each piece with its own identity, such
-  as a character, creature, vehicle, building or key prop, is its own `.blend`
-  with one collection and object names of its own (named for the piece),
-  linked into the level rather than copied, as in a Blender production. Make
-  a piece's file as Blender does, in one script:
-  `bpy.ops.wm.read_homefile(use_empty=True)`, build it, then
-  `bpy.ops.wm.save_as_mainfile(filepath=<project>/src/models/<piece>.blend)`.
-  It opens as its own document; open the level again to link it. Link
-  its collection (`bpy.data.libraries.load(path, link=True, relative=True)`:
-  relative, so the link still resolves when the project moves) and place it as
-  a collection instance. A piece that animates or that the level changes is
-  then made a library override (`bpy.ops.object.make_override_library()` with
-  the instance active), and actions and NLA tracks can still be added to it in
-  the level. Each placement is its own override; rename it as the play script
-  expects. Edits to the piece's own file reach every level that links it the
-  next time the level opens.
+- **A game's level and its models:** in a std game, models are made in
+  Blender, each its own prefab (`prefabs/<name>/<name>.blend`, which std's
+  export turns into its component), and the level lays them out in code
+  (`levels/<Name>Level.tsx`), blocked out there before its models are made.
+- **A scene or film's set and its pieces:** outside a game, the set's `.blend`
+  is the environment, and each piece with its own identity is its own `.blend`
+  (`src/models/<piece>.blend`) linked in rather than copied: link its
+  collection (`bpy.data.libraries.load(path, link=True, relative=True)`) and
+  place it as a collection instance, made a library override
+  (`bpy.ops.object.make_override_library()`) where it animates. Edits to the
+  piece's own file reach every set that links it the next time it opens.
 - **A character or an animation:** see Characters and Animation below; check
   motion in the Timeline at representative and extreme poses.
 - **An interactive model:** implement the requested interaction, preview it in
   the editor, and verify the requested controls and transitions.
-- **A working game:** follow Working games below, including Play, autoplay and
-  manual controls. Match the mechanics and success/failure behavior to the
-  requested game.
+- **A working game:** follow Working games below, including Play, the game's bot
+  goals and a few discrete manual checks. Match the mechanics and success/failure
+  behavior to the requested game.
 - **UI or a HUD:** follow React UI below. A standalone screen needs its own
   visual and interaction checks; UI attached to a game also needs checks in Play.
 - **An edit or repair:** inspect the existing result first and change the
@@ -106,14 +100,15 @@ Replace unused scaffold placeholders as the requested result calls for.
 
 Apply this section to models, scenes and the Blender parts of games.
 
-- `src/models/*.blend` are the saved documents, including full scenes.
+- The `.blend` files are the saved documents (`src/models/`, or a game's
+  `prefabs/` and `levels/`), including full scenes.
   `*.py` beside them record how they were authored. Editing a script alone does
   not update the document.
-- Look in the asset library before authoring an asset from nothing:
-  `GET <editor>/__editor/asset-library/search?source=local&type=model&q=<words>`
-  at the editor's address (the one `cyclotron edit` printed). Results carry
-  `tags` (such as `animated`), a license and attribution; fetch one with `POST <editor>/__editor/asset-library/download`,
-  import it through Blender, and record the asset and its license in the project.
+- Look in the asset library before authoring an asset from nothing. It is part
+  of the editor's automation API (`editor.assetLibrary`), reached with
+  `cyclotron eval`. Results carry `tags` (such as `animated`), a license and
+  attribution. A download lands in the project's `public/asset-library/` with
+  the asset and its license recorded in the project; import it through Blender.
 - Inspect the open scene with `get_scene_info` and `get_object_info` before
   changing it. Rerunning a script that clears the scene replaces existing work;
   update scripts to preserve user edits and the `References` and `Notes`
@@ -129,11 +124,13 @@ Apply this section to models, scenes and the Blender parts of games.
   editing another document, wait and retry, then switch to another document
   and back or run `editor.reloadPage()` in eval; do not build through `eval`
   instead.
-- Orient procedural closed-mesh faces outward and inspect their exterior in
-  Rendered shading before building many copies. Recalculate normals when needed.
+- A closed mesh's faces point outward (normals recalculated where needed),
+  checked shaded before many copies of it are built.
 - Verify object properties and inspect captures after meaningful changes.
-  The editor autosaves edits to the open `.blend`; confirm the saved file
-  before reporting completion. Arbitrary Python execution creates an undo step,
+  The editor saves the open `.blend` when Code-OSS autosaves it
+  (`files.autoSave`), a moment after an edit, and not at all when the project
+  turns autosave off; read the file only after that, and confirm the saved
+  file before reporting completion. Arbitrary Python execution creates an undo step,
   so prefer the inspection tools for reads.
 - Blender coordinates are metres with Z up. The glTF exporter converts to Y up.
   Preserve the existing script license headers.
@@ -186,13 +183,25 @@ Apply this section to models, scenes and the Blender parts of games.
   game with its React HUD (a raw game-canvas capture omits the UI). An editor
   capture reconstructs DOM and canvas pixels; it is not a browser or desktop
   screenshot.
+- The person may have the editor's tab out of sight (another tab in front, its
+  window minimized or covered; `status()`'s `presence.visibility` says so):
+  then a player's page is hidden, and one hidden since it loaded refuses
+  `capture --region play`. Never raise the editor's tab or window for it. See
+  the game in the videos std records of the bot's plays out of view
+  (`build/runs/<run>/video/`, each whole once its play ends), and read its HUD
+  with `editor.inspect()`'s `inspection.screen` (its `objects` are empty on a
+  page that has drawn no frame).
 
 ## Establish the visual match first
 
 For new visual work, match the requested view before adding behavior. For a new
-game, this first pass is the authored 3D scene and React UI composed as a static
-game screenshot; movement, scoring, opponents and items come afterward. A
-behavior-only repair preserves the established appearance.
+game, this first pass is the level and its models, lit, with the game's things
+in place and the React UI, composed as a static game screenshot: the game's
+first frame in Play. The level's document draws it as the game does
+(captured with `cyclotron capture --region document`)
+while it is laid out. Movement, scoring, opponents and item behavior come
+afterward. A behavior-only repair
+preserves the established appearance.
 
 - Match the reference's aspect ratio, crop, camera angle, perspective and object
   scale, with the real 3D model and React components at comparable resolution;
@@ -225,94 +234,136 @@ behavior-only repair preserves the established appearance.
 
 ## Working games
 
-- Complete the visual pass before implementing gameplay for a new game.
-- Implement and run the game inside the editor. Continue an existing game's
-  runtime and source organization, and preserve its models, source and settings. For a new model-based game, use the
-  `playable` template; in an existing models-only project run
-  `npx --no-install cyclotron add-play` (it never overwrites files). Its
-  `src/models/*.play.ts` scripts implement gameplay; Play runs them on a
-  detached copy of the model. When extending an existing model-based project,
-  declare `@volter/play` and the React/UI dependencies with
-  compatible project versions, and add the UI root as needed.
-- Register your bot as named behaviours, one per outcome worth checking:
-  `play.autoplay({ win: …, lose: … })`, at least one that plays to win and one
-  that loses on purpose (walks into enemies, lets the timer run out). Test an
-  ending by running the behaviour that reaches it, never by leaving the game
-  alone. Never bind autoplay to a game key or start it yourself; the person
-  turns it on in the Game panel (or you, with `play autoplay on <behaviour>`).
-  Each controller is a plain function called before each `update` while its
-  behaviour drives, given `{ behavior, dt, simT, tick, keys }` (`keys` are the
-  person's), and returns the `KeyboardEvent.code` keys it holds for that
-  update, or `{ keys, state }` where `state` says in a few words what it is
-  doing and why ("heading to nest 2"). The Game panel shows that state and the
-  play log records each change (`bot-state`), so return it whenever the bot's
-  intention changes. The keys are merged into `keys`, so the bot drives through
-  the same movement, collision and scoring code as manual play. Autoplay is off
-  at every Play and Restart, and any key or click in the game hands control back
-  to the person (`autoplay-off` with `by: 'takeover'` in the play log).
-- Every autoplay run is limited to simulation seconds, 300 unless you pass
-  `--for <seconds>`; at the limit autoplay turns off, the game pauses and the
-  log says `autoplay-limit` with the bot's last state. Reaching the limit is a
-  finding: the behaviour has no reachable ending, or the bot is stuck. Give
-  every game a terminal state reachable in bounded time (a mission timer that
-  fails the mission), and wait on a run by reading `play-log` until a deadline,
-  never open-ended.
-- Keep a gameplay log with `play.log(kind, facts)`: it stamps each entry with
-  simulation time and tick, keeps a bounded history, and records Play start,
-  stop, script reloads and errors itself. Log transitions with the facts that
-  explain them: phase changes and restarts; autoplay's decisions and the inputs
-  it held; manual inputs that start an action; contacts that matter (by object
-  name); checkpoints, pickups, score and inventory; deaths, failures and
-  finishes with cause and position. Log transitions rather than every frame,
-  so a full run stays readable; logging must not change timing, inputs or
-  state. Read it with `npx --no-install cyclotron play-log [--since <simTime>]
-  [--kind <kind>]` during and after each run, and explain what happened from it
-  before changing code: where autoplay stalled or died and why, and whether
-  that is a level, physics or controller problem. `console.log` does not reach the console feed (only
-  warnings and errors do).
-- Animate characters from the play script: `play.setAction(object, name)` sets
-  the active action, crossfading from the last; `play.setTrack(object, track,
-  { action, influence })` sets an NLA track; `play.setConstraint(object, bone,
-  name, { influence })` a constraint; `play.actions(object)` lists the actions.
-  Recolour or fade an object with `play.tint(object, color)` and
-  `play.setOpacity(object, value)`: the presenter reapplies its own materials,
-  so editing `mesh.material.color` does not show.
-- Run each behaviour (`play autoplay on <behaviour>`) and exercise manual
-  controls through representative continuous play, including turning, braking
-  and special actions; inspect movement while a key is held for sustained
-  actions. Inspect runtime errors and game state with captures; a still image
-  alone does not verify gameplay. Use public controls and observable state, not
-  private state writes that skip the behavior being checked.
-- Observe a complete session through every participant's terminal state,
-  including finish, failure and post-finish clearance as applicable, then
-  use the actual Restart control and complete another, checking that every
-  entity's position, movement, progression, inventory, effects and terminal
-  state reset. Stop/Play alone does not verify restart.
-- During active gameplay, verify pause freezes simulation time, entity state,
-  effects and inventory, that input while paused preserves it, and that resume
-  restores normal controls. Presenting another editor document can stop Play;
-  it does not verify an in-game pause.
-- Make meaningful game state observable through the HUD or a read-only
-  inspection surface: phase, simulation time, participants' positions and
-  signed movement, progression, terminal states and inventory as applicable.
+A game here is a [std](node_modules/@volter-ai/std-dev/docs/) game:
+three.js, React Three Fiber, Rapier and Colyseus, written as their own docs
+describe them, with std adding only what they lack. std's guide ships with the
+game, in `node_modules/@volter-ai/std-dev/docs/`; its pages "Write a game",
+"Levels" and "Bots" are where to start.
+
+The project's standards:
+
+- The room is the authority. A client sends what its player does, the room
+  decides in its state, and every client draws that state. std 0.8 has no
+  items, pickups, health or scores of its own: they are the game's own state.
+- Models are made in Blender; the level is code that lays them out. What std's
+  export writes from a `.blend` is generated: change the `.blend`, never its
+  output. A body is authored where it belongs: in the model's `.blend` as
+  Blender has it, or by the level that places the model (std's guide,
+  "Levels").
+- Content is data (Content is data, below).
+- What a player reads is labelled, on screen and in the world: the person, a
+  screen reader and the bots read the same.
+- Every game has its bot (`autopilot/`): a goal for each ending the game has,
+  and checks that judge each goal's recorded play.
+- The visual pass comes before gameplay.
+- `pnpm check` (TypeScript, lint and the web build) is clean before a game is
+  called done, and what its play was seen to get wrong (a goal, a check, a
+  press by hand) is fixed, not left for the person as a caveat. A fault in the
+  editor or std is shown with a focused reproduction and reported instead.
+- The game is made and played on the web. Roblox and Unreal are targets the
+  person adds when they want to ship there; never add one they didn't ask for.
+
+Where things go:
+
+- `levels/<Name>Level.tsx` is the level, a document of its own that draws it.
+- `prefabs/<name>/<name>.blend` is a model, and beside it what std's export
+  writes from it (`<name>.glb`, `<Name>.tsx`). A model's file has no lights of
+  its own: the level that places it lights it.
+- `server/index.ts` is the room, std's `StdRoom`, a Colyseus room;
+  `shared/state.ts` is its state schema.
+- `client/` is the React Three Fiber app every player runs: `index.tsx` joins
+  the room and draws the level, `hud.tsx` is the HUD. std draws nothing on
+  the page itself: what a player sees when the game can't go on
+  (`failure.tsx`) and a P2P host's invite (`invite.tsx`) are the game's.
+- `autopilot/index.ts` is the bot's goals, `autopilot/checks.ts` their checks.
+- `std.json` is the manifest. A project without one becomes a std game with
+  `npx --no-install cyclotron add-play`.
+
+Playing it in the editor:
+
+- Play (the Game panel, under every document) saves the Blender file you
+  changed (std exports it) and opens the Game view, with the game's own page for
+  each player: one unless the project's `volter.play.players` says
+  more (which the Game panel's Players [-][+] and `play players <n>`
+  set). The viewed
+  player is yours, the others are bots playing the Game panel's goal. The Game
+  view's Scene is the level live; the level's own tab stays as authored.
+  Pause, step and speed (the Game panel, or
+  `play pause`, `play resume`, `play step [count]`, `play speed <x>`) hold every
+  player's page; the room keeps running, as Colyseus cannot pause a room.
+- `npx --no-install cyclotron play autoplay on <goal>` is std's own play of a
+  goal, recorded and checked, as the Game panel's Autoplay is: on the viewed
+  player's page, which the person watches, while the Game view is on screen,
+  and out of view on std's headless device while it is not. It answers when
+  std says how the goal ended (`autoplay.state`, with how its checks ran:
+  `checks of <goal>: 2 passed (…)`, `…: 1 of 2 failed (…)` or `…: none ran
+  (…)`; the report's `checks.verdict` says which), so it
+  runs in the background. `autoplay.report` is its report. `npx --no-install cyclotron play-log` is what happened, the
+  room's own `console.log` among it (`server-output`).
+- Continuous play is the bot's, never yours by hand: your inputs arrive one tool
+  call at a time, seconds apart, so a real-time game driven by hand plays in
+  stop-motion and rarely reaches an ending. A manual check is a few discrete
+  key presses and HUD clicks (`editor.document.key`, `editor.document.click`;
+  at most about ten), then hand back to the bot.
+- Say in Chat that the game is playable as soon as it is, then check its
+  endings with its goals and by hand, restarting it as a player would.
 - Capture the running game, HUD included (`capture --region play`), at the
-  start, during representative actions and after changes; fix what you see,
-  play again and report what was actually observed.
+  start, during representative actions and after changes; its labelled nodes
+  (`editor.inspect()`'s `inspection.screen`) say what the HUD reads. Report what
+  was actually observed.
 
 ## Animation
 
-- Characters and creatures that move are animated as in Blender: an armature,
-  and its motions as named actions in the `.blend`. The action an armature has
-  assigned (`animation_data.action`) is the one it plays.
-- The Timeline and a game play it as Blender does: NLA tracks, then the active
-  action, then Damped Track constraints. Layer motions with NLA tracks (an
-  action keyed only on the upper body, on a track over a run, aims while the
-  legs run), and aim a bone with a Damped Track at an Empty the game moves.
-  Other constraints and IK play only in Blender: bake them into the action. The
-  console names any difference from Blender's own pose.
-- Give every action that may play a fake user (`action.use_fake_user = True`):
-  Blender drops an action nothing uses when the file saves, so an unassigned
-  clip library vanishes on the next save.
+- Motion is authored in Blender: an armature and its actions, in the
+  character's `.blend`, each a clip of its component. Clips play with three.js's
+  own animation system; what it lacks that Blender has (layers by weight, NLA
+  tracks, run-time aims), std adds in three's style (std's guide,
+  "Animation").
+- Every action that may play has a fake user: Blender drops an action nothing
+  uses when the file saves.
+
+## Cutscenes and films
+
+- A moment inside the game (a launch, a set piece, an emote) is authored on the
+  Timeline, in a collection of its own, and plays live in the game (std's
+  guide, "Animation", "A level's timeline").
+- A film as a file (an intro, a trailer) is rendered, not captured:
+  `npx --no-install cyclotron render-movie --from <marker> --to <marker> --out <file>.webm`
+  renders the span through Blender's Render Animation on the three.js engine,
+  a frame at a time at the scene's resolution and frame rate, and encodes it.
+  The movie carries the scene's sound: the sequencer's sound strips and the
+  speakers, mixed from the movie's first frame. Put a sound in the scene, at the
+  frame it belongs to, and the movie has it in sync.
+- A titled or animated graphic (a title card, a lower third, an end card) is a
+  React composition: a UI story whose component takes its time only from
+  `useMovieFrame()` (`@volter/editor-movie/clock`) and whose story declares
+  `parameters: { volter: { movie: { fps, frames } } }`. The story document's
+  Render, or `npx --no-install cyclotron render-movie --composition <story> --out <file>.webm`,
+  renders it frame by frame; CSS animations play at the movie's time.
+- Never assemble footage from `capture` or `play step` loops, or with an
+  external encoder: a capture is evidence of what the person sees, and a loop
+  of them holds the person's editor for hours.
+- Light a film's set with emissive materials and the scene's own light; a
+  point lamp is lit on every surface of a game's level in every frame.
+
+## Film projects
+
+A project with a `film.json` (`cyclotron create --template film`) is a film as
+files, which you read and change by hand, with or without the editor open:
+
+- `film.json`: the title, the frame rate every frame count is in, and the
+  picture's size.
+- `story.md` and `script.fountain`: the story and the screenplay.
+- `shots.json` and `boards/`: the shot list, each shot routed to a `.blend`, a
+  React composition in `src/graphics/`, a storyboard still or camera takes.
+- `cut.json`, `takes.json` with `takes/`, `music.json` with `music/`: the cut,
+  the recorded takes and the music.
+
+Before changing one, read its skill in `.claude/skills/`: `film-story`,
+`film-shots` and `film-cut`. After every change run `npm run check`: it
+validates every film file and the references between them, needs no editor,
+and exits 1 with each problem as `file path: message`. Fix what it prints
+before the next change.
 
 ## Characters
 
@@ -348,27 +399,29 @@ A character is two jobs, in this order: how it looks, then how it moves.
   the console. A character needs no game to be checked; Play is for checking
   game behaviour.
 
+## Content is data
+
+A game's content is data, as a game studio keeps it. Each asset is authored
+offline, saved as a file, and used by its path: a model is a `.blend`
+(std's export carries it to the game), a texture an image, a word a string the
+HUD shows. The code never builds at run time a mesh,
+a texture or a sound a file could hold. Run-time construction stays for what is
+truly procedural: a trail's points, a destructible's fragments, a score's value.
+
+- Models are `prefabs/<name>/<name>.blend`; the level that lays them out is
+  code (A game's level and its models, above). A block-out primitive in the
+  level stands only until its model is made.
+- A source sits beside the asset it makes: a `.blend` and the script that
+  builds it (with its seed), an image's source.
+
 ## React UI
 
-- Build HUDs, menus and screens as React components in `src/ui/`. A game's
-  DOM root is `src/ui/game.tsx`; the playable template includes the required
-  React/UI tools and manifest root. Existing projects need `react`, `react-dom`,
-  `@volter/editor-ui` and `@volter/editor-react`, with compatible project versions.
-  Declare the UI story region in `editor/volter.adapter.ts` (the playable template uses
-  `regionIncludes.ui` for `src/ui/**/*.tsx`). Preserve the project's other content.
-- Add `.stories.tsx` states and open them in the UI canvas: representative
-  states such as normal, empty, error and active, with their captures and
-  interactions inspected. Reveal the board with
-  `editor.present({ version: 1, document: { kind: 'workspace', id: 'workspace:ui-components' } })`
-  in eval; it appears after UI story discovery (read console errors if it is
-  missing). A declared UI root alone does not supply stories.
-- Give the intended initial state an explicit default and inspect opening the
-  canvas without selecting a story. Keep previews deterministic and isolated:
-  a timer in one preview must not advance it into another state or change
-  another preview. Keep each state's entities, inventory and results
-  consistent with the real game.
-- For a game HUD, verify the same components over the running game against live
-  game state. For standalone UI, verify its interactions in the UI canvas.
+- A game's HUD, menus and screens are React in its client (`client/hud.tsx`
+  and beside it): plain DOM over the `<Canvas>`, drawn from the room's state.
+- For a game HUD, verify the components over the running game against live
+  game state (`capture --region play`, and its labelled nodes in
+  `editor.inspect()`'s `inspection.screen`: role, name, bounds). For
+  standalone UI, verify its interactions on screen.
 
 ## Session controls
 
@@ -390,9 +443,10 @@ diagnosing a problem. Do not call `editor.reloadPage()` to reveal new
 files, boards, references or scripts: a reload interrupts the editor and its
 chat, so reserve it for an explicit request or a diagnosed problem.
 
-The bottom area has two views, Game (the Game panel) and Animation (Blender's
-Timeline, Action Editor and NLA editor); they arrange the editor and do not
-change what plays, and a running game keeps running in either. Play is
+The bottom area is the Game panel. Below a model, it has two views, Game (the
+Game panel) and Animation (Blender's Timeline, Action Editor and NLA editor);
+they arrange the editor and do not change what plays, and a running game keeps
+running in either, and whatever tab is in front. Play is
 running the game.
 
 Commands, all through `npx --no-install cyclotron`:
@@ -414,14 +468,21 @@ Commands, all through `npx --no-install cyclotron`:
 - `capture --region document|play|page [--name <words>] [--out file.png [--force]]`:
   what the person sees, saved (default under `.volter/captures/`) and shown in
   the editor's corner, captioned and named by `--name`. `document` is the
-  active document with its overlays; `play` is the running game with its HUD.
-- `add-play`: make a models project playable. `play-log`: the running game's log.
+  active document with its overlays; `play` is the viewed player's page, the
+  game with its HUD, as that page captures itself.
+- `add-play`: make this project a std game. `play-log`: the running game's log.
 - The Game panel's controls, each printing its state: `play autoplay on
-  <behaviour> [--for <seconds>]` and `play autoplay off`; `play pause` (no
-  `update` calls; the game's clock stops) and `play resume`; `play step
-  [count]` (one 1/60 s update of a paused game each); `play speed
-  0.25|0.5|1|2|4` (scales the `dt` the script is handed); `play restart` (a
-  fresh copy of the model, clock at zero); `play mode game|animation` (the view).
+  [<goal>]` (std's play of a goal, on the viewed player's page while the Game
+  view is on screen) and `play autoplay
+  off` (that play ended, and the viewed player's bot where it drives); `play pause` and
+  `play resume` (every player's page holds its clock); `play step [count]` (one
+  1/60 s frame each, pausing first); `play speed 0.25|0.5|1|2|4`; `play players [1-8]`
+  (how many players Play starts: the project's `volter.play.players`,
+  which it sets); `play restart`
+  (the game's pages loaded afresh); `play mode game|animation` (a model's view).
+- `export web|roblox|unreal`: the game exported, as the Game panel's Export
+  does: `web` its web build (`dist/`), an engine one of its targets
+  (`npx std target add roblox` adds one, only when the person asks).
 - Timeline: `eval 'return await editor.command("volter.timeline.frame", { frame: 24 })'`
   moves the playhead; `volter.timeline.editor` with `{ editor: "action" }` shows the
   Action Editor (the clip an armature plays, its keys) and `{ editor: "nla" }` the
@@ -431,8 +492,7 @@ If the project uses a Volter World, run app and test commands through that World
 
 Keep the project clean. Once the real document exists, remove the template
 placeholder unless the person is using it: `cube.blend` and `cube.py` in a
-models project; in a playable one, the Canyon Comet example (`src/models/canyon.*`
-with the step scripts beside it, `course.ts`, `race-state.ts`, `src/textures/`
-and the race UI in `src/ui/`). Put your
+models project; in a film, the starter's story, script, shots, cut,
+`src/models/opening.*`, `sounds/whoosh.wav`, `src/graphics/title.*` and `boards/title.png` as well. Put your
 own helper scripts and evidence images under `.volter/scratch/`, not in the
 project's source folders, and do not leave them behind as project files.

package/starter/cube.py

@@ -39,7 +39,7 @@ Run it through the session's Blender, from this project:
     # The agent uses the blender server declared in .mcp.json. It starts
     # Node with this project's installed Cyclotron CLI (no npm/bin shim).
     # Or, in a live editor session:
-    # editor.blender('blender-execute', { code: open('src/models/cube.py').read() })
+    # editor.contributedVerb('blender-execute', { code: open('src/models/cube.py').read() })
 
 The session saves the open document about a second after the last call, so a
 script that models is a script that saves.
@@ -69,14 +69,8 @@ cube = bpy.context.active_object
 cube.name = "Cube"
 cube.data.name = "Cube"
 
-# AND BLENDER'S OWN DEFAULT MATERIAL, because Blender's own default cube has
-# one. Without it the Shading workspace opens on `Shader Editor · No material`
-# with nothing drawn and nothing a person can click to change that — its one
-# control, Use Nodes, correctly refuses, because this view inspects a node
-# tree and never writes one (walk 3, beat 4). `materials.new` leaves
-# `use_nodes` FALSE, which is a material the header names and the canvas still
-# cannot draw; setting it True is what builds the pair Blender builds —
-# Principled BSDF into Material Output, 2 nodes and 37 sockets.
+# Give the cube a node-based material for the Shader Editor to inspect.
+# use_nodes builds Blender's default Principled BSDF into Material Output graph.
 material = bpy.data.materials.new(name="Material")
 material.use_nodes = True
 cube.data.materials.append(material)

package/starter/film/cut.json

@@ -0,0 +1,12 @@
+{
+  "version": 1,
+  "shots": [
+    { "shot": "opening", "in": 0, "out": 48 },
+    { "shot": "title", "in": 0, "out": 72 }
+  ],
+  "audio": [
+    { "source": "scene", "gain": 0 },
+    { "source": "music", "gain": 0 },
+    { "source": "takes", "gain": 0 }
+  ]
+}

package/starter/film/film.json

@@ -0,0 +1,7 @@
+{
+  "version": 1,
+  "title": "The Cube",
+  "fps": 24,
+  "width": 1280,
+  "height": 720
+}

package/starter/film/music.json

@@ -0,0 +1,4 @@
+{
+  "version": 1,
+  "cues": []
+}

package/starter/film/script.fountain

@@ -0,0 +1,16 @@
+Title: The Cube
+
+INT. GREY ROOM - DAY
+
+A cube sits alone on a grey floor under a single light.
+
+It turns, slowly, until one face meets the camera.
+
+> THE CUBE <
+
+INT. GREY ROOM - LATER
+
+A person stands beside the cube and looks into the lens.
+
+PERSON
+It never moves when anyone is watching.

package/starter/film/shots.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "shots": [
+    {
+      "id": "opening",
+      "heading": "INT. GREY ROOM - DAY",
+      "description": "The cube turns until one face meets the camera.",
+      "frames": 48,
+      "route": { "kind": "blender", "file": "src/models/opening.blend", "from": 1, "to": 48 }
+    },
+    {
+      "id": "title",
+      "heading": "INT. GREY ROOM - DAY",
+      "description": "The title card.",
+      "frames": 72,
+      "route": { "kind": "composition", "file": "src/graphics/title.stories.tsx", "story": "Title" }
+    },
+    {
+      "id": "witness",
+      "heading": "INT. GREY ROOM - LATER",
+      "description": "A person beside the cube speaks to the lens.",
+      "frames": 96,
+      "route": { "kind": "board", "file": "boards/title.png" }
+    }
+  ]
+}