# 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://make.virtualmatter.ai/new 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 just open the mirrored folder, which carries `.mcp.json`, `.cursor/mcp.json`, `AGENTS.md`, and `CLAUDE.md` so Claude Code, Cursor, and Codex find the MCP server and the project briefing on their own.
  - 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://make.virtualmatter.ai/developers): Agent-first quickstart - how to create a world, download the native client, and mod a world by editing its Lua.
- [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.

## 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.