GridPlacement 6.0 (formerly GridBuilding)
Development ⚠️ GridPlacement 6.0 documentation is in active development. APIs and content may change, and the site may be temporarily unstable.

Test Preload Policy (res:// vs uid://)

Overview

This guide documents the preload policy for GridBuilding 5.1 GDScript tests and GridPlacement 6.0+ tests.

  • Tests must not use preload("uid://...") in .gd files.
  • Tests must instead preload resources via res:// paths, with all reusable resources centralized in shared helpers.
  • Demo projects should consume the same helpers via the exported addon; they are not the canonical source.

Canonical Test Helpers

GridBuilding (5.1 GDScript)

  • Location: plugins/gameplay/GridPlacement/gdscript/grid_building/test/grid_building/helpers/
  • Helpers:
    • GBTestConstants.gd – preloaded test scenes, placeables, rules, and data resources.
    • GBTestPreloads.gd – preloaded test components (managers, handlers, utilities, factories, helpers).
  • All preload("uid://...") entries have been replaced with preload("res://...") for these helpers.

GridPlacement (6.0+ GDScript layer)

  • Canonical plugin folder: plugins/gameplay/GridPlacement/gdscript/grid_placement/
  • Test helpers (mirroring GridBuilding):
    • test/grid_building/helpers/GBTestConstants.gd
    • test/grid_building/helpers/GBTestPreloads.gd
  • These helpers preload only by res:// into the core addons/grid_building/... scripts and test resources.

No UID Preloads in Test Scripts

When writing or updating tests:

  • Do:
    • Use GBTestConstants for shared scenes/resources, e.g.
      • scene_runner(GBTestConstants.BUILDING_TEST_ENV.resource_path)
    • Use GBTestPreloads for shared components, e.g.
      • const FlipManager = GBTestPreloads.FLIP_MANAGER
    • Preload one-off helpers via res:// paths if they are not generally reusable.
  • Do not:
    • Call preload("uid://...") or load("uid://...") directly inside test scripts.
    • Add new UID-only constants to helpers; always map to a concrete res:// file.

Canonical vs Demo Addons

  • Canonical source:
    • GridBuilding: plugins/gameplay/GridPlacement/gdscript/grid_building/
    • GridPlacement GDScript: plugins/gameplay/GridPlacement/gdscript/grid_placement/
  • Demo addon: demos/grid_building_dev/godot/addons/grid_building/

Rules:

  • Make all fixes and new preloads in the canonical plugin folders first.
  • Export or copy the updated addon to the demo project as a separate step.
  • Never treat the demo addon as authoritative; it should mirror the plugin, not diverge.

Runtime vs Test Preloads

  • Runtime resources (e.g. .tscn and .tres headers) may still use UIDs as managed by the Godot editor.
  • Test scripts and helpers must use res:// paths for stability across machines and editor reimports.

Following this policy keeps the test suite resilient to UID cache corruption, simplifies migrations, and clearly separates canonical plugin code from demo wiring.