Grid Placement

GridPlacement GDScript Roadmap (5.0 / 5.1 Track)

Scope: GDScript‑based GridBuilding 5.0 / 5.1 usage, including demo scenes and internal testing/docs. Time horizon: next legacy‑support cycle up until 6.0 C# GA. 5.0/5.1 GDScript is treated as a legacy‑stable line: only high‑value, pre‑agreed fixes and small improvements are allowed; no new large features or architectural rewrites. 6.0 is C#‑first and any future GDScript 6.0 support would be a direct translation of the 6.0 C# APIs, not a 5.1 → 6.0 GDScript in‑place upgrade.

6.0 GDScript is demand‑driven:

  • If we receive 10+ user requests (unique users) for a 6.0 GDScript port/adapter, we will take 6.0 GDScript support seriously and add it to the roadmap.
  • Otherwise, we will push the user base toward 6.0 C# for Godot projects (one primary language is easier to maintain and higher leverage).

This roadmap follows the /roadmap workflow: tasks are grouped by priority lane and ordered to land foundations (tests, infra, docs) before dependent work.

Canonical parity contract (6.0 ↔ 5.1): docs/Parity/PARITY_CONTRACT_6_0_TO_5_1.md

5.1 Port-forward policy (what is IN vs OUT)

Goal: keep 5.1 as a legacy-stable line while still allowing a small, high-leverage parity slice.

5.1 public integration contract (release constraint): 5.1’s supported stable surface is Node-first. The opt-in “advanced path” (adapter/service access) exists, but internal workflow/service class names are not guaranteed stable. Source of truth: docs/content/grid-placement/v5-1/guides/node-first-public-api.md.

Scoring intent:

  • 🔴 = parity-critical (Slice A contract)
  • 🟠 = allowed only if it directly supports Slice A and remains pure/deterministic
  • 🟡 = usually game-level responsibility (avoid in 5.1 plugin unless unavoidable)
  • 🟢 = keep out of 5.1 (push to 6.0 or host/game)

🔴 IN (port to 5.1; Slice A parity)

  1. Placement validation (bounds + collision/overlap + rule failure categories)
  2. Indicator decision mapping (valid/invalid → canonical indicator state)
  3. Footprint + rotation math (grid cell coverage invariants)
  4. Execution result categories (success/failure + stable coordinates/ids)

🟠 IN (only as minimal adapters/interfaces for Slice A)

  1. Read-only occupancy snapshot adapter (inputs for collision/overlap validation)
  2. Small rule evaluation hooks needed only to preserve stable “reason category” results
  3. Thin GBInjectorSystem wiring adapters that call internal pure logic modules

🟡 OUT (game-level responsibility; do not add to 5.1 plugin)

  1. Placeable catalog loading (config formats, inheritance resolution, conversion to Resources)
  2. Save/load serialization formats and persistence strategy
  3. Editor importers / authoring pipeline tooling

🟢 OUT (6.0 / host responsibility; explicitly not supported in 5.1 plugin)

  1. Headless JSON / asset loading pipeline (use 6.0 host + AssetLoader; 5.1 uses Godot JSON APIs)
  2. New composition framework / service container re-architecture (keep GBInjectorSystem)
  3. Cross-engine runtime abstractions and generalized integration frameworks
  4. Advanced async IO, streaming, caching subsystems
  5. Full user/session integration requirements (keep 5.1 “owner identity” concept only)

Strategy (required execution order for 5.1 work)

This roadmap is intentionally organized around this pipeline:

  1. Create / debug classes at 6.0 C# level
    • Core input routing (Option B) design captured.
    • Core input router + interpreters implemented (CoreInputService, CoreInputRoutingService, *InputInterpreter).
  2. Unit / Integration test at 6.0 C# level (authoritative behavior contract)
    • xUnit tests exist for routing order, gating, first-handler-wins (Core input service + router + interpreters).
    • Verified passing via:
      • dotnet test -c Release Tests/Core/GridBuilding.Core.Tests/GridBuilding.Core.Tests.csproj
  3. Port logic + class structure back to 5.1 GDScript (pure logic only)
    • Translate selected 6.0 Core behavior into 5.1 pure RefCounted modules (no Nodes, deterministic IO).
    • Keep 5.1 public-facing adapters 5.0-compatible (class_name, exports, signals) and keep .tscn/.tres compatibility as best as possible.
  4. Implement mirrored test cases in GDScript + sanity checks
    • Add small GdUnit tests that mirror the C# behavior contracts (keep harness-based; avoid heavy scenes).
  5. Final runtime verification
    • In-editor playtest + smoke scene verification for place/move/remove + indicators + basic manipulation.

