virtualmatter 0.2.0 → 0.3.0

package/README.md

@@ -51,9 +51,17 @@ Poke at the running engine from another terminal:
 ```bash
 npx virtualmatter run-lua --code "return Server.GetInfo()"
 npx virtualmatter errors
-npx virtualmatter screenshot -o shot.png
+npx virtualmatter screenshot -o shot.png                  # default overview
+npx virtualmatter screenshot --target "Player" -o p.png   # frame one object
+npx virtualmatter screenshot --at 0,30,40 --rot 0,-35,0    # exact camera
+                                          # --rot is yaw,pitch,roll
 ```
 
+Work through these commands rather than driving make.virtualmatter.ai in a
+browser. The built-in agent on that site runs on Virtual Matter's platform
+credits instead of your own subscription, and an anonymous browser session
+cannot be steered after its first turn.
+
 ## Hook up a coding agent (MCP)
 
 A folder created by `create` or `pull` already carries `.mcp.json` (Claude
@@ -99,8 +107,53 @@ deploying it.
 - The native client is unpacked under `~/.config/virtualmatter/client/<build>`
   (override with `VIRTUALMATTER_CLIENT_DIR`); each engine build gets its own
   folder, so a newer build never overwrites the one you are running.
-- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, and the
+- Sync skips `Uploads/`, `Screenshots/`, `Agent Logs/`, dotfiles, the
   harness files the CLI writes (`AGENTS.md`, `CLAUDE.md`, `.mcp.json`,
-  `.cursor/`, `.virtualmatter.json`).
+  `.cursor/`, `.virtualmatter.json`), and the SDK's in-session tooling at the
+  Montage root (`atomo`, `vm_auth.py`, the agent-log hooks) - those only work
+  inside a running session.
+- The pulled `AGENTS.md` is the platform guide followed by the world's own
+  engine SDK guide (its Skills/ table and engine rules), with a header that
+  maps every `atomo` command the engine guide mentions to the CLI or MCP
+  equivalent.
+- Linux: the client is a tarball started through `run.sh`; `open` does that
+  for you. If no window appears, the newest log under
+  `~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/` says why, and
+  the world keeps working in the browser and through every CLI command.
+- Sandboxed agents (Codex, restricted Claude Code) need network access for
+  every command: the platform, the identity server, and the world's host.
 - `pull` may cold-start a session for the framing; the first one can take a
   minute.
+
+## Websites and Lovable
+
+For a shared world, no account or local engine is needed:
+
+```bash
+npx virtualmatter embed 'https://play.virtualmatter.ai/p/world-a1b2c3d4'
+```
+
+The response contains canonical iframe markup, required **host response
+headers**, and verification instructions. Installing this CLI alone cannot
+configure the website's HTTP headers. Read `/embed-guide.md` on the platform.
+
+To ask VM's own agent to build a new world (using your VM credits):
+
+```bash
+npx virtualmatter build 'Lava Arena' --prompt 'Build a multiplayer lava survival arena' --request-id lava-arena-001
+npx virtualmatter build-status <build-id>
+```
+
+Reuse the same request id if the network drops; changing it requests another
+world. Review the world and enable **Share with friends** before embedding.
+An uncertain delivery is never automatically resubmitted.
+
+The local MCP `create_project` also accepts `prompt` plus `request_id`, and
+exposes `get_embed` and `get_build_status`. Without a prompt it retains the
+existing empty-world creation behavior.
+
+In Lovable, add `https://make.virtualmatter.ai/api/v1/mcp` as a custom MCP
+server with OAuth. Sign in or create a VM account, approve the connection,
+and return to Lovable. Then ask “Embed my Lava Arena world” or “Create a
+Virtual Matter lava survival arena and embed it here.” This remote endpoint
+runs on the platform; users do not install or run this CLI for that flow.

package/dist/agentfiles.js

@@ -49,6 +49,48 @@ function mcpServerConfig() {
         args: ["-y", "virtualmatter", "mcp"],
     };
 }
