UniBridge (VS Code)
Localhost TCP + NDJSON RPC bridge to the Unity Editor package com.workshop2d.uni-bridge.
Codex MCP integration
UniBridge exposes the active Unity connection to Codex through a local,
token-authenticated agent gateway and a stdio MCP adapter. Build the extension,
then register out/mcp/server.js in the Unity project's .codex/config.toml,
passing the Unity project root as the first argument.
The MCP adapter provides the same unity_* verification tools as the VS Code
language-model integration, including compilation, readiness, structured console
logs, tests, hierarchy inspection, and play-mode smoke tests. Reload VS Code after
updating the extension, and restart Codex after changing MCP configuration.
How it works
- Open a Unity project folder in VS Code (
Assets/ + ProjectSettings/).
- The extension listens on
127.0.0.1 and writes .uni-bridge/session.json.
- The Unity package connects as a client, sends
core.hello, and stays connected.
- Commands and Language Model Tools call Unity over the socket.
Commands
- UniBridge: Get Context Snapshot
- UniBridge: Request Compilation
- UniBridge: Inspect Selection
- UniBridge: Set Play Mode
- UniBridge: Run Tests
- UniBridge: Get Scene Hierarchy
- UniBridge: Ping Unity
| Tool |
Purpose |
notify_user |
Show a completion notification through VS Code |
unity_get_context |
Live editor snapshot |
unity_compile |
Compile and return diagnostics |
unity_run_tests |
Run EditMode/PlayMode tests |
unity_inspect_selection |
Inspect selection / object |
unity_set_play_mode |
enter/exit/pause/resume/step |
unity_get_hierarchy |
Shallow scene tree |
unity_search_assets |
AssetDatabase search |
unity_get_logs |
Filtered console ring buffer (errors/warnings/logs/…) |
unity_get_log_path |
Editor.log path for rare forensic reads |
unity_wait_for_ready |
Wait until Unity idle (survives domain reload) |
unity_refresh_assets |
AssetDatabase.Refresh + wait ready |
unity_play_smoke |
Short Play Mode runtime sanity check |
Autonomous loop
Recommended agent sequence after editing scripts:
unity_refresh_assets (or unity_compile)unity_wait_for_ready (usually already done by the tools above)unity_run_tests (failedOnly on retries)- optional
unity_play_smoke
unity_get_logs if something failed
uniBridge.agentMode defaults to true so verify actions skip confirmation prompts.
