Skip to content
Grid Building Docs

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.

🎯 Key Entry Point

Section titled “🎯 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

Section titled “Overview”
  1. Select a placeable to enter build mode.
  2. Compute candidate tiles (collision mapping).
    • Active preview shape(s) → epsilon-filtered tile set for evaluation.
  3. Generate live indicators.
  4. Per-frame rule evaluation on indicators.
  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), 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.

Major Enhancements in v5.0.0

Section titled “Major Enhancements in v5.0.0”

🏗️ Architectural Improvements

Section titled “🏗️ Architectural Improvements”
  • Dependency Injection Integration: Complete integration with GBCompositionContainer for better decoupling
  • Unified Configuration: All building settings consolidated in GBConfig resource
  • Enhanced State Management: Improved BuildingState with better lifecycle handling

🔧 Process Enhancements

Section titled “🔧 Process Enhancements”
  • Comprehensive Workflow Documentation: New detailed end-to-end build placement workflow
  • Enhanced Visual Process Flows: Clear documentation with step-by-step explanations
  • Improved Error Handling: Better error reporting and user feedback throughout the process
  • Performance Optimizations: Reduced allocations and faster validation cycles

📊 New Features

Section titled “📊 New Features”
  • Enhanced Preview System: More responsive live preview with better visual indicators
  • Improved Instantiation: Better metadata attachment and subsystem registration
  • Advanced Post-Placement Handling: Enhanced multi-place mode and manipulation support
  • Better Edge Case Handling: Improved handling of error scenarios and edge cases

🐛 Debugging & Diagnostics

Section titled “🐛 Debugging & Diagnostics”
  • Enhanced Logging: Better tracing throughout the build placement workflow
  • Visual Debug Support: Integration with GBDebugSettings for process debugging
  • Performance Monitoring: Built-in timing for workflow steps

Error & Edge Scenarios

Section titled “Error & Edge Scenarios”
ScenarioHandling
Cursor leaves valid build areacan_place false; indicators tinted invalid.
Placeable rule list emptyNo tile indicators; full validation still runs but likely always valid.
Lost reference (placeable freed) mid-previewCancel preview; require reselection.
Rotation changes geometry drasticallyIndicators regenerated; cached tiles invalidated.

Data Flow Overview

Section titled “Data Flow Overview”

Primary Build Flow:

Post-Placement Manipulation Flow:

Build Type System (v5.0.0+)

Section titled “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:

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:

  1. DragManager calls building_system.try_build(GBEnums.BuildType.DRAG) during drag operations
  2. BuildingSystem accepts build_type parameter in try_build(), report_built(), and report_failure()
  3. BuildActionData stores the build type and passes it through signals
  4. GBActionLog checks build type to suppress drag/area build messages when print_on_drag_build=false
  5. 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:

# 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

Section titled “Signals”
SignalEmitted ByPurpose
preview_changed(preview: Node)BuildingStatePreview instance changed; UI reacts (tooltips, ghost model).
success(build_action_data: BuildActionData)BuildingStatePlacement committed; downstream indexing & save registration. BuildActionData contains build_type to differentiate SINGLE/DRAG/AREA builds.
failed(build_action_data: BuildActionData)BuildingStateBuild failed; feedback to player (HUD/log), indicator flash. BuildActionData contains build_type for conditional handling.
placed_parent_changed(placed_parent: Node)BuildingStateParent for placed objects changed.
system_changed(system: BuildingSystem)BuildingStateConnected building system changed.

Cross‑References

Section titled “Cross‑References”

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

Community & Purchase Hub: Linktree – All Grid Builder Links