Architecture overview (5.0)

Mental model for GridBuilding 5.0: node-first integration, injector/container era, and state-first wiring.

Quick Start Guide

Get up and running with GridBuilding v5.0 in minutes

Manipulation Workflow

Why 5.0 splits manipulation into ManipulationSystem (logic) and ManipulationParent (visual transforms).

Targeting Workflow

How 5.0 targeting and preview nodes interact, and what typically causes previews to clear unexpectedly.

Test Title Behavior

Testing title and header behavior

Composition Container Configuration (v5.0)

The GBCompositionContainer is the central configuration hub for GridBuilding v5.0, organizing all sub-resources and providing dependency injection for the building system.

For a complete setup overview, see Getting Started Setup.

Overview

The composition container follows a hierarchical resource structure where each sub-resource controls a specific aspect of the building system. This design allows for modular configuration and live updates without system restarts.

Resource Hierarchy

GBCompositionContainer (Resource)
├── config: GBConfig
│   ├── settings: GBSettings
│   │   ├── building: BuildingSettings
│   │   ├── manipulation: ManipulationSettings  
│   │   ├── targeting: GridTargetingSettings
│   │   ├── visual: GBVisualSettings
│   │   ├── action_log: ActionLogSettings
│   │   ├── placement_rules: Array[PlacementRule]
│   │   ├── runtime_checks: GBRuntimeChecks
│   │   └── debug: GBDebugSettings
│   ├── templates: GBTemplates
│   └── actions: GBActions

Creating Resources (Editor-Based Approach)

Important: For v5.0, resource assignment must be done manually in the Godot Editor Inspector. There is no automatic assignment of resources. You must manually create and assign each sub-resource. Save frequently to prevent data loss.

GridBuilding 5.0 Documentation Score

Scoring Rubric (100 points total)

Core Content (40 points)

• Getting Started Guide (10 points): Complete setup from zero to working system
• Architecture Overview (8 points): Clear understanding of system design and patterns
• Configuration Guide (8 points): Detailed resource and settings setup
• Integration Examples (7 points): Practical implementation scenarios
• API Reference (7 points): Complete method/property documentation

User Experience (25 points)

• Troubleshooting Guide (8 points): Common issues and solutions
• FAQ Section (6 points): Frequently asked questions
• Error Handling (6 points): Debugging and validation guidance
• Best Practices (5 points): Recommended patterns and approaches

Technical Accuracy (20 points)

• Code Examples (8 points): Working, tested code snippets
• Version Accuracy (6 points): Correct 5.0-specific information
• Cross-References (6 points): Proper linking between guides

Accessibility (15 points)

• Clear Structure (5 points): Logical organization and navigation
• Visual Aids (5 points): Diagrams, screenshots, examples
• Searchability (5 points): Easy to find specific information

Current Documentation Evaluation

✅ Strengths (High Scores)

Getting Started Guide (9/10)

Getting Started Setup (v5.0.0)

This guide covers the essential node setup for v5.0.0.

Note: 5.0 is the stable line. If you are starting a new project, you may also consider:

• v5-1 (Upcoming feature release)
• v6-0 (C# Edition - Complete architectural redesign)

v5.0.0 (GDScript)

• Canonical name (5.0): / GB
• Canonical addon path (Godot):

Template Locations (v5.0.0)

All templates are located in /templates/:

Core System Templates

• Systems: templates/systems/
  • gb_systems.tscn - Complete systems stack
  • gb_systems_isometric.tscn - Isometric-specific systems

Grid Positioner Templates

• Grid Positioners: templates/grid_positioner/
  • grid_positioner_stack.tscn - Standard top-down grid
  • grid_positioner_stack_isometric.tscn - Isometric grid
  • components/ - Individual grid components

UI Templates

• User Interface: templates/ui/
  • action_bar.tscn - Main action buttons
  • action_log/action_log.tscn - Action feedback display
  • placement_selection/placeable_selection_ui.tscn - Building selector
  • target_informer.tscn - Target information display

Indicator Templates

• Visual Indicators: templates/indicator/
  • Various rule check indicators for different grid types
  • Collision shapes and visual feedback elements

Quick Start Setup

Follow these numbered steps for a minimal v5.0.0 setup:

Grid Positioner Setup (v5.0)

The GridPositioner is the core component that handles grid positioning, targeting, and coordinate system management for v5.0.0.

For a complete setup overview, see Getting Started Setup.

Overview

The GridPositioner manages the spatial relationship between world coordinates and grid coordinates, providing the foundation for all building and targeting operations.

Template Types

Standard Grid Positioner

• File: grid_positioner_stack.tscn
• Use Case: Top-down games, standard rectangular grids
• Coordinate System: 2D Cartesian coordinates

Isometric Grid Positioner

• File: grid_positioner_stack_isometric.tscn
• Use Case: Isometric games, diamond-shaped grids
• Coordinate System: Transformed isometric coordinates

Node Hierarchy

GridPositioner2D (Node2D) - Main positioning controller
├── TargetingShapeCast2D (ShapeCast2D)
│   ├── Shape: RectangleShape2D or custom indicator shape
│   ├── Script: targeting_shape_cast_2d.gd
│   └── Collision mask: 2048 (for grid detection)
└── ManipulationParent (Node2D)
    ├── Script: manipulation_parent.gd
    └── IndicatorManager (Node2D)
        └── Script: indicator_manager.gd

Note: GridTargetingSystem is a separate system node that lives in the Systems hierarchy, not as part of the GridPositioner stack.

Level Context Integration (v5.0)

The GBLevelContext provides the essential bridge between systems and your game’s level structure, managing TileMapLayers, object placement, and spatial context.

⚠️ CRITICAL: Without a properly configured LevelContext node, systems will NOT run. The LevelContext is required for all targeting and placement operations.

For a complete setup overview, see Getting Started Setup.

Overview

GBLevelContext is responsible for:

• Providing TileMapLayer references to targeting systems
• Managing the objects parent for placed buildings
• Supplying spatial context for grid operations

Core Properties

Required Properties

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

class_name GBLevelContext
extends GBGameNode

## The TileMapLayer to use as the tile selection target
@export var target_map: TileMapLayer

## All maps in the game level
@export var maps: Array[TileMapLayer]

## Where objects should be placed in the scene hierarchy  
@export var objects_parent: Node2D

Simple Setup Process

1. Create Level Context Node

Add a GBLevelContext node to your level scene:

UI Templates and Setup (v5.0)

v5.0 provides a comprehensive set of UI templates for building interfaces, selection systems, and user feedback. This guide covers template setup, customization, and integration using the drag-and-drop editor first approach.

For a complete setup overview, see Getting Started Setup.

Editor-First Approach

🎯 Primary Method: Drag and drop .tscn scenes directly into your game’s HUD/UI stack, then configure settings in the Inspector rather than through script.

Benefits of Editor-First Approach:

Troubleshooting & FAQ (5.0)

Comprehensive troubleshooting guide and FAQ for GridBuilding 5.0

Validation & Debugging (5.0)

Validation tools, debugging options, and error handling for GridBuilding 5.0