foundation-gdscript-system-design

name: foundation-gdscript-system-design description: Tier 1 foundation for game-agnostic GDScript system design: ownership boundaries, signal contracts, composition, and resource-backed configuration. tier: core godot_version: 4.6+ doc_anchors: - godot-docs/tutorials/best_practices/what_are_godot_classes.rst - godot-docs/tutorials/best_practices/scene_organization.rst - godot-docs/tutorials/best_practices/godot_interfaces.rst - godot-docs/tutorials/scripting/resources.rst tags: - gdscript - architecture - systems depends_on: - godot-skills/godot-foundations/foundation-architecture/SKILL.md

Foundation GDScript System Design

Use When

• Designing/refactoring non-trivial GDScript systems.
• Establishing architecture before implementation slices.

Outcomes

• GDScript systems have clear ownership, composition, and messaging boundaries.
• Configuration and tunables are resource-backed instead of hardcoded.
• Interfaces remain stable under iterative refactors.

Required Rules

• One authoritative owner per mutable state domain.
• Prefer composition over deep inheritance chains.
• Use explicit signal contracts for inter-system communication.
• Keep runtime logic and resource/config data separated.
• Externalize tunables in resources/config instead of hardcoded literals.

Workflow

1. Define mutable-state domains and authoritative owners.
2. Split systems by composition responsibilities rather than inheritance depth.
3. Declare signal contracts and message payload schemas.
4. Move tunable parameters into resources/config assets.
5. Validate refactor resilience by moving components without breaking contracts.

Validation

• Ownership map shows no shared mutable state without arbitration.
• Signal contract tests/assertions catch payload drift.
• Config changes via resources alter behavior without code edits.

Failure Modes

• Inheritance-heavy scripts accumulate mixed responsibilities.
• Signal payloads are undocumented and break consumers silently.
• Gameplay constants are hardcoded across scripts and diverge over time.

Local Doc Anchors

• godot-docs/tutorials/best_practices/what_are_godot_classes.rst
• godot-docs/tutorials/best_practices/scene_organization.rst
• godot-docs/tutorials/best_practices/godot_interfaces.rst
• godot-docs/tutorials/scripting/resources.rst