Layer 5 Reconnects Automatically

Layer 5 (the Engine API Bridge) is the only layer that lives inside Unity. It reconnects automatically after every recompilation, ensuring seamless continuity without manual intervention.

How auto-reconnection works:

The reconnection process is fully automatic and happens in seconds:

1. Unity finishes recompiling — Domain reload completes, C# code is ready
2. GameCatalystManager.Initialize() runs (Unity’s domain reload callback) — This is a static method marked with [InitializeOnLoad] that Unity calls automatically
3. Initialize() checks if servers were running before recompilation — Reads gc_settings.db to see if API Bridge was active
4. If yes: restarts the API Bridge HTTP server — Launches the HTTP server on Unity’s main thread
5. API Bridge binds to the same port (8080-8180 range) — Uses the port stored in gc_settings.db
6. Engine Instance Server detects the API Bridge is back online — Heartbeat messages resume
7. Connection restored — Normal operation continues

Total reconnection time: 2-5 seconds. You’ll barely notice it.

Heartbeat monitoring:

The API Bridge sends heartbeat messages to the Instance Server every few seconds. These heartbeats include:

• Unity Editor process ID
• Project path
• Recompilation status (idle, compiling, or reloading)
• Timestamp

When Unity recompiles, heartbeats stop. The Instance Server knows to wait for reconnection instead of timing out. The Instance Server uses a generous timeout (60 seconds) to accommodate slow recompilations on large projects.

What you’ll notice:

During recompilation, if you ask Vex to do something, Vex will respond:

“Unity is currently recompiling. I’ll wait for it to finish before executing commands.”

After recompilation completes, Vex automatically resumes work. You don’t need to reconnect or reselect the project. The conversation continues exactly where it left off.

Plan-aware recompilation:

If workspace.plan is active and Recompile-Aware TTL is enabled, the discovery gate TTL freezes during recompilation and restores with remaining time when Vex calls resume. This eliminates repetitive validate calls after every recompile.

Here’s how it works:

• Vex creates a script, triggering recompilation
• Discovery gate TTL has 45 seconds remaining
• Unity recompiles for 10 seconds
• Discovery gate TTL freezes at 45 seconds
• Unity finishes recompiling
• Vex calls workspace.plan action=resume
• Discovery gate TTL restores to 45 seconds (not 35)

This prevents the frustrating scenario where recompilation consumes your TTL, forcing Vex to re-validate the project structure unnecessarily.

Reconnection failure handling:

If Layer 5 fails to reconnect (port conflict, Unity crash, etc.), the Instance Server logs the error and waits. You’ll see a warning in the Dashboard: “API Bridge disconnected. Check Unity Console for errors.”

To fix:

1. Check Unity Console for error messages
2. Restart GameCatalyst from the Dashboard
3. If port conflict: change the port in Dashboard → Settings → API Bridge Port