Godot architecture (gameplay programmer and architect)

Version 0.1 (2026-10-02), part of Godot Expert Skills v0.1. Target: Godot 4.7.2.stable, macOS Apple Silicon.

Expert architecture in Godot means scenes that run alone, data in Resources, behaviour in small components, and every boundary (save file, input, export) proven by a test. This skill holds the expert rules from the sources, corrected where Godot 4.7.2 behaves differently, plus a tested G1 core (inventory, health and damage, save and load, input with rebinding) and the tools that build and audit it.

REQUIRED BACKGROUND: godot-expert (channels, gd_run, the review loop, 4.7 traps).

Status (2026-10-02, round 2): everything below ran in Godot 4.7.2 here. 12 live tests: 11 pass, the C# check was not run. 30 GUT tests and 17 offline lint checks also pass; round-2 probes are P15 to P17 in references/procedures.md.

Stance (the expert delta)

1. Every scene runs alone; the owner injects. A scene that reaches up (get_node("/root/..."), ../) is coupled to one tree. Use "call down, signal up, event out" (Eric Peterson, yB3Wv-Lr7pg [00:05:54]; Godot docs, Scene organization). An event bus autoload holds signals and no state (Peterson [00:17:36]). State is owned high in the tree and injected downward, because _ready runs children first (Mark Wilson, BgrHnJDt2ww [00:12:29]). arch_audit.gd instantiates each scene alone and flags errors, NodePaths that do not resolve and node exports left empty.
2. Definitions are Resources; per-instance state is not. Keep item databases in typed custom Resources, not Dictionaries: no id typos, and paths follow file moves (Godotneers, 4vAkTHeoORk [00:12:57]). A loaded Resource is one shared instance: a change through one reference is seen by the next load() (verified), so treat definitions as read-only. Stacks, health and cooldowns go in RefCounted or Node objects. For a per-instance copy (durability, rolled stats) use duplicate() when the Resource is flat, and duplicate_deep(Resource.DEEP_DUPLICATE_ALL) when it holds external sub-resources: duplicate(true) kept those shared (verified). One Resource class per file, and a default for every _init parameter (Godot docs, Resources): an inner-class Resource reloaded its field as null, and _init(p_hp) without a default lost its fields (verified).
3. Never list folders at runtime; build a registry at edit time. Folder scans work in the editor and break in exports (Godotneers [01:13:35]). In an exported .pck, DirAccess.get_files_at returned only *.tres.remap (a naive scan loaded 0 of 3), while list_directory and the ItemCatalog from build_catalog found all 3 (verified). The pack is case-sensitive: a wrong-case path loaded on macOS with only a "Case mismatch" warning and did not exist in the pack, so name every file and folder in lowercase snake_case (Godot docs, Project organization; lint A11, A12). A .gdignore must be empty and takes no patterns (lint A15). It hides a folder from the importer, not from load(): an .svg inside failed with "No loader found", while a text .tres still loaded (verified [added]).
4. A save file is data, never code. Verified 4.7.2 [added]:
   • a .tres written to user:// with an embedded GDScript ran that script on load();
   • str_to_var and ConfigFile.parse both built a Node from Object(Node,...) text.