godot-game-architecture
Skill2 starsChanged 4 months agoMITView on GitHub
Godot 4.x game architecture, authoritative state, data ownership, managers, autoloads, scene flow, and save/load boundaries. Use when deciding where runtime state lives, splitting scene-local and persistent systems, coordinating menus and gameplay scenes, designing new-run/reset behavior, or implementing versioned persistence.
In this repository14 other files it gives its agents.
- game-balanceSkill
- game-design-vocabularySkill
- gamedev-mathSkill
- game-mechanics-designSkill
- game-systems-designSkill
- godot-2d-gameplaySkill
- godot-3d-gameplaySkill
- godot-desktop-appsSkill
- godot-fundamentalsSkill
- godot-mobileSkill
- godot-navigation-aiSkill
- godot-procedural-generationSkill
- godot-programming-patternsSkill
- godot-uiSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
20 rules. About 0 are common, 17 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈17
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
Use this skill for:
- Very specific: line 31
Read [application] to identify the main scene and [autoload] to inventory process-lifetime nodes and their order.
- Very specific: line 35
Search for direct writes to shared fields, global lookups, get_tree().root.add_child(), manager references, user-file access, and startup …
- Distinctive: line 39
Do not add a new manager until existing owners and autoloads have been evaluated.
- Distinctive: line 43
Use four separate concepts:
- Distinctive: line 50
Never use one shared resource as all four.
- Distinctive: line 59
Run state that crosses level scenes belongs to a session owner that survives those transitions.
- Distinctive: line 67
Keep a manager scene-local when its state should disappear with that scene.
- Distinctive: line 69
Use an autoload only when at least one condition is true:
- Distinctive: line 83
Treat replacement and overlay as different operations.
- Distinctive: line 84
Keep runtime-created gameplay nodes under the current scene so replacement frees them.
- Very specific: line 85
Wait for SceneTree.scene_changed when initialization requires nodes in the incoming scene.
- Distinctive: line 97
Keep disk I/O and serialization outside gameplay entities.
- Distinctive: line 102
Write an ownership map for only the affected state and flows.
- Distinctive: line 106
Put coordinators at the lifetime they manage.
- Distinctive: line 108
Add snapshot conversion, validation, versioning, and storage as separate steps.
- Distinctive: line 109
Remove obsolete duplicate state only after all readers use the authority.
- Distinctive: line 110
Test lifecycle and persistence matrices, not only the happy path.
- Distinctive: line 114
Run existing project checks and exercise these cases where relevant:
- Distinctive: line 142
Old saves crash: no schema version, migration, defaults, or unknown-ID policy exists.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Godot Game Architecture
Give every piece of state one authoritative owner at the narrowest lifetime that satisfies the game flow.
Scope
Use this skill for:
- Classifying state by lifetime and choosing its authoritative writer.
- Separating static definitions, live simulation state, presentation, and persisted snapshots.
- Deciding whether a coordinator belongs in a scene or an autoload.
- Defining manager responsibilities and public mutation boundaries.
- Coordinating menu, gameplay, results, reload, and overlay scene flow.
- Designing new-session, reset, checkpoint, save, load, migration, and corruption behavior.
- Preventing scene transitions from leaking nodes or retaining stale references.
Do not use this skill for basic node selection, scene instantiation, custom-resource syntax, Input Map setup, or editor navigation; use the fundamentals skill. Do not use it to teach SOLID, signal mechanics, commands, or pooling; use the programming-patterns skill. Architecture may select an event or component boundary, but the patterns skill owns its implementation details.
Inspect Before Designing
- Locate
project.godotand inspectconfig/featuresfor the exact Godot 4.x target. - Read
[application]to identify the main scene and[autoload]to inventory process-lifetime nodes and their order. - Inspect the project's scene, script, resource, and data layout. Preserve naming, folder, typing, and dependency conventions.
- Trace every current scene transition and overlay. Record who initiates it, what is freed, what persists, and what the next scene expects.
- Build a state inventory. For each value, record its writer, readers, lifetime, reset rule, definition source, and whether it is persisted.
- Search for direct writes to shared fields, global lookups,
get_tree().root.add_child(), manager references, user-file access, and startup emissions. - Reproduce baseline flows: fresh boot, new game, scene change, retry, return to menu, and save/load when present.
- Inspect existing tests and any save fixtures before changing schemas or ownership.
Do not add a new manager until existing owners and autoloads have been evaluated.
Classify State
Use four separate concepts:
- Definition data: authored facts shared by instances, often resources, such as item cost or unit base speed.
- Runtime state: mutable facts for this entity, room, match, or session, such as current health or discovered rooms.
- Presentation state: transient view details, such as selected tab, animation progress, or a visible tooltip.
- Snapshot data: primitive, versioned values crossing the persistence boundary.
Never use one shared resource as all four. In particular, mutating a definition resource to store runtime progress can change every consumer and complicate saves.
Assign Ownership by Lifetime
Choose the nearest stable owner:
- Entity state belongs to the entity or one of its focused components.
- Room or level state belongs to that room/level coordinator.
- Match state belongs to the match root or a match model owned by it.
- Run state that crosses level scenes belongs to a session owner that survives those transitions.
- Profile progress and settings belong to profile/settings services with explicit persistence APIs.
- UI displays state but should not become the authoritative gameplay store.
For each state value, allow one writer. Other systems request mutations through methods and observe results through reads or events. Avoid public dictionaries that every scene edits directly.
Decide Manager Lifetime
Keep a manager scene-local when its state should disappear with that scene. A level director, encounter tracker, or match referee normally belongs under the gameplay root.
Use an autoload only when at least one condition is true:
- The capability must exist before and after current-scene replacement.
- Multiple unrelated root scenes need the same process-lifetime service.
- It coordinates scene replacement itself.
- It owns session/profile state whose defined lifetime crosses those scenes.
An autoload must not retain ordinary nodes from a scene after that scene exits. Store plain state, stable IDs, or reacquired references. Provide explicit start_new_*, reset, and restore methods; process lifetime is not a reset policy.
Design Scene Flow
- Give one coordinator authority to replace the current scene.
- Express destinations as exported
PackedScenevalues or a centralized route map, not repeated string paths across UI and actors. - Guard duplicate transitions caused by several inputs or end conditions in one frame.
- Treat replacement and overlay as different operations. Replace mutually exclusive roots; add pause, dialog, and loading overlays under a deliberate owner.
- Keep runtime-created gameplay nodes under the current scene so replacement frees them.
- Wait for
SceneTree.scene_changedwhen initialization requires nodes in the incoming scene. - Pull initial state after the scene is ready; do not rely on a global startup event that late listeners can miss.
- Define whether death, retry, next level, and return to menu preserve or reset run state.
Define Persistence Boundaries
- Save snapshots, not nodes, callables, signal connections, or live resource references.
- Convert game objects to primitive dictionaries/arrays with stable IDs.
- Store user data under
user://, never under importedres://content. - Include a schema version and define migration or rejection for every supported old version.
- Validate types, ranges, IDs, and required relationships before mutating live state.
- Restore into a clean model first, then build or update scenes from that model.
- Keep disk I/O and serialization outside gameplay entities.
- Define save timing and failure behavior; do not let every subsystem write independently.
Implementation Workflow
- Write an ownership map for only the affected state and flows.
- Define the narrow public API of the authoritative owner.
- Route all mutations through that owner while preserving current behavior.
- Make views initialize from a current snapshot and then observe later changes.
- Put coordinators at the lifetime they manage; avoid promoting scene-local state to an autoload for convenience.
- Centralize scene replacement and define reset semantics for every route.
- Add snapshot conversion, validation, versioning, and storage as separate steps.
- Remove obsolete duplicate state only after all readers use the authority.
- Test lifecycle and persistence matrices, not only the happy path.
Verification
Run existing project checks and exercise these cases where relevant:
- Fresh boot with no user data.
- Direct main-scene run and normal boot through the configured entry scene.
- New game after a previous run in the same process.
- Repeated menu, gameplay, result, retry, and next-level transitions.
- Two transition requests in the same frame.
- Scene exit while timers, awaits, or runtime-created nodes are active.
- UI created after state already changed; it must still show the current value.
- Save then load round trip into a clean session.
- Missing, truncated, malformed, unknown-version, and partially valid save data.
- Stable-ID resolution when authored content was renamed or removed.
- Profile/settings persistence without accidental run-state persistence.
- Remote scene tree and object counts after several loops; no old roots or scene references remain.
Report which state owner, reset policy, transition flow, and schema version were verified.
Failure Modes
- Everything becomes an autoload: convenience replaced ownership. Move state to the narrowest scene or model lifetime.
- Manager is a global bag: unrelated systems write fields directly. Split coherent capabilities and expose mutation methods.
- UI is stale on entry: it waited for a past event. Read current state when initialized, then subscribe for changes.
- New game keeps old values: process-lifetime state has no explicit reset path.
- Scene change leaks actors: nodes were attached above
current_scene, or a long-lived object retains them. - Autoload calls missing HUD nodes: global initialization ran before the destination scene was ready. React after
scene_changedor let the scene pull state. - Two owners disagree: state is duplicated in UI, manager, entity, or resource. Choose one authority and derive the rest.
- Shared definitions mutate: a
.tresused as a template also holds per-run progress. Split definition and runtime models. - Load half-applies: validation and mutation were interleaved. Parse and validate a complete temporary snapshot first.
- Old saves crash: no schema version, migration, defaults, or unknown-ID policy exists.
- Transition strings drift: paths are scattered across buttons and actors. Centralize routing or export scene resources.
References
- State and data ownership
- Managers and scene flow
- Persistence boundaries
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

