Grid Placement

GridPlacement GDScript Track Health (5.0 / 5.1)

Scope: GDScript‑based GridBuilding 5.0 / 5.1 line, including demo scenes and tests.

Current Health Score

  • Score: 86 / 100
  • Trend: stable

5.1 Release Gate Checklist (ship/no-ship)

  • GdUnit test suites are green via orchestrator (236/236 passing; 50/50 suites)
  • 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)
  • Release output contains no symlinks (portable addon; exporter resolves symlinks into real files)
  • Preload paths are portable (all preload(...) references resolve via local addon paths; confirm in release output before shipping 5.1)
  • No headless teardown crashes (no segfaults on exit when running curated slice)
  • No engine runtime errors during curated runs (e.g. Invalid shape.)
  • No recurring orphan-node warnings in curated runs (treat as a cleanliness requirement, not just “noise”)
  • 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; this is expected for now and not a 5.1 blocker.

Factors Considered

Workflow entrypoints (canonical)

1
2
3
4
5
6
7
8

# Scan for common demo/plugin issues (uid://, parse errors, typed-dict return errors)
./scripts/testing/demo_doctor.sh scan

# Tier-1 smoke gate (release-blocking surface)
./scripts/testing/demo_doctor.sh smoke

# Wider run (non-gating)
./scripts/testing/demo_doctor.sh all-full
  • Tests & CI (GDScript / GdUnit)
    • Do 5.0/5.1 GDScript tests compile and run (locally and via orchestrator)?
    • Any suites disabled or excluded?
  • Architecture & APIs (GDScript)
    • Are public GDScript APIs stable and documented?
    • Any major breaking changes planned vs 6.0 C#?
  • Documentation
    • Is there clear setup + usage guidance for GDScript users on 5.1?
    • Are migration notes toward 6.0 C# available?
  • Dev Experience
    • Ease of running the 5.1 demo and tests.
    • Known flakiness or tooling issues.
  • Known Risks
    • Critical bugs or data‑loss risks in the 5.1 line.
    • Gaps between 5.1 behavior and 6.0 design.

Latest Assessment Snapshots

