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:

  1. Add Addon

    • Ensure grid_building addon is enabled in Project Settings

  2. Create Core Systems

    • Add a Systems node to your scene root
    • Add InjectorSystem as child with gb_injector_system.gd script
    • Add BuildingSystem as child with building_system.gd script
    • Add GridTargetingSystem as child with grid_targeting_system.gd script

  3. Add Grid Positioner

    • Add GridPositioner node to your world
    • Instance appropriate template:
      • Top-down: grid_positioner_stack.tscn
      • Isometric: grid_positioner_stack_isometric.tscn
    • See Grid Positioner Setup for detailed configuration

  4. Set Up Level Context (CRITICAL)

    • Add LevelContext node to your level scene
    • Wire target_map to your TileMapLayer
    • Set objects_parent to where buildings should spawn
    • ⚠️ ESSENTIAL: Systems will NOT run without properly configured LevelContext
    • See Level Context Integration for detailed setup

  5. Add Owner Context

    • Add Owner node to your camera or player
    • Set owner_root to point to your world node

  6. Create Basic UI

    • Add UI → HUD hierarchy
    • Instance placeable_selection_ui.tscn for building selection
    • Add action_bar.tscn for main controls
    • See UI Templates and Setup for detailed UI configuration

  7. Configure Composition Container

    • Create a GBCompositionContainer resource using the Inspector
    • Assign it to your InjectorSystem via the Inspector
    • Manually create and assign each sub-resource (no automatic assignment)
    • Save each resource immediately to prevent data loss
    • Configure build rules and settings using the Inspector (not script preloading)
    • See Composition Container Configuration for detailed setup
    • Critical: Manual assignment required for all sub-resources, save frequently

  8. Set Up Input Actions

    • Add build_confirm and build_cancel actions in Input Map
    • Configure key bindings for building controls

GBCompositionContainer Configuration

The GBCompositionContainer is the central configuration hub that organizes all sub-resources for the system. Each sub-resource controls a specific aspect of the building system.

For comprehensive configuration details, see Composition Container Configuration.

Container Structure

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

Individual Sub-Resources

1. GBSettings (Main Settings Container)

  • building: Core building/placement parameters
    • Grid size, placement validation, building rules
    • Cost requirements, resource management
  • manipulation: Object movement and editing settings
    • Drag sensitivity, snap settings, manipulation modes
  • targeting: Grid targeting and selection behavior
    • Target range, selection shape, collision layers
  • visual: UI and visual feedback settings
    • Cursor styles, highlight colors, target information display
  • action_log: Logging system configuration
    • Message filtering, log duration, display settings
  • placement_rules: Array of placement validation rules
    • Custom rules for where objects can be placed
  • runtime_checks: System validation flags
    • Debug checks, performance monitoring
  • debug: Debugging and development settings
    • Log levels, debug overlays, testing flags

2. GBTemplates (System Templates)

  • System templates: Pre-configured system stacks
  • UI templates: User interface component templates
  • Indicator templates: Visual feedback elements
  • Grid positioner templates: Different grid configurations

3. GBActions (Input Configuration)

  • Action mappings: Input action definitions
  • Key bindings: Default keyboard/mouse mappings
  • Gesture settings: Touch and gesture controls

Configuration Process

  1. Create Base Resources

    Create GBCompositionContainer resource
├── Create GBConfig resource
├── Create GBSettings resource
├── Create individual setting resources
└── Create GBTemplates and GBActions resources

  2. Assign Settings

    • Wire each individual settings resource to its parent
    • Example: building_settings.tres → GBSettings.building
    • All settings are shared resources - changes propagate automatically

  3. Configure Rules

    • Add PlacementRule resources to GBSettings.placement_rules
    • Rules validate placement conditions (terrain, cost, etc.)

  4. Set Up Templates

    • Assign template scenes to GBTemplates
    • Templates define UI components and system prefabs

  5. Configure Actions

    • Define input actions in GBActions
    • Map to Godot Input Map actions

Resource Assignment Example

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# In your composition container resource:
config = preload("res://settings/my_config.tres")

# In your config resource:
settings = preload("res://settings/my_settings.tres")
templates = preload("res://settings/my_templates.tres")
actions = preload("res://settings/my_actions.tres")

# In your settings resource:
building = preload("res://settings/building_settings.tres")
manipulation = preload("res://settings/manipulation_settings.tres")
targeting = preload("res://settings/targeting_settings.tres")
# ... and so on for each setting type

Shared Resource Behavior

  • All settings resources are shared Godot Resources
  • Changes to any setting resource immediately affect all systems
  • No need to restart or reload - changes propagate live
  • Enable resource_local_to_scene = true for scene-specific instances

Validation

The composition container automatically validates:

  • All required sub-resources are present
  • Settings are properly configured
  • Templates and actions are valid
  • Runtime dependencies are satisfied

