Godot Master: Lead Architect Knowledge Hub

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

Library target — Godot 4.7+

All Domain Skill mirrors target Godot 4.7+ (stable). For any engine version upgrade (1.x/2.x legacy → 3→4 → hop-by-hop 4.x), use godot-version-migration — do not treat this hub as a migration changelog.

Cross-cutting 4.7 reminders while routing: AreaLight3D / HDR → [3D Lighting](references/3d-lighting.md); Asset Store vs Asset Library → export/platform modules; RichTextLabel ImageUnit, input device ID constants, Jolt behavior → migration hub module notes.

🧠 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 (matchstarted, playerdied, 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.getrootmotion_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.
• Eyes → Verification: After UI, lighting, or scene-building work, agents must see the current representation — route to [Agent Vision](references/agent-vision.md) (capture → budgeted WebP → scored taste), not verbal guesswork.
• Score → Certify: Before calling architecture “production-ready,” route to [Analyst](references/analyst.md) (Anara) — rubric sectors + helper scripts, not vibes.
• Slop → Decree: Before merge/ship, route to [Auditor](references/auditor.md) (Aurelius) — never-list encyclopedia + deterministic scanners.
• 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 intersectray() (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.loadthreadedrequest() 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

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](references/project-foundations.md)

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](references/signal-architecture.md) — Create GlobalSignalBus autoload with < 15 events.
3. READ: [GDScript Mastery](references/gdscript-mastery.md) — Enable untyped_declaration warning in Project Settings → GDScript → Debugging.
4. Apply [Project Templates](references/project-templates.md) for base .gitignore, export presets, and input map.
5. Use [Builder](references/builder.md) (buildercreatescene.py, builderaddnode.py, buildersavescene.py) to generate scene hierarchies programmatically via the Godot CLI.
6. After the container exists: optional early Workflow 13 ([Analyst](references/analyst.md)) on foundations cohesion; before first ship, Workflow 14 ([Auditor](references/auditor.md)) on signal/typing/export never-lists.

[!CAUTION] Workflow 1 NEVER List
- NEVER use res:// paths in logic scripts. Use @exportfile or @exportdir 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.physicsticksper_second for adaptive logic.
- NEVER use print() in process() for debugging; use the Debugger or pusherror() 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](references/composition.md) → [State Machine](references/state-machine-advanced.md) → [CharacterBody2D](references/characterbody-2d.md) or [Physics 3D](references/physics-3d.md) → [Animation Tree](references/animation-tree-mastery.md) 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.dothing(). If the parent changes, the entity breaks. Emit a signal requestaction 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](references/resource-data-patterns.md) → [RPG Stats](references/rpg-stats.md) → [Combat](references/combat-system.md) → [Inventory](references/inventory-system.md)

• 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 playerhealthchanged 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](references/autoload-architecture.md) → [Save/Load](references/save-load-systems.md) → [Scene Management](references/scene-management.md)

• 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 vartobytes 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](references/debugging-profiling.md) → [Performance Optimization](references/performance-optimization.md)

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](references/2d-physics.md) or [3D Physics](references/physics-3d.md). 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.loadthreadedrequest().

[!CAUTION] Workflow 5 NEVER List
- NEVER use getnodesingroup() inside process. It's an O(n) operation every frame. Cache the array in _ready().
- NEVER use Area2D signals for "Stay" logic. Use getoverlappingbodies() periodically or a manager-level PhysicsServer check.
- NEVER optimize before profiling. A 1ms script is irrelevant if you have 2000 draw calls killing the GPU.
- NEVER use load() in hot paths; strictly preload or use ResourceLoader for async loading.

Workflow 6: Cross-Platform Adaptation

MANDATORY: [Input Handling](references/input-handling.md) → [Adapt Desktop→Mobile](references/adapt-desktop-to-mobile.md) → [Platform Mobile](references/platform-mobile.md) Also read: [Platform Desktop](references/platform-desktop.md), [Platform Web](references/platform-web.md), [Platform Console](references/platform-console.md), [Platform VR](references/platform-vr.md) as needed.

• Use an InputManager autoload that translates all input types into normalized actions. NEVER read Input.iskeypressed() 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.

[!CAUTION] Workflow 6 NEVER List
- NEVER use OS.getname() for feature detection. Use OS.hasfeature("mobile") or custom feature tags to handle subsets like "SteamDeck."
- NEVER assume a specific aspect ratio. Always use Expand or Keep Aspect in combinations with Anchor nodes.
- NEVER use desktop-only shaders (e.g., complex depth sampling) on Mobile/Web without a GLES3/Compatibility secondary path.
- NEVER ignore physical_keycode for desktop builds; it ensures keyboard layouts (AZERTY/QWERTY) don't break movement.