Next steps (ordered, based on current state)

  1. C# contract tests (unblocks safe backports)
    • Input routing Core xUnit tests (order/gating/first-handler-wins).
    • Identify 1-2 additional “backportable” pure-logic targets in 6.0 Core and add tests first.
  2. Roadmap ↔ Node-first public API consistency gate (5.1 integration contract)
    • Confirm this roadmap does not imply a stable internal service/workflow API in 5.1.
    • Ensure public-facing 5.1 docs consistently describe Node-first as the supported stable surface.
    • Source of truth: docs/content/grid-placement/v5-1/guides/node-first-public-api.md.
  3. Public Hugo docs alignment pass (5.1) — release gate
    • Goal: ensure every Hugo-facing 5.1 page describes the same stability promises and does not accidentally imply stable internal service/workflow APIs.
    • Done when: all pages below are reviewed in one pass and any drift is fixed or explicitly called out.
    • Pages to review (Hugo content source):
      • docs/content/grid-placement/v5-1/_index.md
      • docs/content/grid-placement/v5-1/api/_index.md
      • docs/content/grid-placement/v5-1/api/public-api/index.md
      • docs/content/grid-placement/v5-1/api/public-api/GDSCRIPT_5_1_TO_6_0_MIGRATION.md
      • docs/content/grid-placement/v5-1/guides/_index.md
      • docs/content/grid-placement/v5-1/guides/node-first-public-api.md
      • docs/content/grid-placement/v5-1/guides/runtime-chain.md
      • docs/content/grid-placement/v5-1/guides/user-scope-root-and-lifetime.md
  4. Adopt per-plugin composition/ glue folder (5.1 legacy track)
    • Create addons/grid_building/composition/ as the canonical location for 5.1 composition glue.
    • Keep glue minimal: wiring + adapter boundaries only (no deep behavior).
    • Mirror the 6.0 concepts for parity:
      • Scope identity (5.1 GBOwner-style) maps to 6.0 UserId / IUserScope conceptually.
      • Settings/profile override pattern exists (data provider first, exported defaults second).
      • Input routing policy matches the 6.0 C# contract (GDScript translation, not runtime C# bridge).
    • Done when:
      • 5.1 has a documented, single entrypoint that wires services + adapters for one owner.
      • No public class_name / export / signal breakage occurs in existing 5.1 nodes.
  5. 5.1 resource load gate cleanup
    • Finish replacing/repairing invalid uid:// references in shipped 5.1 resources/templates/tests (prefer res://).
  6. Backport lane: first pure-logic module translation
    • Pick one high-ROI module (collision/indicator selection/validation) and translate behind existing adapters.
  7. Mirror the C# tests in 5.1 GDScript
    • Add small, deterministic GdUnit cases matching the C# contract.
  8. Runtime verification pass
    • Update/confirm the smoke scene(s) and verify end-to-end in the demo.

Breaking change note (low impact): GBCompositionContainer validation shims removed

The following GBCompositionContainer methods were intentionally removed as low-impact shims. They were convenience wrappers with no meaningful runtime adoption in the 5.0/5.1 line and were creating confusion about the intended validation flow.

  • Removed: get_readiness_issues(), validate_editor(), validate_structure(), validate_readiness(), validate_runtime()
  • Use instead:
    • Runtime issues (authoritative): composition_container.get_runtime_issues()
    • Structure issues: composition_container.get_structure_issues()
    • Editor issues: composition_container.get_editor_issues() or GBConfigurationValidator.validate_editor(composition_container)
    • Injector boolean gate: GBInjectorSystem.validate_runtime()

Runtime Architecture Recovery (5.1) — 30-Step Plan (Top 5 Worst Offenders)