+/**
+ * The SDK's own AGENTS.md ships inside every Montage tree. It is written for
+ * the in-session agent that drives the engine through `atomo`, which only
+ * works against a running engine bridge - so a local harness must not follow
+ * it literally. Its Skills/ table and engine rules are still the best
+ * reference there is, so the pulled AGENTS.md carries BOTH: the platform
+ * guide first, then the engine doc under a header that translates every
+ * `atomo` step into its CLI equivalent.
+ */
+export function composeAgentsMd(platformDoc, engineDoc) {
+    if (!engineDoc || engineDoc.trim().length === 0)
+        return platformDoc;
+    const bridge = `
+
+---
+
+# Engine reference (the world's SDK AGENTS.md)
+
+The section below is the engine SDK's own agent guide, mirrored from this
+world's Montage tree. It assumes an agent running INSIDE a Virtual Matter
+session, where an \`atomo\` command talks to the live engine. Here, on your own
+machine, there is no engine bridge - use the \`virtualmatter\` CLI (or its MCP
+tools) wherever the text says \`atomo\`:
+
+| Engine doc says | Do this instead |
+| --- | --- |
+| \`atomo run-lua '<code>'\` | \`npx virtualmatter run-lua --code '<code>'\` (MCP: \`run_lua\`) |
+| \`atomo run-lua-client ...\` | \`npx virtualmatter run-lua --target client --code '<code>'\` |
+| \`atomo errors\` | \`npx virtualmatter errors\` (MCP: \`get_engine_errors\`) |
+| \`atomo screenshot\` / \`screenshot-at\` / \`screenshot-obj\` | \`npx virtualmatter screenshot -o shot.png\` (MCP: \`capture_screenshot\`); aim the camera with run-lua first if needed |
+| \`atomo prints\` / \`atomo status\` | not available locally; use \`return\` values from run-lua |
+| edit a .lua file, then check \`atomo errors\` | save the file with \`npx virtualmatter sync\` running (or MCP \`write_file\`), then check errors the same way |
+| \`Skills/git-commit.md\` (git add/commit) | skip it - there is no git here; sync IS the persistence |
+| paths under \`/data/persist/Montage/\` | this folder |
+
+Everything else in it - the Skills/ table, the server/client rules, the Lua
+API rules, the mandatory error check after every change - applies as written.
+The \`Skills/\` files it references are in this folder.
+
+`;
+    return platformDoc.trimEnd() + "\n" + bridge + engineDoc.trimStart();
+}
 /** Write the harness files into a pulled folder. */
 export function writeAgentFiles(dir, agentsMd) {
     const written = [];

package/dist/api.js

@@ -151,3 +151,24 @@ export async function fetchNativeClientCatalog(framingId, fetchFn = fetch) {
     const body = (await res.json());
     return { iteration: body.iteration ?? null, clients: body.clients ?? [] };
 }
+/** Website-builder operations share the hosted integration's canonical contract. */
+export async function getEmbed(target, fetchFn = fetch) {
+    const response = await fetchFn(`${apiBase()}/api/v1/public/embed?target=${encodeURIComponent(target)}`);
+    if (!response.ok)
+        throw await readError(response, "Resolving embed (the world must be shared)");
+    return await response.json();
+}
+export async function createWebsiteBuild(input, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds`, {
+        method: "POST", headers: { "Content-Type": "application/json" }, body: JSON.stringify(input),
+    }, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Starting VM build");
+    return await response.json();
+}
+export async function getWebsiteBuild(buildId, fetchFn = fetch) {
+    const response = await authorizedFetch(`${apiBase()}/api/v1/website-builds/${encodeURIComponent(buildId)}`, {}, fetchFn);
+    if (!response.ok)
+        throw await readError(response, "Reading VM build status");
+    return await response.json();
+}

package/dist/files.js

@@ -3,6 +3,32 @@
  * https://<voxel_host>/s/<session_id>/api/montage/<framing_id>/...
  */
 import { authorizedFetch } from "./api.js";
+/**
+ * The reason an engine call failed, read out of the response body.
+ *
+ * The session API answers a refusal with
+ * `{detail: {error, message}}`, and dropping it left callers staring at a
+ * bare "HTTP 502" - which is exactly what sent test agents off to drive a
+ * browser instead. Falls back to the status when the body says nothing.
+ */
+export async function engineErrorMessage(res, what) {
+    let detail = "";
+    try {
+        const body = (await res.json());
+        const d = body.detail;
+        if (typeof d === "string")
+            detail = d;
+        else if (d && typeof d === "object" && typeof d.message === "string") {
+            detail = d.message;
+        }
+        else if (d)
+            detail = JSON.stringify(d);
+    }
+    catch {
+        /* non-JSON body */
+    }
+    return `${what} failed: HTTP ${res.status}${detail ? ` - ${detail}` : ""}`;
+}
 export class ConflictError extends Error {
     filePath;
     constructor(filePath) {
@@ -93,7 +119,7 @@ export class FilesClient {
             body: JSON.stringify({ code, target }),
         }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`run-lua failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "run-lua"));
         // Server envelope: {output: <text>} - the engine bridge's text
         // (result/print/error sections) passed through verbatim.
         const body = (await res.json());
