Skip to content
Grid Building Docs

Project Architecture

The plugin architecture is layered to keep systems modular and testable while supporting flexible game integration.

Layer Overview

Section titled “Layer Overview”
LayerContentsNotes
Resource ConfigurationGBConfig, GBSettings, GBTemplates, GBMessages, rule resourcesEditable in inspector; serialized with project
Composition & InjectionGBCompositionContainer, GBInjectorSystemProvides dependency injection & lazy construction
Core SystemsPlacement, Targeting, Building, Manipulation, Validation, IndicatorEach focuses on a single domain concern
State ContainersGBStates (mode, targeting, building, manipulation)Shared by injected nodes; supports multi-context
ContextsGBContexts (placement, systems, owner, level)Encapsulate environment dependencies
UI & InteractionAction bar, selection lists, info displaysDriven by states & actions resources
Testing UtilitiesFactories, reports, test setupsFacilitate GdUnit coverage & deterministic assertions

Dependency Injection Model

Section titled “Dependency Injection Model”

Instead of global singletons, systems resolve dependencies from the injected composition container. Benefits:

  • Multitenancy (multiple players/levels)
  • Clear test seams (swap in a fresh container)
  • Lazy provisioning (logger/settings only built when required)

Nodes opt‑in via resolve_gb_dependencies pattern. See the Dependency Injection document.

How the Systems Work Together

Section titled “How the Systems Work Together”

Instead of a complex diagram, let’s walk through how the Grid Building system works in simple steps:

The Basic Flow:

Section titled “The Basic Flow:”
  1. You pick something to build: Click a placeable in the UI
  2. BuildingSystem wakes up: enter_build_mode() gets called with your choice
  3. IndicatorManager provides feedback: Sets up live indicators as you target tiles
  4. GridTargetingSystem helps: Figures out where you’re pointing on the grid
  5. PlacementValidator checks rules: Makes sure you can build there (tile rules first)
  6. IndicatorManager shows feedback: Colors appear to show valid/invalid spots
  7. ManipulationSystem (optional): If enabled, lets you move/rotate the preview before placing
  8. You confirm placement: BuildingSystem.try_build() runs full validation
  9. Object gets created: If everything checks out, your building appears in the world
  10. ManipulationSystem (again): Now you can move/rotate/delete the placed object

Key Points to Remember:

Section titled “Key Points to Remember:”
  • BuildingSystem is the “boss” - it starts and ends the building process
  • IndicatorManager handles the live preview feedback
  • ManipulationSystem has two jobs: preview adjustment (if enabled) and post-placement editing
  • Validation happens twice: quick checks during preview, full checks when you confirm
  • Everything is connected but each system has one clear job

Key Data Flows

Section titled “Key Data Flows”
  1. UI Selection → User selects placeable from UI → BuildingSystem.enter_build_mode(placeable) is called
  2. Build Mode Initialization: BuildingSystem prepares preview with selected placeable
  3. Targeting Setup: GridTargetingSystem tracks cursor/grid position
  4. Live Validation: PlacementValidator runs tile rules, IndicatorManager shows live feedback
  5. Preview Manipulation: If enabled in placeable settings, ManipulationSystem can move/rotate preview instances during placement
  6. Confirmation: User confirms placement, BuildingSystem.try_build() runs full rule validation (including non-tile rules)
  7. Instantiation: If valid, BuildingSystem spawns PlaceableInstance with metadata for manipulation & save/load
  8. Post-Placement: ManipulationSystem handles move/rotate/delete operations on placed instances

Save / Load Considerations

Section titled “Save / Load Considerations”

PlaceableInstance holds references back to originating Placeable enabling reconstruction. Systems should avoid storing raw scene node references across sessions; rely on IDs or resource paths.

Logging & Debug Controls

Section titled “Logging & Debug Controls”

GBDebugSettings gates verbosity. High verbosity surfaces:

  • Injection operations
  • Indicator setup summaries
  • Rule validation traces (future extension)

Extensibility Guidelines

Section titled “Extensibility Guidelines”
  • Favor composition (create a new rule resource) over conditionals inside existing rules.
  • Keep resource scripts lean; complex logic belongs in systems.
  • Add new UI affordances by observing states rather than polling systems directly.

Planned Evolutions

Section titled “Planned Evolutions”
  • Cross-context synchronization primitives (multiplayer scenarios).
  • Performance profiling hooks (duration_ms in reports).
  • Rule documentation tooling.

Core Architecture References

Section titled “Core Architecture References”
  • Context & State – Distinguishes long‑lived context objects from frequently mutating state containers; essential for understanding rule evaluation purity.
  • Placement Chain – End‑to‑end flow from input to instantiated object.
  • Dependency Injection – Container pattern enabling multi‑tenant/testable setup.
  • Placement Rules Pipeline – Validation composition & indicator generation.

High-Level System Architecture

Section titled “High-Level System Architecture”

Core Components:

Data Flow:

Last updated: 2025-08-20