@volter/cyclotron 0.5.202 → 0.5.204

package/dist-node/create.js

@@ -6,9 +6,9 @@ var __export = (target, all) => {
 
 // node/create.ts
 import { spawn } from "node:child_process";
-import { existsSync, symlinkSync } from "node:fs";
-import { mkdir, writeFile, copyFile, readFile } from "node:fs/promises";
-import { resolve, join, dirname } from "node:path";
+import { constants, existsSync, symlinkSync } from "node:fs";
+import { mkdir, writeFile, copyFile, readFile, readdir } from "node:fs/promises";
+import { resolve, join, dirname, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // ../../node_modules/zod/v4/classic/external.js
@@ -13779,7 +13779,7 @@ function date4(params) {
 // ../../node_modules/zod/v4/classic/external.js
 config(en_default());
 
-// ../editor-project/src/manifest/schema.ts
+// ../project/src/manifest/schema.ts
 var GAME_MANIFEST_VERSION = 2;
 var REMOVED_SURFACE_SPELLING = {
   threejs: "three",
@@ -13917,7 +13917,7 @@ var GameManifestSchema = external_exports.object({
   version: external_exports.string().describe("The game's own version (used for orphan detection)"),
   engine: external_exports.object({
     version: external_exports.string().describe(
-      "Exact @volter/editor-project semver this game was scaffolded/last upgraded against \u2014 an identity pin, not a range"
+      "Exact @volter/project semver this game was scaffolded/last upgraded against \u2014 an identity pin, not a range"
     )
   }).strict().describe("Engine version pin"),
   roots: external_exports.array(AdapterRootSchema).superRefine((roots, ctx) => {
@@ -14017,14 +14017,14 @@ var GameManifestSchema = external_exports.object({
   )
 }).strict().describe("Game manifest (volter.project.json) \u2014 the complete v2 project configuration");
 
-// ../editor-project/src/manifest/filename.ts
+// ../project/src/manifest/filename.ts
 var MANIFEST_FILENAME = "volter.project.json";
 
 // package.json
 var package_default = {
   name: "@volter/cyclotron",
   author: "Volter AI, Inc.",
-  version: "0.5.202",
+  version: "0.5.204",
   publishConfig: {
     access: "public"
   },
@@ -14033,7 +14033,7 @@ var package_default = {
     node: ">=24"
   },
   license: "AGPL-3.0-only AND GPL-3.0-or-later AND MIT",
-  description: "A free, open-source game editor by VideoGame AI using Blender 5.2 compiled to WebAssembly, Code-OSS, three.js, TypeScript and React.",
+  description: "A free, open-source game editor by videogame.ai using Blender 5.2 compiled to WebAssembly, Code-OSS, three.js, TypeScript and React.",
   homepage: "https://cyclotron.videogame.ai",
   keywords: [
     "blender",
@@ -14077,31 +14077,33 @@ var package_default = {
       install: "npx @volter/cyclotron create my-game",
       colorTheme: "dark",
       upgrade: true,
+      adapterRequired: true,
       workbench: {
         "darwin-arm64": {
-          release: "cyclotron-f16dc165c0df-28b19dec3e1a-darwin-arm64",
-          tarballSha256: "5bc0f4df6b89477e7563afd83e2bdab5ddebac565ed55fb8af634225d5e6fe63"
+          release: "cyclotron-f16dc165c0df-2d5aeb1b4cd7-darwin-arm64",
+          tarballSha256: "5db124b24aeb0f59291011b58de8c785218411f7ddbdf82ab3d0d3d7ae27a2a3"
         },
         "linux-x64": {
-          release: "cyclotron-f16dc165c0df-28b19dec3e1a-linux-x64",
-          tarballSha256: "f091a9d6759adb06089e6db35d2be08ac747a154b93904cb5d0da0eba8ca2964"
+          release: "cyclotron-f16dc165c0df-2d5aeb1b4cd7-linux-x64",
+          tarballSha256: "3a435ef2084ab063330b83fa67477773a07170b5f5992a2f0546db691af488f8"
         },
         "win32-x64": {
-          release: "cyclotron-f16dc165c0df-28b19dec3e1a-win32-x64",
-          tarballSha256: "f5fe532a1571fd34a6b5b1f1c10b6c92e933be4132c164ed9ca35ee557587162"
+          release: "cyclotron-f16dc165c0df-2d5aeb1b4cd7-win32-x64",
+          tarballSha256: "96389b6a0c6430daf08a282425c3cda81af211e60607819782aab27922617eee"
         }
       }
     }
   },
   dependencies: {
-    "@volter/editor-core": "0.5.202",
-    "@volter/editor-blender": "0.1.141",
-    "@volter/editor-threejs": "0.5.202",
-    "@volter/blender-engine": "0.1.139",
-    "@volter/editor-project": "0.5.202",
-    "@volter/editor-sdk": "0.5.202",
-    "@volter/editor-live": "0.5.202",
+    "@volter/editor-core": "0.5.204",
+    "@volter/editor-blender": "0.1.143",
+    "@volter/editor-threejs": "0.5.204",
+    "@volter/blender-engine": "0.1.141",
+    "@volter/project": "0.5.204",
+    "@volter/sdk": "0.5.204",
+    "@volter/live": "0.5.204",
     "@modelcontextprotocol/sdk": "1.32.1",
+    typescript: "5.9.3",
     undici: "7.29.1"
   },
   bin: {
@@ -14121,25 +14123,21 @@ var UPGRADING = {
     names: [["Volter Model Editor", "Volter Cyclotron"], ["Model Editor", "Cyclotron"]]
   }]
 };
-var PLAYABLE = {
+var PLAY_SCAFFOLD = {
   uiRoot: { id: "ui", adapter: "dom", entry: "src/ui/game.tsx", zOrder: 1 },
   resolution: { width: 1280, height: 720 },
   dependencies: { react: "~19.2.4", "react-dom": "~19.2.4", three: "^0.180.0" },
   /** The kit packages Play and the DOM root need, at the kit version this product was released against. */
-  devDependencies: (kit) => ({ "@volter/editor-model-play": kit, "@volter/editor-ui": kit, "@volter/editor-react": kit }),
+  devDependencies: (kit) => ({ "@volter/play": kit, "@volter/editor-ui": kit, "@volter/editor-react": kit }),
   /** The adapter line that lets the UI board discover `src/ui` stories. */
-  regionIncludes: "  regionIncludes: { ui: { include: ['src/ui/**/*.tsx'] } },\n",
-  defaultDocument: "model:src/models/track.blend",
-  /** Starter file → project path. */
-  example: [
-    ["track.blend", "src/models/track.blend"],
-    ["track.py", "src/models/track.py"],
-    ["track.play.ts", "src/models/track.play.ts"],
-    ["race-state.ts", "src/models/race-state.ts"],
-    ["ui/game.tsx", "src/ui/game.tsx"],
-    ["ui/race-hud.tsx", "src/ui/race-hud.tsx"],
-    ["ui/game.stories.tsx", "src/ui/game.stories.tsx"]
-  ]
+  regionIncludes: "  regionIncludes: { ui: { include: ['src/ui/**/*.tsx'] } },\n"
+};
+var PLAYABLE = {
+  ...PLAY_SCAFFOLD,
+  resolution: { width: 1672, height: 941 },
+  defaultDocument: "model:src/models/canyon.blend",
+  /** The folder under `starter/` that is copied onto the new project. */
+  example: "playable"
 };
 var PROJECT_TSCONFIG = JSON.stringify({
   compilerOptions: {
@@ -14157,13 +14155,13 @@ var PROJECT_TSCONFIG = JSON.stringify({
 }, null, 2) + "\n";
 async function productVersions() {
   const product = JSON.parse(await readFile(join(productRoot, "package.json"), "utf8"));
-  return { product, kit: product.dependencies["@volter/editor-project"] };
+  return { product, kit: product.dependencies["@volter/project"] };
 }
 var declaration = {
   product: "@volter/cyclotron",
   templates: [
     { id: "models", name: "Models", description: "Blender modeling with a starter cube." },
-    { id: "playable", name: "Playable", description: "A cube circuit with a model play script and React HUD." }
+    { id: "playable", name: "Playable", description: "Canyon Comet: a three-lap kart race with a model play script and React HUD." }
   ],
   async create(request) {
     const result = await writeProject(request);
@@ -14186,7 +14184,7 @@ function checkoutNodeModules() {
   for (let dir = productRoot; dirname(dir) !== dir; dir = dirname(dir)) {
     if (existsSync(join(dir, "packages", "cyclotron", "package.json"))) {
       const nodeModules = join(dir, "node_modules");
-      return existsSync(join(nodeModules, "@volter", "editor-project", "package.json")) ? nodeModules : null;
+      return existsSync(join(nodeModules, "@volter", "project", "package.json")) ? nodeModules : null;
     }
   }
   return null;
@@ -14223,13 +14221,14 @@ async function writeProject({ name, targetDir, template }) {
     ...playable ? { dependencies: PLAYABLE.dependencies } : {},
     devDependencies: {
       "@volter/cyclotron": product.version,
-      "@volter/editor-project": kit,
+      "@volter/project": kit,
       "@volter/editor-blender": product.dependencies["@volter/editor-blender"],
       ...playable ? PLAYABLE.devDependencies(kit) : {}
     }
   }, null, 2) + "\n");
   await write("tsconfig.json", PROJECT_TSCONFIG);
-  await write("volter.adapter.ts", `import { defineAdapter } from '@volter/editor-project/adapter/adapter-module';
+  await mkdir(join(target, "editor"));
+  await write("editor/volter.adapter.ts", `import { defineAdapter } from '@volter/project/adapter/adapter-module';
 import { ModelLayout } from '@volter/editor-blender/layouts';
 import { blenderStyle, blenderKeymap } from '@volter/editor-blender/looks';
 
@@ -14259,8 +14258,14 @@ ${playable ? PLAYABLE.regionIncludes : ""}  editor: { Layout: ModelLayout, style
   for (const file2 of ["AGENTS.md", "CLAUDE.md"])
     await copyFile(join(productRoot, "starter", file2), join(target, file2));
   if (playable) {
-    await mkdir(join(target, "src/ui"));
-    for (const [from, to] of PLAYABLE.example) await copyFile(join(productRoot, "starter", from), join(target, to));
+    const example = join(productRoot, "starter", PLAYABLE.example);
+    for (const entry of await readdir(example, { recursive: true, withFileTypes: true })) {
+      if (!entry.isFile()) continue;
+      const from = join(entry.parentPath, entry.name);
+      const to = join(target, relative(example, from));
+      await mkdir(dirname(to), { recursive: true });
+      await copyFile(from, to, constants.COPYFILE_EXCL);
+    }
   } else {
     for (const file2 of ["cube.blend", "cube.py"])
       await copyFile(join(productRoot, "starter", file2), join(target, "src/models", file2));
@@ -14269,6 +14274,7 @@ ${playable ? PLAYABLE.regionIncludes : ""}  editor: { Layout: ModelLayout, style
 }
 export {
   PLAYABLE,
+  PLAY_SCAFFOLD,
   PROJECT_TSCONFIG,
   UPGRADING,
   declaration,

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@volter/cyclotron",
   "author": "Volter AI, Inc.",
-  "version": "0.5.202",
+  "version": "0.5.204",
   "publishConfig": {
     "access": "public"
   },
@@ -10,7 +10,7 @@
     "node": ">=24"
   },
   "license": "AGPL-3.0-only AND GPL-3.0-or-later AND MIT",
-  "description": "A free, open-source game editor by VideoGame AI using Blender 5.2 compiled to WebAssembly, Code-OSS, three.js, TypeScript and React.",
+  "description": "A free, open-source game editor by videogame.ai using Blender 5.2 compiled to WebAssembly, Code-OSS, three.js, TypeScript and React.",
   "homepage": "https://cyclotron.videogame.ai",
   "keywords": [
     "blender",
@@ -54,31 +54,33 @@
       "install": "npx @volter/cyclotron create my-game",
       "colorTheme": "dark",
       "upgrade": true,
+      "adapterRequired": true,
       "workbench": {
         "darwin-arm64": {
-          "release": "cyclotron-f16dc165c0df-28b19dec3e1a-darwin-arm64",
-          "tarballSha256": "5bc0f4df6b89477e7563afd83e2bdab5ddebac565ed55fb8af634225d5e6fe63"
+          "release": "cyclotron-f16dc165c0df-2d5aeb1b4cd7-darwin-arm64",
+          "tarballSha256": "5db124b24aeb0f59291011b58de8c785218411f7ddbdf82ab3d0d3d7ae27a2a3"
         },
         "linux-x64": {
-          "release": "cyclotron-f16dc165c0df-28b19dec3e1a-linux-x64",
-          "tarballSha256": "f091a9d6759adb06089e6db35d2be08ac747a154b93904cb5d0da0eba8ca2964"
+          "release": "cyclotron-f16dc165c0df-2d5aeb1b4cd7-linux-x64",
+          "tarballSha256": "3a435ef2084ab063330b83fa67477773a07170b5f5992a2f0546db691af488f8"
         },
         "win32-x64": {
-          "release": "cyclotron-f16dc165c0df-28b19dec3e1a-win32-x64",
-          "tarballSha256": "f5fe532a1571fd34a6b5b1f1c10b6c92e933be4132c164ed9ca35ee557587162"
+          "release": "cyclotron-f16dc165c0df-2d5aeb1b4cd7-win32-x64",
+          "tarballSha256": "96389b6a0c6430daf08a282425c3cda81af211e60607819782aab27922617eee"
         }
       }
     }
   },
   "dependencies": {
-    "@volter/editor-core": "0.5.202",
-    "@volter/editor-blender": "0.1.141",
-    "@volter/editor-threejs": "0.5.202",
-    "@volter/blender-engine": "0.1.139",
-    "@volter/editor-project": "0.5.202",
-    "@volter/editor-sdk": "0.5.202",
-    "@volter/editor-live": "0.5.202",
+    "@volter/editor-core": "0.5.204",
+    "@volter/editor-blender": "0.1.143",
+    "@volter/editor-threejs": "0.5.204",
+    "@volter/blender-engine": "0.1.141",
+    "@volter/project": "0.5.204",
+    "@volter/sdk": "0.5.204",
+    "@volter/live": "0.5.204",
     "@modelcontextprotocol/sdk": "1.32.1",
+    "typescript": "5.9.3",
     "undici": "7.29.1"
   },
   "bin": {

package/starter/AGENTS.md

@@ -71,6 +71,23 @@ 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 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
@@ -215,7 +232,7 @@ behavior-only repair preserves the established appearance.
   `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/editor-model-play` and the React/UI dependencies with
+  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
@@ -331,7 +348,7 @@ A character is two jobs, in this order: how it looks, then how it moves.
   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 `volter.adapter.ts` (the playable template uses
+  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
@@ -367,8 +384,9 @@ 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 layouts, Game (the Game panel) and Movie (the
-Timeline); they arrange the editor and do not change what plays. Play is
+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
 running the game.
 
 Commands, all through `npx --no-install cyclotron`:
@@ -393,13 +411,18 @@ Commands, all through `npx --no-install cyclotron`:
   `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|movie` (the layout).
+  fresh copy of the model, clock at zero); `play mode game|animation` (the view).
 - Timeline: `eval 'return await editor.command("volter.timeline.frame", { frame: 24 })'`
-  moves the playhead.
+  moves the playhead; `volter.timeline.editor` with `{ editor: "action" }` shows the
+  Action Editor (the clip an armature plays, its keys) and `{ editor: "nla" }` the
+  NLA editor (its tracks). While a game runs they show what it is animating.
 
 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 (`cube.blend`, `cube.py`) unless the person is using it. Put your
+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
 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/add-play/game-state.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright 2026 Volter AI, Inc.
+
+/** What the play script publishes and the React UI draws: one value, and who to tell when it changes. */
+export interface GameState {
+  x: number;
+  y: number;
+  height: number;
+  jumps: number;
+}
+
+let state: GameState = { x: 0, y: 0, height: 0, jumps: 0 };
+const listeners = new Set<() => void>();
+
+export const getGameState = (): GameState => state;
+
+export function subscribeGameState(listener: () => void): () => void {
+  listeners.add(listener);
+  return () => { listeners.delete(listener); };
+}
+
+export function publishGameState(next: GameState): void {
+  state = next;
+  for (const listener of listeners) listener();
+}

package/starter/add-play/game.tsx

@@ -0,0 +1,16 @@
+// SPDX-License-Identifier: MIT
+// Copyright 2026 Volter AI, Inc.
+
+/** The game's DOM root (the manifest's `ui` root), drawn over Play from what the play script publishes. */
+import { useSyncExternalStore } from 'react';
+import { getGameState, subscribeGameState } from '../models/game-state';
+
+export default function GameUI() {
+  const state = useSyncExternalStore(subscribeGameState, getGameState, getGameState);
+  return (
+    <div style={{ position: 'absolute', left: 16, top: 16, padding: '8px 12px', borderRadius: 8, background: '#000000aa', color: 'white', font: '600 13px system-ui, sans-serif', pointerEvents: 'none' }}>
+      x {state.x.toFixed(1)} m · y {state.y.toFixed(1)} m · jumps {state.jumps}
+      <div style={{ marginTop: 4, fontWeight: 400, opacity: 0.8 }}>Arrows or WASD move · Space jumps</div>
+    </div>
+  );
+}

package/starter/add-play/model.play.ts

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: MIT
+// Copyright 2026 Volter AI, Inc.
+
+/**
+ * A FIRST PLAY SCRIPT, from `cyclotron add-play`. Play runs `<model>.play.ts` on a detached
+ * copy of the `.blend` beside it, so this one drives that model: the arrow keys or WASD move
+ * its first object across the ground, Space jumps, and the camera follows. It logs each jump
+ * (`cyclotron play-log`), offers the Game panel's Autoplay one behaviour (`wander`), and
+ * publishes its state to `game-state.ts`, which the React UI in `src/ui/game.tsx` draws.
+ * Positions under `root` are Blender's metres, Z up. Make it your game.
+ */
+import * as THREE from 'three';
+import type { ModelPlayContext, ModelPlayGame } from '@volter/play/play-script';
+import { publishGameState } from './game-state';
+
+const SPEED = 4;
+const JUMP = 5;
+const GRAVITY = 9.81;
+
+export default function firstPlay(play: ModelPlayContext): ModelPlayGame {
+  // The first object with a mesh in it: the starter Cube, or whatever this model holds.
+  const first = play.root.children.find((object) => {
+    let mesh = false;
+    object.traverse((child) => { mesh ||= (child as THREE.Mesh).isMesh === true; });
+    return mesh;
+  });
+  const player = first ? play.find(first.name) : null;
+  if (!player) throw new Error('This model has no mesh object for its play script to move.');
+  const ground = player.position.z;
+  let height = 0;
+  let rise = 0;
+  let jumps = 0;
+  let jumpHeld = false;
+  const eye = new THREE.Vector3();
+  const target = new THREE.Vector3();
+  // Play lights the model with its own lamps; the starter cube has none, so it gets a sky light.
+  let lit = false;
+  play.root.traverse((object) => { lit ||= (object as THREE.Light).isLight === true; });
+  const sky = lit ? null : new THREE.HemisphereLight('#ffffff', '#4d5a66', 2.5);
+  if (sky) play.root.add(sky);
+
+  // The bot holds keys exactly as a person would; the Game panel's Autoplay switches it on.
+  play.autoplay({
+    wander: ({ tick }) => {
+      const side = [['ArrowUp'], ['ArrowRight'], ['ArrowDown'], ['ArrowLeft']][Math.floor(tick / 60) % 4]!;
+      return { keys: tick % 60 === 0 ? [...side, 'Space'] : side, state: 'walking a square, jumping at each corner' };
+    },
+  });
+
+  return {
+    update(dt) {
+      const held = (...codes: string[]) => codes.some((code) => play.keys.has(code));
+      player.position.x += ((held('ArrowRight', 'KeyD') ? 1 : 0) - (held('ArrowLeft', 'KeyA') ? 1 : 0)) * SPEED * dt;
+      player.position.y += ((held('ArrowUp', 'KeyW') ? 1 : 0) - (held('ArrowDown', 'KeyS') ? 1 : 0)) * SPEED * dt;
+      if (held('Space') && !jumpHeld && height === 0) {
+        rise = JUMP;
+        jumps += 1;
+        play.log('jump', { jumps, x: player.position.x, y: player.position.y });
+      }
+      jumpHeld = held('Space');
+      rise -= GRAVITY * dt;
+      height = Math.max(0, height + rise * dt);
+      if (height === 0) rise = 0;
+      player.position.z = ground + height;
+      // Chase from behind and above. `root` turns Blender's Z up into the stage's Y up.
+      play.root.localToWorld(eye.set(player.position.x, player.position.y - 6, ground + 3));
+      play.root.localToWorld(target.copy(player.position));
+      play.camera.position.copy(eye);
+      play.camera.up.set(0, 1, 0);
+      play.camera.lookAt(target);
+      publishGameState({ x: player.position.x, y: player.position.y, height, jumps });
+    },
+    dispose() {
+      sky?.removeFromParent();
+    },
+  };
+}

package/starter/package.json

@@ -5,5 +5,10 @@
     "react": "~19.2.4",
     "react-dom": "~19.2.4",
     "three": "~0.180.0"
+  },
+  "devDependencies": {
+    "@volter/play": "^0.5.0",
+    "@volter/editor-ui": "^0.5.0",
+    "@volter/editor-react": "^0.5.0"
   }
 }

package/starter/playable/src/models/canyon.play.ts

@@ -0,0 +1,107 @@
+// SPDX-License-Identifier: MIT
+// Copyright 2026 Volter AI, Inc.
+import * as THREE from 'three';
+import type {ModelPlayContext} from '@volter/play/play-script';
+import {initialState,publishRaceState,consumeCommands,type Racer,type RaceState,type RaceEvent,type Command} from './race-state';
+import {at,nearest,length,wrap,angle,leftWidth} from './course';
+type Car=Racer & {object:THREE.Object3D;s:number;distance:number;checkpoint:number;lane:number;parked:boolean;boostCooldown:number;drift:number;drifting:boolean;offroad:boolean;collisionCooldown:number;lastDecision:number};
+type Inputs={throttle:number;brake:boolean;steer:number;drift:boolean;boost:boolean};
+export default function play(ctx:ModelPlayContext){
+ const initialPositions=[[0,0],[-6.2,2.7],[4.8,6],[-1.5,24],[1,31],[7,41]];
+ const names=['Pip','Miso','Nova','Sprig','Mica','Rook'];
+ let state:RaceState={...initialState,events:[],racers:[]};let events:RaceEvent[]=[];let simTime=0,frame=0,clock=0,accumulator=0,previousKeys=new Set<string>(),endTime:number|null=null;let lastManual='';
+ // Each race event is kept for the HUD's race state and written to the editor's play log (`cyclotron play-log`).
+ const log=(kind:string,detail:Record<string,unknown>={})=>{events.push({time:+simTime.toFixed(3),frame,kind,...detail});if(events.length>1200)events.shift();ctx.log(kind,detail)};
+ const cars:Car[]=initialPositions.map(([x,y],id)=>{const object=ctx.find('Kart.'+id);if(!object)throw new Error('Missing authored Kart.'+id);const n=nearest(x,y);return {id,name:names[id],object,x,y,s:n.s,distance:n.s,heading:0,speed:0,progress:n.s/length,lap:1,finished:false,finishTime:null,coins:id===0?8:4,boost:0,checkpoint:1,lane:[0,-4.6,4.6,-2.2,1.8,3.7][id],parked:false,boostCooldown:0,drift:0,drifting:false,offroad:false,collisionCooldown:0,lastDecision:-1}});
+ ctx.root.traverse((o:any)=>{if(o.isDirectionalLight){o.shadow.mapSize.set(4096,4096);o.shadow.map?.dispose();o.shadow.map=null}});
+ const pickups=new THREE.Group();pickups.name='Race coin pickups';ctx.root.add(pickups);
+ const coinMaterial=new THREE.MeshStandardMaterial({color:0xffbe18,metalness:.55,roughness:.25});
+ const coinGeometry=new THREE.TorusGeometry(.34,.1,8,20);
+ const coins=Array.from({length:24},(_,i)=>{const s=(.25+Math.floor(i/3)*.086)*length, lane=[-4,0,4][i%3],p=at(s,lane);const mesh=new THREE.Mesh(coinGeometry,coinMaterial);mesh.name='Coin.'+i;mesh.position.set(p.x,p.y,.95);mesh.rotation.x=Math.PI/2;mesh.castShadow=true;pickups.add(mesh);return {mesh,x:p.x,y:p.y,ready:0,id:i}});
+ const sparks=new THREE.Group();sparks.name='Boost exhaust';ctx.root.add(sparks);const flameMat=new THREE.MeshBasicMaterial({color:0x47e5ff,transparent:true,opacity:.7});const flameGeo=new THREE.ConeGeometry(.18,.8,8);const flames=cars.map(()=>{const a=new THREE.Mesh(flameGeo,flameMat);a.rotation.x=Math.PI/2;sparks.add(a);return a});
+ const reset=(start=false)=>{const auto=state.autoplay;events=[];simTime=frame=clock=accumulator=0;endTime=null;lastManual='';for(const c of cars){const [x,y]=initialPositions[c.id],n=nearest(x,y);Object.assign(c,{x,y,s:n.s,distance:n.s,heading:0,speed:0,progress:n.s/length,lap:1,finished:false,finishTime:null,coins:c.id===0?8:4,boost:0,checkpoint:1,parked:false,boostCooldown:0,drift:0,drifting:false,offroad:false,collisionCooldown:0,lastDecision:-1});c.object.position.set(x,y,0);c.object.rotation.set(0,0,0)}for(const c of coins){c.ready=0;c.mesh.visible=true;c.mesh.rotation.z=0;}flames.forEach(f=>f.visible=false);state={...initialState,autoplay:auto,phase:start?'countdown':'ready',events:[],racers:[]};log('restart',{autoplay:auto,positions:cars.map(c=>({id:c.id,x:c.x,y:c.y}))});if(start)log('phase',{phase:'countdown'});publish();};
+ const publish=()=>{const order=[...cars].sort((a,b)=>a.finished&&b.finished?(a.finishTime??0)-(b.finishTime??0):a.finished?-1:b.finished?1:b.distance-a.distance);const p=cars[0];state={...state,time:simTime,frame,speed:p.speed,lap:p.lap,coins:p.coins,boost:p.boost,place:order.indexOf(p)+1,racers:cars.map(c=>({id:c.id,name:c.name,x:+c.x.toFixed(3),y:+c.y.toFixed(3),heading:+c.heading.toFixed(4),speed:+c.speed.toFixed(3),progress:+(c.distance/length).toFixed(5),lap:c.lap,finished:c.finished,finishTime:c.finishTime,coins:c.coins,boost:+c.boost.toFixed(3),parked:c.parked,drifting:c.drifting,offroad:c.offroad})),events:[...events],message:cars.every(c=>c.parked)?'All six racers finished':state.message};publishRaceState(state)};
+ const start=()=>{if(state.phase==='ready'){state={...state,phase:'countdown',countdown:3};log('phase',{phase:'countdown'})}};
+ const command=(cmd:Command)=>{if(cmd==='restart'){reset(state.autoplay);return;}if(cmd==='pause'){if(state.phase!=='ready'){state={...state,paused:!state.paused};log(state.paused?'pause':'resume')}return;}if(state.paused)return;if(cmd==='auto'){state={...state,autoplay:!state.autoplay};log('autoplay',{enabled:state.autoplay});if(state.autoplay)start()}else if(cmd==='start')start();};
+ function controller(c:Car):Inputs{
+  const look=at(c.s+7+Math.abs(c.speed)*.45,c.finished?9.5:c.lane);const desired=Math.atan2(look.x-c.x,look.y-c.y),err=angle(desired-c.heading);const bend=Math.abs(angle(at(c.s+18).heading-at(c.s+3).heading));const target=(c.id===0?24.5:20.5+c.id*.25)-Math.min(6,bend*7);
+  const inputs={throttle:c.speed<target?1:0,brake:c.speed>target+1,steer:Math.max(-1,Math.min(1,err*2.4)),drift:Math.abs(err)>(c.drifting?.20:.40)&&c.speed>13,boost:!c.finished&&bend<.15&&c.coins>=2&&c.speed>15&&c.boostCooldown===0};
+  if(c.finished){const remaining=length*3+28+c.id*8-c.distance;const desiredSpeed=Math.min(15,Math.sqrt(Math.max(0,remaining-.7)*32));inputs.throttle=c.speed<desiredSpeed-.2?1:0;inputs.brake=c.speed>desiredSpeed+.05;inputs.drift=false;inputs.boost=false;}
+  if(c.id===0&&simTime-c.lastDecision>2){c.lastDecision=simTime;log('autoplay-decision',{racer:c.id,targetSpeed:+target.toFixed(2),target:{x:+look.x.toFixed(2),y:+look.y.toFixed(2)},inputs:{...inputs,steer:+inputs.steer.toFixed(2)}})}
+  return inputs;
+ }
+ const boost=(c:Car,drift=false)=>{if(c.boostCooldown>0||c.finished)return;if(!drift&&c.coins<2)return;if(!drift)c.coins-=2;c.boost=drift?.7:1.4;c.boostCooldown=drift?1.2:3;log('boost',{racer:c.id,source:drift?'drift':'coins',coins:c.coins,duration:c.boost})};
+ function drive(c:Car,input:Inputs,dt:number){
+  if(c.parked)return;
+  c.collisionCooldown=Math.max(0,c.collisionCooldown-dt);c.boostCooldown=Math.max(0,c.boostCooldown-dt);
+  if(c.boost>0){c.boost=Math.max(0,c.boost-dt);if(c.boost===0)log('boost-end',{racer:c.id})}
+  if(input.boost)boost(c);
+  const drift=input.drift&&Math.abs(input.steer)>.1&&c.speed>6;
+  if(drift!==c.drifting){log(drift?'drift-start':'drift-end',{racer:c.id,charge:+c.drift.toFixed(2)});if(!drift&&c.drift>.6)boost(c,true);if(!drift)c.drift=0;c.drifting=drift}if(drift)c.drift+=dt;
+  let acceleration=input.throttle*12;
+  if(input.brake)acceleration=c.speed>0?-22:(c.finished?0:-9);
+  if(c.finished&&Math.abs(c.speed)<=.5&&c.distance>=3*length+26.5+c.id*8){c.speed=0;c.parked=true;log('parked',{racer:c.id,x:c.x,y:c.y,clearedFinish:true});return;}
+  const drag=input.throttle===0&&!input.brake?2.8:1.7;
+  if(c.speed!==0)acceleration-=Math.sign(c.speed)*drag;
+  c.speed+=acceleration*dt;
+  const maxSpeed=c.boost>0?33:25.5;
+  c.speed=Math.max(-7,Math.min(maxSpeed,c.speed));if(!input.throttle&&!input.brake&&Math.abs(c.speed)<.12)c.speed=0;
+  const turn=input.steer*(drift?1.9:1.45)*Math.min(1,Math.abs(c.speed)/7)*(c.speed<0?-1:1);c.heading=angle(c.heading+turn*dt);
+  c.x+=Math.sin(c.heading)*c.speed*dt;c.y+=Math.cos(c.heading)*c.speed*dt;
+  let n=nearest(c.x,c.y);const left=leftWidth(n.t,n.y),limit=n.lane<0?left:12;
+  const offroad=n.d>limit-1.2;
+  if(offroad!==c.offroad){c.offroad=offroad;log(offroad?'surface-leave':'surface-enter',{racer:c.id,surface:'Circuit asphalt',x:+c.x.toFixed(2),y:+c.y.toFixed(2)})}
+  if(offroad)c.speed*=Math.exp(-1.8*dt);
+  if(n.d>limit+1.2){const sign=Math.sign(n.lane),p=at(n.s,sign*(limit+1));c.x=p.x;c.y=p.y;c.speed*=.6;if(c.collisionCooldown===0){log('barrier-contact',{racer:c.id,object:sign<0?'Outside guardrail':'Inside sandstone verge',x:c.x,y:c.y});c.collisionCooldown=.8}n=nearest(c.x,c.y)}
+  let delta=n.s-c.s;if(delta>length/2)delta-=length;if(delta<-length/2)delta+=length;
+  // Projection advances only through physically adjacent road segments.
+  if(Math.abs(delta)<3+Math.abs(c.speed)*dt*2)c.distance+=delta;
+  c.s=n.s;
+  if(!c.finished&&c.distance>=c.checkpoint*length/4){log('checkpoint',{racer:c.id,checkpoint:c.checkpoint,x:c.x,y:c.y});c.checkpoint++;}
+  const lap=Math.min(3,Math.max(1,Math.floor(c.distance/length)+1));if(lap!==c.lap){c.lap=lap;log('lap',{racer:c.id,lap})}
+  if(!c.finished&&c.distance>=3*length&&c.checkpoint>=12){c.finished=true;c.finishTime=simTime;log('finish',{racer:c.id,name:c.name,time:simTime,x:c.x,y:c.y});if(c.id===0){endTime=simTime;state={...state,phase:'finished'};log('phase',{phase:'finished'})}}
+  c.object.position.set(c.x,c.y,0);c.object.rotation.set(0,0,-c.heading);
+ }
+ const eye=new THREE.Vector3(),target=new THREE.Vector3();
+ function camera(){const p=cars[0],h=p.heading;ctx.root.localToWorld(eye.set(p.x-Math.sin(h)*10.7,p.y-Math.cos(h)*10.7,4.7));ctx.root.localToWorld(target.set(p.x+Math.sin(h)*18,p.y+Math.cos(h)*18,.05));ctx.camera.position.copy(eye);ctx.camera.up.set(0,1,0);ctx.camera.lookAt(target);const cam=ctx.camera as THREE.PerspectiveCamera;cam.fov=47;cam.far=180;cam.updateProjectionMatrix();}
+ function physics(dt:number){
+  if(state.phase==='ready'||state.paused||cars.every(c=>c.parked))return;
+  simTime+=dt;frame++;
+  if(state.phase==='countdown'){state={...state,countdown:Math.max(0,state.countdown-dt)};if(state.countdown===0){state={...state,phase:'racing'};log('phase',{phase:'racing'});}return;}
+  const k=ctx.keys,manual:Inputs={throttle:k.has('ArrowUp')||k.has('KeyW')?1:0,brake:k.has('ArrowDown')||k.has('KeyS'),steer:(k.has('ArrowRight')||k.has('KeyD')?1:0)-(k.has('ArrowLeft')||k.has('KeyA')?1:0),drift:k.has('Space'),boost:k.has('ShiftLeft')||k.has('ShiftRight')};
+  const manualString=JSON.stringify(manual);if(!state.autoplay&&!botNow&&manualString!==lastManual){lastManual=manualString;log('manual-input',{inputs:manual});}
+  for(const c of cars)drive(c,c.id===0&&!state.autoplay&&!c.finished?manual:controller(c),dt);
+  for(let i=0;i<cars.length;i++)for(let j=i+1;j<cars.length;j++){
+   const a=cars[i],b=cars[j];if(a.finished||b.finished)continue;const dx=b.x-a.x,dy=b.y-a.y,d=Math.hypot(dx,dy);if(d>0&&d<2){const push=(2-d)*.51;a.x-=dx/d*push;a.y-=dy/d*push;b.x+=dx/d*push;b.y+=dy/d*push;if(a.collisionCooldown===0&&b.collisionCooldown===0){a.speed*=.85;b.speed*=.85;log('kart-contact',{a:i,b:j,object:'Kart.'+j,x:a.x,y:a.y});a.collisionCooldown=b.collisionCooldown=.5}}
+  }
+  for(const coin of coins){coin.mesh.visible=simTime>=coin.ready;if(!coin.mesh.visible)continue;coin.mesh.rotation.z=simTime*2;for(const c of cars){if(c.finished)continue;if(Math.hypot(c.x-coin.x,c.y-coin.y)<1.5){c.coins++;coin.ready=simTime+6;coin.mesh.visible=false;log('pickup',{racer:c.id,object:'Coin.'+coin.id,coins:c.coins});break}}}
+  cars.forEach((c,i)=>{const f=flames[i];f.visible=c.boost>0&&!c.parked;f.position.set(c.x-Math.sin(c.heading)*1.8,c.y-Math.cos(c.heading)*1.8,.38);f.rotation.set(Math.PI/2,0,-c.heading);f.scale.setScalar(.8+.25*Math.sin(simTime*42));});
+ }
+ // THE GAME PANEL'S AUTOPLAY (`play autoplay on race`): a bot that drives Pip with the keys a person
+ // holds, through the manual code above, steering as the race's own AUTO does (`controller`, which logs
+ // its decisions). Steering keys are pulsed so their average follows that steer; while the bot drives,
+ // those key changes are not logged as manual input.
+ let botDriving=false,botNow=false,steerDebt=0;
+ ctx.autoplay({race:()=>{
+  botDriving=true;const c=cars[0];
+  if(state.paused)return {keys:[],state:'race paused'};
+  if(state.phase==='ready')return {keys:['ArrowUp'],state:'starting the race'};
+  if(state.phase==='countdown')return {keys:[],state:'waiting for the countdown'};
+  if(c.finished)return {keys:[],state:'finished; Pip parks past the line'};
+  const input=controller(c),keys:string[]=[];steerDebt+=input.steer;
+  if(steerDebt>=.5){keys.push('ArrowRight');steerDebt-=1}else if(steerDebt<=-.5){keys.push('ArrowLeft');steerDebt+=1}
+  if(input.throttle)keys.push('ArrowUp');if(input.brake)keys.push('ArrowDown');if(input.drift)keys.push('Space');if(input.boost)keys.push('ShiftLeft');
+  return {keys,state:`racing lap ${c.lap} of 3`};
+ }});
+ reset(false);
+ return {update(dt:number){
+  botNow=botDriving;botDriving=false;
+  const keyCommands:[string,Command][]=[['Enter','start'],['KeyO','auto'],['KeyP','pause'],['KeyR','restart']];
+  const commands=consumeCommands();for(const [key,cmd]of keyCommands)if(ctx.keys.has(key)&&!previousKeys.has(key))commands.push(cmd);
+  for(const cmd of commands)command(cmd);
+  const moving=['ArrowUp','ArrowDown','ArrowLeft','ArrowRight','KeyW','KeyA','KeyS','KeyD'].some(k=>ctx.keys.has(k));
+  if(moving&&!state.paused&&!cars[0].finished){if(state.autoplay){state={...state,autoplay:false};log('autoplay',{enabled:false,cause:'manual takeover'})}start()}
+  previousKeys=new Set(ctx.keys);if(!state.paused){accumulator+=Math.min(dt,.1);while(accumulator>=1/60){physics(1/60);accumulator-=1/60}}else accumulator=0;
+  camera();clock+=dt;if(clock>.075||commands.length){publish();clock=0;}
+ },dispose(){pickups.removeFromParent();sparks.removeFromParent();coinGeometry.dispose();coinMaterial.dispose();flameGeo.dispose();flameMat.dispose();}};
+}