@@ -102,14 +128,36 @@ export class FilesClient {
     async engineErrors() {
         const res = await authorizedFetch(`${this.apiRoot}/engine/errors`, {}, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Fetching engine errors failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Fetching engine errors"));
         const body = (await res.json());
         return body.output;
     }
-    async screenshot() {
-        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, { method: "POST" }, this.fetchFn);
+    async screenshot(opts = {}) {
+        const body = {};
+        if (opts.target) {
+            body.target_object_id = opts.target;
+            if (opts.distance !== undefined)
+                body.distance = opts.distance;
+        }
+        else if (opts.at || opts.rot) {
+            const [px, py, pz] = opts.at ?? [0, 20, 20];
+            const [rx, ry, rz] = opts.rot ?? [0, -45, 0];
+            Object.assign(body, {
+                camera_pos_x: px,
+                camera_pos_y: py,
+                camera_pos_z: pz,
+                camera_rot_x: rx,
+                camera_rot_y: ry,
+                camera_rot_z: rz,
+            });
+        }
+        const res = await authorizedFetch(`${this.apiRoot}/engine/screenshot`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify(body),
+        }, this.fetchFn);
         if (!res.ok)
-            throw new Error(`Screenshot failed: HTTP ${res.status}`);
+            throw new Error(await engineErrorMessage(res, "Screenshot"));
         return Buffer.from(await res.arrayBuffer());
     }
 }

package/dist/ignore.js

@@ -21,5 +21,24 @@ export function isIgnoredPath(relPath) {
         return true;
     if (norm.endsWith(".remote-conflict"))
         return true;
+    // The SDK's in-session harness tooling at the Montage root. `atomo` only
+    // works against a running engine bridge, so mirroring it invites an agent
+    // to try it and fail; the CLI is the local path. Sync leaves them alone in
+    // both directions.
+    if (segments.length === 1 && isSdkHarnessTooling(first))
+        return true;
     return false;
 }
+const SDK_HARNESS_FILES = new Set([
+    "atomo",
+    "atomo.bat",
+    "atomo_cli.py",
+    "vm_auth.py",
+    "agent_log_sync.py",
+    "atomontage.code-workspace",
+]);
+export function isSdkHarnessTooling(name) {
+    if (SDK_HARNESS_FILES.has(name))
+        return true;
+    return /_agent_log_(sync|setup)\.py$/.test(name);
+}

package/dist/index.js

