How Layers 1-4 Survive Unity Recompilation

Layers 1-4 run as external Python processes, completely independent of Unity’s compilation cycle. This architectural decision is what makes GameCatalyst’s recompile resistance possible.

Why this matters:

When Unity recompiles C# code (triggered by script changes, package imports, or domain reloads), the Unity Editor process pauses. All C# code stops executing. MonoBehaviours are destroyed and recreated. The entire C# application domain reloads.

If GameCatalyst ran entirely inside Unity, recompilation would:

• Kill the MCP Bridge connection — Your AI client would disconnect
• Lose session state — Permissions, project selection, discovery history all gone
• Disconnect the AI client — You’d see connection errors in your AI client
• Force you to reconnect and reselect the project — Manual intervention required every time

This would make AI-assisted development frustrating and slow. Every script creation would trigger recompilation, disconnecting your AI. You’d spend more time reconnecting than building.

How external processes solve this:

• Layers 1-4 run in separate Python processes — These are completely independent operating system processes with their own memory space
• These processes are not affected by Unity recompilation — Unity can recompile, crash, or even close entirely without affecting Layers 1-4
• Session state, permissions, and plan data persist in Python memory and SQLite databases — Everything important lives outside Unity
• AI client stays connected to the MCP Bridge throughout recompilation — From your AI’s perspective, nothing changes. It just waits for Unity to finish recompiling.

What happens during recompilation:

Here’s the exact sequence when Unity recompiles:

1. Unity starts recompiling — You create a new script or modify existing code
2. Layer 5 (API Bridge) stops responding — The C# HTTP server inside Unity shuts down as part of domain reload
3. Layer 4 (Instance Server) detects the disconnection — Heartbeat messages from Layer 5 stop arriving
4. Layers 1-4 continue running, maintaining AI client connection — Your AI client sees no disconnection. It’s still connected to Layer 2.
5. Unity finishes recompiling — Typically 5-15 seconds depending on project size
6. Layer 5 restarts automatically — GameCatalystManager.Initialize() runs on domain reload and restarts the HTTP server
7. Layer 4 reconnects to Layer 5 — Heartbeat resumes, connection restored
8. Normal operation resumes — Vex can execute Unity commands again

Total reconnection time: 2-5 seconds. No lost context. No manual intervention.

Technical details:

• Layer 4 uses a reconnection backoff strategy: tries every 1 second for the first 10 seconds, then every 5 seconds
• Layer 5 binds to the same port it used before recompilation (stored in gc_settings.db)
• If Layer 5 can’t bind to its preferred port, it tries the next port in the range (8080-8180)
• Session fingerprints ensure Layer 4 reconnects to the correct Unity instance if multiple are open

Why Python for Layers 1-4:

Python was chosen for external layers because:

• Cross-platform (Windows, macOS, Linux)
• Easy HTTP server implementation (Flask)
• SQLite support built-in
• Fast development iteration
• No compilation required (scripts run directly)