Explaining the 5-Layer Architecture

GameCatalyst uses a five-layer architecture where critical services run outside Unity, ensuring your AI sessions survive recompilation without losing context or requiring reconnection. Understanding this architecture helps you appreciate why GameCatalyst is so resilient and reliable.

The five layers:

1. Layer 1: Conductor — Lightweight STDIO-to-HTTP proxy spawned by AI clients. Manages Discovery Server startup and transport bridging. When you connect an AI client like Claude Desktop, the Conductor launches automatically and creates the communication bridge between your AI and GameCatalyst’s servers.
2. Layer 2: MCP Bridge Server — Implements MCP protocol (2025-06-18 spec). Handles session management with fingerprinting, command routing, permission enforcement, and transport abstraction. This is where your AI client connects. The MCP Bridge translates between MCP messages and GameCatalyst’s internal command system.
3. Layer 3: Discovery Server — Central project registry with heartbeat monitoring. Hosts WhatIs documentation API and web UI. Manages Web Relay control. Runs on port 5001 by default. This is the “brain” of GameCatalyst—it knows about all your Unity projects, tracks which ones are active, and coordinates connections between AI clients and projects.
4. Layer 4: Engine Instance Server — Runs outside Unity Editor process. Survives recompilation. Per-engine adapter (Unity fully supported, Unreal/Godot planned). Uses ports 9001-9100. This layer is engine-specific but still runs externally. For Unity, it’s UnityInstanceServer.py. For Unreal (future), it will be UnrealInstanceServer.py.
5. Layer 5: Engine API Bridge — HTTP server inside Unity Editor. Thread-safe command execution via MainThreadDispatcher. Uses ports 8080-8180. Reconnects automatically after recompilation. This is the only layer that lives inside Unity. It’s a C# HTTP server that receives commands from Layer 4 and executes them on Unity’s main thread.

Language breakdown:

• Layers 1-4: Python (external processes) — These run as separate Python processes completely independent of Unity. They survive Unity recompilation, crashes, and domain reloads.
• Layer 5: C# (inside Unity) — This runs inside Unity Editor as a MonoBehaviour-managed HTTP server. It’s the only layer affected by recompilation.

Why this architecture matters:

The key insight is that Layers 1-4 are external processes. When Unity recompiles:

• Layers 1-4 keep running
• Your AI client stays connected to Layer 2 (MCP Bridge)
• Session state persists in Python memory and SQLite databases
• Only Layer 5 restarts (and it reconnects automatically)

This means you never lose context, never need to reconnect, and never need to reselect your project. Recompilation becomes a minor pause instead of a major interruption.

Data flow example:

When you ask Vex to create a GameObject:

1. Your AI client sends MCP message to Layer 2 (MCP Bridge)
2. Layer 2 validates permissions and routes to Layer 3 (Discovery Server)
3. Layer 3 identifies which project you’re working on and forwards to Layer 4 (Instance Server)
4. Layer 4 sends HTTP request to Layer 5 (API Bridge inside Unity)
5. Layer 5 executes the command on Unity’s main thread
6. Result flows back through all layers to your AI client

This multi-layer design adds latency (typically 50-100ms), but the benefits (recompile resistance, session persistence, multi-engine support) far outweigh the cost.