@volter/play 0.5.212 → 0.5.213

package/dist-node/serving.mjs

@@ -83,7 +83,7 @@ var blenderHalfOf = (root) => join(stdDev(root), "blender", "blend-to-scene.py")
 var isLevelGlb = (path) => (/^levels\/.+\.glb$/.test(path) || /^prefabs\/([^/]+)\/\1\.glb$/.test(path)) && !path.includes("\\") && path.split("/").every((part) => part !== "" && part !== "." && part !== "..");
 function runStdLevel(root, glb) {
   return new Promise((resolve2) => {
-    const run = spawn(process.execPath, [join(stdDev(root), "bin", "std.js"), "level", glb, "--description", glb.replace(/\.glb$/, ".level.json")], { cwd: root, windowsHide: true });
+    const run = spawn(process.execPath, [join(stdDev(root), "bin", "std.js"), "level-scene", glb], { cwd: root, windowsHide: true });
     let output = "";
     run.stdout.on("data", (chunk) => {
       output += chunk.toString();
@@ -257,28 +257,35 @@ async function runningServer(root) {
   const record = JSON.parse(text);
   return alive(record.pid) ? record : null;
 }
-var ERRORS_KEPT = 500;
+var OUTPUT_KEPT = 500;
 var LINE_MOST = 4e3;
 var owned = /* @__PURE__ */ new Map();
-function heardError(server, chunk) {
-  const text = chunk === null ? server.decoder.end() : server.decoder.write(chunk);
-  const lines = stripVTControlCharacters(server.partial + text).split(/\r?\n/);
-  server.partial = chunk === null ? "" : (lines.pop() ?? "").slice(-LINE_MOST);
-  server.errors.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ""));
-  const over = server.errors.length - ERRORS_KEPT;
+function heardOutput(stream, chunk) {
+  const text = chunk === null ? stream.decoder.end() : stream.decoder.write(chunk);
+  const lines = stripVTControlCharacters(stream.partial + text).split(/\r?\n/);
+  stream.partial = chunk === null ? "" : (lines.pop() ?? "").slice(-LINE_MOST);
+  stream.lines.push(...lines.filter((line, at) => chunk !== null || at < lines.length - 1 || line !== ""));
+  const over = stream.lines.length - OUTPUT_KEPT;
   if (over > 0) {
-    server.errors.splice(0, over);
-    server.dropped += over;
+    stream.lines.splice(0, over);
+    stream.dropped += over;
   }
 }
-function errorsFrom(root, server, from) {
+var lineOf = (asked) => asked === null ? null : Number(asked) || 0;
+function streamFrom(stream, from) {
+  const next = stream.dropped + stream.lines.length;
+  return { lines: from === null ? [] : stream.lines.slice(Math.max(0, from - stream.dropped)), next };
+}
+function outputFrom(root, server, from) {
   const mine = owned.get(root);
   const pid = mine?.child.pid ?? null;
-  if (!mine || pid === null) return { lines: [], next: 0, server: null };
-  const next = mine.dropped + mine.errors.length;
-  if (from === null) return { lines: [], next, server: pid };
-  const start = server === pid ? from : 0;
-  return { lines: mine.errors.slice(Math.max(0, start - mine.dropped)), next, server: pid };
+  if (!mine || pid === null) return { server: null, stdout: { lines: [], next: 0 }, stderr: { lines: [], next: 0 } };
+  const start = (line) => line === null ? null : server === pid ? line : 0;
+  return {
+    server: pid,
+    stdout: streamFrom(mine.streams.stdout, start(from.stdout)),
+    stderr: streamFrom(mine.streams.stderr, start(from.stderr))
+  };
 }
 function endOwned() {
   for (const { child } of owned.values()) if (child.pid !== void 0 && child.exitCode === null) signalProcessTree(child.pid, "SIGTERM");
@@ -291,15 +298,18 @@ async function startedServer(root) {
   if (!mine || mine.child.exitCode !== null || mine.failed !== null) {
     const npm = npmProcess(["run", "dev", "--", "--no-open"], root);
     const child = spawn(npm.program, npm.args, { cwd: root, detached: process.platform !== "win32", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
-    mine = { child, said: "", failed: null, errors: [], dropped: 0, partial: "", decoder: new StringDecoder("utf8") };
+    const stream = () => ({ lines: [], dropped: 0, partial: "", decoder: new StringDecoder("utf8") });
+    mine = { child, said: "", failed: null, streams: { stdout: stream(), stderr: stream() } };
     const kept = mine;
     const hear = (chunk) => {
       kept.said = (kept.said + chunk.toString("utf8")).slice(-4e3);
     };
     child.stdout?.on("data", hear);
     child.stderr?.on("data", hear);
-    child.stderr?.on("data", (chunk) => heardError(kept, chunk));
-    child.stderr?.on("end", () => heardError(kept, null));
+    for (const name of ["stdout", "stderr"]) {
+      child[name]?.on("data", (chunk) => heardOutput(kept.streams[name], chunk));
+      child[name]?.on("end", () => heardOutput(kept.streams[name], null));
+    }
     child.on("error", (error) => {
       kept.failed = error.message;
     });
@@ -360,8 +370,8 @@ async function traceFrom(root, page, from) {
 var PLAY_MS = 15 * 6e4;
 async function playGoal(root, body, response) {
   const asked = body;
-  if (typeof asked?.goal !== "string" || asked.goal === "" || asked.bots !== void 0 && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1))
-    return answer(response, 400, { error: `A play is { goal, bots? }: a goal of the game's bot, and a whole number of bots; it was given ${JSON.stringify(body)}.` });
+  if (typeof asked?.goal !== "string" || asked.goal === "" || asked.bots !== void 0 && !(Number.isInteger(asked.bots) && Number(asked.bots) >= 1) || asked.device !== void 0 && (typeof asked.device !== "string" || asked.device === ""))
+    return answer(response, 400, { error: `A play is { goal, bots?, device? }: a goal of the game's bot, a whole number of bots, and one of std's devices by its id; it was given ${JSON.stringify(body)}.` });
   const running = await runningServer(root);
   if (!running) return answer(response, 409, { error: "The game's dev server is not running: press Play." });
   response.statusCode = 200;
@@ -382,7 +392,7 @@ async function playGoal(root, body, response) {
     if (socket.readyState === WebSocket.OPEN || socket.readyState === WebSocket.CONNECTING) socket.close();
   };
   const limit = setTimeout(() => end(false, `Play ended std's play of ${asked.goal}: it ran ${PLAY_MS / 6e4} minutes.`), PLAY_MS);
-  socket.addEventListener("open", () => socket.send(JSON.stringify({ goal: asked.goal, bots: asked.bots ?? 1, device: "headless" })));
+  socket.addEventListener("open", () => socket.send(JSON.stringify({ goal: asked.goal, bots: asked.bots ?? 1, device: asked.device ?? "headless" })));
   socket.addEventListener("message", (event) => {
     const message = JSON.parse(String(event.data));
     if (message.end !== void 0) end(message.end.ok === true);
@@ -407,7 +417,9 @@ function answer(response, status, value) {
 async function askStd(root, path, init) {
   const running = await runningServer(root);
   if (!running) return { status: 409, body: { error: "The game's dev server is not running: press Play." } };
-  const response = await fetch(`${running.url}${path}?token=${running.token}`, init);
+  const at = new URL(path, running.url);
+  at.searchParams.set("token", running.token);
+  const response = await fetch(at, init);
   return { status: response.status, body: await response.json() };
 }
 function stdDevPlugin(services) {
@@ -449,14 +461,14 @@ function stdDevPlugin(services) {
           return;
         }
         const control = /^\/devices\/([^/]+)\/control$/.exec(url.pathname)?.[1];
-        const asked = url.pathname === "/" && request.method === "GET" ? Promise.resolve({ status: 200, body: stdGame(root) }) : url.pathname === "/start" && request.method === "POST" ? startedServer(root).then(({ url: at }) => ({ status: 200, body: { url: at } })) : url.pathname === "/devices" && request.method === "GET" ? askStd(root, "/__std/devices") : control !== void 0 && request.method === "POST" ? askStd(
+        const asked = url.pathname === "/" && request.method === "GET" ? Promise.resolve({ status: 200, body: stdGame(root) }) : url.pathname === "/start" && request.method === "POST" ? startedServer(root).then(({ url: at }) => ({ status: 200, body: { url: at } })) : url.pathname === "/devices" && request.method === "GET" ? askStd(root, "/__std/devices") : url.pathname === "/scene" && request.method === "GET" ? askStd(root, `/__std/scene${url.search}`) : control !== void 0 && request.method === "POST" ? askStd(
           root,
           `/__std/devices/${encodeURIComponent(decodeURIComponent(control))}/control`,
           { method: "POST", headers: { "content-type": "application/json" }, body: JSON.stringify(bodyOf(request)) }
-        ) : url.pathname === "/level" && (request.method === "GET" || request.method === "POST") ? levelAnswer(root, request.method, bodyOf(request)) : url.pathname === "/goals" && request.method === "GET" ? botGoals(root) : url.pathname === "/pages" && request.method === "GET" ? pageSlots(root).then((body) => ({ status: 200, body })) : url.pathname === "/trace" && request.method === "GET" && PAGE_ID.test(url.searchParams.get("page") ?? "") ? traceFrom(root, url.searchParams.get("page"), Number(url.searchParams.get("from") ?? 0)).then((body) => ({ status: 200, body })) : url.pathname === "/errors" && request.method === "GET" ? Promise.resolve({ status: 200, body: errorsFrom(
+        ) : url.pathname === "/level" && (request.method === "GET" || request.method === "POST") ? levelAnswer(root, request.method, bodyOf(request)) : url.pathname === "/goals" && request.method === "GET" ? botGoals(root) : url.pathname === "/pages" && request.method === "GET" ? pageSlots(root).then((body) => ({ status: 200, body })) : url.pathname === "/trace" && request.method === "GET" && PAGE_ID.test(url.searchParams.get("page") ?? "") ? traceFrom(root, url.searchParams.get("page"), Number(url.searchParams.get("from") ?? 0)).then((body) => ({ status: 200, body })) : url.pathname === "/output" && request.method === "GET" ? Promise.resolve({ status: 200, body: outputFrom(
           root,
           url.searchParams.has("server") ? Number(url.searchParams.get("server")) : null,
-          url.searchParams.has("from") ? Number(url.searchParams.get("from")) || 0 : null
+          { stdout: lineOf(url.searchParams.get("stdout")), stderr: lineOf(url.searchParams.get("stderr")) }
         ) }) : Promise.resolve({ status: 404, body: { error: `${STD_ROUTE}${url.pathname} is not a route of Play's` } });
         asked.then(
           ({ status, body }) => answer(response, status, body),
@@ -511,6 +523,8 @@ function levelFiles(blend) {
     grading: `${dir}/${base}.grading.tsx`
   };
 }
+var BLEND_LEVEL = /^levels\/.+\.blend$/;
+var CODE_LEVEL = /^levels\/(?:[^/]+\/)*([A-Z][A-Za-z0-9]*Level)\.tsx$/;
 
 // serving/std-scene.ts
 var PREFIX = "/@volter-std-scene/";
@@ -518,11 +532,11 @@ var VIRTUAL = "\0volter-std-scene:";
 var RUNTIME = "volter-std-scene-runtime";
 var RUNTIME_ID = "\0volter-std-scene-runtime";
 var RUNTIME_FILE = join3(dirname3(fileURLToPath(import.meta.url)), "..", "serving", "std-scene-runtime.js");
-var LEVEL = /^levels\/.+\.blend$/;
 var MARK = "volter-std-scene";
 var RUNTIME_PACKAGES = ["@react-three/fiber", "@react-three/rapier"];
 var THROUGH = /* @__PURE__ */ new Map([["postprocessing", "@volter-ai/std/level/client"]]);
 var installedFolder = (root, name) => installedPackageDir(root, name.split("/").slice(0, name.startsWith("@") ? 2 : 1).join("/"));
+var refused = (why) => `throw new Error(${JSON.stringify(why)});`;
 var fileUrl = (file, version) => `${fsFileUrl(file)}?${MARK}=${version}`;
 function sceneModule(root, blend, read, version) {
   const files = levelFiles(blend);
@@ -559,6 +573,22 @@ function sceneModule(root, blend, read, version) {
     ""
   ].join("\n");
 }
+function codeSceneModule(root, file, read) {
+  const component = CODE_LEVEL.exec(file)[1];
+  read.add(normalizePath(join3(root, file)));
+  if (!existsSync3(join3(root, file))) throw new Error(`${file} is not in the game: a level in code is levels/<Name>Level.tsx.`);
+  return [
+    `import { mountScene as mountLevel } from ${JSON.stringify(RUNTIME)};`,
+    `import { ${component} } from ${JSON.stringify(`/${file}`)};`,
+    `export const component = ${JSON.stringify(file)};`,
+    "export const canvas = { shadows: 'percentage' };",
+    "export const gradingExtra = false;",
+    `const level = { Level: ${component}, Environment: null, canvas: { shadows: 'percentage' } };`,
+    "export const mountScene = (stage) => mountLevel(level, stage);",
+    "export const viewTransform = async () => null;",
+    ""
+  ].join("\n");
+}
 function gameFile(root, file) {
   if (file === null) return false;
   const at = relative(root, file);
@@ -587,7 +617,7 @@ function stdScenePlugin(services) {
   return {
     name: "volter-play-std-scene",
     enforce: "pre",
-    // (a std game's Scene view and its levels' modules prebundled as the session starts: found on the view's first open,
+    // (a std game's level documents and its levels' modules prebundled as the session starts: found on the view's first open,
     // Vite would optimize them again then, and the editor's page, which does not reload for it, would hold two copies of
     // React. The levels' files are crawled, and the runtime's own packages are included where the game has them)
     config() {
@@ -608,26 +638,27 @@ function stdScenePlugin(services) {
       }
       if (!source.startsWith(PREFIX)) return null;
       const [path = "", query = ""] = source.slice(PREFIX.length).split("?");
-      const blend = decodeURIComponent(path);
-      if (!LEVEL.test(blend)) throw new Error(`${blend} is not a std level's Blender file (levels/<name>.blend).`);
-      return `${VIRTUAL}${blend}?${query}`;
+      const level = decodeURIComponent(path);
+      if (!BLEND_LEVEL.test(level) && !CODE_LEVEL.test(level))
+        throw new Error(`${level} is not a std level: a level's Blender file (levels/<name>.blend) or a level in code (levels/<Name>Level.tsx).`);
+      return `${VIRTUAL}${level}?${query}`;
     },
     load(id) {
       if (id === RUNTIME_ID) return readFileSync2(RUNTIME_FILE, "utf8");
       if (id.startsWith(VIRTUAL)) {
         const root2 = stdGame2();
-        if (!root2) throw new Error("The open project is not a std game (no std.json), so it has no level to draw.");
-        const blend = id.slice(VIRTUAL.length).replace(/\?.*$/, "");
+        if (!root2) return refused("The open project is not a std game (no std.json), so it has no level to draw.");
+        const level = id.slice(VIRTUAL.length).replace(/\?.*$/, "");
         const read = /* @__PURE__ */ new Set();
-        scenes.set(blend, { id, read });
-        return sceneModule(root2, blend, read, version);
+        scenes.set(level, { id, read });
+        return CODE_LEVEL.test(level) ? codeSceneModule(root2, level, read) : sceneModule(root2, level, read, version);
       }
       const [file = id, query] = id.split("?");
       const root = query === "url" ? stdGame2() : null;
       if (!root || !gameFile(root, file)) return null;
       return `export default ${JSON.stringify(fileUrl(file, version))};`;
     },
-    // (a Scene view depends on its module's whole import closure among the game's files, the modules whose import failed
+    // (a level's document depends on its module's whole import closure among the game's files, the modules whose import failed
     // to resolve within it and the files its source was written from. Any file of those written, made or removed bumps
     // the content version, invalidates the closure, so each of its modules and URLs is served anew, and is announced on
     // the session's change channel naming the levels it reached)

package/package.json

@@ -1,14 +1,14 @@
 {
   "name": "@volter/play",
   "publisher": "volter",
-  "version": "0.5.212",
+  "version": "0.5.213",
   "engines": {
     "vscode": "^1.104.0"
   },
   "author": "Volter AI, Inc.",
   "license": "Apache-2.0",
   "type": "module",
-  "description": "Play for a volter-ai/std game in Cyclotron: the game's own dev pages as std devices in the level's stage, the Game panel, a level's export on save and its Scene view.",
+  "description": "Play for a volter-ai/std game in Cyclotron: the game's own dev pages as std devices in the level's stage, the Game panel, a level's export on save and a level in code's document.",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/volter-ai/editor.git",
@@ -34,7 +34,8 @@
   "contributes": {
     "volter": {
       "activationEvents": [
-        "onCustomEditor:volter.blender.model"
+        "onCustomEditor:volter.blender.model",
+        "onDocument:std-level"
       ],
       "serving": [
         "./dist-node/serving.mjs"
@@ -44,7 +45,8 @@
       ],
       "editors": [
         {
-          "document": "./contributions/std-scene.document.tsx"
+          "document": "./contributions/std-level.document.tsx",
+          "kind": "std-level"
         }
       ],
       "projectAdapters": [
@@ -52,11 +54,17 @@
           "when": "std.json",
           "module": "./src/std-game-adapter.ts"
         }
+      ],
+      "finders": [
+        {
+          "name": "stdLevelDocuments",
+          "module": "./contributions/levels.finder.ts"
+        }
       ]
     },
     "languageModelTools": [
       {
-        "name": "model-play-log",
+        "name": "play-log",
         "tags": [
           "volter"
         ],
@@ -65,10 +73,6 @@
         "inputSchema": {
           "type": "object",
           "properties": {
-            "documentId": {
-              "type": "string",
-              "description": "The model document; the active Play's when omitted."
-            },
             "since": {
               "type": "number",
               "description": "Keep entries at or after this many game seconds."
@@ -83,12 +87,12 @@
         }
       },
       {
-        "name": "model-play",
+        "name": "play",
         "tags": [
           "volter"
         ],
         "displayName": "Play control",
-        "modelDescription": "Control Play for the open level's std game: state, play, stop, pause, resume or restart. Answers the game's state.",
+        "modelDescription": "Control Play for the project's std game: state, play, stop, pause, resume or restart. Answers the game's state: play and restart answer once a player's page has joined the game (clock.running), or fail with why it did not start.",
         "inputSchema": {
           "type": "object",
           "properties": {
@@ -113,91 +117,89 @@
     ],
     "commands": [
       {
-        "command": "volter.model-play",
-        "title": "model-play",
-        "category": "Play",
-        "volter": {
-          "derivedRefresh": "none"
-        }
-      },
-      {
-        "command": "volter.model-play-log",
-        "title": "model-play-log",
+        "command": "volter.play",
+        "title": "play",
         "category": "Play",
         "volter": {
-          "derivedRefresh": "none"
+          "derivedRefresh": "none",
+          "timeoutMs": 120000
         }
       },
       {
-        "command": "volter.std-scene",
-        "title": "Open Scene View",
+        "command": "volter.play-log",
+        "title": "play-log",
         "category": "Play",
         "volter": {
           "derivedRefresh": "none"
         }
       },
       {
-        "command": "volter.model-play.state",
+        "command": "volter.play.state",
         "title": "state",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.mode",
+        "command": "volter.play.mode",
         "title": "mode",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.game-mode",
+        "command": "volter.play.game-mode",
         "title": "Switch to Game Mode",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.animation-mode",
+        "command": "volter.play.animation-mode",
         "title": "Switch to Animation Mode",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.play",
+        "command": "volter.play.play",
         "title": "Play",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.stop",
+        "command": "volter.play.stop",
         "title": "Stop",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.pause",
+        "command": "volter.play.pause",
         "title": "Pause",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.resume",
+        "command": "volter.play.resume",
         "title": "Resume",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.step",
+        "command": "volter.play.step",
         "title": "Step One Tick",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.speed",
+        "command": "volter.play.speed",
         "title": "speed",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.autoplay",
+        "command": "volter.play.players",
+        "title": "players",
+        "category": "Game"
+      },
+      {
+        "command": "volter.play.autoplay",
         "title": "autoplay",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.restart",
+        "command": "volter.play.restart",
         "title": "Restart",
         "category": "Game"
       },
       {
-        "command": "volter.model-play.export",
+        "command": "volter.play.export",
         "title": "export",
         "category": "Game"
       }
@@ -205,46 +207,66 @@
     "menus": {
       "commandPalette": [
         {
-          "command": "volter.model-play",
+          "command": "volter.play",
           "when": "false"
         },
         {
-          "command": "volter.model-play-log",
+          "command": "volter.play-log",
           "when": "false"
         },
         {
-          "command": "volter.model-play.state",
+          "command": "volter.play.state",
           "when": "false"
         },
         {
-          "command": "volter.model-play.mode",
+          "command": "volter.play.mode",
           "when": "false"
         },
         {
-          "command": "volter.model-play.speed",
+          "command": "volter.play.speed",
           "when": "false"
         },
         {
-          "command": "volter.model-play.autoplay",
+          "command": "volter.play.players",
           "when": "false"
         },
         {
-          "command": "volter.model-play.export",
+          "command": "volter.play.autoplay",
+          "when": "false"
+        },
+        {
+          "command": "volter.play.export",
           "when": "false"
         }
       ]
+    },
+    "configuration": {
+      "title": "Play",
+      "properties": {
+        "volter.play.players": {
+          "type": "integer",
+          "default": 1,
+          "minimum": 1,
+          "maximum": 8,
+          "scope": "window",
+          "description": "How many players a std game's Play starts: yours, and a bot playing the Game panel's goal for each other. One where unset. The Game panel's Players [-][+] and `play players <n>` write it to the project's settings (.vscode/settings.json), and a running game's players join or leave whenever it changes."
+        }
+      }
     }
   },
+  "dependencies": {
+    "zod": "^4.3.6"
+  },
   "peerDependencies": {
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
     "three": ">=0.186.0 <0.187.0",
-    "@volter/sdk": "0.5.212",
-    "@volter/project": "0.5.212",
+    "@volter/sdk": "0.5.213",
+    "@volter/project": "0.5.213",
     "vite": "^6.4.3 || ^7.0.0 || ^8.0.0",
-    "@volter/live": "0.5.212",
-    "@volter/editor-blender": "0.1.151",
-    "@volter/editor-threejs": "0.5.212",
+    "@volter/live": "0.5.213",
+    "@volter/editor-blender": "0.1.152",
+    "@volter/editor-threejs": "0.5.213",
     "@react-three/fiber": "^9.8.2",
     "@react-three/rapier": "^2.2.0",
     "postprocessing": "^6.39.5",
@@ -259,10 +281,10 @@
     "access": "public"
   },
   "devDependencies": {
-    "@volter/editor-blender": "0.1.151",
-    "@volter/editor-threejs": "0.5.212",
-    "@volter/live": "0.5.212",
-    "@volter/sdk": "0.5.212",
+    "@volter/editor-blender": "0.1.152",
+    "@volter/editor-threejs": "0.5.213",
+    "@volter/live": "0.5.213",
+    "@volter/sdk": "0.5.213",
     "esbuild": "0.25.12",
     "typescript": "5.9.3"
   },

package/serving/index.ts

@@ -1,7 +1,7 @@
 /**
  * `@volter/play`'s server half (`package.json#contributes.volter.serving`): a std game's dev server as Play reaches it,
  * and its level export's Node half (`std-dev.ts`); a std level's scene as a module of the game's own graph, which the
- * Scene view draws (`std-scene.ts`).
+ * level's document draws (`std-scene.ts`).
  */
 import type { ProjectServingServices } from '@volter/sdk/session/project-serving';
 import { stdDevPlugin } from './std-dev';