Configuration & Settings

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)
  ├── ManipulationSettings (rotation step, snap toggle, message strings)
  ├── ActionLogSettings    (UI display messages, action log configuration)
  └── (Future) RuleSettings (per rule thresholds)

Access Pattern

Systems receive a GBConfig reference during construction (DI). They do not store individual primitive values; they store references to the resolved Resource subclasses (e.g. BuildingSettings). There are some exceptions to this like RuleCheckIndicator which saves a direct reference to the IndicatorVisualSettings to allow for multiple templates within a GBCompositionContainer to have different visual styles or to display different image texture sizes.

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.

Setting Up Input Actions

The plugin requires specific input actions to be configured in your project’s InputMap (Project → Project Settings → Input Map). While the plugin validates these actions exist, you must add them manually.

Required Mode Control Actions

Add these actions to your InputMap for basic mode switching:

Action	Description	Suggested Key
info_mode	Info/inspection mode	1 (Number key)
build_mode	Build/placement mode	2 (Number key)
moving_mode	Move/manipulation mode	3 (Number key)
demolish_mode	Demolish mode	4 (Number key)
off_mode	Exit all modes	Escape

Required Building Actions

Action	Description	Suggested Key	Required When
confirm	Confirm placement	Left Mouse Button or Enter	Always required
rotate_right	Rotate clockwise	E	Only if using manipulatable objects with rotation
rotate_left	Rotate counter-clockwise	Q	Only if using manipulatable objects with rotation
flip_horizontal	Flip horizontally	F	Only if using manipulatable objects with flipping
flip_vertical	Flip vertically	V	Only if using manipulatable objects with flipping

Keyboard Grid Navigation (Optional)

For keyboard-based grid cursor control, add these actions. Note: These are only required if you want players to navigate the grid using keyboard input instead of mouse-only interaction.

Action	Description	Suggested Key
positioner_up	Move cursor up	W or Arrow Up
positioner_down	Move cursor down	S or Arrow Down
positioner_left	Move cursor left	A or Arrow Left
positioner_right	Move cursor right	D or Arrow Right
positioner_center	Center cursor	C

Adding Actions via Project Settings

1. Open Project → Project Settings
2. Navigate to the Input Map tab
3. For each action:
   • Type the action name (e.g., build_mode) in the “Add New Action” field
   • Click “Add”
   • Click the ”+” button next to the action to add a key binding
   • Press the desired key (e.g., “2” for build_mode)
   • Click “OK”

Action Validation

The plugin automatically validates that all required actions exist at runtime. If any are missing, you’ll see warnings in the console with the exact action names that need to be added.

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