sbox-agent-bridge is a provider-neutral MCP server + s&box editor bridge. It gives agents a safe, observable way to operate the editor: read live scene state, make undoable changes, assign assets, run play mode, inspect compile/log feedback, and verify results from the editor instead of guessing from files.
Think: Claude/Codex/Kimi/etc. as a careful level-design and gameplay prototyping partner inside s&box — with narrow tools, read-backs, and smoke tests instead of an unsafe arbitrary-code bridge.
MCP server + s&box editor bridge that lets AI agents inspect, edit, test, and recover live s&box scenes.
星數
4
工具
—
可用率
—
A normal coding agent can edit C# files, but it cannot see what actually happened in the s&box editor. This bridge closes that loop.
Without the bridge
With sbox-agent-bridge
Guess scene state from source files
Read the active editor scene or runtime GameSession
Write code and hope hotload worked
Wait for compile, read diagnostics, inspect logs
Manually place/check objects
Create, transform, parent, frame, and verify GameObjects
Guess asset paths and component shapes
Search assets and inspect property schemas before writing
Test gameplay by squinting at the viewport
Invoke deterministic runtime test actions and capture cameras
Recover stale play-mode sessions manually
Use editor.recover_scene, tab reads, and wait helpers
Quick start
Requirements: s&box installed, Node.js 20+, npm, and an MCP-capable client.
1. Build the MCP server
git clone https://github.com/user1303836/sbox-agent-bridge.git
cd sbox-agent-bridge\mcp-server
npm install
npm run build
2. Install the editor bridge into a project
For a fresh test project, create a Minimal Game project and install the bridge:
Use the sbox-agent-bridge MCP tools to run the bridge doctor, list editor tabs, summarize the active scene, and inspect the current selection. Do not mutate the scene yet.
Then try one tiny edit:
Create one GameObject named Agent Bridge Test, verify that it exists, then undo the creation.
What agents can do today
Area
Examples
Editor health
bridge.doctor, project info, tab/session reads, stale play-tab warnings
Once the bridge is installed, an agent can perform a full editor loop:
Run bridge.doctor and read the active project/scene.
Create or recover a saved scene.
Add GameObjects, components, models, materials, physics, sound, and prefabs.
Validate component values before mutating them.
Save the scene and enter play mode.
Wait for runtime readiness and inspect the live GameSession.
Run deterministic runtime test actions.
Capture camera output and inspect compile/log feedback.
Stop play mode and recover the editable scene.
That loop is what makes the bridge different from a file-only coding assistant: the agent can observe the editor, act, and verify.
Smoke tests
CI validates the TypeScript MCP server and metadata. Live editor behavior requires s&box to be open.
cd mcp-server
npm run ci # typecheck, unit tests, build
npm run smoke:mvp-suite # preferred external-tester live gate
npm run audit:capabilities
The MVP suite creates its own saved scene and verifies the main bridge path: doctor, compile wait, scene recovery, object creation, model/material assignment, asset type/resource/cloud reads, physics/sound/network/prefab read-back, runtime preview capture, scene metadata, spatial radius search, runtime component type discovery, undoable destruction, project file/input/reference helpers, script introspection and compile recovery, animation helper setup, particle setup, play/stop settle, and cleanup.
Other focused smokes:
npm run smoke:bootstrap
npm run smoke:matrix-core
npm run smoke:project
npm run smoke:reference
npm run smoke:scripts
npm run smoke:assets
npm run smoke:asset-resources
npm run smoke:physics
npm run smoke:prefabs
npm run smoke:sounds
npm run smoke:network
npm run smoke:capability-gaps
npm run smoke:runtime
npm run walkthrough:arpg
npm run walkthrough:boxing
npm run audit:capabilities
See docs/testing.md for all live-smoke commands and environment variables.
Current caveats
This is useful now, but still intentionally honest:
The editor bridge must be installed into each s&box project that should expose live access.
CI cannot currently run a real s&box editor, so editor behavior is verified by local smoke tests.
Component discovery combines editor-visible TypeLibrary entries with runtime assembly scanning; exact-name component.add remains the fallback for compiled local components.
gameobject.duplicate is shallow: name/enabled/transform/parent, not full child/component cloning.
visual.capture_camera captures camera output, not the full editor/game viewport overlay or generic UI panel hierarchy.
Semantic model orientation still needs stored overrides or human/vision confirmation; bounds alone cannot prove “upright.”
There is no in-editor project switch action yet; use scripts/start-sbox-project.ps1 or open the .sbproj manually.
See docs/status.md for current verification status and limitations.