• NEVER pass unsanitized strings to JavaScriptBridge.eval() — Prevents script injection in web builds. Use a sanitizejsstring() helper.

Workflow 7: Procedural Generation

MANDATORY: [Procedural Gen](references/procedural-generation.md) → [Tilemap Mastery](references/tilemap-mastery.md) or [3D World Building](references/3d-world-building.md) → [Navigation](references/navigation-pathfinding.md)

• ALWAYS use FastNoiseLite resource with a fixed seed for deterministic generation.
• Never bake NavMesh on the main thread. Use NavigationServer3D.parsesourcegeometrydata() + NavigationServer3D.bakefromsourcegeometrydataasync().
• For infinite worlds: chunk loading MUST happen on a background thread using WorkerThreadPool. Build the scene chunk off-tree, then addchild.calldeferred() on the main thread.

[!CAUTION] Workflow 7 NEVER List
- NEVER instantiate nodes for "Background" noise. Use MultiMeshInstance or draw loops in _draw for thousands of small details.
- NEVER regenerate the entire map for one change. Use a "Dirty Chunk" system to only update what exactly changed.
- NEVER place collisions on the same frame as mesh generation if using concavepolygonshape. It stalls the physics thread.
- NEVER perform pathfinding queries every frame for all units. Use a NavigationAgent with target_position updates on a timer.

Workflow 8: Multiplayer Architecture

MANDATORY — READ: [Single→Multiplayer](references/adapt-single-to-multiplayer.md) → [Networking](references/multiplayer-networking.md) → [Server Arch](references/server-architecture.md) Do NOT load single-player genre blueprints.

• Client sends Input, Server calculates Outcome. The Client NEVER determines damage, position deltas, or inventory changes.
• Use Client-Side Prediction with server reconciliation: predict locally, correct from server snapshot. Hides up to ~150ms of latency.
• MultiplayerSpawner handles replication in Godot 4. Configure it per scene, not globally.

[!CAUTION] Workflow 8 NEVER List
- NEVER trust rpc_id(1, ...) (Client to Server) without validation. A hacked client can send damage = 999999.
- NEVER replicate _process transforms directly. Replicate Input vector and simulate movement on both sides.
- NEVER use TCP for high-frequency packets (movement). Use UDP / ENet and handle dropped packets with interpolation.
- NEVER synchronize every projectile; use Client-Side Prediction for visuals and only RPC the "Fire" event.

• ReflectionProbe vs VoxelGI vs SDFGI: Probes are cheap/static, VoxelGI is medium/baked, SDFGI is expensive/dynamic. Choose based on your platform budget (see Part 5).

Workflow 9: Responsive UI & Expert Theming (Audit Verified)

MANDATORY Chain: [UI Containers](references/ui-containers.md) → [UI Theming](references/ui-theming.md) → [Rich Text](references/ui-rich-text.md) → [Tweening](references/tweening.md)

1. The F6 Principle: Every UI scene must be testable in isolation. Use MOUSEFILTERSTOP only on the background, PASS on children.
2. Breathing Room: Use addthemeconstant_override("separation", X) over manual padding.
3. Adaptive Scaling: Use uicontainersresponsivelayoutbuilder.gd for breakpoint-aware mobile/desktop switching.
4. Lifecycle Safety: Never scroll to a new child on the same frame. await gettree().processframe before modifying scroll_vertical.
5. Data Integration: Use Resource-to-UI binding; UI nodes MUST be stateless projection layers.
6. See it: Close with Workflow 12 — [Agent Vision](references/agent-vision.md) window/asset capture → scored layout/type review. Agents cannot QA UI from text alone.

[!CAUTION] Workflow 9 NEVER List
- NEVER use absolute pixel offsets. UI becomes unreadable on 4K or tiny mobile screens. Use Container sizing.
- NEVER deep-nest MarginContainers. It makes the Inspector unusable. Use a single Theme resource for project-wide margins.
- NEVER connect UI buttons to gameplay logic directly. UI sends "Signal", PlayerController listens. This prevents UI-deletion crashes.
- NEVER use _process() to move a UI element to a target. Use a Tween to avoid stuttering and frame-rate dependence.
- NEVER leave mouse_filter as STOP on transparent containers; it "eats" clicks for everything behind it.
- NEVER use dynamic load() on paths without validating the res:// prefix and safe extension (.tres, .res, .theme) — Prevents arbitrary code/resource execution.
- NEVER declare UI “done” without an Agent Vision capture of the live layout.

Workflow 10: Cinematic Lighting & VFX (Audit Verified)

MANDATORY Chain: [3D Lighting](references/3d-lighting.md) → [Particles](references/particles.md) → [3D Materials](references/3d-materials.md) → [Shaders](references/shaders-basics.md)