Goal: Restore runtime compile health and refactor the 5 worst offending runtime classes toward a 6.0-style architecture (service + pure logic separation) while keeping pure GDScript and preserving public node/resource class_name compatibility for 5.0 → 5.1 upgrades.

Canonical-policy note (Dec 2025): Treat 6.0 C# Core as canonical and “backport” only by translating selected logic into pure RefCounted classes used internally by 5.1 adapters. This is not a runtime C# bridge and must not change public 5.1 Godot APIs.

Input parity note (Dec 2025): Even though 6.0 input routing is canonical in C# Core + Godot-side C# bridge/adapters, we will also port the same adapter concepts to 5.1 GDScript (legacy line) so GDScript users get the same mental model and deterministic routing policy. This is a GDScript translation, not a cross-language bridge, and must not change public class_name APIs.

Core-first pattern: Implement behavior in 6.0 C# Core first and make it pass Core unit tests. Only after Core is green, translate selected runtime logic into 5.1 GDScript as pure RefCounted modules. Keep 5.1 tests small and contract-level (mirror Core behavior) to reduce the need for broad GDScript test coverage.

Front-end compatibility rule: 5.1 public Godot-facing adapters remain 5.0 naming compatible (public class_name, exports, signals). “Mirroring” happens behind them via internal pure logic.

Targeting note: 5.1 targeting keeps its public 5.0-compatible API. If any targeting logic is mirrored into 5.1, it must be internal-only pure logic and must not change the public TargetingService2D surface.

Locked compatibility constraints (do not break):

  • Do not rename public Node/Resource class_name types.
  • Do not rename exported property names relied on by scenes/resources.
  • Internal refactors must be behind existing entry points (adapters), similar to the 6.0 C# pattern.

Backport constraints (do not break):

  • Backported logic must be pure: deterministic input/output, no scene tree access, no implicit globals.
  • Backported logic must be RefCounted only (no Node inheritance).
  • No cross-language imports: 5.1 remains pure GDScript.
  • Prefer backports that delete brittle legacy code or reduce strict-typing friction.

Top 5 runtime offenders (current compile cascade roots):

  1. systems/placement/managers/indicator_service.gd
  2. systems/placement/managers/indicator_factory.gd
  3. systems/placement/processors/collision_mapper.gd
  4. systems/placement/processors/collision_processor.gd
  5. core/base/gb_injectable.gd

