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)
Status: Draft
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”- Select a placeable to enter build mode.
- UI selection triggers BuildingSystem to activate a preview.
- IndicatorManager is accessed via IndicatorContext.
- Compute candidate tiles (collision mapping).
- Active preview shape(s) → epsilon-filtered tile set for evaluation.
- Generate live indicators.
- IndicatorManager spawns/updates RuleCheckIndicator nodes and returns an 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.
- Per-frame rule evaluation on indicators.
- Each physics frame, PlacementValidator runs TileCheckRule subclasses and updates indicator validity (via RuleCheckIndicator).
- Indicators continuously reflect current validity status during preview.
- Confirm placement.
- Player presses confirm (e.g.
gb_select) while preview is active; guard checks ensure preview is currently valid.
- Player presses confirm (e.g.
- 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
PlacementResultand emit signals for build logging/reporting.
- 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”| 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
Section titled “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
Signals
Section titled “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. |
failed(build_action_data: BuildActionData) | BuildingState | Build failed; feedback to player (HUD/log), indicator flash. |
placed_parent_changed(placed_parent: Node) | BuildingState | Parent for placed objects changed. |
system_changed(system: BuildingSystem) | BuildingState | Connected building system changed. |
Cross‑References
Section titled “Cross‑References”- Placement Chain: Placement processing chain documentation
- Manipulation System: Object manipulation system overview
- Placement Rules Pipeline: Placement rules system documentation
- Collision Mapping: Collision mapping system overview
- Context & State: Context and state management
- Configuration & Settings: System configuration options
Last updated: 2025-09-07 (converted to Steps list; refactor: PlacementManager → IndicatorManager; clarified Selection UI boundaries)
Community & Purchase Hub: Linktree – All Grid Builder Links