Scenario Godot Architecture

Godot architecture (gameplay programmer and architect)

Target: Godot 4.7.2.stable, macOS Apple Silicon.

Expert architecture in Godot means scenes that run alone, data in Resources, behavior 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. If a sibling skill named here is missing from your available skills, ask the user to install it (npx skills add scenario-labs/skills --skill <name>); unattended, proceed from tool schemas and flag the gap.

REQUIRED BACKGROUND: scenario-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.

   Use a JSON envelope (format, version, data) with JSON.from_native. It keeps int, StringName and Vector3, while plain JSON returns 3 as 3.0. It refuses objects: it logs an error and writes null. Write atomically (.tmp, .bak, rename) and migrate by version. Plan saving from the start (Wilson [00:17:03]).

5. Stable roots, one level entry point, spawns under a stable parent. MainGame coordinates fixed containers, and the level exposes spawn markers and never owns the player (FAT Earth Studios, V4SO7foDoW4 [00:04:56]). Projectiles go under EntityRoot or EffectRoot, because freeing a tower freed its children (Godotneers, W8gYHTjDCic [01:05:16]). Change levels at idle time (FAT Earth [00:10:13]). Changing level inside body_entered logs "Removing a CollisionObject node during a physics callback"; request_level() defers and is clean. Fix to the source's instantiate() as BaseLevel [added]: a wrong type gave null and leaked the instance after the old level was gone, so check is BaseLevel first and free it on refusal (verified).

6. Input is one table, written by a tool. InputActions.defaults() feeds setup_input, which writes [input] into project.godot. Every event uses device = -1. Verified: a joypad event built in code defaults to device 0 and does not match pad 1. Keyboard reports device 16 and mouse 32 in 4.7 (version deltas). Bind keys by physical_keycode [added]. Store runtime rebinds as plain JSON in user://, never as InputEvent resources.

7. Static typing is a gate, not a style. Typing warnings are off by default (Godot docs, Static typing). At warn level (1) nothing prints headless, so typing_gate sets them to error (2) on an APFS clone. Typed code is faster by less than Boon's 116% (mNa0m2fvGOc [00:01:39]; see Numbers). Cast policy (docs, Static typing): x as T returns null silently, while a typed assignment var l: Label = node fails loudly ("Trying to assign value of type 'Button' to a variable of type 'Label'") and aborts the function. Use is and a typed local, or the typed assignment where a wrong type is a bug; keep as for a null you handle. var n := get_node("X") infers plain Node, and the gate rejects n.position ("not present on the inferred type Node"): write var n: Node2D = $X. Nested typed collections do not compile ("Nested typed collections are not supported"); Array[Array] and Dictionary[StringName, Array] do. Use typed math: clampf ran 1.70x to 1.74x faster than clamp over 1M calls, and clamp() on Colors is a parse error, so use Color.clamp() (verified).

8. Flip the sprite, not the body. FAT Earth's rule (zLdTvkLsmgA [00:04:30]) holds, but the cause differs. Verified in 2D: shapes followed the mirror, but move_and_slide rewrote scale (-1, 1) as rotation 180 and scale.y -1, so per-frame scale.x = -1 flipped the body every frame. Use flip_h and mirror the marker positions.

9. preload is a strong reference held by the script (FAT Earth, zLdTvkLsmgA [00:05:34]). Verified: a preloaded .tres was cached as soon as its holder script loaded, with no instance, and stayed cached after the probe dropped the script; a load() in _ready was released when its node was freed. A permanent node preloading menu > cutscene > level keeps the chain alive: preload small pieces next to their user, load levels and menus on demand (lint A09).

Also from the sources (short rules)