🔴 Critical (compile + stability gates)

  1. Freeze the public compatibility contract (5.0 → 5.1)

    • Done when: a single doc enumerates the locked Node/Resource class_name + exports/signals.

  2. Establish a “0 parse errors” runtime load gate

    • Done when: demo project loads with 0 GDScript parse errors.

  3. Eliminate class_name duplication sources (without renaming public API)

    • Done when: only one addon source is visible to Godot/LSP at a time.

    Canonical policy note: The demo should consume the canonical addon via a symlink (not a mirrored/copy). This is the simplest way to guarantee a single source of truth and avoid LSP/type duplication.

  4. Normalize strict-warning style (warnings treated as errors)

    • Done when: offending runtime scripts compile without “warning treated as error”.

  5. Fix indicator_service.gd parse blockers (type + preload hygiene)

    • Replace invalid IndicatorService references with the correct internal type.
    • Done when: indicator_service.gd loads and exports symbols successfully.

  6. Fix indicator_setup_utils.gd resolution + naming collisions

    • Ensure the script path resolves in demo (res://addons/...).
    • Done when: IndicatorService can call setup utils without parse errors.

  7. Fix indicator_factory.gd parse blockers (internal-only + no global collisions)

    • Make it an internal pure-logic module (avoid global class_name if it conflicts).
    • Done when: indicator factory loads and is callable by IndicatorService.

  8. Fix collision_processor.gd parse blockers (treat as internal module)

    • Keep API stable for call sites (preload-based use is allowed).
    • Done when: collision processor loads and runs in isolation.

  9. Fix collision_mapper.gd parse blockers (strict typing + unused params)

    • Remove unused params (prefix _param) and add typed iterators.
    • Done when: collision mapper compiles with strict warnings.

  10. Fix gb_injectable.gd base class parse blockers

  • Ensure injection contract compiles: resolve_gb_dependencies() and get_runtime_issues().
  • Done when: all GBInjectable-derived scripts compile.
  1. Rebuild the dependency chain (no cascade failures)
  • Done when: IndicatorManager, IndicatorContext, BuildingSystem, GBContexts, GBCompositionContainer compile.
  1. Add a minimal runtime smoke scene that exercises the indicator pipeline
  • Done when: place preview → indicators spawn → validation runs (no errors).
  1. Define the RefCounted backport lane contract (5.1)
  • Done when:
    • A short list exists of eligible backport domains: placement validation, collision geometry math, indicator state selection.
    • A single set of rules exists for purity (no Node, deterministic IO) and API stability (no class_name changes).
  • Depends on: none
  • Blocks: any “backport” changes that would otherwise drift into ad-hoc refactors

🟠 High (architecture upgrades for the 5 offenders)

  1. Document the 6.0-style GDScript architecture target
  • Service + Adapter + Pure Logic separation (no scene tree in pure logic).
  1. Introduce a GDScript service registry inside GBCompositionContainer (internal)
  • Done when: runtime services resolve from one place (mirrors 6.0 composition root).
  1. Refactor indicator_service.gd into orchestration-only
  • Done when: indicator creation logic is delegated to pure modules.
  1. Refactor indicator_factory.gd into pure, stateless logic
  • Done when: it returns data/results; Node instancing stays in adapters.
  1. Refactor collision_mapper.gd into orchestration-only
  • Done when: geometry math + filtering are delegated to pure processors.
  1. Refactor collision_processor.gd into a pure geometry module
  • Done when: no implicit global state; input/output is deterministic.
  1. Harden the injection boundary (GBInjectable)
  • Done when: all services validate dependencies with fail-fast runtime issues.
  1. Add targeted unit tests for each offender’s pure logic
  • Done when: tests exist that do not require a full demo scene tree.
  1. Backport: establish a RefCounted pure-logic folder and migrate 1 component
  • Done when:
    • A dedicated internal folder exists for pure logic (RefCounted-only).
    • One high-ROI logic component is translated from 6.0 C# contract into 5.1 pure logic.
    • One existing 5.1 Node adapter uses it with zero public API changes.
  • Depends on: Critical item 13

🟡 Medium (quality + maintainability)

  1. Introduce structured diagnostics objects (C#-style reports)
  • Done when: indicator + collision pipelines return a report with issues/notes.
  1. Reduce coupling: replace direct state mutation with narrow service calls
  • Done when: key flows are “command in → report out”.
  1. Canonical parity docstrings: every 5.1 class_name points to its 6.0 C# equivalent
  • Done when: all public/bridge 5.1 GDScript class_name scripts include a short header docstring that:
    • Links to docs/6.0/Core/GRIDBUILDING_CLASS_MAPPING.md
    • Lists the canonical C# type(s) (Core + Godot layer where applicable)
  • Depends on: none
  • Blocks: long-term parity/migration work (keeps mapping explicit and searchable)
  1. Manipulation parity port (5.1 GDScript): mirror the 6.0 manipulation chain + add GDScript integration tests
  • Scope: port the pure manipulation lifecycle + workflow boundary from 6.0 C# into 5.1 as RefCounted logic, then wire into the existing 5.1 manipulation system without breaking public class_name APIs.
  • Core classes that must have parity equivalents (C# → 5.1 GDScript):
    • GridBuilding.Core.Services.Manipulation.ManipulationService2D (state lifecycle + validation, state-only completion)
    • GridBuilding.Core.Systems.Manipulation.ManipulationWorkflowOrchestrator (commit boundary: complete + execute actions)
    • GridBuilding.Core.Services.Manipulation.ManipulationCommands (high-level commands should route through orchestrator)
    • GridBuilding.Core.State.Manipulation.ManipulationState (data model; keep pure)
    • GridBuilding.Core.Types.ManipulationResult (result object parity)
    • GridBuilding.Core.State.Manipulation.ManipulationConstraint (constraint model)
    • GridBuilding.Core.State.Manipulation.ActionDefinition (action model; keep minimal + deterministic in 5.1)
    • GridBuilding.Core.State.Manipulation.*Event types (started/updated/completed/cancelled/failed)
  • GDScript integration (demo/runtime):
    • Implement 5.1 ManipulationService2D + ManipulationWorkflowOrchestrator under addons/grid_building/core/services/** (pure RefCounted).
    • Update systems/manipulation/manipulation_system.gd to use the orchestrator boundary for commit/execute.
    • Ensure input wiring still flows through the existing injector + GBInputService (no new cross-language bridges).
  • Testing (GDScript side):
    • Add unit tests for the pure services (service lifecycle; orchestrator execute policy) under the 5.1 test tree.
    • Add 1 wiring/integration smoke that exercises a real manipulation flow end-to-end in the demo (start → update → complete → effects).
    • Run via existing GdUnit/TestOrchestrator path and keep tests small (mirror C# tests; avoid heavy scenes).
  • Done when:
    • GDScript parity services pass unit tests
    • Demo manipulation flow passes the integration smoke
    • All new 5.1 scripts include canonical C# parity header docstrings
  1. Cache + performance posture aligned with gameplay needs
  • Done when: caching exists but per-frame correctness is preserved.
  1. Compatibility regression checks (5.0 → 5.1)
  • Done when: a small suite verifies old scenes/resources still load.
  1. Consolidate path-first / preload policy for runtime
  • Done when: internal modules use res:// and avoid uid:// in scripts.
  1. Developer-facing docs: “How to extend placement/indicators safely”
  • Done when: contributors know where to put logic (adapter vs pure module).

🟢 Low (polish / optional)

  1. UID hygiene tooling for tests/resources
  • Done when: missing .uid warnings are prevented or auto-repaired.
  1. Optional: internal domain-events style signals for service outputs
  • Done when: adapters subscribe to events instead of polling.
  1. Optional: “placement service facade” naming alignment (docs-only)
  • Done when: docs use 6.0 terminology without renaming 5.1 code identifiers.
  1. Close the loop: re-score the 5 offenders after refactor
  • Done when: each offender has reduced responsibilities + stable tests.

🔴 Critical

  1. [~] 5.1 release gate: tests must be consistently runnable
    • Curated 5.1 GdUnit slice runs cleanly (no parse errors, no discovery failures). (Currently: 133 passing)
    • Test execution is stable under headless orchestration.
    • Run an in-game smoke test of core placement flows (place/move/remove buildings, basic grid interactions).

5.1 Release Gate Checklist (ship/no-ship)

  • Tier-1 curated GdUnit slice is green (133 passing)
  • Demo loads cleanly (0 errors; no UID-driven load warning regressions)
  • Headless orchestration is stable (no flake over repeated runs)
  • In-game smoke is verified (place/move/remove; basic grid interactions)
  • Canonical addon is symlinked (single source visible to Godot/LSP; no class_name duplicates)
  • CI smoke gate exists (single command, fail-fast, treated as release-blocking)

Note (non-blocking): headless --quit can emit ObjectDB instances leaked and ERROR: 4 resources still in use at exit for a small set of scripts; this is currently expected and should not block 5.1.

  1. Eliminate hidden test exclusions for 5.1 GDScript track

    • Verified no Compile Remove="Tests/**" hiding GDScript tests – GdUnit discovers all suites directly.
    • UnifiedTestFactory deprecated files deleted; references updated to modern factories.

  2. Single-source runbook for demo + GdUnit suites

    • Runbook captured below and referenced from HEALTH.

  3. [~] Fail-fast dependency validation in runtime scripts

    • Enhanced test helpers with fail-fast validation (service_fakes.gd, assertions.gd, integration_harness.gd).
    • Tighten validators/controllers to error loudly when required services/signals are missing.
    • Add minimal logging for misconfiguration paths (missing rules, blocked tiles).

  4. 5.1 release gate: zero addon/demo load errors (and no UID-driven load warnings regressions)

    • Replace/repair invalid uid:// references in shipped 5.1 resources (prefer path-first res:// references).
    • Ensure templates load cleanly (configs, indicators, settings resources).
    • Ensure test resources do not break editor load when the tests are present.
    • Prefer removing metadata/_custom_type_script = "uid://..." from .tres/.tscn templates and test assets to reduce invalid UID warning noise.

    Guardrails (local hooks):

    • Local pre-commit GDScript hook blocks new uid:// usage in test/testkit .gd files.
    • demo_doctor.sh scan reports actionable uid:// violations as uid_runtime_gd vs uid_test_gd (instead of raw totals).

  5. Canonical source policy (5.1): fix in plugins first, demo uses symlink to canonical

    • Canonical source for 5.1 GDScript fixes: plugins/gameplay/GridPlacement/gdscript/grid_building.
    • Demo project consumes the addon via symlink to canonical source (no mirrored copies).
    • Done when: developers have one documented, repeatable symlink setup for the demo and know how to verify the demo is using the canonical source.

    Verify the demo is using the symlinked addon:

    • res://addons/grid_building resolves to the canonical folder when inspected on disk.
    • There is no second copy of grid_building on the demo addon search path.
    • Godot loads with no class_name duplication warnings for GridBuilding types.

    Notes: If you see UID cache/import issues when switching to symlinked sources, treat that as a release-blocking stability issue (do not revert to mirroring/copying as the default policy).

  6. Strict typing policy: do not loosen runtime code to make tests pass

    • Keep runtime code strongly typed.
    • Adapt tests to match the typed API.

    Recent strict-typing fixes (kept runtime typing intact):

    • GBPlacementPersistence: safe metadata typing + iterator hints + safe Transform2D assignment.
    • CollisionProcessor: typed dictionary access guarded; polygon arrays typed consistently.
    • ManipulationData: safe access to dynamic root property via get()/set() guards.

  7. CI smoke gate for 5.1

    • Add a single command that runs the curated GdUnit slice and fails fast on regressions.
    • Treat failures and discovery issues as release blockers.

  8. Immediate refactor set (5.1): address lowest-scoring GDScript classes (≤ 70/100)

    • GridPositioner2D (44/100) — split responsibilities (model after C# Grid Controller 2D)
      • Extract/centralize pure logic so GridPositioner2D becomes orchestration-only:
        • Coordinate conversion + snapping logic (pure, testable)
        • Viewport recentering plan/strategy (pure, testable)
        • Input/drive/update loop glue (thin adapter)
      • Ensure per-frame updates remain correct for gameplay feedback (do not reduce update frequency).
      • Done when:
        • GridPositioner2D is reduced to a thin adapter (target: < 600 lines).
        • Core math/plan logic is delegated to dedicated helper(s) already used by tests (e.g. GridPositionerLogic, TargetingUpdateLogic, RecenterPlan).
        • Curated Tier-1 targeting tests still pass.
    • ManipulationSystem (62/100) — extract internal managers into explicit components
      • Move workflow, demolish workflow, physics disable/enable, and placement validation should remain separate collaborators.
      • Done when: ManipulationSystem no longer grows as the default dumping ground (target: < 700 lines).
    • RuleCheckIndicator (66/100) — reduce responsibilities & TODO/FIXME debt
      • Separate: indicator state model, collision probing, and visual presentation.
      • Done when: TODO/FIXME hotspots resolved or deleted, and public API surface is stable.
    • BuildingSystem (69/100) — split orchestration from rule execution / state mutation
      • Done when: build flow logic is decomposed into small helpers and Tier-1 build smokes remain green.
    • GBActionLog (70/100) — documentation + cohesion pass
      • Clarify responsibilities (UI-only vs persistence vs diagnostics) and remove accidental coupling.

Top 5 remaining testability fixes (5.1 release horizon)

  1. Tier-1 smoke suite expanded (GBTestHarness)

    • Keep tests harness-based (no heavy demo scenes / no scene_runner).
    • Cover: build + move + demolish, bounds/OOB, and one collision/indicator case.
    • Tier-1 smoke suite expanded to 6 high-signal files (still fast; run via demo_doctor.sh smoke).
    • Done when: Tier-1 run is 0 failures / 0 errors via TestOrchestrator.

  2. TestKit made single-source (no drift)

    • Keep res://addons/grid_building/testkit/** authored in the canonical source.
    • Align helper internals with current testing rules (typed, deterministic, minimal graph).

    Preferred enforcement: the demo addon is symlinked to canonical so TestKit cannot drift.

  3. Path-first and constants guardrails for tests

    • Ban new preload("uid://...") usage in .gd tests/helpers (require res://...).
    • Ban *_UID constant usage; require .resource_path pattern.

  4. Typed-dictionary friction removed (fix tests, not runtime API)

    • Resolve top typed-dictionary mismatch hotspots by adjusting test inputs and helpers.
    • Keep runtime code strongly typed; do not loosen types to satisfy tests.

  5. Keep/drop policy enforced in CI

    • Ensure dropped/archived suites do not re-enter discovery (no editor/LSP parse noise).
    • Keep only >= 8/10 suites as part of the release gating surface.

Runbook: Run 5.1 GdUnit Suites

1
2
3
4
5
6

# NOTE: The legacy 5.1 GDScript GdUnit harness + suite tree has been deleted.
# We are recreating the 5.1 release gates using lightweight harness patterns.
#
# Until the new suites land, use the scan/smoke tooling and the 6.0 C# harness tests.
./scripts/testing/demo_doctor.sh scan
./scripts/testing/demo_doctor.sh smoke
  • Expected: demo_doctor.sh smoke is green.

Test-writing rules reference (no test.md found in repo):

  • Legacy assertion/testing docs were removed alongside the legacy suite tree.
  • New testing guidance lives under the C# harness pattern docs.

🟠 High

  1. Document and freeze the 5.1 GDScript public API surface

    • Enumerate key GDScript classes, signals, and exported properties used by consumers.
    • Mark what is considered stable vs internal.
    • Reference this from higher‑level public docs as needed.
    • Created docs/5.1/gdscript/5.1/GDSCRIPT_5_1_PUBLIC_API.md with comprehensive API documentation.

  2. Backport safe bugfixes from 6.0 into 5.1 where behaviour diverges

    • Identify 6.0 bugfixes that are safe to backport without adopting the new architecture.
    • Apply only minimal, behaviour‑focused fixes to 5.1.

  3. Narrow responsibilities of critical globals/controllers

    • Pick top 1–2 singleton/controllers; extract small helpers for UI wiring vs rule logic.
    • Keep behaviour intact; reduce coupling ahead of any adapters.

  4. Name alignment where cheap

    • Align internal helper names with 6.0 terminology when non‑breaking (placement/manipulation, mode service).

🟡 Medium

  1. Improve 5.1 GDScript test coverage (targeted)

    • Added boundary/rounding coverage for grid rotation + positioning utilities:
      • GBGridRotationUtils: degrees_to_cardinal rounding boundaries, direction deltas, opposite direction, horizontal/vertical classification.
      • GBPositioning2DUtils: coordinate boundary semantics (just-before-boundary), negative coordinate flooring, non-zero-origin region clamp.
    • Tests remain small and focused (utility-level, no heavy integration harness).

  2. Clarify 5.1 → 6.0 migration story for GDScript users

    • Add internal notes describing how common 5.1 flows map to 6.0 C# services/adapters.
    • Link to this from the main 6.0 migration docs.
    • Created docs/5.1/gdscript/5.1/GDSCRIPT_5_1_TO_6_0_MIGRATION.md with comprehensive migration guide.

  3. Lightweight regression GdUnit backfills

    • Add small tests for known sharp edges (blocked tiles, collisions, undo/redo).
    • Include a quick regression for any backported 6.0 fixes.

🟢 Low

  1. Quality‑of‑life improvements in 5.1 demo and tooling

    • Minor UX tweaks in demo scenes.
    • Small scripting helpers for developers debugging GDScript flows.

  2. Optional GDScript adapters for select 6.0 C# services (if demand appears)

    • Prototype thin GDScript wrappers over a small subset of 6.0 C# APIs.

  3. Telemetry/logging polish

    • Add low-noise warnings for common user misconfigs to ease support/debugging.

Milestones

  • Milestone 1: 5.1 demo + tests green
    • All 🔴 Critical items completed.
  • Milestone 2: GDScript API surface documented and stable
    • Key 🟠 High items completed; docs published internally.
  • Milestone 3: 5.1 positioned as “stable legacy” once 6.0 C# GA
    • Roadmap updated to reflect that 5.1 GDScript is frozen to critical fixes and curated tests only.
    • Any future GDScript 6.0 work tracks the canonical 6.0 C# line via direct translation, not an in‑place upgrade of 5.1 projects.

Update this roadmap as tasks complete or priorities change, keeping it in sync with the GDScript health document.