1. The GI Choice: VoxelGI for interiors, SDFGI for open world. Never ship with both overlapping.
2. Shadow Budget: Max 2 Shadow-casting DirectionalLights. Use 3dlightingfakegibounce.gd for mobile fills.
3. VFX Lifecycle: Use finished signal over Timers. Re-run with restart() to avoid async GPU stalls.
4. Optimization: Use ORM Texture packing (AO/Rough/Metal) to save GPU cache and texture slots.
5. Batching: Use Instance Uniforms for material variations across thousands of instances without draw call penalties.
6. See it: Close with Workflow 12 — [Agent Vision](references/agent-vision.md) editor/window capture to verify lighting, exposure, and VFX read in pixels.

[!CAUTION] Workflow 10 NEVER List
- NEVER scale CollisionShape nodes; strictly scale the Shape Resource to avoid physics jitter.
- NEVER use TRANSPARENCYALPHA for cutout meshes (leaves/fences); use ALPHASCISSOR to prevent sorting artifacts.
- NEVER animate CSG nodes during gameplay; forces expensive CPU geometry recalculation.
- NEVER use real-time Global Illumination (SDFGI/VoxelGI) for a 2D-looking game. Stick to DirectionalLight2D and CanvasModulate.
- NEVER ignore Camera3D near/far planes; improper settings cause Z-fighting in large worlds.
- NEVER trust lighting “looks fine” from code alone — capture the viewport with Agent Vision.

Workflow 11: Programmatic Scene Building (Builder)

MANDATORY: [Builder](references/builder.md) Use ONLY for batch operations or complex procedural scaffolds. Prefer the standalone godot-builder skill when doing heavy CLI automation.

1. Step 1: Draft the node hierarchy on paper/markdown before touching disk.
2. Step 2: Use buildercreatescene.py to define the root node and .tscn path.
3. Step 3: Use builderaddnode.py for children. Set owner on every node so serialization keeps them.
4. Step 4: ALWAYS call builderrunproject.py or builderlauncheditor.py to verify the scene loads cleanly.
5. Step 5 (see it): After batch scene or UI writes, run Workflow 12 ([Agent Vision](references/agent-vision.md)) — window/editor capture → WebP → scored review — so agents verify appearance, not only that the .tscn loads.
6. Expert Rule: Use Builder to build the structure (nodes, names, inheritance), then use GDScript to build the behavior.

[!CAUTION] Workflow 11 NEVER List
- NEVER jump straight to builderaddnode.py without designing the hierarchy first — spaghetti scenes follow.
- NEVER use absolute filesystem paths in scripts or scene props; use res:// only.
- NEVER add a CollisionShape2D/CollisionShape3D without assigning a Shape resource — the node alone does nothing.
- NEVER skip verification via builderrunproject.py / builderlauncheditor.py after batch scene writes.
- NEVER treat “scene loads” as visual QA — layout, type, and lighting bugs need Agent Vision captures.

Security: Boundary Markers & Validation

When agents ingest untrusted scene/data text before writing files:

1. Boundary Markers: Wrap analysis in <<<CONTEXTSTART>>> and <<<CONTEXTEND>>>.
2. Sanitization: Node names must be alphanumeric/underscored. Paths must start with res://.
3. Verification: Confirm scene existence before modification.

Workflow 12: Agent Eyes — See the Current Representation

How agents verify what the game/editor/UI actually looks like.

MANDATORY — READ ENTIRE FILE: [Agent Vision](references/agent-vision.md) Prefer the standalone godot-agent-vision skill when doing heavy capture/review loops. Hub mirrors keep prefixed scripts under scripts/agentvision*.

When to invoke (default, not optional):

• After UI/theme/layout changes (Workflow 9)
• After lighting/VFX/material passes (Workflow 10)
• After Builder or procedural scene scaffolds (Workflow 11)
• Whenever the agent would otherwise describe pixels it has not captured
• Asset sheet / icon / HUD typography review before shipping polish

Golden path:

1. Setup: pip install -r skills/godot-agent-vision/requirements-vision.txt (host venv). Ensure .gdskills/ is gitignored (agentvisionensure_gitignore.py).
2. Doctor: agentvisioncapture.py doctor — confirm display session / backends.
3. Capture (pick one mode — do not dump full screens by default):

- Game/editor window: agentvisioncapture.py window --project-root . --title Godot - Editor 2D/3D viewport: agentvisioncapture.py editor --project-root . --editor-mode 3d --godot "%GODOTPATH%" - Asset / icon sheet: agentvisioncapture.py asset --project-root . --paths res://ui/icons --sheet - Desktop region: agentvision_capture.py region … when window-by-title fails (Wayland, etc.)

