Grid Placement

GridPlacement GDScript 5.1 – GdUnit Test Selection (Keep vs Delete)

Scope: GDScript 5.0 / 5.1 GdUnit suites under the legacy grid_building addon. Goal: define a small curated test slice to keep for 5.1 and mark the rest as safe to delete in favor of C# coverage.

This file should be read together with the canonical mapping:

  • gdscript/grid_placement/test/docs/LEGACY_GDSCRIPT_GDUNIT_MIGRATION.md
    (source of truth for all legacy GdUnit suites, IDs, and C# migration status.)

1. Scoring & Policy

  • Score meaning (1–10)

    • 9–10 – Critical coverage for 5.1 demo/plugin, low maintenance.
      → Keep as part of the curated 5.1 slice.
    • 7–8 – Useful but redundant with C# coverage or heavy harness.
      → Prefer Delete, rely on C# tests.
    • ≤6 – Overly complex, infra-heavy, or superseded.
      → Delete (or keep only as historical docs in the mapping file).

  • Default rule

    • If a suite is marked Ported / Replaced / Removed / Won’tPort in the migration table,
      it is treated as ≤8 for 5.1 and is a Delete candidate from the GDScript tree.
    • Only a small set of NotStarted unit suites is kept for 5.1 as pure GDScript smoke tests.

2. KEEP – Curated 5.1 GDScript GdUnit Slice

These suites are worth keeping as 5.1-era GDScript tests: they exercise key grid/placement/collision behaviors in the actual legacy addon without requiring the newer C# harness.

Paths are relative to the legacy addon root: res://addons/grid_building/test/grid_building/.

  • Targeting / Positioning

    • systems/grid_targeting/unit/handlers/grid_positioner_unit_test.gd
      • Score: 9/10 – Core tile-center positioning behaviour; thin enough to maintain.
    • systems/grid_targeting/unit/handlers/targeting_shape_cast_2d_unit_test.gd
      • Score: 8.5/10 – Validates TargetingShapeCast2D API behaviour in a GDScript context.

  • Manipulation core state

    • systems/manipulation/unit/manipulation_data_unit_test.gd
      • Score: 8.5/10 – Core data object behaviour for manipulation, cheap to keep.
    • systems/manipulation/unit/manipulation_state_unit_test.gd
      • Score: 8.5/10 – State transitions at the GDScript level, complements C#.
    • systems/manipulation/unit/manipulation_state_machine_unit_test.gd
      • Score: 9/10 – State machine wiring; high leverage for catching regressions in legacy flows.

  • Placement rules

    • systems/placement/unit/validators/placement_rules/validation/tile map_bounds_rule_unit_test.gd
      • Score: 9/10 – Directly guards tile map bounds behaviour in legacy addon.
    • systems/placement/unit/validators/placement_rules/validation/rule_system_integration_tests.gd
      • Score: 8.5/10 – Consolidated rule-system behaviour; still valuable as a 5.1 smoke.

  • Collision / Tile map specifics

    • shared/utils/collision/detection/building_env_box_collision_test.gd
      • Score: 8.5/10 – Environment box collision behaviour in a Godot scene context.
    • shared/utils/collision/detection/shape_collision_validation_tests.gd
      • Score: 9/10 – Shape collision validation scenarios that are hard to fully express in pure C#.
    • shared/utils/collision/detection/tile map_transform_offset_unit_test.gd
      • Score: 9/10 – Tile map transform/offset behaviour that is specific to the GDScript addon.

These suites form the recommended curated 5.1 GdUnit slice. When you touch 5.1, run these first.

3. DELETE – Suites Safe to Remove from 5.1 GDScript Tree

The following buckets are safe to delete from the legacy GdUnit tree for the 5.1 line:

  • All suites with Status = Ported in LEGACY_GDSCRIPT_GDUNIT_MIGRATION

    • Example IDs (non-exhaustive): 1, 5, 6, 7, 8, 10, 11, 13, 17, 24, 27, 28, 29, 30, 32, 33, 34, 57, 61, 65, 72, 76, 79, 80.
    • Rationale: behaviour is already covered by C# Core / Godot tests; keeping GDScript copies adds cost without adding new information.

  • All suites with Status = Replaced

    • Example IDs: 14, 15, 18, 19, 20, 21, 22, 23, 26, 31, 59, 67, 73.
    • Rationale: new C# tests or structures now cover the same or better behaviour.

  • All suites with Status = Won'tPort or Removed

    • Example IDs: 2, 3, 4, 9, 12, 16, 25, 39, 55, 56, 62, 63, 64, 69, 70, 71, 74, 75.
    • Rationale: explicitly marked as too heavy, obsolete, or superseded; should not consume maintenance budget in the 5.1 track.

  • Most NotStarted suites not listed in the KEEP section

    • Example IDs: 35, 36, 37? (if you decide not to keep it), 40–48, 49–54, 58, 60, 66, 68, 77?, 78? etc.
      See the migration table for the exact list.
    • Rationale: large consolidated integrations, regressions, or performance harnesses that are better expressed as C# tests + manual QA.

Implementation note: When cleaning up, use the migration mapping as the authoritative index: for each row where the suite is not in the KEEP section above, you can safely delete the corresponding .gd file from the addon test tree.

4. How to Use This File

  • When deciding whether to fix a breaking GdUnit suite in 5.1:

    • If it is in the KEEP list above → fix it (or adjust slightly) so it stays green.
    • If it is not in the KEEP list → strongly prefer deleting the suite instead of fixing it.

  • When adding new 5.1 tests (rare):

    • Prefer small, focused unit/smoke tests that match the style of the KEEP list.
    • Avoid new large integration harnesses in GDScript; put that energy into C# tests instead.

This keeps the 5.1 GDScript test surface small, understandable, and cheap to maintain, while leaning on C# 6.0+ as the canonical source of truth for detailed behaviour.

5. 5.1 GDScript Coding & Test Style

  • Strong typing

    • Treat all lint warnings as errors for the curated 5.1 slice.
    • Always add explicit types for variables, parameters, return values, and for iterators.
    • Prefer plain Resource / data types in helpers; keep Godot nodes at the edge.

  • Small, deterministic tests

    • Each test should validate one behaviour with clear Arrange/Act/Assert blocks.
    • Avoid global state, singletons, and random timers inside tests.
    • Prefer pure functions and small helpers that are easy to mirror in C#.

  • Godot shell vs. core logic

    • Keep scene/node setup in thin helpers; move calculations into plain scripts.
    • When you find heavy logic inside a node, extract it into a reusable utility.
    • Design those utilities so the same API can exist in C# later.

  • Helpers and fixtures

    • Shared helpers must be strongly typed and side-effect-minimal.
    • Delete brittle or over-generic helpers instead of layering more conditionals.
    • Prefer explicit test builders (e.g. for grids/environments) over magic constants.

  • Naming and global classes

    • Avoid class_name collisions with engine or addon globals.
    • Use clear prefixes like GB... for 5.1 helper classes and facades.
    • Keep test names descriptive of behaviour, not implementation details.

  • User / owner terminology

    • When adding or updating tests that deal with per-user state or ownership, prefer the user/scope naming used in 6.0.
    • Use GBUser / GBUserScope in test names and comments rather than only referring to “owner” where practical.
    • For C# mirrors, see the Owner & Contexts section in plugins/gameplay/GridPlacement/docs/6.0/Core/GRIDBUILDING_CLASS_MAPPING.md for the 5.0/5.1 → 6.0 mapping (UserId/IUserScope/IGridBuildingSession).

  • Backport awareness

    • When adding or updating tests, ask what is the C# mirror?.
    • Prefer patterns that can be ported 1:1 into C# xUnit tests.
    • If a test cannot be reasonably mirrored, consider whether it belongs in 5.1 at all.

6. Module Seams and C# Backport Map

The curated KEEP slice aligns to a small set of logical seams:

  • Grid targeting handlers

    • GDScript: systems/grid_targeting/unit/handlers/*_unit_test.gd
    • Seam: pure grid math + selection utilities separate from Godot nodes.
    • C# target: GridPlacement.Core.Targeting.GridTargeter, shape-cast helpers.

  • Manipulation data and state

    • GDScript: systems/manipulation/unit/*_unit_test.gd
    • Seam: immutable data + state transitions, no direct scene access.
    • C# target: GridPlacement.Core.Manipulation.* data/state classes.

  • Placement rules / validators

    • GDScript: systems/placement/unit/validators/placement_rules/validation/*.gd
    • Seam: rule evaluation on pure structs (positions, areas, tile bounds).
    • C# target: GridPlacement.Core.Placement.Rules.* validators and rule system.

  • Collision and tilemap utilities

    • GDScript: shared/utils/collision/detection/* tests in KEEP list.
    • Seam: collision math + shape/rect transforms separate from TileMap APIs.
    • C# target: GridPlacement.Core.Collision.* + helper math modules.

  • Environment / world helpers (5.1-only)

    • GDScript: small loaders like environment_loading_unit_test.gd.
    • Seam: thin Godot shell around reusable environment descriptors.
    • C# target: optional; prefer keeping as Godot-only glue if not reused.

When refactoring 5.1 GDScript, prefer extracting logic at these seams so the same contracts can later be implemented and tested in C# with minimal drift.

Legacy test pruning (keep/drop)

  • Decisions and scores: demos/grid_building_dev/docs/LEGACY_TEST_KEEP_DROP_5_1.md