Connect Unity bridge

The setup is short: open the project, click Install bridge in Settings → MCP, refocus Unity, watch the pill turn green. The full step-by-step is on the Unity quickstart and Install and connect pages.

This page covers what to do when it doesn’t go that smoothly.

Pill stays grey

The bridge isn’t reachable. Walk through these in order:

1. Is Unity actually open? The bridge only listens while the Editor is running. Closing the Editor disconnects the pill.
2. Did Unity finish compiling? Watch the bottom-right of the Unity Editor for the spinning compile indicator. If a script error in your project blocks compilation, the bridge can’t start either. Fix the error and Unity recompiles.
3. Is port 7400 open? Some firewalls block localhost ports for unsigned executables. Allow Unity through your firewall, or change the bridge port in Window → Forge Bridge in the Unity Editor.
4. Reinstall the bridge. Settings → MCP → Reinstall. This rules out a stale package after a Forge update.

If the pill still won’t connect, open the Unity Console and look for messages prefixed with [ForgeBridge]. Errors there usually point at the underlying cause.

Bridge stops working after entering Play mode

Domain Reload disable hasn’t been applied. The bridge sets it the first time it runs, but if you’ve cleared player prefs or imported a fresh project, you may need to re-enable.

Edit → Project Settings → Editor → Enter Play Mode Options. Both Disable Domain Reload and Disable Scene Reload should be on. If they’re not, turn them on.

This is non-negotiable. Unity 6 crashes on TcpListener.Stop() during Domain Reload, and Forge can’t recover from a crashed editor.

”Version mismatch” warning in the Forge log

Forge declares a protocol version it expects from the bridge. If the bridge in your project is older than what Forge expects (because you updated Forge but not the bridge), Forge logs a warning and degrades gracefully to whatever subset still works.

Fix: Settings → MCP → Reinstall. This overwrites the bridge with the version Forge has bundled.

Hierarchy tab is empty

Two common causes:

1. Bridge is connected but the active scene is empty. Check Unity’s Hierarchy panel; if Unity has no scene loaded, Forge has nothing to show either.
2. Bridge subscribed but didn’t get a snapshot. Save the active scene in Unity (Ctrl+S). Saving fires a hierarchy_changed event that Forge picks up.

Console tab shows nothing

subscribe_console registers Forge for live events but doesn’t replay history. Trigger a Debug.Log("test") from a script (or play your game and let it log normally) and the entry should appear in the Console tab.

If new logs in Unity don’t appear in Forge, the subscription may have dropped. Click any other Inspector tab and back to Console to re-subscribe.

Editor crashes after install

This shouldn’t happen, but it has been reported on Unity 6 with specific configurations. If the Editor crashes:

1. Restart Unity.
2. If it crashes again, delete Packages/ai.ranga.forge-unity-bridge/ from your project and restart Unity.
3. Email support@ranga.ai with your Unity version and a copy of Editor.log (typically at %APPDATA%\Unity\Editor\Editor.log).

The bridge has been audited for Unity 6 specifically, but unusual setups can still trip it. Reports help.