Grid Placement

GridBuilding 5.0 → 5.1 Node & Resource API Compatibility

Scope

  • Plugins: GridBuilding 5.0 / 5.1 GDScript line.
  • Surfaces covered:
    • Godot scenes under addons/grid_building/templates/** used by demos.
    • Core resource configs under addons/grid_building/templates/resources/**.
  • Goal: 5.1 must not break the public node/resource surface exposed to 5.0 projects; only internals and backend components may change.

Contract: Scenes (Nodes)

For each scene below, 5.1 must preserve:

  • Root node name and type.
  • Presence of documented child nodes (by path).
  • Script class bound to the root (where applicable).
  • Exported properties that user code or tests rely on.

1. Rule Check Indicator 16×16

  • Path:
    • res://addons/grid_building/templates/indicator/rule_check_indicator_16x16.tscn
  • Root:
    • Name: "RuleCheckIndicator_16x16"
    • Type: ShapeCast2D
    • Script: RuleCheckIndicator
  • Required children:
    • "ValiditySprite2D" (Sprite2D)
  • Key properties on root:
    • validity_sprite : Sprite2D
    • valid_settings : IndicatorVisualSettings
    • invalid_settings : IndicatorVisualSettings

2. Rule Check Indicator Isometric

  • Path:
    • res://addons/grid_building/templates/indicator/rule_check_indicator_isometric.tscn
  • Root:
    • Name: "RuleCheckIndicatorIsometric"
    • Type: ShapeCast2D
    • Script: RuleCheckIndicator
  • Required children:
    • "Sprite2D" (Sprite2D) for visual overlay.

3. Grid Targeter

  • Path:
    • res://addons/grid_building/templates/grid_positioner/components/grid_targeter.tscn
  • Root:
    • Name: "GridTargeter"
    • Type: AnimatedSprite2D
  • Key behavior contract:
    • Animated frames represent targeting cursor; API consumers rely on the node name and type, not on exact frame layout.

4. Action Bar

  • Path:
    • res://addons/grid_building/templates/ui/action_bar.tscn
  • Root:
    • Name: "GBActionBar"
    • Type: PanelContainer
  • Required children:
    • "MarginContainer/HBoxContainer/InfoModeButton"
    • "MarginContainer/HBoxContainer/BuildingModeButton"
    • "MarginContainer/HBoxContainer/MovingModeButton"
    • "MarginContainer/HBoxContainer/DemolishModeButton"
  • Behavior expectations:
    • Four mode buttons exist with stable node names so tests and input wiring by path continue to work.

Contract: Resources (.tres)

These resources must continue to load and expose the expected roles; internal script implementations may evolve.

5. Top-down Placement Config

  • Path:
    • res://addons/grid_building/templates/resources/top_down/td_config.tres
  • Contract:
    • Resource loads without error.
    • Provides top-down placement settings used by templates and tests.
    • Texture/icon references use res:// paths (UID-free, path-first).

6. Isometric Placement Config

  • Path:
    • res://addons/grid_building/templates/resources/isometric/config.tres
  • Contract:
    • Resource loads without error.
    • Provides isometric placement/indicator settings; callers treat it as a configuration resource, not an API object.

7. Theme & Indicator Resources

  • Examples:
    • templates/resources/themes/grid_builder_warm_earth_theme.tres
    • Indicator texture configs under systems/placement/utilities/rule_check_indicator/**
  • Contract:
    • Resources load without UID warnings (path-first).
    • Exposed properties such as texture, modulate remain available for existing tests and scenes.

Allowed Changes (5.1 Internals)

The following changes are allowed, provided the contracts above hold:

  • Extracting heavy logic from Nodes into RefCounted backend components (e.g., collision mappers, rule evaluators, state calculators).
  • Changing internal scene wiring as long as:
    • Root node name/type and documented children stay the same.
    • Publicly relied-on exported properties and signals stay compatible.
  • Replacing UID-based resource references with res:// paths.
  • Adding new optional properties that have safe, backwards-compatible defaults.

Disallowed Changes (Breaking 5.0 Compatibility)

The following are not allowed in 5.1 without a deliberate breaking-change plan:

  • Renaming root nodes or changing their Godot type.
  • Removing or renaming documented child nodes relied on by tests or user code (e.g., InfoModeButton).
  • Renaming or removing exported properties that existing tests use (e.g., valid_settings, invalid_settings).
  • Changing resource file roles (e.g., repurposing td_config.tres to a different config type).
  • Introducing hard UID dependencies for resources where 5.0 used paths.

Candidate Backend Components (RefCounted)

These areas are good candidates for extraction into RefCounted backends while keeping the node/resource API intact:

  • Collision mapping backend
    • Encapsulate tile mapping logic currently on CollisionMapper and related helpers.
  • Rule Check Indicator backend
    • Extract validity evaluation and sprite selection into a service that RuleCheckIndicator delegates to.
  • Placement rule evaluation
    • Move rule evaluation and constraint checking into a pure backend that scenes call into.

Each extracted component should:

  • Be RefCounted (non-Node) and unit-testable in isolation.
  • Be constructed or injected by existing nodes without changing node names, types, or exported properties.