Plugin Overview

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.

Note

Minimum supported Godot version: 4.4+. Also supports 4.5.

🎯 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
• 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

🔧 System Improvements

• Enhanced Validation: Validation results are exposed via ValidationResults and per‑class issue getters (e.g. get_runtime_issues() / get_editor_issues()), rather than returning Array[String] from validate()
• 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	Builds rule check indicators & reports diagnostics	Visual feedback system	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. Player enters build mode (ModeState / BuildingState).
2. Targeting state updates grid position under cursor each frame.
3. PlacementValidator assembles combined rules (global + placeable + contextual).
4. IndicatorManager maps rules to tiles → generates RuleCheckIndicator instances (colored / shaped feedback) and returns an IndicatorSetupReport.
5. User confirms placement → BuildingSystem spawns a persisted instance (usually via a Placeable template).
6. ManipulationSystem enables post‑placement adjustments (move, rotate, flip, demolish) while respecting 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.

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.

Tests run both headless in CI and interactively in the Godot editor to match real usage.

---

Last updated: 2025-09-07

---

Support / Purchase Hub: Linktree – All Grid Builder Links