Use composition_container.get_runtime_issues() to check configuration status.

Required Core Systems

Create a Systems node in your scene root with the following child nodes:

1. InjectorSystem

  • Type: Node
  • Script: /systems/injection/gb_injector_system.gd
  • Purpose: Dependency injection and composition container setup
  • Properties: Set composition_container to your composition resource

2. BuildingSystem

  • Type: Node
  • Script: /systems/building/building_system.gd
  • Purpose: Core building and placement logic
  • Children:
    • DragManager (Node) - /systems/building/managers/drag_manager.gd

3. GridTargetingSystem

  • Type: Node
  • Script: /systems/grid_targeting/grid_targeting_system.gd
  • Purpose: Grid targeting and selection logic
  • Note: This node is no longer needed starting in v5.1 and can be removed in newer versions

4. ManipulationSystem

  • Type: Node with manipulation components
  • Purpose: Object manipulation and editing
  • Children:
    • TargetHighlighter - Visual feedback for targets
    • ModeCursors - Cursor management for different modes
  • Setup: Create a Node with manipulation script and add highlighter/cursor children

5. SaveLoadSystem (Optional)

  • Type: Node
  • Purpose: Save/load functionality
  • Setup: Create your own save/load system or integrate with existing game state management
  • Integration: Connect to world state and player state resources as needed

6. AudioSystem (Optional)

  • Type: Node
  • Purpose: Audio system for building actions
  • Setup: Create your own audio system or integrate with existing game audio

World Setup

Create a World node (typically Node2D) with:

1. GridPositioner

  • Type: Instance of appropriate grid positioner template
    • Isometric: /templates/grid_positioner/grid_positioner_stack_isometric.tscn
    • Top-down: /templates/grid_positioner/grid_positioner_stack.tscn
  • Purpose: Grid positioning and coordinate system
  • Core 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`
  • GridTargetingSystem: Separate node in Systems hierarchy (not part of GridPositioner stack)
  • For detailed setup and configuration, see Grid Positioner Setup.

2. LevelContext (Required for TileMap integration)

  • Type: Node
  • Script: /shared/components/context/gb_level_context.gd
  • Purpose: Provides level-specific context for TileMapLayers and object placement
  • Properties:
    • target_map: Primary TileMapLayer for grid targeting
    • maps: Array of all TileMapLayers in the level
    • objects_parent: Node2D where placed objects are parented
  • Setup: Add to your level scene and wire to your TileMapLayers
  • Example:
    YourLevel (Node2D)
├── Ground (TileMapLayer) ← target_map and maps[0]
├── Objects (Node2D) ← objects_parent (add "placed_parent" group)
└── LevelContext (Node)
    ├── target_map: NodePath("../Ground")
    ├── maps: [NodePath("../Ground")]
    └── objects_parent: NodePath("../Objects")
  • For detailed integration examples, see Level Context Integration.

3. Owner (Required for camera systems)

  • Type: Node
  • Script: /core/contexts/gb_owner.gd
  • Parent: Usually child of camera controller
  • Properties: Set owner_root to point to the World node

UI Setup

Create a UI → HUD hierarchy with these components:

Essential UI Elements

  • PlaceableSelectionUI: Building selection interface
  • ControlsTileInfoTabs: Grid information and controls
  • ActionLog: Action logging and feedback
  • ActionBar: Main action buttons

Optional UI Elements

  • TargetInformer: Target information display
  • SaveLoadContainer: Save/load interface
  • CameraZoomSlider: Camera zoom controls
  • RuntimeAnalyzer: Debug and analysis tool

Setup Order

  1. Create Systems node with all system components
  2. Create World node with GridPositioner
  3. Add Owner to camera hierarchy
  4. Create UI/HUD with essential interface elements
  5. Configure composition container in InjectorSystem
  6. Set up state resources (world_state, player_state) for save/load functionality

Configuration Resources

You’ll need to create these resource files:

  • Composition container resource (defines system dependencies)
  • World state resource (persistent world data)
  • Player state resource (player-specific data)
  • Save settings resource (save/load configuration)

Version-Specific Notes

v5.0 Requirements

  • GridTargetingSystem is required for proper targeting functionality
  • All systems must be properly configured in the composition container
  • State resources are required for save/load functionality

v5.1+ Changes

  • GridTargetingSystem is no longer needed - targeting functionality was integrated into other systems
  • Simplified setup process with fewer required nodes
  • Improved dependency injection reduces manual configuration

Common Setup Patterns

Isometric Games

  • Use grid_positioner_stack_isometric.tscn
  • Configure camera controller for isometric view
  • Set up appropriate tile mapping for isometric grids

Platformer Games

  • Use grid_positioner_stack.tscn
  • Configure grid to match platformer tile size
  • Integrate with character movement systems

Top-Down Games

  • Use standard grid positioner
  • Configure camera for overhead view
  • Set up UI for grid-based controls