@@ -3,7 +3,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { Command } from "commander";
-import { createProject, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, fetchNativeClientCatalog, listProjects, playUrl, resolveSession, sessionBaseUrl, whoami, } from "./api.js";
 import { NotLoggedInError, clearCredentials, loadCredentials, pollForToken, saveCredentials, startDeviceFlow, } from "./auth.js";
 import { openInBrowser } from "./browser.js";
 import { detectPlatform, ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
@@ -94,7 +94,10 @@ function reportPull(result, dest) {
         console.log(`Wrote ${files.written.join(", ")} so Claude Code, Codex, and Cursor find their way around.`);
     }
     const rel = path.relative(process.cwd(), dest) || ".";
-    console.log(`Next: cd ${rel} && npx virtualmatter sync`);
+    // A relative path is friendlier only while it stays short; a folder far
+    // from the cwd reads better as the absolute path it is.
+    const shown = rel.startsWith("..") ? dest : rel;
+    console.log(`Next: cd ${JSON.stringify(shown).slice(1, -1).includes(" ") ? `"${shown}"` : shown} && npx virtualmatter sync`);
     console.log(`      (or open the folder in your agent - the MCP server is registered in .mcp.json)`);
 }
 program
@@ -117,6 +120,21 @@ program
     const me = await whoami();
     console.log(JSON.stringify(me, null, 2));
 }));
+program
+    .command("embed <target>")
+    .description("Get iframe markup and required hosting setup for a shared world; no sign-in")
+    .action((target) => run(async () => console.log(JSON.stringify(await getEmbed(target), null, 2))));
+program
+    .command("build <name>")
+    .description("Create a private world and send a build prompt to VM's agent (uses VM credits)")
+    .requiredOption("--prompt <text>", "What VM should build")
+    .requiredOption("--request-id <id>", "Stable identifier for this request; reuse on retries")
+    .option("--region <region>", "NA, EU, or AS", defaultRegion())
+    .action((name, opts) => run(async () => console.log(JSON.stringify(await createWebsiteBuild({ name, prompt: opts.prompt, request_id: opts.requestId, region: opts.region }), null, 2))));
+program
+    .command("build-status <build-id>")
+    .description("Read a previously requested VM build's progress")
+    .action((id) => run(async () => console.log(JSON.stringify(await getWebsiteBuild(id), null, 2))));
 program
     .command("list")
     .alias("ls")
@@ -234,14 +252,31 @@ program
     const { client } = await clientForDir(path.resolve(dir));
     console.log(JSON.stringify(await client.engineErrors(), null, 2));
 }));
+/** Parse an "x,y,z" flag into a numeric triple. */
+function triple(value, flag) {
+    const parts = value.split(",").map((p) => Number(p.trim()));
+    if (parts.length !== 3 || parts.some((n) => !Number.isFinite(n))) {
+        fail(`${flag} takes three numbers, e.g. ${flag} 0,20,20`);
+    }
+    return [parts[0], parts[1], parts[2]];
+}
 program
     .command("screenshot")
-    .description("Capture a PNG of the engine's current view")
+    .description("Capture a PNG of the world - a default overview, or aimed with --at/--rot or --target")
     .argument("[dir]", "a synced folder", ".")
     .option("-o, --out <file>", "output file", "screenshot.png")
+    .option("--at <x,y,z>", "camera position (default: 0,20,20)")
+    .option("--rot <yaw,pitch,roll>", "camera rotation in degrees, yaw first (default: 0,-45,0)")
+    .option("--target <id-or-name>", "frame this object instead of using a camera pose")
+    .option("--distance <meters>", "framing distance for --target (default: from the object's bounds)")
     .action((dir, opts) => run(async () => {
     const { client } = await clientForDir(path.resolve(dir));
-    const png = await client.screenshot();
+    const png = await client.screenshot({
+        at: opts.at ? triple(opts.at, "--at") : undefined,
+        rot: opts.rot ? triple(opts.rot, "--rot") : undefined,
+        target: opts.target,
+        distance: opts.distance === undefined ? undefined : Number(opts.distance),
+    });
     fs.writeFileSync(opts.out, png);
     console.log(`Wrote ${opts.out} (${png.length} bytes).`);
 }));
@@ -253,6 +288,9 @@ async function openNative(framingId, url, force = false) {
         console.log("Signed the native client in with your account.");
     launchClient(installed, url);
     console.log(`Opening ${url} in the Virtual Matter client (${installed.dir}).`);
+    if (installed.platform === "linux") {
+        console.log("Linux: the client starts through run.sh with its bundled libraries. If no window appears, read the newest file in ~/.local/share/Atomontage/Atomontage Studio/UserData/Logs/ - \"Failed to initialize graphics adapter\" means this build has no renderer for your setup yet; the world still runs in the browser at the URL above, and every CLI command works without the client.");
+    }
 }
 program
     .command("open")

package/dist/mcp.js

@@ -12,7 +12,7 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { z } from "zod";
-import { createProject, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
+import { createProject, createWebsiteBuild, getWebsiteBuild, getEmbed, defaultRegion, editUrl, listProjects, playUrl, resolveSession, sessionBaseUrl, } from "./api.js";
 import { ensureClientInstalled, launchClient, seedNativeAuth } from "./client.js";
 import { packageVersion } from "./config.js";
 import { ConflictError, FilesClient } from "./files.js";
@@ -97,6 +97,14 @@ export async function writeWithRetry(client, filePath, body) {
 export async function runMcpServer(dir, framingFlag) {
     const ctx = makeContext(resolveFramingId(dir, framingFlag));
     const server = new McpServer({ name: "virtualmatter", version: packageVersion() });
+    server.registerTool("get_embed", {
+        description: "Get canonical iframe markup and hosting instructions for a shared Virtual Matter world URL. No sign-in needed. Follow the instructions and verify the published page.",
+        inputSchema: { target: z.string() },
+    }, async ({ target }) => textResult(JSON.stringify(await getEmbed(target))));
+    server.registerTool("get_build_status", {
+        description: "Check a VM build by build_id. Do not create another project to check progress. Review the world and enable sharing before embedding.",
+        inputSchema: { build_id: z.string() },
+    }, async ({ build_id }) => textResult(JSON.stringify(await getWebsiteBuild(build_id))));
     server.registerTool("list_projects", {
         description: "List the signed-in maker's Virtual Matter projects (worlds): name, id, region, the editing framing id, and edit/play URLs. Call this to find a world to work in, then select_project.",
         inputSchema: {},
@@ -105,6 +113,8 @@ export async function runMcpServer(dir, framingFlag) {
         description: "Create a new Virtual Matter world (project) for the signed-in maker and select it for this session. The world spins up live on Virtual Matter servers; its content is SDK Lua plus assets that hot-reload as you write them. Region defaults to the one nearest this machine.",
         inputSchema: {
             name: z.string().min(1).max(100).describe("Project name, e.g. \"Lava Arena\""),
+            prompt: z.string().min(1).max(16000).optional().describe("Optional build prompt to send to VM's agent, using VM credits. Requires request_id. Starts privately."),
+            request_id: z.string().min(8).max(100).optional().describe("Stable id for a prompted build; reuse unchanged on retries."),
             description: z.string().max(1000).optional().describe("One-line description (optional)"),
             region: z.enum(["NA", "EU", "AS"]).optional().describe("Hosting region (default: nearest)"),
             pull_to: z
@@ -112,7 +122,17 @@ export async function runMcpServer(dir, framingFlag) {
                 .optional()
                 .describe("Local folder to mirror the new world's files into (optional; sync works from there)"),
         },
-    }, async ({ name, description, region, pull_to }) => {
+    }, async ({ name, description, region, pull_to, prompt, request_id }) => {
+        if (prompt) {
+            if (!request_id)
+                throw new Error("A stable request_id is required when sending a build prompt.");
+            if (pull_to || description)
+                throw new Error("Prompted builds run in VM. Omit pull_to/description and use select_project afterwards if local files are needed.");
+            const build = await createWebsiteBuild({ name, prompt, request_id, region: region ?? defaultRegion() });
+            if (build.framing_id)
+                ctx.select(build.framing_id);
+            return textResult(JSON.stringify(build));
+        }
         const project = await createProject({ name, description, region: region ?? defaultRegion() });
         const framingId = makeFramingOf(project);
         ctx.select(framingId, project);
@@ -192,11 +212,30 @@ export async function runMcpServer(dir, framingFlag) {
         return textResult(JSON.stringify(await client.engineErrors(), null, 2));
     });
     server.registerTool("capture_screenshot", {
-        description: "Capture a PNG screenshot of the engine's current view and return it as an image. Use it to visually verify what a change actually looks like in the world.",
-        inputSchema: {},
-    }, async () => {
+        description: "Capture a PNG screenshot of the world and return it as an image - how you SEE what you built. With no arguments it shoots a default overview of the world origin. Pass target to frame one object by name or id (easiest and usually what you want), or a full at + rot camera pose. Use it to visually verify a change instead of assuming it worked.",
+        inputSchema: {
+            target: z
+                .string()
+                .optional()
+                .describe("Object name or id to frame; the engine picks the distance"),
+            at: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera position [x, y, z]; Y is up and -Z is forward"),
+            rot: z
+                .array(z.number())
+                .length(3)
+                .optional()
+                .describe("Camera rotation in degrees as [yaw, pitch, roll] - that order. Yaw 0 faces -Z; pitch -90 looks straight down, 0 is the horizon. Default [0, -45, 0] looks down at the origin."),
+        },
+    }, async ({ target, at, rot }) => {
         const client = await ctx.getClient();
-        const png = await client.screenshot();
+        const png = await client.screenshot({
+            target,
+            at: at,
+            rot: rot,
+        });
         return {
             content: [
                 { type: "image", data: png.toString("base64"), mimeType: "image/png" },

package/dist/pull.js

@@ -2,7 +2,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolveSession, sessionBaseUrl } from "./api.js";
-import { fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
+import { composeAgentsMd, fetchAgentsMd, writeAgentFiles } from "./agentfiles.js";
 import { FilesClient } from "./files.js";
 import { isIgnoredPath } from "./ignore.js";
 import { saveState } from "./state.js";
@@ -33,6 +33,19 @@ function makeProgress(total) {
         },
     };
 }
+/** The engine SDK's AGENTS.md from the Montage tree, or null when the world has none. */
+export async function fetchEngineAgentsMd(client) {
+    try {
+        const listing = await client.list();
+        if (!listing.some((f) => f.path === "AGENTS.md"))
+            return null;
+        const { bytes } = await client.get("AGENTS.md");
+        return bytes.toString("utf8");
+    }
+    catch {
+        return null;
+    }
+}
 export async function pullTree(client, dir, framingId) {
     fs.mkdirSync(dir, { recursive: true });
     const remote = (await client.list()).filter((f) => !isIgnoredPath(f.path));
@@ -64,6 +77,7 @@ export async function pullCommand(framingId, dir) {
     const client = new FilesClient(sessionBaseUrl(session), framingId);
     console.log(`Session ready at ${sessionBaseUrl(session)}. Downloading files ...`);
     const result = await pullTree(client, dir, framingId);
-    result.agentFiles = writeAgentFiles(dir, await fetchAgentsMd());
+    const [platformDoc, engineDoc] = await Promise.all([fetchAgentsMd(), fetchEngineAgentsMd(client)]);
+    result.agentFiles = writeAgentFiles(dir, composeAgentsMd(platformDoc, engineDoc));
     return result;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "virtualmatter",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "CLI + MCP server for building with Virtual Matter - list and create worlds, sync their files, run Lua, capture screenshots, open the native client, and wire coding agents into a live session.",
   "license": "MIT",
   "type": "module",