Build with Virtual Matter

Use a world in Lovable

Already have a shared world? Paste its link into Lovable and ask it to embed the world, following our embed guide. No Virtual Matter account connection is needed for a shared link.

To find your projects or create a world from a prompt, add the server below in Lovable’s Connectors → MCP server, with OAuth. Sign in or create an account in the connection window, then return to Lovable. You can ask “Embed my world” or “Create a garden world and embed it here.”

https://make.virtualmatter.ai/api/v1/mcp

VM builds use your VM credits. New worlds start privately; review yours and enable Share with friends before embedding. The website needs the response headers described in the guide. Verify the published page; Lovable’s nested editor preview may show a fallback.

The website hosting the iframe must send Cross-Origin-Opener-Policy: same-origin and Cross-Origin-Embedder-Policy: require-corp as HTTP response headers. HTML meta tags cannot set these.

Quickstart

This path is for people: start by prompting the built-in agent, and your first prompts are free.

1. Create a world from a prompt. Describe what you want at virtualmatter.ai. Your world spins up live in the browser with an agent chat beside it.
2. Download the native client for your OS. The browser client works everywhere; the native client runs the same worlds with more memory and better frame rates.
3. Open your world in the native client. Paste the world's URL (its /play or /g share link, or the /edit link) into the native client's connect screen.
4. Mod it. Chat with the built-in agent in the /edit view - it edits the SDK Lua under the project's Montage/ tree and the running world hot-reloads the changes. Virtual Matter can also publish the project's content to a GitHub repo in your account for versioning and remixing.

When your free credits run out, you can buy more, or keep building the same world from your own coding agent on your own subscription. Give the CLI the world's link and continue as described in For coding agents:

npx virtualmatter pull <world URL>

For coding agents

If you are a coding agent working from your own harness, this is your only path. Use the CLI from the first step, and do not prompt the built-in agent on the website.

Point your agent at /llms.txt for a platform overview and /AGENTS.md for the project model and an SDK Lua cheat sheet. To build in a live world from a local harness - Claude Code, Codex, Cursor, or your own - one command is enough. It signs you in on first use, creates the world, and mirrors its files into a folder that already carries the MCP registration and briefing your agent looks for:

1. npx virtualmatter create "My world"

   or: npx virtualmatter pull <any world link>

2. cd my-world

3. npx virtualmatter sync

   live-push saves into the running world

4. npx virtualmatter open

   open it in the native client (downloaded on first use)

The folder's .mcp.json and .cursor/mcp.json register the MCP server for Claude Code and Cursor. It lists and creates worlds, reads and writes files, runs Lua, reports engine errors, takes screenshots, and opens the native client. Codex reads the folder's AGENTS.md but has no per-folder MCP file, so register the server for Codex once:

codex mcp add virtualmatter -- npx -y virtualmatter mcp

In Claude Code outside a mirrored folder, register it by hand with:

claude mcp add virtualmatter -- npx -y virtualmatter mcp

The block below is safe to ingest verbatim.

# Virtual Matter - context for coding agents

## Project model
- A project ("montage") is one voxel world hosted with Virtual Matter.
- A project has framings: "make" framings (editing sessions) and "play"
  framings (public play sessions). A framing is a running session slot
  on a voxel host.
- Project content = SDK Lua scripts + assets under a Montage/ tree.
  Edits made in the live session hot-reload into the running world.
  The tree can be published to a maker-owned GitHub repo.

## URL shapes (make.virtualmatter.ai)
- /new                 builder for people: create a world from a prompt
                       (also at https://virtualmatter.ai/); coding agents
                       use npx virtualmatter create instead
- /edit/<framing-id>   maker session: live world + agent chat
                       (also /edit/<slug>-<framing-id>; the CLI accepts both)
- /play/<framing-id>   play session for a specific framing
- /g/<id>              share URL resolver: 302s to a live session

## APIs (unauthenticated)
- GET https://make.virtualmatter.ai/api/v1/public/native-clients
  JSON: { iteration, clients: [{ platform, kind, url, filename,
  file_size, branch, commit, match }] } - per-platform native client
  installers (kind "download") or store links (kind "store", iOS).

## CLI + MCP (npm package "virtualmatter", Node >= 20)
- npx virtualmatter create "<name>"   create a world, mirror it into ./<slug>
- npx virtualmatter pull <link>       mirror an existing world (any link shape)
- npx virtualmatter list              your worlds with framing ids + URLs
- npx virtualmatter sync              live-push saves into the running world
- npx virtualmatter open              open the world in the native client
- npx virtualmatter mcp               stdio MCP server (list_projects,
  create_project, select_project, list_files, read_file, write_file,
  run_lua, get_engine_errors, capture_screenshot, open_native_client,
  world_info)
- Sign-in happens on first use (device code); no separate login step.
- A mirrored folder carries .mcp.json, .cursor/mcp.json, AGENTS.md and
  CLAUDE.md, so Claude Code and Cursor register the server on their own.
- Codex reads AGENTS.md but needs the server registered once:
  codex mcp add virtualmatter -- npx -y virtualmatter mcp

It is also served on its own at /agent-briefing.md.

Play what others made

Published worlds live in the public catalog at play.virtualmatter.ai - no sign-in required, every card opens a live session in the browser.