# Virtual Matter

> Virtual Matter is a platform for building and hosting live multiplayer voxel worlds. You build a world by prompting a built-in coding agent or by editing its SDK Lua directly - the world runs on Virtual Matter servers, hot-reloads as you edit, and is shareable by URL from minute one. The built-in agent runs on platform credits; external coding agents (Claude Code, Cursor, Codex) work with your own subscription through the `virtualmatter` CLI and its MCP server.

Key facts for agents and crawlers:

- Worlds ("projects") are created with Virtual Matter at https://virtualmatter.ai/ by describing what you want in a prompt.
- Every world is live and multiplayer from creation: an /edit URL for making, /play and /g share URLs for anyone to join in a browser, no install required.
- A world's content is SDK Lua scripts plus assets under a Montage/ tree. Edits made in the live session hot-reload into the running world - including edits pushed from a local mirror by `virtualmatter sync`. Virtual Matter can publish a project's content to a GitHub repo in your account for versioning and remixing.
- A native desktop/mobile client exists for higher performance than the browser WASM client. Per-platform installer URLs are served as JSON by an unauthenticated API: GET https://make.virtualmatter.ai/api/v1/public/native-clients
- The `virtualmatter` CLI (npm, Node >= 20) is the whole developer surface for external agents: it signs in with a device code on first use (no separate login step), lists and creates worlds, mirrors a world's files locally, live-syncs edits into the running session, runs Lua in the engine, reads engine errors, takes screenshots, downloads and opens the native desktop client already signed in, and serves all of it to coding agents over MCP:
  - Create a world and mirror it: `npx virtualmatter create "My world"` (signs you in if needed)
  - Or mirror an existing one - any Virtual Matter link works, /edit, /play, /g, /p, /projects, slugged or not: `npx virtualmatter pull <world URL>`
  - See your worlds: `npx virtualmatter list`
  - Live-sync saves into the running world: `npx virtualmatter sync` (inside the mirrored folder)
  - Open the world in the native client (downloaded on first use): `npx virtualmatter open`
  - Wire it into Claude Code: `claude mcp add virtualmatter -- npx -y virtualmatter mcp`, or into Codex: `codex mcp add virtualmatter -- npx -y virtualmatter mcp`. A mirrored folder also carries `.mcp.json`, `.cursor/mcp.json`, `AGENTS.md`, and `CLAUDE.md`, so Claude Code and Cursor find the MCP server on their own and Codex finds the project briefing; Codex still needs the one-time `codex mcp add`.
  - Do NOT drive make.virtualmatter.ai in a browser, and do NOT type prompts into the built-in agent on that site. That agent runs on Virtual Matter's platform credits rather than your own subscription, an anonymous browser session cannot be steered after its first turn, and a browser gives you no way to read engine errors. Everything the site's agent can do, the CLI does from your own harness: create the world, write its Lua, hot-reload it, read errors, take screenshots.
  - Sandboxed agents (Codex, Claude Code in restricted mode): every `npx virtualmatter` command needs network access to make.virtualmatter.ai, auth.atomontage.app, and the world's voxel host; run it with network enabled or outside the sandbox.
  - The AGENTS.md shipped INSIDE the desktop client's Data/Sdk/Montage/ is the engine's in-session guide and assumes `atomo`, which only works against a running engine. From a local harness use this CLI; the folder it creates carries a merged AGENTS.md that translates every `atomo` step.
  - MCP tools: `list_projects`, `create_project`, `select_project`, `list_files`, `read_file`, `write_file`, `run_lua`, `get_engine_errors`, `capture_screenshot`, `open_native_client`, `world_info`.

## Docs

- [Developer quickstart](https://virtualmatter.ai/developers): Agent-first quickstart - how to create a world, download the native client, and mod a world by editing its Lua.
- [Developer quickstart as Markdown](https://virtualmatter.ai/developers.md): The same page as plain Markdown, generated from the same source, so the two never differ.
- [Agent briefing](https://virtualmatter.ai/agent-briefing.md): Only the block from the quickstart that is safe to ingest verbatim.
- [AGENTS.md](https://make.virtualmatter.ai/AGENTS.md): How a coding agent should think about a Virtual Matter project, with an SDK Lua cheat sheet.
- [Full developer docs](https://virtualmatter.ai/llms-full.txt): The quickstart and AGENTS.md concatenated into one Markdown file.
- [Embed guide](https://make.virtualmatter.ai/embed-guide.md): How to embed a world in Lovable or another website, including the required COOP and COEP response headers.

## Tools

- [virtualmatter on npm](https://www.npmjs.com/package/virtualmatter): The CLI and its local stdio MCP server (`npx virtualmatter mcp`).
- [Hosted MCP server](https://make.virtualmatter.ai/api/v1/mcp): Remote MCP endpoint with OAuth sign-in, for Lovable and other MCP clients that cannot run a local command.

## Play

- [Public games catalog](https://play.virtualmatter.ai/): Published worlds anyone can play in the browser without signing in.

## API

- [Native client downloads](https://make.virtualmatter.ai/api/v1/public/native-clients): JSON list of per-platform native client installers (Windows, macOS, Linux, Android, iOS).

## Embed worlds in Lovable and other website builders
- When asked to embed a Virtual Matter URL, fetch https://make.virtualmatter.ai/api/v1/public/embed?target=<encoded-world-URL>. It returns the iframe and required hosting setup; the user does not need to supply a documentation URL.
- [Website embedding guide](https://make.virtualmatter.ai/embed-guide.md): authoritative iframe markup, isolation headers, and published-site verification.
- GET /api/v1/public/embed?target=<encoded-world-URL> resolves a shared world without an account.
- Remote MCP: https://make.virtualmatter.ai/api/v1/mcp (OAuth; connect in Lovable's custom MCP connectors).
- Public MCP: https://make.virtualmatter.ai/api/v1/mcp/public (no authentication; get_embed only).
- Tools: list_projects, get_embed, create_project (name, prompt, stable request_id), get_build_status.
- New users sign up in the connection window. New builds use VM credits and start privately; enable Share with friends after reviewing before embedding. Do not publish automatically.