godot-master

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.

🔗 The "Smart Interconnect" Mandate

Expert systems are defined not by their isolation, but by their Payload Synthesis.

• Physics → Performance: PhysicsServer2D and RenderingServer bypass SceneTree node overhead. Use for 1,000+ bullets or particles to achieve O(1) processing.
• Animation → Physics: AnimationTree.get_root_motion_position() converts animation displacement into physics velocity, preventing "foot sliding" in complex movement.
• Data → Reactivity: Serialized Resource objects (like Stats) emit signals when modified, allowing UI to update automatically without tight coupling.
• Asset → Spawning: An O(1) Dictionary-based cache (preloaded during ResourceLoader async phases) prevents I/O hitches when spawning items or enemies.
• Mobile → Visuals: Prevent runtime frame-hitches by instantiating hidden effects during loading screens to force GPU shader pipeline compilation.
• Networking → Bandwidth: Use bit-packing into PackedByteArray for synchronization instead of JSON/Strings to keep packets under 100 bytes.
• Genre Synthesis:
  • Shooter: strictly use intersect_ray() (direct space state) over RayCast3D nodes for 100x performance.
  • RPG: Damage follows base * pow(scaling, level) to sustain end-game progression.
  • RTS: Moves groups based on their Center of Mass with Relative Offset to preserve formation integrity.
  • Metroidvania: Uses ResourceLoader.load_threaded_request() for seamless room swaps.
  • Platformer: Mandatory Jump Buffering (~0.15s) and Coyote Time for professional feel.
  • Simulation: Tick Manager batch processing; avoid per-entity _process to sustain thousands of units.
  • Romance: Multi-Axial Affection (Attraction, Trust, Comfort) to map complex narrative branching.
  • Architecture: Signal Architecture strictly follows Signal Up, Call Down to eliminate circular scene coupling.

---

🧭 Part 2: Architectural Decision Frameworks

The Master Decision Matrix

Scenario	Strategy	MANDATORY Skill Chain	Trade-off
Rapid Prototype	Event-Driven Mono	READ: Foundations → Autoloads. Do NOT load genre or platform refs.	Fast start, spaghetti risk
Complex RPG	Component-Driven	READ: Composition → States → RPG Stats. Do NOT load multiplayer or platform refs.	Heavy setup, infinite scaling
Massive Open World	Resource-Streaming	READ: Open World → Save/Load. Also load Performance.	Complex I/O, float precision jitter past 10K units
Server-Auth Multi	Deterministic	READ: Server Arch → Multiplayer. Do NOT load single-player genre refs.	High latency, anti-cheat secure
Mobile/Web Port	Adaptive-Responsive	READ: UI Containers → Adapt Desk→Mobile → Platform Mobile.	UI complexity, broad reach
Application / Tool	App-Composition	READ: App Composition → Theming. Do NOT load game-specific refs.	Different paradigm than games
Romance / Dating Sim	Affection Economy	READ: Romance → Dialogue → UI Rich Text.	High UI/Narrative density
Secrets / Easter Eggs	Intentional Obfuscation	READ: Secrets → Persistence.	Community engagement, debug risk
Collection Quest	Scavenger Logic	READ: Collections → Marker3D Placement.	Player retention, exploration drive
Seasonal Event	Runtime Injection	READ: Easter Theming → Material Swapping.	Fast branding, no asset pollution
Souls-like Mortality	Risk-Reward Revival	READ: Revival/Corpse Run → Physics 3D.	High tension, player frustration risk
Wave-based Action	Combat Pacing Loop	READ: Waves → Combat.	Escalating tension, encounter design
Survival Economy	Harvesting Loop	READ: Harvesting → Inventory.	Resource scarcity, loop persistence
Racing / Speedrun	Validation Loop	READ: Time Trials → Input Buffer → Genre Racing.	High precision, ghost record drive
Horror / Stealth	Tension Management	READ: Genre Horror → Genre Stealth → Audio.	Atmosphere, player vulnerability
Card / Board Game	Rule Enforcement	READ: Genre Card Game → Turn System.	Deterministic state, UI heavy
Simulation / RTS	Batch Processing	READ: Genre Simulation → Genre RTS → Performance.	High unit counts, O(1) logic

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":

Type	When to Use	Cost	Expert Use Case
Object	Custom data structures, manual memory management	Lightest. Must call .free() manually.	Custom spatial hash maps, ECS-like data stores
RefCounted	Transient data packets, logic objects that auto-delete	Auto-deleted when no refs remain.	DamageRequest, PathQuery, AbilityEffect — logic packets that don't need the scene tree
Resource	Serializable data with Inspector support	Slightly heavier than RefCounted. Handles .tres I/O.	ItemData, EnemyStats, DialogueLine — any data a designer should edit in Inspector
Node	Needs _process/_physics_process, needs to live in the scene tree	Heaviest — SceneTree overhead per node.	Only for entities that need per-frame updates or spatial transforms

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.

[!CAUTION] Workflow 1 NEVER List

• NEVER use res:// paths in logic scripts. Use @export_file or @export_dir to ensure resources remain valid when moved.
• NEVER initialize children in _init(). The scene tree isn't ready. Use _ready() or @onready.
• NEVER keep "Default" project settings for Physics Ticks. Set to 60 for consistency, or use Engine.physics_ticks_per_second for adaptive logic.
• NEVER use print() in _process() for debugging; use the Debugger or push_error() to avoid frame-time spikes.

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.

[!CAUTION] Workflow 2 NEVER List

• NEVER call parent.do_thing(). If the parent changes, the entity breaks. Emit a signal request_action instead.
• NEVER use _process for movement. Use _physics_process to avoid jitter on variable-refresh-rate monitors.
• NEVER hardcode animation names. Use a StringName constant or a Resource map to enable easy renaming in AnimationPlayer.
• NEVER use get_node() with absolute paths. Use %UniqueName to survive tree refactoring.

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.

[!CAUTION] Workflow 3 NEVER List

• NEVER pass Node references in a Signal Bus. Objects get freed; RIDs or IDs are safer for long-term tracking.
• NEVER modify a .tres file at runtime via code (it modifies the disk file). Always .duplicate() before modifying.
• NEVER use Array for high-frequency search. Use Dictionary with StringName keys for O(1) lookups.
• NEVER use float for item counts or precise resource tracking; use int and scale for display.

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.

[!CAUTION] Workflow 4 NEVER List

• NEVER save whole Object or Node instances. They contain transient pointers. Extract data into a Dictionary or custom Resource.
• NEVER use JSON for data that needs strict typing (e.g., Vector2). Use var_to_bytes or ConfigFile for structured Godot types.
• NEVER block the main thread for auto-saves. Use a Thread or WorkerThreadPool to serialize large dictionaries.
• NEVER save to res:// in an exported project; strictly use user:// for persistent data.

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 `_p

...