v5.0 Guides

Version: 5.0.8 (Maintenance Stable) Last Updated: May 14, 2026

This directory contains the official user guides for Grid Building 5.0.8. These guides were ported from the online documentation and updated for 5.0.8 validity.

Guide Index

Getting Started

| Guide | Description | | ***– | *********– | | Getting Started | Minimum install path, scene wiring, and first successful placement. Start here if you are new to the plugin. | | Architecture Overview | High-level architecture and how the core systems fit together. | | Composition & Injection | Dependency wiring, composition containers, and scene setup patterns. |

Core Workflows

| Guide | Description | | ***– | *********– | | Placement Workflow | End-to-end node-centric placement flow: build entry, validation, commit. | | Capturing Tile Positions | How to capture and store Vector2i tile coordinates for placed objects, occupancy, and pathfinding. | | Targeting Flow | How targeting works: positioner, shapecast, targeting state, and highlighting. | | Manipulation: System vs Parent | Move, rotate, and flip: understanding the system/parent split. |

Rules & Validation

| Guide | Description | | ***– | *********– | | Placement Rules | Runtime placement validation, built-in rules, and custom rule authoring. | | Custom Placement Rules | Godot 4.4-compatible patterns for defining your own rules, setup issues, diagnostics, and indicator behavior. | | Validation: Configuration | Configuration validation at startup and runtime readiness checks. |

Persistence & Export

| Guide | Description | | ***– | *********– | | Save and Load | Persisting placed objects across game sessions. | | Web Export Guide | Web export requirements, resource loading, and troubleshooting. |

Troubleshooting

| Guide | Description | | ***– | *********– | | Troubleshooting | Common issues, 5.0.8-specific fixes, and general debugging steps. |

Quick Reference

Essential Integration Checklist

  • GBInjectorSystem.composition_container is assigned.
  • GBLevelContext.target_map and objects_parent are assigned.
  • GBOwner.owner_root is assigned.
  • Default input actions are loaded (Project → Tools → Grid Placement / Setup Default Input Actions).
  • Base placement_rules reference external .tres files (not embedded subresources).
  • Collision shapes are set up for placeable scenes.

5.0.8 Highlights

  • TileCheckRule.get_runtime_issues() bug fix — custom rules that override get_runtime_issues() now work correctly with indicator display. Order-of-operations bug fixed: call super.get_runtime_issues() BEFORE appending custom issues.
  • Console warning spam removed — placeable.gd no longer pushes warnings for null packed_scene or null placement rule entries.
  • Indicator fallback fix — custom tile rules with validate_placement() but no get_failing_indicators() override now correctly mark indicators invalid when placement fails.

5.0.5 Highlights

  • GBAssetResolver recursively scans sub folders — assets in nested directories are now discovered correctly.
  • Web export guide updated — documented that embedded SubResources fail on web; typed arrays and _init() work correctly on Godot 4.6.2.
  • 11 new GBAssetResolver tests — recursive sub folder scanning coverage for placeables, tags, and sequences.

5.0.4 Highlights

  • Web exports now work — placement rules, resources, and indicators load correctly in exported builds.
  • Manipulation system fully stabilized — no more crashes from stale state, deleted sources, or rapid interactions.
  • Templates work out-of-the-box — collision layers and resource references are project-agnostic.
  • New pre_instance_added signal — configure placed objects before _ready() runs.
  • 1772 tests passing — full regression coverage across 198 test suites.

See Patch Notes for the complete changelog.

For 5.0.3 Users

If you are upgrading from 5.0.3:

  1. Read the Patch Notes for the full list of changes.
  2. Check Troubleshooting for fixes to issues you may have encountered in 5.0.3.
  3. Review Placement Rules for web export compatibility best practices.