Configuration & Settings

Status: Draft

All tunable behavior is consolidated into a structured configuration resource hierarchy rooted at GBConfig.

Goals

• Single injection point (DI) for systems needing settings
• Clear separation between game design knobs and runtime state
• Support for future serialization & profile overrides

Major Enhancements in v5.0.0

🏗️ Architectural Improvements

• Unified Configuration System: Complete consolidation of all settings in GBConfig resource
• Dependency Injection Integration: Full integration with GBCompositionContainer for better decoupling

• Enhanced Hot Reload: Better support for runtime configuration changes

🔧 Configuration Enhancements

• GBConfig Consolidation: All configuration now centralized in single root resource
• Enhanced Access Patterns: More efficient configuration access with better caching
• Improved Validation: Better editor-time validation and error reporting
• Migration Support: Automatic migration from v4.x configuration structures

📊 New Configuration Categories

• Enhanced GBActions: More comprehensive input action definitions
• Improved GBSettings: Better organization of general settings and knobs
• Advanced GBVisualSettings: Enhanced visual configuration with theme support
• Better ManipulationSettings: More detailed manipulation configuration options

🐛 Debugging & Tooling

• Configuration Debugging: Better support for inspecting configuration during development
• Enhanced Validation: More comprehensive editor-time validation
• Migration Tools: Automated tools for upgrading from v4.x configurations
• Performance Monitoring: Built-in configuration performance tracking

Configuration Hierarchy (Conceptual)

GBConfig
  ├── GBActions            (input action names)
  ├── GBSettings           (general numeric / boolean knobs)
  │     ├── grid_size_px
  │     ├── placement_epsilon
  │     ├── multi_place_enabled
  │     └── ...
  ├── GBTemplates          (paths / resource refs to common scene templates)
  ├── GBVisualSettings     (colors, indicator styles, animation speeds)
  ├── GBMessages           (optional – message bus instance)
  ├── ManipulationSettings (rotation step, snap toggle, default indicator shape)
  └── (Future) RuleSettings (per rule thresholds)

Access Pattern

Systems receive a GBConfig reference during construction (DI). They do not store individual primitive values; instead they read them on demand, enabling future hot reloads.

Example (pseudocode):

func _ready():
    _epsilon = config.settings.placement_epsilon

If live reload is needed later, replace value caching with lookup or subscribe to a settings_changed signal.

Key Settings

Setting	Typical	Purpose
grid_size_px	16	Base tile dimension (square)
placement_epsilon	0.05	Fractional tile area threshold (collision mapping)
rotation_step_deg	90	Rotation snap increment
multi_place_enabled	true	Keep preview active after confirm
indicator_default_shape	Rect	Shape used when placeable lacks explicit preview geometry
indicator_valid_color	#00d084	Positive feedback color
indicator_invalid_color	#ff4d4f	Failure tint color

Actions vs Settings

Input action names live in GBActions so changing a binding (e.g. rotate_item) requires editing only one resource; systems reference the symbolic name.

Templates & Resources

GBTemplates centralizes packed scenes / resources (e.g. default indicator scene, selection UI prefab). This avoids scattering hard‑coded load() paths across systems.

Visual Settings

Color & UI style values are grouped for consistent theming. Indicator style (line thickness, alpha) is referenced both by preview node and any rule overlays.

Validation & Tooling

An editor script can assert on load:

• All required actions exist in the project’s InputMap
• All template paths resolve
• Epsilon within sane bounds (0 < epsilon < 0.5)

Failing fast prevents subtle runtime errors.

Extensibility

To add a new setting category:

1. Create a new Resource subclass (e.g. GBRuleSettings)
2. Add exported fields
3. Reference it from GBConfig
4. Add accessor helpers or pass full config as before

Cross‑References

• Input & Actions: systems/input_and_actions.md
• Manipulation System: systems/manipulation_system.md
• Placement Rules: systems/placement_rules.md
• Collision Mapping: systems/collision_mapping.md

---

Support / Purchase Hub: Linktree – All Grid Builder Links