Mosaic Bridge

AI agents that drive the Unity Editor.

Mosaic Bridge connects MCP-compliant AI clients — Claude Code, Claude Desktop, Cursor, Gemini CLI, and any other Model Context Protocol client — to a running Unity Editor. It exposes ~290 tools covering GameObject and scene operations, procedural generation, physics simulation, pathfinding, rendering, animation, and more.

Free and open source under Apache 2.0. No telemetry. Your project never leaves your machine.

See it work

"Build me a Flappy Bird clone in Unity"

48 minutes later: a working game. No code written by hand, no manual editor clicks — Claude drove every Unity action through Mosaic Bridge tools.

▶ Watch the full build on YouTube

  You:     "Create a 3D tic-tac-toe board with warm wood styling and
            glowing cyan X pieces"
  Claude:  calls mosaic_gameobject_create, mosaic_material_create (uses
            KB for oak albedo), mosaic_physics_add-rigidbody, …
  Unity:   board appears in your scene, ready to play

---

What makes it different

• Research-paper implementations. ~90 of the tools are original implementations of published CS, graphics, and AI papers — Bridson's Poisson Disk (2007), Müller's SPH fluid (2003), Stam's Stable Fluids (1999), Orkin's GOAP (F.E.A.R. 2003), Lorensen-Cline Marching Cubes (1987), Reynolds' Boids (1987), Harabor-Grastien Jump Point Search (2011), Garland-Heckbert quadric decimation (1997). Not wrappers over Unity APIs — actual algorithms, callable by AI.

• Curated knowledge base. Tools that return physical quantities (density, friction, IOR, color temperature) draw from a bundled reference library — NIST physics constants, Unity's PhysicallyBased material data. Responses include citations. No hallucinated numbers.

• Multi-Unity-version. Works across Unity 6 (see Requirements for the tested matrix). Each Editor runs in its own per-project runtime directory, so multiple Editors on different projects can run concurrently without fighting for ports or files.

• Privacy-first. Loopback-only HTTP listener bound to 127.0.0.1, HMAC-SHA256 authenticated, telemetry off by default. Ephemeral ports, per-project discovery files (mode 0600 on Unix).

• Vendor-neutral. Apache 2.0 with explicit patent grant. Not a funnel for a paid product. Your tools, your keys, your data.

---

Requirements

• Unity 6000.3 or newer (see the matrix below)
• Node.js 18+ (for the MCP server)
• macOS, Windows, or Linux

Unity version support

The installer checks this for you. npx @mosaicxr-ai/create-bridge reads the project's ProjectVersion.txt and refuses to install into an editor the bridge cannot work on, rather than letting you discover it as compile errors after Unity reimports. Warnings don't block; errors do, and can be overridden with --ignore-unity-version if you know what you're doing.

| Unity | Installer | Status | |-------|-----------|--------| | 6000.3 | ✅ installs | Verified — full Editor test suite | | 6000.4 | ⚠️ warns | Works, but logs deprecation warnings | | 6000.5 | ✅ installs | Verified — full Editor test suite (recommended) | | 6000.0 – 6000.2 | ❌ blocks | No UnityEngine.EntityId | | 2022 LTS and older | ❌ blocks | Not supported | | Any alpha or beta | ❌ blocks | Prereleases are not tested — see below |

Stable releases only. Unity changes engine internals mid-cycle: the EntityId bit layout shifted between 6000.6.0a2 and 6000.6.0b5, which silently breaks every object lookup by InstanceId. Rather than chase moving targets, the bridge is tested against stable releases and the installer refuses prereleases. Use --ignore-unity-version if you want to try one anyway.

Node 18+ is checked the same way, before the installer touches your project.

All checks run identically on macOS, Windows, and Linux — the installer resolves paths per-platform and reads ProjectVersion.txt with either LF or CRLF line endings, so a project authored on Windows and one on macOS are treated the same.

Unity 6.5 replaced the 32-bit instance ID with the 64-bit EntityId. The bridge adapts automatically and keeps InstanceId a 32-bit int on the MCP wire, so tool schemas and clients are unchanged.

---

Quick install

One command. It walks you through the rest:

npx @mosaicxr-ai/create-bridge

The installer:

