Godot Master: Lead Architect Knowledge Hub

Every section earns its tokens by focusing on Knowledge Delta — the gap between what Claude already knows and what a senior Godot engineer knows from shipping real products.

🧠 Part 1: Expert Thinking Frameworks

"Who Owns What?" — The Architecture Sanity Check

Before writing any system, answer these three questions for EVERY piece of state:

• Who owns the data? (The StatsComponent owns health, NOT the CombatSystem)
• Who is allowed to change it? (Only the owner via a public method like apply_damage())
• Who needs to know it changed? (Anyone listening to the health_changed signal)

If you can't answer all three for every state variable, your architecture has a coupling problem. This is not OOP encapsulation — this is Godot-specific because the signal system IS the enforcement mechanism, not access modifiers.

The Godot "Layer Cake"

Organize every feature into four layers. Signals travel UP, never down:

┌──────────────────────────────┐
│  PRESENTATION (UI / VFX)     │  ← Listens to signals, never owns data
├──────────────────────────────┤
│  LOGIC (State Machines)      │  ← Orchestrates transitions, queries data
├──────────────────────────────┤
│  DATA (Resources / .tres)    │  ← Single source of truth, serializable
├──────────────────────────────┤
│  INFRASTRUCTURE (Autoloads)  │  ← Signal Bus, SaveManager, AudioBus
└──────────────────────────────┘

Critical rule: Presentation MUST NOT modify Data directly. Infrastructure speaks exclusively through signals. If a Label node is calling player.health -= 1, the architecture is broken.

The Signal Bus Tiered Architecture

• Global Bus (Autoload): ONLY for lifecycle events (match_started, player_died, settings_changed). Debugging sprawl is the cost — limit events to < 15.
• Scoped Feature Bus: Each feature folder has its own bus (e.g., CombatBus only for combat nodes). This is the compromise that scales.
• Direct Signals: Parent-child communication WITHIN a single scene. Never across scene boundaries.

🧭 Part 2: Architectural Decision Frameworks

The Master Decision Matrix

The "When NOT to Use a Node" Decision

One of the most impactful expert-only decisions. The Godot docs explicitly say "avoid using nodes for everything":

The expert pattern: Use RefCounted subclasses for all logic packets and data containers. Reserve Node for things that must exist in the spatial tree. This halves scene tree overhead for complex systems.

🔧 Part 3: Core Workflows

Workflow 1: Professional Scaffolding

From empty project to production-ready container.

MANDATORY — READ ENTIRE FILE: Foundations

1. Organize by Feature (/features/player/, /features/combat/), not by class type. A player/ folder contains the scene, script, resources, and tests for the player.
2. READ: Signal Architecture — Create GlobalSignalBus autoload with < 15 events.
3. READ: GDScript Mastery — Enable untyped_declaration warning in Project Settings → GDScript → Debugging.
4. Apply Project Templates for base .gitignore, export presets, and input map.
5. Use MCP Scene Builder if available to generate scene hierarchies programmatically. Do NOT load combat, multiplayer, genre, or platform references during scaffolding.

Workflow 2: Entity Orchestration

Building modular, testable characters.

MANDATORY Chain — READ ALL: Composition → State Machine → CharacterBody2D or Physics 3D → Animation Tree Do NOT load UI, Audio, or Save/Load references for entity work.

• The State Machine queries an InputComponent, never handles input directly. This allows AI/Player swap with zero refactoring.
• The State Machine ONLY handles transitions. Logic belongs in Components. MoveState tells MoveComponent to act, not the other way around.
• Every entity MUST pass the F6 test: pressing "Run Current Scene" (F6) must work without crashing. If it crashes, your entity has scene-external dependencies.

Workflow 3: Data-Driven Systems

Connecting Combat, Inventory, Stats through Resources.

MANDATORY Chain — READ ALL: Resource Patterns → RPG Stats → Combat → Inventory

• Create ONE ItemData.gd extending Resource. Instantiate it as 100 .tres files instead of 100 scripts.
• The HUD NEVER references the Player directly. It listens for player_health_changed on the Signal Bus.
• Enable "Local to Scene" on ALL @export Resource variables, or call resource.duplicate() in _ready(). Failure to do this is Bug #1 in Part 8.

Workflow 4: Persistence Pipeline

MANDATORY: Autoload Architecture → Save/Load → Scene Management

• Use dictionary-mapped serialization. Old save files MUST not corrupt when new fields are added — use .get("key", default_value).
• For procedural worlds: save the Seed plus a Delta-List of modifications, not the entire map. A 100MB world becomes a 50KB save.

Workflow 5: Performance Optimization

MANDATORY: Debugging/Profiling → Performance Optimization

Diagnosis-first approach (NEVER optimize blindly):

1. High Script Time → Profile with built-in Profiler. Check if _process is being called on hundreds of nodes. Move to single-manager pattern or Server APIs (see Part 6).
2. High Draw Calls → Use MultiMeshInstance for repetitive geometry. Batch materials with ORM textures.
3. Physics Stutter → Simplify collisions to primitive shapes. Load 2D Physics or 3D Physics. Check if _process is used instead of _physics_process for movement.
4. VRAM Overuse → Switch textures to VRAM Compression (BPTC/S3TC for desktop, ETC2 for mobile). Never ship raw PNG.
5. Intermittent Frame Spikes → Usually GC pass, synchronous load(), or NavigationServer recalculation. Use ResourceLoader.load_threaded_request().

Workflow 6: Cross-Platform Adaptation

MANDATORY: Input Handling → Adapt Desktop→Mobile → Platform Mobile Also read: Platform Desktop, Platform Web, Platform Console, Platform VR as needed.

• Use an InputManager autoload that translates all input types into normalized actions. NEVER read Input.is_key_pressed() directly — it blocks controller and touch support.
• Mobile touch targets: minimum 44px physical size. Use MarginContainer with Safe Area logic for notch/cutout devices.
• Web exports: Godot's AudioServer requires user interaction before first play (browser policy). Handle this with a "Click to Start" screen.

Workflow 7: Procedural Generation

MANDATORY: