Guides Home

The Grid Building Plugin provides a flexible, data‑driven workflow for placing, validating, and manipulating objects on a 2D grid (orthogonal, isometric, or custom tile coordinate logic) in Godot 4.x.

Minimum Godot version

v5.0.0 targets Godot 4.4+ as the minimum supported version.

🎯 Quick Start Entry Points

If you’re new to Grid Building, start with these key classes:

Core Resource Classes (Extend Godot Resource)

• GBConfig - Main configuration hub, your primary entry point
• Placeable - Defines what can be built
• PlacementRule - Base class for validation logic
• TileCheckRule - Spatial validation rules

Core Node Classes (Extend Godot Node)

• BuildingSystem - Main building workflow controller
• ManipulationSystem - Object manipulation and movement
• GridTargetingSystem - Cursor-to-grid conversion, snapping, and targeting state
• GBCompositionContainer - Dependency injection root
• IndicatorManager - Visual feedback system

Core Goals

• Fast iteration: add new placeable object types with minimal boilerplate.
• Strong validation model: prevent invalid placements via configurable rules.
• Visual clarity: real‑time indicators show why a placement is valid/invalid.
• Extensibility: systems loosely coupled through dependency injection and contexts.
• Multi‑context readiness: support multiple players/world instances via composition containers.

Major Enhancements in v5.0.0

🏗️ Architectural Overhaul

• Dependency Injection System: Complete rewrite using GBCompositionContainer and GBInjectorSystem
• Unified Configuration: All settings consolidated in GBConfig resource
• Godot 4.4+ Support: Leverages typed data structures introduced in 4.4 for better performance

🔧 System Improvements

• Issue Reporting & Validation Flow: Use get_runtime_issues() at runtime and get_editor_issues() in the editor to collect issues. validate() methods return bool and delegate messaging to GBLogger (typically warnings). Implementations usually call get_runtime_issues(), log any items via the logger, and return true only when the issues list is empty. validate() never returns Array[String].
• Better Debugging: GBDebugSettings resource for centralized debug control
• Improved UI: Separated clear/setup tabs, better icon scaling
• Performance Optimizations: Reduced allocations, better caching, faster validation

📚 Documentation Enhancements

• Process Flow Documentation: Detailed ordered sequences for system interactions
• Comprehensive Migration Guide: Step-by-step upgrade path from 4.x
• Enhanced API Documentation: Code examples and usage patterns
• Version Comparison Tools: Side-by-side feature comparison

Primary Systems

System	Purpose	Key Class	v5.0.0 Enhancements
IndicatorManager	Orchestrates validation + indicator generation	Node-based entry point	Enhanced validation reporting
PlacementValidator	Combines & executes placement rules	Validation engine	Array[String] error details
IndicatorManager	Builds rule check indicators & reports diagnostics	Visual feedback system	Better debug support
BuildingSystem	High-level interaction state & user actions	Main building node	Dependency injection
ManipulationSystem	Move / rotate / flip / demolish placed items	Object manipulation	Enhanced mode support
GridTargetingSystem	Tracks cursor → grid conversion & snapping	Grid positioning	Improved responsiveness
GBInjectorSystem	Auto dependency wiring for nodes exposing resolve_gb_dependencies	Dependency injection	New in v5.0.0

Data & Configuration Resources

The plugin relies on exported resources to decouple content from logic:

• GBConfig – top-level composition root (references settings, actions, templates, messages, etc.).
• GBSettings → GBVisualSettings, ManipulationSettings, GBMessages (user‑facing strings & UI text), GBDebugSettings.
• GBTemplates – PackedScene references for indicators, previews, UI, etc.
• Rule Resources (PlacementRule, TileCheckRule, custom derived rules) – declarative validation units.

All of these are surfaced through GBCompositionContainer accessor methods, ensuring a stable injection contract.

Runtime Flow (High Level)

1. Enter build mode via UI on the BuildingSystem. This creates a preview object which becomes the current target.
2. GridTargetingState updates the cursor→grid position every frame; the preview snaps to the active grid.
3. The IndicatorManager orchestrates validation by combining global/placeable/contextual rules and delegating rule evaluation to the PlacementValidator.
4. As part of indicator generation, the IndicatorService creates a RuleCheckIndicator for each TileCheckRule and targets its tile(s). On each physics process, these indicators refresh their valid status (the tile spaces are probed via ShapeCast2D nodes).
5. Non‑tile rules (regular PlacementRule) validate non‑collision constraints (e.g., resource requirements via GBOwnerContext).
6. When the player confirms the build action, a final validation runs: all tile indicators must be valid and all placement rules must pass for the placement to succeed. If successful, the BuildingSystem instantiates the committed object (typically from a Placeable template).
7. After placement, the ManipulationSystem allows move/rotate/flip/demolish operations while continuing to respect rules.

For a step-by-step breakdown see Building System Process.

Dependency Injection

Nodes opt‑in by implementing:

func resolve_gb_dependencies(p_config: GBCompositionContainer) -> void:
    # Acquire only what is needed
    _logger = p_config.get_logger()
    _targeting_state = p_config.get_targeting_state()

This keeps most scene scripts lean, avoiding manual node path resolution.

See the dedicated Dependency Injection page.

Indicators & Validation

Validation is rule‑centric. Each PlacementRule can:

• Filter tiles
• Test collisions / constraints
• Provide custom failure reasons

Tile‑level rules (subclasses of TileCheckRule) produce indicators; non‑tile rules produce logical gating results only.

IndicatorSetupReport supplies a diagnostic snapshot (counts, mapped positions, owner shapes) for debugging & tests.

Validation return type

validate() implementations return bool (success/failure) and do not return Array[String]. They typically call get_runtime_issues()/get_editor_issues(), log any items through GBLogger, and consider validation successful when the issues list is empty.

Extending the Plugin

Add new placeable logic by:

1. Creating a new Placeable resource referencing display & behavior settings.
2. Adding any custom PlacementRule resources to its rule list.
3. Optionally implementing a specialized indicator scene if visual differentiation is needed.

Add new validation by subclassing PlacementRule or TileCheckRule and ensuring your rule:

• Exposes exported properties for tuning.
• Implements a deterministic validate() / tile filtering contract.

Debugging & Logging

GBLogger routes messages according to GBDebugSettings.level (ERROR, WARNING, DEBUG, VERBOSE). Verbose logs include injector traces and indicator setup summaries—enable during integration, disable for production builds.

Testing Support

GdUnit test suites cover:

• Placement rule combinations
• Indicator mapping correctness
• Manipulation flows
• Integration workflows (complex build scenarios)

Factories (e.g., UnifiedTestFactory) create injectors + containers quickly, while reports (like IndicatorSetupReport) augment assertion contexts.

Additionally, the development project includes premade testing environments (scenes) to spin up common setups quickly. These scenes establish combinations of core nodes such as GBSystem nodes, the positioner stack, GBLevelContext, and GBOwner, so you can run focused tests without manual scene assembly.

---

Support / Purchase Hub: Linktree – All Grid Builder Links