sbox-claude

s&box Claude Bridge

Let non-coders build s&box games through conversation with Claude Code.

What This Does

Claude Code connects to the s&box editor in real-time. You describe what you want — Claude writes the C# scripts, builds the scenes, and iterates until it works.

You: "Make me a horror game where I explore an abandoned hospital with a flashlight"
Claude: *creates scripts, builds scene, configures lighting, adds player controller*

Architecture

┌──────────────┐     stdio      ┌───────────────┐   file IPC     ┌──────────────┐
│  Claude Code │ ◄────────────► │  MCP Server   │ ◄────────────► │ Bridge Addon │
│              │                │  (Node.js)    │   %TEMP%/      │  (in s&box)  │
└──────────────┘                └───────────────┘                └──────┬───────┘
                                                                       │
                                                                       ▼
                                                                ┌──────────────┐
                                                                │ s&box Editor │
                                                                │  (Source 2)  │
                                                                └──────────────┘

Communication uses file-based IPC through %TEMP%/sbox-bridge-ipc/ — the MCP server writes request JSON files, the bridge addon (running inside s&box) polls for them, processes on the main editor thread, and writes response files back.

Quick Start

Important: the bridge addon MUST live inside an s&box project's Libraries/ folder. Putting it in s&box's global addons/ folder will silently fail to compile. The installer below handles this correctly.

Fastest path — install the Claude Code plugin

If you use Claude Code, the easiest install is the bundled plugin (under plugins/sbox-claude/ in this repo). It registers the MCP server automatically and ships the sbox-build-feature skill + sbox-game-dev agent.

/plugin marketplace add LouSputthole/Sbox-Claude
/plugin install sbox-claude

You still need to install the bridge addon into your s&box project (Steps 1-4 below) — the plugin only handles the Claude side. See plugins/sbox-claude/README.md for details.

Manual install (no plugin)

1. Clone and install the bridge into your project

# Windows
git clone https://github.com/lousputthole/sbox-claude.git
cd sbox-claude
.\install.ps1                                    # auto-detects your s&box project
# or:
.\install.ps1 -ProjectPath "C:\path\to\your\sbox\project"
.\install.ps1 -ListProjects                      # show all projects, then exit
.\install.ps1 -RemoveStaleAddons                 # also clean up old wrong-location installs

# Linux / WSL / macOS
git clone https://github.com/lousputthole/sbox-claude.git
cd sbox-claude
./install.sh                                     # auto-detects
./install.sh /path/to/your/sbox/project          # explicit
./install.sh --list                              # show projects
./install.sh --remove-stale                      # also clean up old wrong-location installs

This copies the bridge to <your-project>/Libraries/claudebridge/. If you previously ran an older installer that put files under <sbox>/addons/, pass -RemoveStaleAddons / --remove-stale to clean them up — those files never compiled and only cause confusion.

2. Build the MCP server

cd sbox-mcp-server
npm install
npm run build

3. Register the MCP server with Claude Code (one-time)

claude mcp add sbox -- node /full/path/to/sbox-claude/sbox-mcp-server/dist/index.js

Or, if you have the published npm package:

claude mcp add sbox -- npx sbox-mcp-server

4. Open the bridge dock

In s&box, go to View → Claude Bridge to open the dock. The dock must stay visible — the bridge's frame handler only fires while the dock is on-screen. If you close it, every Claude tool call will time out.

5. Verify

Ask Claude:

"Check the bridge status."

If it reports connected: true and handlerCount: 100, you're set. If it times out, see TROUBLESHOOTING.md.

6. Start building

"Create a first-person player controller with WASD movement and mouse look"
"Add a cube at position 0,0,100 and give it a box model"
"What scenes are in the project?"
"Create a new script called EnemyAI with patrol behavior"

Available Tools (109 defined)