2025-12-19 – Reachability Coverage Baseline (GDScript)

  • Score: 86 / 100
  • Trend: stable
  • Notes:
    • This repo’s GDScript “coverage” metric is reachability coverage (static scan of res:// references), not Coverlet line coverage.
    • Baseline (reachability): 73.59% (170 / 231 runtime scripts) with 90 seed test files.
    • Canonical runner:
      • scripts/testing/reachability_coverage.sh configs/reachability_coverage.yaml
    • Report written to:
      • demos/grid_building_dev/godot/.godottoolkit/reports/reachability_coverage.json

2025-12-19 – Coverage Gap Snapshot (C# Core)

  • Score: 86 / 100
  • Trend: stable
  • Notes:
    • 5.1 GDScript Tier-1 gate remains green (curated GdUnit runs are still the canonical 5.1 signal).
    • C# Core coverage is currently extremely low – Coverlet run against GridBuilding.Core.Tests reports ~0.9% line coverage (41 / 4578 lines).
      • This is not a 5.1 release blocker, but it does reduce confidence for:
        • parity work (5.1 ↔ 6.0 behavior matching)
        • safe backports from C# → 5.1
        • migration correctness claims
      • Example uncovered area: GridUtilities is currently 0% covered.

2025-12-16 – 5.1 GDScript Track Health Refresh

  • Score: 86 / 100
  • Trend: stable
  • Notes:
    • Core gating surface is healthy – Tier-1 curated GdUnit slice is green and the demo can load cleanly when using the documented workflow entrypoints.
    • Release portability remains the main blocker – dev symlinks are allowed, but the 5.1 release output must contain no symlinks and all preload(...) paths must be portable in the exported addon.
    • Optional demo tooling still adds noise – runtime analyzer references and save/persistence helpers remain a recurring source of non-core failures when running “wide” demo scenario suites.
    • Headless stability is not yet a hard guarantee – some headless runs can still crash during teardown if tests leak nodes or trigger engine-level errors; treat “no crash on exit” as a release gate.
    • Orphan-node warnings are treated as test debt – orphan nodes can correlate with headless instability; require cleanup in the curated slice.
    • Coupling regression risk remains – any direct cross-scope/shared state usage (e.g. GBStates style access) is still treated as a multi-scope regression risk; service accessors remain preferred.

2025-12-14 – Dev Symlink Policy + Portable Export Requirement

  • Notes:
    • Dev workflow allows symlinks for fast iteration (demo res://addons/* points to canonical plugin sources).
    • Release/portable workflows must not ship symlinks; exporter must copy resolved files into the output addon folder.
    • This is treated as a health factor because symlinks break common distribution paths (zip exports, Windows users, clean CI checkouts).

2025-12-14 – Low-Impact API Cleanup (Validation Shims)

  • Notes:
    • Removed unused GBCompositionContainer validation shim methods as a low-impact breaking change.
    • Rationale: zero meaningful runtime adoption in the 5.0/5.1 line, duplicated validator entry points, and increased API surface/maintenance cost.
    • Replacement entry points:
      • Runtime issues: composition_container.get_runtime_issues()
      • Structure issues: composition_container.get_structure_issues()
      • Editor issues: composition_container.get_editor_issues() or composition_container.validate_editor()
      • Injector boolean: GBInjectorSystem.validate_runtime()

2025-12-14 – Architecture Alignment (5.1 Finalization)

  • Notes:
    • 5.1 final architecture clarified – one GBInjectorSystem (bootstrap) per owner scope, one GBOwner per scope, and one of each system node per owner (e.g. BuildingSystem, ManipulationSystem).
    • Service-owned state direction confirmed – PlacementService owns placement session state (PlacementState + owner context) and systems increasingly communicate through services rather than shared state containers.
    • Remaining coupling risk – any direct usage of shared GBStates / cross-scope state access is considered a regression risk for multi-scope setups; prefer service accessors (get_preview, clear_preview, get_builder_owner, etc.).

2025-12-12 – GridBuilding 5.1 Test Inventory Verification

  • Notes:
    • The large GridBuilding 5.1 legacy test suite reduction was intentional (see 2025-12-11 entry).
    • The legacy 5.1 GDScript GdUnit harness + suite tree has been intentionally deleted as part of standardizing on lightweight harness patterns.
    • The 5.1 release gates are being recreated using the smoke/scan tooling and the 6.0 C# harness approach.
    • Decision log remains the source of truth: demos/grid_building_dev/docs/LEGACY_TEST_KEEP_DROP_5_1.md.

2025-12-11 – Legacy Test Pruning (8/10 quality bar)

  • Notes:
    • Applied a strict keep/drop policy: only keep tests scored >= 8/10 (high signal, low maintenance, architecture-aligned).
    • Result: 242 legacy test scripts removed, leaving 14 kept (12 plugin tests + 2 demo tests).
    • Full per-file decisions: demos/grid_building_dev/docs/LEGACY_TEST_KEEP_DROP_5_1.md.
    • Coverage gaps introduced (must be re-covered by Tier-1/2 replacements):
      • End-to-end placement flows (build/move/demolish across scenes)
      • Broad integration harnesses (environment loading, persistence/save-load suites)
      • Large regression sweeps in collision/placement/manipulation
      • Demo scenario tests outside the remaining minimal smoke
    • Language boundaries reaffirmed – canonical GDScript addon stays GDScript-only, and C# runner/tests never import demo helpers. Adapters bridge behavior; no mixed-language utilities.

2025-12-11 – Easy Parse & Helper Cleanup (Non-Blocking)

  • Score: 88 / 100
  • Trend: improving
  • Notes:
    • Dynamic preload parse errors resolved – unused legacy helper res://addons/grid_building/core/security/secure_preloader.gd has been removed entirely (no runtime scripts referenced it), eliminating the Godot 4.5 “Preloaded path must be a constant string” error without keeping unnecessary code.
    • Shared helper syntax normalized – a batch of high-noise, low-risk test helpers had indentation/scope fixes applied so they parse cleanly under the editor/LSP (e.g. gb_grid_rotation_utils_test.gd, factory_utilities_tests.gd, composition_container_subresources_test.gd, environment_loading_unit_test.gd, placeable_sequence_factory_test.gd, grid_positioner_*_tests.gd, mouse gate tests). These changes do not alter runtime behavior; they only make tests loadable again.
    • Deeper behavior and typing issues remain – typed-dictionary mismatches, legacy scenario tests, and some regression suites still require contract/behavior alignment or downsizing (tracked under the 5.1 test & load-health roadmap). This snapshot treats those as medium/high work items, not as quick-parse fixes.

2025-12-11 – Editor Load Cleanliness (Legacy Test Quarantine)

  • Notes:
    • A large set of legacy 5.1 GdUnit/demo test files drifted and produce parse errors when scanned by the editor/LSP.
    • To keep the 5.1 demo project usable for iteration, these folders are currently quarantined via .gdignore:
      • demos/grid_building_dev/godot/addons/grid_building/test/
      • demos/grid_building_dev/godot/test/
    • Before a 5.1 release: these suites must be fixed and re-enabled or retired (deleted/moved out of Godot scan).
    • Tier-1 smoke validation remains the gating surface and must stay green via TestOrchestrator.

2025‑12‑11 – GridPlacement 6.0 C# Health Assessment

  • Score: 78 / 100
  • Trend: stable
  • Factors:
    • Core tests healthy – 1350 C# Core tests passing (100% pass rate) with only deprecation warnings for ManipulationMode → GridMode transition.
    • Architecture modern – 100% Service Registry adoption, clean Core/Godot separation, constructor dependency injection implemented.
    • Documentation current – Comprehensive roadmap and production docs maintained, API stability documented.
    • Local CI infrastructure – Complete CI scripts available (ci-build.sh, ci-test.sh, ci-quality.sh, ci-all.sh).
    • Godot tests failing – GridBuilding.Godot.Tests project crashes during execution (Test host process crashed), blocking full test validation.
    • High warning count – 1016 build warnings in Core tests, 1038 warnings in Godot project (mostly XML documentation missing).
    • No GitHub Actions – CI/CD pipeline exists locally but not automated in GitHub Actions.
    • Security audit pending – Production roadmap identifies security audit as critical blocker.

2025‑12‑10 – Extended 5.1 Demo + Addon GdUnit Run

  • Score: 75 / 100
  • Trend: declining
  • Notes:
    • Broader 5.1 suite executed in demo project (canonical run) – 39 test suites, 253 test cases, 199 errors, 58 failures, 0 skipped, 317 orphans.
    • PixelPerfectCamera tests green (verified) – restored pixel_perfect_camera_2d.gd API compatibility (_update_pixel_snap_offset, default config) and confirmed the demo vendored addon suite runs cleanly via TestOrchestrator.
      • GODOTTOOLKIT_GDUNIT_RUNNER=demos/grid_building_dev/scripts/testing/gdunit_runner.sh dotnet run --project toolkits/cs/TestOrchestrator/GodotToolkit.TestOrchestrator.csproj -- run demos/grid_building_dev/godot 60 --workers 2 demos/grid_building_dev/godot/addons/pixel_perfect_camera/tests
    • Typed dictionary and dictionary casting issues – several helpers and tests fail on Dictionary vs Dictionary[String, bool] / Dictionary[String, Nil] mismatches (e.g. GBLogger.log_verbose_once, IntegrationTestComponent.validate_environment, save/load helpers), reflecting stricter typing rather than core runtime failures.
    • Heavy demo integration and persistence suites unstable – demo camera integration, targeting, save/load, and scene analyzer tests frequently assume older demo scene structures, inventory wiring (get_item_types on ResourceDisplay), and persistence hooks (save_state), leading to null access and contract drift rather than plugin-core crashes.
    • Manipulation and shape collision tests partially failing – manipulation_data_unit_test.gd, manipulation_state_machine_unit_test.gd, manipulation_state_unit_test.gd, and shape_collision_validation_tests.gd expose signal timing assumptions and typed-dictionary parameter issues that need either behavior alignment or test simplification.
    • Action: treat this run as a wide, non-gating regression sweep: keep Tier 1 smoke suites prioritized for green status, and either modernize, trim, or quarantine the heaviest failing demo scenarios according to the 5.1 test roadmap.

2025‑12‑10 – 5.1 GdUnit Pipeline & Demo Scenario Tests

  • Score: 90 / 100
  • Trend: improving
  • Notes:
    • 5.1 GdUnit pipeline green via TestOrchestrator – core demo + addon suites run using toolkits/cs/TestOrchestrator/GodotToolkit.TestOrchestrator.csproj with the shared GdUnit runner wrapper.
    • Coverage: ~25 demo test files + 219 addon test files (~1281 test cases) are exercised with no blocking errors in the curated Tier 1/2 slice.
    • Remaining demo scenario parse issues (targeted) – a small set of legacy scenario tests in the 5.1 demo still have parse/indent/assertion issues (gigantic_egg_tests.gd, smithy_placeable_test.gd, platformer_enemy_manipulation_test.gd).
    • Roadmap alignment: these files are tracked under the 5.1 test roadmap as candidates to either fix or retire so they no longer impact editor/test cleanliness.

2025‑12‑10 – Demo Load: 4 Errors, 0 Warnings

  • Score: 90 / 100
  • Trend: improving
  • Notes:
    • UID fallback warnings cleared – uid-clean tooling applied to addon/templates/tests; Godot now reports 0 UID fallback warnings for addons/grid_building resources.
    • Path-first policy enforced – ext_resource entries now rely on res:// paths only, matching the repo’s UID policy.
    • 4 residual load errors remain – small number of GDScript scripts/scenes still blocking a perfectly clean demo load; tracked under the demo load roadmap.
    • Typed dict / test harness issues unchanged – remaining GdUnit typed-dict mismatches and helper issues still require follow-up.

2025‑12‑10 – UnifiedTestFactory Purge & Runbook Update

  • Score: 88 / 100
  • Trend: stable
  • Notes:
    • UnifiedTestFactory deprecated files deleted – .uid stubs removed from both grid_building and GridPlacement plugin copies.
    • Factory references updated – godot_test_factory.gd, collision_object_test_factory.gd, and TEST_HELPER_ROUTER.md now point to modern factories (EnvironmentTestFactory, GodotTestFactory, CollisionObjectTestFactory).
    • Runbook added to ROADMAP.md – single command to run 5.1 GdUnit suites documented.
    • GdUnit run verified – 898 tests discovered; 81 failures, 327 errors (typed dict mismatches, missing test nodes). No hidden exclusions.
    • Remaining typed dict errors – mostly Dictionary[String, bool] mismatches in GBLogger and SetupResult.owner_shapes. Medium priority.

2025‑12‑09 – 5.1 Demo Load Assessment (FIXED)

  • Score: 85 / 100
  • Trend: improving
  • Notes:
    • Canonical plugin export is resolved – the 5.1 GDScript plugin now lives canonically at addons/grid_building for the demo, with the duplicate addons/grid_placement copy removed.
    • Cursor/icon configuration FIXED – cursor_settings.gd now uses res:// path-based preloads for cursor icons instead of stale UIDs.
    • ~60 indentation/scope errors FIXED – batch-fixed indentation errors in canonical plugin test files (gb_integration_test.gd, gb_test_diagnostics.gd, manipulation_test_helpers.gd, and ~50+ systems/helpers test files).
    • Font reference FIXED – grid_builder_warm_earth_theme.tres now references the correct font path.
    • Demo loads with 0 parse errors – reduced from 251 errors to 0 (only 1 cleanup warning about resources in use at exit).
    • 46 UID warnings remain – these are non-blocking fallback warnings where Godot uses text paths instead of UIDs. Low priority.
    • Runtime analyzer references still missing – runtime_scene_analyzer.tscn is referenced but not vendored.

2025‑12‑09 – Pixel‑Perfect Camera Export & Tests

  • Score: TBD / 100 (pixel‑perfect camera area: high confidence)
  • Trend: improving for optional addons
  • Notes:

    • Canonical source – PixelPerfectCameraGodot lives at plugins/gameplay/PixelPerfectCameraGodot/pixel_perfect_camera and is treated as the single source of truth for pixel‑perfect camera scripts and tests.

    • Export into demo project – the addon is vendored into the 5.1 demo at demos/grid_building_dev/godot/addons/pixel_perfect_camera, so paths like res://addons/pixel_perfect_camera/pixel_perfect_camera_2d.gd and res://addons/pixel_perfect_camera/camera_diagnostics.gd resolve correctly in grid_building_dev.

    • UID‑safe tests (path‑first) – addons/pixel_perfect_camera/tests/test_pixel_perfect_camera.gd now uses res:// path‑based preloads for the camera script, diagnostics overlay, and top‑down demo scene instead of uid://… preloads, matching the repo’s path‑first policy.

    • Addon tests via orchestrator – the addon’s own tests are runnable via the C# TestOrchestrator and GdUnit wrapper:

      • dotnet run --project toolkits/cs/TestOrchestrator/GodotToolkit.TestOrchestrator.csproj -- demos/grid_building_dev/godot addons/pixel_perfect_camera/tests 60

    • Demo integration tests green – the demo‑side GdUnit suite test/demos/camera/pixel_perfect_camera_test.gd runs green via the same orchestrator:

      • dotnet run --project toolkits/cs/TestOrchestrator/GodotToolkit.TestOrchestrator.csproj -- demos/grid_building_dev/godot test/demos/camera/pixel_perfect_camera_test.gd 60

    • M3 partial mitigation – pixel‑perfect camera is no longer a missing/fragile addon for the 5.1 demos; remaining work under this risk is focused on the runtime analyzer and demo save helpers.

2025‑12‑09 – 5.1 GdUnit Test Pipeline (TestOrchestrator)

  • Score: 90 / 100 (tests & CI dimension)
  • Trend: improving
  • Notes:
    • Core 5.1 GdUnit suites pass via GodotToolkit.TestOrchestrator using the shared gdunit_runner.sh wrapper.
    • Coverage: ~25 demo test files + 219 addon test files (~1281 test cases) are exercised in the current pipeline.
    • Runner configuration documented in demos/grid_building_dev/docs/GDUNIT_TEST_HEALTH_ROADMAP.md and scripts/README_GDUNIT_RUNNER.md.
    • No GDScript tests are hidden via <Compile Remove> – 5.1 GDScript suites are discovered directly by GdUnit. Some C# tests in GridBuilding.Tests.csproj remain excluded for 6.0 porting reasons; they are not part of the 5.1 GDScript health surface.
    • Tiering and retirements documented – Tier 1, Tier 2, and Won’tFix 5.1 suites are captured in GDUNIT_TEST_HEALTH_ROADMAP.md and LEGACY_GDSCRIPT_GDUNIT_MIGRATION.md.

Key Risks and Actions

  • Top Risks:

    • R3 – Demo and tooling experience still depend on non‑essential assets and helpers (runtime analyzer, UID warnings), making 5.1 slightly noisy to work on.
    • R4 – Mixed language expectations – without clear guardrails, contributors may accidentally mix C# helpers into GDScript tests (or vice versa), reintroducing fragility.

  • Mitigation / Next Steps:

    • M1 – Resolve duplicate plugin copies in the demo – addons/grid_placement has been removed from the demo; addons/grid_building is canonical.
    • M1b – Fix cursor/icon configuration UIDs – replaced uid://… preloads in cursor_settings.gd with res:// icon paths.
    • M1c – Fix ~60 indentation/scope errors – batch-fixed indentation errors in canonical plugin test files and exported to demo.
    • M1d – Fix font reference – grid_builder_warm_earth_theme.tres now references the correct font path.
    • M2 – Clean up remaining UID warnings – UID fallback warnings reduced from ~46 to 0 via uid-clean and path-first resource configuration.
    • M3 – Clean up optional tooling/assets – either vendor or relax dependence on non‑critical pieces:
      • Pixel‑perfect camera: vendored from PixelPerfectCameraGodot into demos/grid_building_dev/godot/addons/pixel_perfect_camera, with addon tests and demo camera tests running green via GodotToolkit.TestOrchestrator.
      • Runtime analyzer: decide whether to vendor a minimal, supported version or remove demo references (e.g. runtime_scene_analyzer.tscn).
      • Demo save system: fix naming conflicts and parsing issues in shared save scripts (e.g. player_save_data.gd, save_game.gd), or simplify/remove these helpers from the core 5.1 demo path.
    • M4 – Reassert language separation – ensure docs and linting make it clear that GDScript tests/resources never depend on C# helpers, and C# runners do not import demo helpers. Document the adapter pattern for legitimate cross-language interactions.