1. Asks for your Unity project path (create one in Unity Hub first if you haven't — any empty Unity 6000.3+ project works)
2. Asks which MCP client(s) to configure — Claude Code, Claude Desktop, Cursor, Gemini CLI, or OpenAI Codex (any combination)
3. Adds com.mosaic.bridge to the project's Packages/manifest.json
4. Writes the MCP server entry into each selected client's config

Then open the Unity project, wait for compile, restart your MCP client, and start prompting.

Updating to a newer version

Unity resolves a git dependency once and pins the resolved commit in Packages/packages-lock.json. It never re-checks, so simply re-running the installer reports already present — skipped and your project stays on the commit it first landed on. To actually upgrade:

npx @mosaicxr-ai/create-bridge --project-path <your-project> --update --yes

That rewrites the manifest entry and clears the pin, so Unity fetches the latest main the next time you open the project. To pin an exact commit, tag, or branch — useful when you need to know precisely what you're running:

npx @mosaicxr-ai/create-bridge --project-path <your-project> --ref main --yes

--ref implies --update. Reopen the Unity project afterwards and let it recompile. To confirm which commit you ended up on, check the folder name under Library/PackageCache/com.mosaic.bridge@<commit>, or the version shown in Window → Package Manager.

Non-interactive (CI / scripted)

Commands are written on a single line so they work unchanged in cmd, PowerShell, and bash — no shell-specific line continuations:

npx @mosaicxr-ai/create-bridge --project-path /path/to/UnityProject --clients claude-code,cursor --yes

See npx @mosaicxr-ai/create-bridge --help for all flags.

Scene-building intelligence + cross-LLM agents

The installer writes instruction files and specialist agents into your Unity project for every supported AI client:

| File | Client | |------|--------| | CLAUDE.md | Claude Code + Claude Desktop | | GEMINI.md | Gemini CLI | | AGENTS.md | OpenAI Codex | | .cursor/rules/mosaic-bridge.mdc | Cursor |

All instruction files enforce:

• Interview before building — when you give a vague prompt like "make me a desert scene", the AI asks 4 targeted questions (scene type, geographic reference, scale, player perspective) before touching any tools.
• Spatial coherence — every placed object Y is resolved from terrain/sample-height before placement. No more objects buried underground or floating in air.
• Correct build order — terrain → textures → lighting → structures → vegetation → post-processing → camera.

Three specialist skill agents are installed following the bmad-method convention — written to both .claude/skills/ (Claude Code slash commands) and .agents/skills/ (universal, works with Cursor, Gemini, Codex, Windsurf, OpenCode):

| Agent | Claude Code | Cursor | Codex | Best for | |-------|-------------|--------|-------|----------| | Zara — Project Guide | /mosaic-guide | @mosaic-guide | $mosaic-guide | Session start, preflight, pipeline issues | | Ray — Shader Expert | /mosaic-shader | @mosaic-shader | $mosaic-shader | ShaderGraph creation, node wiring, debugging | | Max — Scene Builder | /mosaic-scene | @mosaic-scene | $mosaic-scene | Full scene construction, particles, physics |

The installer also copies four workflows into .claude/workflows/ (preflight, scene-plan, shader-guide, session-handoff).

Workflow prompts (any MCP client)

Beyond the instruction files, the MCP server exposes the same protocol rules as MCP prompts, so every client — not just ones with a CLAUDE.md — can pull them on demand: preflight, scene-interview, session-handoff, and shader-guide. In Claude Code they show up in the prompt picker; other clients list them via prompts/list.

To skip writing instruction files:

npx @mosaicxr-ai/create-bridge --skip-claude

To refresh after an update:

npx @mosaicxr-ai/create-bridge --force

Manual install (if you prefer)

Add to <UnityProject>/Packages/manifest.json:

{
  "dependencies": {
    "com.mosaic.bridge": "https://github.com/MosaicXR-AI/mosaic-bridge.git?path=/packages/com.mosaic.bridge"
  }
}

Then point your MCP client at:

{
  "mcpServers": {
    "mosaic-bridge": {
      "command": "npx",
      "args": ["-y", "@mosaicxr-ai/mcp-server", "--project-path", "/path/to/UnityProject"]
    }
  }
}

---

What's inside

~290 tools across 64 categories. A sample:

| Category | Tools | Notable | |---|---|---| | Procedural Generation | 17 | Poisson Disk, Marching Cubes, Hydraulic Erosion, Wave Function Collapse, L-Systems, Voronoi, Blue Noise, Perlin / Simplex noise, 3D noise textures | | Simulation | 8 | SPH fluid, Boids, Stable Fluids / smoke, agent-based (ant colony, slime mold), cloth, orbital mechanics | | AI Behaviors | 11 | GOAP, Utility AI, Context Steering, Flow Fields, Jump Point Search, Behavior Trees, Steering | | Advanced Mesh | 10 | Quadric decimation, QuickHull, BSP/CSG boolean, Dual Contouring, icosphere subdivision | | Advanced Rendering | 12 | Volumetric clouds, atmospheric scattering, ray marching, SDF text, portals | | Physics | 10 | Rigidbody, collider, raycast, overlap, gravity, physics material, joints | | Spatial Data Structures | 6 | Spatial hash, k-d tree, octree | | Scene Intelligence | 4 | scene/create-object (asset search → store → procedural build), asset/find-3d, scene/plan-composition, terrain/get-regions | | GameObjects & Scenes | 15 | Create, delete, duplicate, reparent, hierarchy, stats, snap-to-ground | | Prefabs & Assets | 13 | Create, instantiate, overrides, variants, import, list, find-3d | | Components & Scripts | 9 | Add, remove, set property / reference, create/read/update scripts | | Animation | 7 | Controllers, states, blend trees, clips, IK setup, transitions | | Lighting & Graphics | 13 | Lights, baking, shaders, post-processing, shadergraph | | Cameras & ScreenShots | 6 | Camera info, scene/game/camera screenshots | | UI | 5 | Canvas, elements, layouts, rect transforms | | Navigation | 10 | NavMesh, agents, obstacles, pathfinding, FOV visualization, FABRIK IK | | Terrain | 10 | Height, paint, trees, detail, settings, grid, erosion, sample-height, get-regions | | Particles | 7 | Cr