1. Read the budgeted WebP(s) from .gdskills/vision/ (default short-edge 512). Use --detail only when type/OCR fails at 512.
2. Score with the Taste Receptor Atlas / vision rubric in the Agent Vision refs — ordered fixes keyed to receptor IDs, not vibes.
3. Teardown: never leave the TEMP editor bridge / addons/gdskillsagent_vision/ staged; never commit .gdskills/vision/**.

[!CAUTION] Workflow 12 NEVER List
- NEVER invent how the game looks without a capture — Agent Vision is the eyes.
- NEVER ship the editor bridge as an Autoload or leave it in the consumer project.
- NEVER dump uncompressed PNG walls into context — WebP only, budgeted.
- NEVER replace scored taste with binary PASS/FAIL or purple-gradient “AI default” UI praise.
- NEVER put ornate display faces on ammo/HP/timers (TYPE-DISPLAY-HUD-SPLIT).

Workflow 13: Architecture Scoring — Analyst (Anara)

Certify whether the project can survive tomorrow — not whether it merely runs.

MANDATORY — READ ENTIRE FILE: [Analyst](references/analyst.md) Prefer the standalone godot-analyst skill for full certification loops. Hub mirrors: scripts/analyst_, nested references/analyst-.md.

When to invoke:

• Before calling a milestone “architecture complete”
• After large refactors (folder-by-feature, autoload sprawl, Resource graphs)
• When the user asks for modernity / scalability / Visionary Certificate scoring
• After Workflow 1 scaffolding or Workflow 2–4 systems land — score cohesion before more features

Golden path:

1. Map: Request the project root; map res:// structure (feature folders, autoloads, dependency hotspots).
2. Atlas: Load [analyst-markingrubricsatlas.md](references/analyst-markingrubricsatlas.md) — pick the Evolutionary Sector(s) in scope.
3. Sector only: MANDATORY load matching category rubric file(s) under the Analyst progressive-disclosure tree. Do NOT load every category file.
4. Engine helpers (only what exists on disk): analystscoringlogic.gd, analystmarkingrubricsatlas.gd, analystvisionarycomparison.gd — do not invent phantom score*.py fleets.
5. Synthesize: Weighted scores → Visionary Certificate narrative + transcendence blueprint (gaps ordered by impact).

[!CAUTION] Workflow 13 NEVER List
- NEVER certify without the active sector rubric — guessing weights is not Visionary.
- NEVER parse .tscn/.tres by hand — use ResourceLoader.getdependencies / PackedScene.getstate.
- NEVER treat “it runs” or green play as a pass — score scale, typing, decoupling, cohesion.
- NEVER load the entire Analyst categories tree into context.

Workflow 14: Never-List Enforcement — Auditor (Aurelius)

Find the invisible slop that invites bugs — then decree remediation.

MANDATORY — READ ENTIRE FILE: [Auditor](references/auditor.md) Prefer the standalone godot-auditor skill for deep audits. Hub mirrors: scripts/auditor_, nested references/auditor-.md.

When to invoke:

• Pre-merge / pre-release integrity pass
• After signal, typing, export, or memory regressions
• When Analyst scores flag decay — Auditor proves it with scanners + encyclopedia
• Pair with Workflow 5 (performance) when ObjectDB / orphan / batching slop is suspected

Golden path:

1. Survey: Confirm project path + feature-folder integrity.
2. Encyclopedia: Open [auditor-neverlistencyclopedia.md](references/auditor-neverlistencyclopedia.md) — identify the Architectural Sector.
3. Surgical load: MANDATORY read only the matching category never-list file(s). Do NOT ingest the entire encyclopedia.
4. Scanners on disk (call individually — do not invent missing tools):

- auditorauditsignals.py — string .connect decay - auditoraudittypehints.py — untyped Array/Dictionary + string-connect - auditorauditmemoryfragmentation.gd — ObjectDB / orphan snapshots - auditorpurgereport_generator.gd — purge / unused-resource rollup

1. Decrees: Findings with the why behind each never-list hit; ordered remediation. For sectors without a scanner, cite engine APIs from the loaded category — do not claim a phantom script ran.

[!CAUTION] Workflow 14 NEVER List
- NEVER load every never-list category at once — progressive disclosure only.
- NEVER invent audit_*.py scanners that are not in scripts/.
- NEVER soft-pedal export case-sensitivity, signal decay, or untyped hot-path collections.
- NEVER skip deterministic proof when a scanner exists for the request.

Persona triad (ship loop): [Builder](references/builder.md) builds structure → [Agent Vision](references/agent-vision.md) sees pixels → [Analyst](references/analyst.md) scores architecture → [Auditor](references/auditor.md) enforces never-lists.

🚫 Part 4: The Expert NEVER List

Each rule includes the non-obvious reason — the thing only shipping experience teaches.

1. NEVER use gettree().root.getnode("...") — Absolute paths break when ANY ancestor is renamed or reparented. Use %UniqueNames, @export NodePath, or signal-based discovery.
2. NEVER use load() inside a loop or process — Synchronous disk read blocks the ENTIRE main thread. Use preload() at script top for small assets, ResourceLoader.loadthreaded_request() for large ones.
3. NEVER queuefree() while external references exist — Parent nodes or arrays holding refs will get "Deleted Object" errors. Clean up refs in exit_tree() and set them to null before freeing.
4. NEVER put gameplay logic in draw() — draw() is called on the rendering thread. Mutating game state causes race conditions with physicsprocess.
5. NEVER use Area2D for 1000+ overlapping objects — Each overlap check has O(n²) broadphase cost. Use ShapeCast2D, PhysicsDirectSpaceState2D.intersect_shape(), or Server APIs for bullet-hell patterns.
6. NEVER mutate external state from a component — If HealthComponent calls $HUD.update_bar(), deleting the HUD crashes the game. Components emit signals; listeners decide how to respond.
7. NEVER use await in physicsprocess — await yields execution, meaning the physics step skips frames. Move async operations to a separate method triggered by a signal.
8. NEVER use String keys in hot-path dictionary lookups — String hashing is O(n). Use StringName (&"key") for O(1) pointer comparisons, or integer enums.
9. NEVER store Callable references to freed objects — Crashes silently or throws errors. Disconnect signals in exittree() or use CONNECTONESHOT.
10. NEVER use process for 1000+ entities — Each process call has per-node SceneTree overhead. Use a single Manager._process that iterates an array of data structs (Data-Oriented pattern), or use Server APIs directly.
11. NEVER use Tween on a node that may be freed — If a node is queuefree()'d while a Tween runs, it errors. Kill tweens in exittree() or bind to SceneTree: gettree().create_tween().
12. NEVER request data FROM RenderingServer or PhysicsServer in _process — These servers run asynchronously. Calling getter functions forces a synchronous stall that kills performance. The APIs are intentionally designed to be write-only in hot paths.
13. NEVER use call_deferred() as a band-aid for initialization order bugs — It masks architectural problems (dependency on tree order). Fix the actual dependency with explicit initialization signals or @onready.
14. NEVER create circular signal connections — Node A connects to B, B connects to A. This creates infinite loops on the first emit. Use a mediator pattern (Signal Bus) to break cycles.
15. NEVER let inheritance exceed 3 levels — Beyond 3, debugging super() chains is a nightmare. Use composition (Node children) to add behaviors instead.
16. NEVER use process for hit detection or movement in physics-heavy genres (FPS/ARPG); strictly use physics_process to ensure frame-independent collision detection.
17. NEVER trust the client for authority on persistent game state (Health, XP, Inventory). Handled exclusively via Server-Auth or Secure Checksums.
18. NEVER use standard strings for high-frequency runtime checks; strictly use StringName (&"active") to avoid O(n) hashing.
19. NEVER manually handle RVO avoidance every frame in unit-heavy games (RTS/MOBA); offload to NavigationAgent internal threading.
20. NEVER block the main thread for procedural generation or heavy I/O; strictly offload to WorkerThreadPool.
21. NEVER ignore Local-to-Scene on Resources used in unique instances (e.g. enemy stats); failure causes shared-memory bugs across all instances.
22. NEVER use float for currency; strictly use Integer Cents to avoid precision drift in complex economies.
23. NEVER set targetposition before physicsframe; navigation maps are not ready during _ready().
24. NEVER use TRANSPARENCYHASH or ALPHA for large cutout surfaces (foliage); use ALPHASCISSOR for performance and sorting.
25. NEVER scale CollisionShape nodes (Node2D/3D scale) — Use shape handles or resize the resource to avoid unpredictable physics normals and jitter.
26. NEVER apply gravity while isonfloor() is true — Causes micro-jitter and prevents floor-snapping; strictly reset vertical velocity to 0 or a small constant.
27. NEVER forget to disconnect dynamic signals (Capturing Lambdas) — Godot cannot auto-disconnect lambdas that capture local variables; they will cause crashes on freed objects.
28. NEVER use mouse events for mobile touch — Strictly use InputEventScreenTouch and InputEventScreenDrag for reliable multi-touch support.
29. NEVER use Forward+ renderer for mobile — Strictly use Mobile or Compatibility renderers to avoid GPU bottlenecks and battery drain.
30. NEVER accumulate mouse rotation directly on Transforms — Strictly store separate Yaw/Pitch variables to prevent gimbal lock and precision loss.
31. NEVER use standard Strings for high-frequency runtime checks — Strictly use StringName (&"active") to avoid O(n) hashing overhead.
32. NEVER trust the client for game state (Health, Inventory) — Clients suggest actions; Server validates and broadcasts to prevent cheating.
33. NEVER use Reliable RPCs for movement updates — Use UnreliableOrdered to prevent Head-of-Line blocking in high-latency scenarios.

📊 Part 5: Performance Budgets (Concrete Numbers)

⚙️ Part 6: Server APIs — The Expert Performance Escape Hatch

This is knowledge most Godot developers never learn. When the scene tree becomes a bottleneck, bypass it entirely using Godot's low-level Server APIs.

When to Drop to Server APIs

• 10K+ rendered instances (sprites, meshes): Use RenderingServer with RIDs instead of Sprite2D/MeshInstance3D nodes.
• Bullet-hell / particle systems with script interaction: Use PhysicsServer2D body creation instead of Area2D nodes.
• Mass physics simulation: Use PhysicsServer3D directly for ragdoll fields, debris, or fluid-like simulations.

📊 Performance Comparison: SceneTree vs. Server APIs

Bypassing the SceneTree eliminates the heavy CPU overhead of node lifecycle management, signal propagation, and virtual function overhead (like _process).

Expert Note: Using RIDs allows managing raw data and interacting directly with engine core logic. This is the primary "escape hatch" for bullet-hells, massive foliage, or complex procedural simulations where SceneTree housekeeping becomes the bottleneck.

The RID Pattern (Expert)

Server APIs communicate through RID (Resource ID) — opaque handles to server-side objects. Critical rules:

# Create server-side canvas item (NO node overhead)
var ci_rid := RenderingServer.canvas_item_create()
RenderingServer.canvas_item_set_parent(ci_rid, get_canvas_item())

# CRITICAL: Keep resource references alive. RIDs don't count as references.
# If the Texture resource is GC'd, the RID becomes invalid silently.
var texture: Texture2D = preload("res://sprite.png")
RenderingServer.canvas_item_add_texture_rect(ci_rid, Rect2(-texture.get_size() / 2, texture.get_size()), texture)

Threading with Servers

• The scene tree is NOT thread-safe. But Server APIs (RenderingServer, PhysicsServer) ARE thread-safe when enabled in Project Settings.
• You CAN build scene chunks (instantiate + addchild) on a worker thread, but MUST use addchild.call_deferred() to attach them to the live tree.
• GDScript Dictionaries/Arrays: reads and writes across threads are safe, but resizing (append, erase, resize) requires a Mutex.
• NEVER load the same Resource from multiple threads simultaneously — use one loading thread.

🧩 Part 7: Expert Code Patterns

Expert implementations of common architectural and gameplay systems.

• [Component Registry](references/patterns/component_registry.md): Centralized dictionary-based component retrieval.
• [Safe Signal Handler](references/patterns/safesignalhandler.md): Preventing crashes on freed object references.
• [Async Resource Loader](references/patterns/asyncresourceloader.md): Threaded asset ingestion.
• [State Machine Transition Guard](references/patterns/statemachinetransition_guard.md): Validating state changes.
• [Thread-Safe Chunk Loader](references/patterns/threadsafechunk_loader.md): Low-level server-api construction.
• [Vision Cone Detection](references/patterns/visionconedetection.md): Expert NPC vision with dot products and raycasts.
• [Sound Propagation System](references/patterns/soundpropagationsystem.md): Acoustic occlusion logic.
• [Stealth Hiding Logic](references/patterns/stealthhidinglogic.md): Global visibility and concealment management.

🔥 Part 8: Godot 4.x Gotchas (Veteran-Only)

1. @export Resources are shared by default: Multiple scene instances ALL share the same Resource. Use resource.duplicate() in _ready() or enable "Local to Scene" checkbox. This is the #1 most reported Godot 4 bug by newcomers.
2. Signal syntax silently fails: connect("signalname", target, "method") (Godot 3 syntax) compiles but does nothing in Godot 4. Must use signalname.connect(callable).
3. Tween is no longer a Node: Created via createtween(), bound to the creating node's lifetime. If that node is freed, the Tween dies. Use gettree().create_tween() for persistent tweens.
4. PhysicsBody layers vs masks: collisionlayer = "what I am". collisionmask = "what I scan for". Setting both to the same value causes self-collision or missed detections.
5. StringName vs String in hot paths: StringName (&"key") uses pointer comparison (O(1)). String uses character comparison (O(n)). Always use StringName for dictionary keys in _process.
6. @onready timing: Runs AFTER init() but DURING ready(). If you need constructor-time setup, use init(). If you need tree access, use @onready or ready(). Mixing them causes nulls.
7. Server query stalls: Calling RenderingServer or PhysicsServer getter functions in _process forces a synchronous pipeline flush. These servers run async — requesting data from them stalls the entire pipeline until the server catches up.
8. moveandslide() API change: Returns bool (whether collision occurred). Velocity is now a property, not a parameter. velocity = dir * speed before calling moveandslide().

📂 Part 9: Module Directory (99 Blueprints)

[!IMPORTANT]
Load ONLY the modules needed for your current workflow. Use the Decision Matrix in Part 2 to determine which chain to follow.

Architecture & Foundation

[Foundations](references/project-foundations.md) | [Composition](references/composition.md) | [App Composition](references/composition-apps.md) | [Signals](references/signal-architecture.md) | [Autoloads](references/autoload-architecture.md) | [States](references/state-machine-advanced.md) | [Resources](references/resource-data-patterns.md) | [Templates](references/project-templates.md) | [Analyst](references/analyst.md) | [Auditor](references/auditor.md) | [Builder](references/builder.md) | [Agent Vision](references/agent-vision.md)

Version upgrades (external hub): godot-version-migration — full-history router (legacy eras, 3→4 bridge, 4.0→4.7 hops); not mirrored here.

GDScript & Testing

[GDScript Mastery](references/gdscript-mastery.md) | [Testing Patterns](references/testing-patterns-expert-testing-patterns.md) | [Debugging/Profiling](references/debugging-profiling.md) | [Performance Optimization](references/performance-optimization.md)

2D Systems

[2D Animation](references/2d-animation.md) | [2D Physics](references/2d-physics.md) | [Tilemaps](references/tilemap-mastery.md) | [Animation Player](references/animation-player.md) | [Animation Tree](references/animation-tree-mastery.md) | [CharacterBody2D](references/characterbody-2d.md) | [Particles](references/particles.md) | [Tweening](references/tweening.md) | [Shader Basics](references/shaders-basics.md) | [Camera Systems](references/camera-systems.md)

3D Systems

[3D Lighting](references/3d-lighting.md) | [3D Materials](references/3d-materials.md) | [3D World Building](references/3d-world-building.md) | [Physics 3D](references/physics-3d.md) | [Navigation/Pathfinding](references/navigation-pathfinding.md) | [Procedural Generation](references/procedural-generation.md) | [Raycasting](references/raycasting-queries.md)

Gameplay Mechanics

[Abilities](references/ability-system.md) | [Combat](references/combat-system.md) | [Dialogue](references/dialogue-system.md) | [Economy](references/economy-system.md) | [Inventory](references/inventory-system.md) | [Questing](references/quest-system.md) | [RPG Stats](references/rpg-stats.md) | [Turn System](references/turn-system.md) | [Audio](references/audio-systems.md) | [Scene Transitions](references/scene-management.md) | [Save/Load](references/save-load-systems.md) | [Secrets](references/mechanic-secrets.md) | [Collections](references/game-loop-collection.md) | [Waves](references/game-loop-waves.md) | [Harvesting](references/game-loop-harvest.md) | [Time Trials](references/game-loop-time-trial.md) | [Revival](references/mechanic-revival.md) | [Monte Carlo Balancer](references/monte-carlo-balancer.md)

UI & UX

[UI Containers](references/ui-containers.md) | [Rich Text](references/ui-rich-text.md) | [Theming](references/ui-theming.md) | [Input Handling](references/input-handling.md) | [Seasonal Theming](references/theme-easter.md) | [Agent Vision](references/agent-vision.md)

Connectivity & Platforms

[Multiplayer](references/multiplayer-networking.md) | [Server Logic](references/server-architecture.md) | [Export Builds](references/export-builds.md) | [Desktop](references/platform-desktop.md) | [Mobile](references/platform-mobile.md) | [Web](references/platform-web.md) | [Console](references/platform-console.md) | [VR](references/platform-vr.md)

Adaptation Guides

• [Adapting Desktop -> Mobile](references/adapt-desktop-to-mobile.md)
• [Adapting Mobile -> Desktop](references/adapt-mobile-to-desktop.md)
• [Adapting Single -> Multiplayer](references/adapt-single-to-multiplayer.md)
• [Adapting 2D -> 3D](references/adapt-2d-to-3d.md)
• [Adapting 3D -> 2D](references/adapt-3d-to-2d.md)

Genre Blueprints (Exhaustive)

[Action RPG](references/genre-action-rpg.md) | [Shooter](references/genre-shooter.md) | [Shooter FPS](references/genre-shooter-fps.md) | [RTS](references/genre-rts.md) | [MOBA](references/genre-moba.md) | [Rogue-like](references/genre-roguelike.md) | [Survival](references/genre-survival.md) | [Open World](references/genre-open-world.md) | [Metroidvania](references/genre-metroidvania.md) | [Platformer](references/genre-platformer.md) | [Fighting](references/genre-fighting.md) | [Stealth](references/genre-stealth.md) | [Sandbox](references/genre-sandbox.md) | [Horror](references/genre-horror.md) | [Puzzle](references/genre-puzzle.md) | [Racing](references/genre-racing.md) | [Rhythm](references/genre-rhythm.md) | [Sports](references/genre-sports.md) | [Battle Royale](references/genre-battle-royale.md) | [Card Game](references/genre-card-game.md) | [Visual Novel](references/genre-visual-novel.md) | [Romance](references/genre-romance.md) | [Simulation](references/genre-simulation.md) | [Tower Defense](references/genre-tower-defense.md) | [Idle Clicker](references/genre-idle-clicker.md) | [Party](references/genre-party.md) | [Educational](references/genre-educational.md)

🐛 Part 10: Expert Diagnostic Patterns

The "Invisible Node" Bug

Symptom: Node exists in tree but isn't rendering. Expert diagnosis chain: visible property → zindex → parent CanvasLayer wrong layer → modulate.a == 0 → behind camera's near clip (3D) → SubViewport.rendertargetupdatemode not set → CanvasItem not in any CanvasLayer (renders behind everything).

The "Input Eaten" Bug

Symptom: Clicks or key presses ignored intermittently. Expert diagnosis: Another Control node with mousefilter = STOP overlapping the target. Or, modal PopupMenu consuming unhandled input. Or, unhandledinput() in another script calling getviewport().setinputas_handled().

The "Physics Jitter" Bug

Symptom: Character vibrates at surface contacts. Expert diagnosis: Safe Margin too large. Or, process used for movement instead of physics_process (interpolation mismatch). Or, collision shapes overlap at spawn (push each other apart permanently).

The "Memory Leak"

Symptom: RAM grows steadily during play. Expert diagnosis: queuefree() called but reference held in Array/Dictionary. Or, signals connected with CONNECTREFERENCE_COUNTED without cleanup. Use Profiler "Objects" tab to find orphaned instances. Search for Node instances without a parent.

The "Frame Spike"

Symptom: Smooth FPS but periodic drops. Expert diagnosis: GDScript GC pass. Or, synchronous load() for a large resource. Or, NavigationServer rebaking. Or, Server API query stall (requesting data from RenderingServer in _process). Profile with built-in Profiler → look for function-level spikes.

🚀 Part 11: Quick Start — Unity (C#) to Godot (GDScript)

Mental model shifts for senior engineers transitioning from the Unity ecosystem.

1. Nodes vs. GameObjects & Components

In Unity, a GameObject is a container for Components. In Godot, everything is a Node.

• Unity: GameObject + Transform + MeshFilter + Script.
• Godot: A MeshInstance3D node (which is a Transform and a Mesh) with a script attached.
• Expert Shift: Use Node composition. If you need a "Health Component", add a Node or Area3D as a child called "Health". Use RefCounted for logic-only components to save memory.

2. Scenes are Nested Prefabs

Godot doesn't have "Prefabs" because every scene is a prefab.

• You can instantiate a scene inside another scene, infinitely.
• Expert Shift: Every reusable system (Player, Enemy, UI Button) should be its own .tscn file. This promotes "Post-Order Traversal" (children are ready before parents).

3. Signals vs. Events/Actions

Godot's Signal system is a native implementation of the Observer pattern.

• Unity: event Action OnDeath;.
• Godot: signal died.
• Expert Shift: Signals are first-class citizens. They are visible in the Inspector and can be connected dynamically or via the editor. Use the "Signal Bus" pattern (Autoload) for global events to mimic Unity's Singleton managers.

4. Scripts as Class Extensions

When you attach a script to a node, that script is the node.

• Unity: GetComponent<MyScript>().
• Godot: The script extends the node's class (e.g., extends CharacterBody3D).
• Expert Shift: Use Typed GDScript (var x: int = 5) to gain compilation speedups and editor completion. Typed GDScript uses optimized opcodes when types are known at compile time.

5. Memory Management: No Garbage Collection stalls

Unlike Unity's C# which can have "GC spikes", GDScript uses Reference Counting.

• Expert Shift: Objects are freed the moment they are no longer referenced. This provides deterministic performance and avoids the intermittent "stutters" common in large Unity projects.

6. StringNames & Performance

Unity uses int or Enum for performance. Godot uses StringName.

• Expert Shift: Use &"name" for constant-time (O(1)) pointer comparisons in dictionaries and signal lookups.

Reference

• Godot 4.7 Official Documentation
• Godot 4.7 Migration Guide
• Godot Engine GitHub Discussions