Building System Process

This page details the end‑to‑end build placement workflow powered by the BuildingSystem - a core entry point for any grid-based building functionality.

For the previous (5.1 injector-era) architecture and runtime chain reference, see:

docs/content/grid-placement/v5-1/guides/runtime-chain.md
docs/content/grid-placement/v5-1/guides/user-scope-root-and-lifetime.md

🎯 Key Entry Point

When to use: Essential for any grid building functionality - handles the complete placement workflow.

Main class: BuildingSystem (extends Node)
Configuration: GBConfig (Resource) State management: BuildingState (Resource)

This page details the end‑to‑end build placement workflow: from entering build mode with a selected placeable, through live rule validation with indicators, to final instantiation of the object in the game world.

Overview

1. Select a placeable to enter build mode. - UI selection triggers [BuildingSystem](../api/BuildingSystem/) to activate a preview. - [IndicatorManager](../api/IndicatorManager/) is accessed via [IndicatorContext](../api/IndicatorContext/). 2. Compute candidate tiles (collision mapping). - Active preview shape(s) → epsilon-filtered tile set for evaluation. 3. Generate live indicators. - [IndicatorManager](../api/IndicatorManager/) spawns/updates [RuleCheckIndicator](../api/RuleCheckIndicator/) nodes and returns an [IndicatorSetupReport](../api/IndicatorSetupReport/). - Optional pre-setup validation can run here to catch hard preconditions before the live loop. - You see a live heatmap scaffolding for validity feedback. 4. Per-frame rule evaluation on indicators. - Each physics frame, [PlacementValidator](../api/PlacementValidator/) runs [TileCheckRule](../api/TileCheckRule/) subclasses and updates indicator validity (via [RuleCheckIndicator](../api/RuleCheckIndicator/)). - Indicators continuously reflect current validity status during preview. 5. Confirm placement. - Player presses confirm (e.g. `gb_select`) while preview is active; guard checks ensure preview is currently valid. 6. Run full validation. - Re-run (or reuse cached) tile checks; execute non‑tile/aggregate rules (costs, biome, adjacency, dependencies, slope, clearance, etc.). - Aggregate results into a `PlacementResult` and emit signals for build logging/reporting. 7. Commit or abort. - If valid: instantiate the scene, attach metadata (e.g. [PlaceableInstance](../api/PlaceableInstance/)), and register with subsystems. - If invalid: abort and surface feedback (indicator flash / log messages). - If multi‑place is enabled, remain in preview and loop back to step 2; otherwise exit preview.

Error & Edge Scenarios

Scenario	Handling
Cursor leaves valid build area	`can_place` false; indicators tinted invalid.
Placeable rule list empty	No tile indicators; full validation still runs but likely always valid.
Lost reference (placeable freed) mid-preview	Cancel preview; require reselection.
Rotation changes geometry drastically	Indicators regenerated; cached tiles invalidated.

Data Flow Overview

Primary Build Flow:

Selection UI (placeable chosen) → BuildingSystem → IndicatorManager → IndicatorContext
IndicatorContext → Collision Mapping → Live Indicators → Per-frame Tile Rules (on indicators)
BuildingSystem (Confirm) → Full Validation + Signals → PlacementResult → Instantiation (if valid)

Post-Placement Manipulation Flow:

Mode Toggle/Actions → ManipulationSystem → Manipulatable Nodes
ManipulationSystem → IndicatorContext (move) → Manipulatable Nodes
MOVE operation builds temporary context for manipulation

Build Type System (v5.0.0+)

New in v5.0.0: The building system now uses a BuildType enum to differentiate between different build operation modes:

1
2
3
4
5
enum BuildType {
    SINGLE,  ## Single click/confirmation build
    DRAG,    ## Continuous drag-building across multiple tiles
    AREA     ## Future: Build across a defined area (e.g., fence line from point A to B)
}

How it flows through the system:

DragManager calls building_system.try_build(GBEnums.BuildType.DRAG) during drag operations
BuildingSystem accepts build_type parameter in try_build(), report_built(), and report_failure()
BuildActionData stores the build type and passes it through signals
GBActionLog checks build type to suppress drag/area build messages when print_on_drag_build=false
GBAudioInstancer (in demos) skips sounds and throttles failure audio based on build type

Benefits:

Clean separation between single-click and drag-building operations
Action log can properly suppress drag build spam
Audio system can throttle failure sounds during rapid drag attempts
Future-ready for area building features (fence lines, walls)

Example usage:

1
2
3
4
5
6
7
8
# Single build (default)
var report = building_system.try_build()  # Defaults to BuildType.SINGLE

# Drag building
var report = building_system.try_build(GBEnums.BuildType.DRAG)

# Future area building
var report = building_system.try_build(GBEnums.BuildType.AREA)

Signals

Signal	Emitted By	Purpose
`preview_changed(preview: Node)`	BuildingState	Preview instance changed; UI reacts (tooltips, ghost model).
`success(build_action_data:` BuildActionData`)`	BuildingState	Placement committed; downstream indexing & save registration. BuildActionData contains `build_type` to differentiate SINGLE/DRAG/AREA builds.
`failed(build_action_data:` BuildActionData`)`	BuildingState	Build failed; feedback to player (HUD/log), indicator flash. BuildActionData contains `build_type` for conditional handling.
`placed_parent_changed(placed_parent: Node)`	BuildingState	Parent for placed objects changed.
`system_changed(system:` BuildingSystem`)`	BuildingState	Connected building system changed.

{/* Testing Strategy moved to internal/testing_strategy.md */}

Cross‑References

core-godot-integration.md
service_architecture_and_adapters.md

Last updated: 2025-09-07 (converted to Steps list; refactor: PlacementManager → IndicatorManager; clarified Selection UI boundaries)

Community & Purchase Hub: Linktree – All Grid Builder Links