GridPlacement GDScript 5.1 – Remaining High‑Value Work

Scope: GridBuilding 5.0 / 5.1 GDScript line only (plugin, demo scenes, GdUnit tests). Goal: capture concrete, high‑value changes that are still worth doing now that 5.1 is functionally working in‑game.

This document complements:

README.md (what this folder is and what belongs here)
ROADMAP.md (prioritized task lanes)
HEALTH.md (current score and risks)
GDSCRIPT_6_0_PLAN.md (forward-looking 6.x GDScript story and migration tooling plan)

Here we focus on what is actually worth changing in 5.1 given that:

6.0 is the C#‑first future, and
5.1 GDScript is legacy but still in use and should remain reliable.

1. Constraints & Design Principles for 5.1

No big rewrites
- Avoid large architectural overhauls of GDScript systems.
- Prefer surgical fixes and small refactors with clear payoff.
Stability over purity
- Behaviour that players already rely on should not change unless it is clearly a bug.
- Architectural improvements must not introduce regressions in core placement flows.
Align with 6.0 direction, don’t mirror it
- Use 6.0 as a reference for better boundaries and naming, not as a template to fully port into GDScript.
- Where possible, structure scripts so that future adapters to 6.0 C# are easier.
Tests first for risky areas
- For any non‑trivial behaviour change, add/extend small GdUnit tests or demo‑scene repros first.
- Keep fixtures light; avoid complex orchestrator harnesses.

2. High‑Value Areas

2.1 Tests & CI (highest value)

Objectives

Make sure the 5.1 GDScript line is easy to re‑validate when you touch it.

Concrete steps

2.1.1 Demo + tests runnable path
- Document a single, up‑to‑date set of steps to:
  - Open and run the main 5.1 demo scene(s).
  - Run the key GdUnit test suites.
- Capture this in ROADMAP.md and/or HEALTH.md as checklists.
2.1.2 Targeted regression tests
- For each known “sharp edge” in 5.1 (bugs you’ve seen in‑game, confusing behaviours, etc.):
  - Add a small GdUnit test or a documented manual repro step in HEALTH.md.
  - Focus on:
    - Placement edge cases (blocked tiles, collisions, snapping issues).
    - Undo/redo or multi‑step manipulations that previously broke.
2.1.3 No hidden exclusions
- Verify there are no configuration tricks that hide failing 5.1 tests.
- If a suite is failing but valuable, fix the underlying issue instead of disabling it.

2.2 Public API Surface (stabilize what exists)

Objectives

Make the current 5.1 GDScript API surface explicit so you know what you must not break.

Concrete steps

2.2.1 Enumerate public entrypoints
- In ROADMAP.md (or a dedicated section in this file):
  - List the key GDScript classes/nodes that external users are expected to touch (e.g., top‑level plugin scripts, autoloads, major controllers, primary signals).
  - For each, mark Public / Internal.
2.2.2 Freeze contracts
- For the Public set:
  - Avoid renaming nodes, changing signal signatures, or removing exported properties.
  - If a change is required, note it as breaking and only do it with strong justification.
2.2.3 Minimal doc strings / comments
- For the worst offenders (complex scripts external users touch):
  - Add short, focused comments or Godot‑style docstrings explaining how they are intended to be used, not their entire implementation.

2.3 Pragmatic Architecture Improvements

Goal: improve the worst architectural pain points without redesigning the whole stack.

Common issues to look for:

Overuse of global singletons that mix concerns (state, input, and UI in one script).
Controllers that contain both placement rules and scene wiring.
Large scripts that are hard to reason about because they encode too many flows.

Concrete steps

2.3.1 Narrow responsibilities of globals
- Where a singleton currently owns both data and view wiring, consider:
  - Keeping behaviour intact but extracting small helper functions or child nodes for UI bits.
- The target is not “perfect purity” but:
  - Globals that mostly expose clear methods and signals, not a huge bag of fields.
2.3.2 Separate rules from presentation in obvious hotspots
- Identify one or two scripts where placement/manipulation rules are deeply mixed with UI code.
- For those only:
  - Extract the rule logic into a small internal helper script or pure function where possible.
  - Leave the UI script focused on calling that helper and updating visuals.
- This makes it easier later to:
  - Compare logic against the 6.0 C# services.
  - Potentially replace the rules with an adapter to 6.0.
2.3.3 Align naming with 6.0 where cheap
- For internal helpers or recently‑touched code, prefer naming that matches the 6.0 concepts (e.g., “placement”, “manipulation”, “mode service”) when it doesn’t break public API.
- This reduces mental overhead when switching between 5.1 GDScript and 6.0 C#.
2.3.4 Introduce service facade over injector system
- Add a thin, testable service‑style facade in front of the existing injector / global wiring, mirroring key 6.0 C# service concepts (placement, targeting, manipulation, inventory).
- Keep the public 5.1 GDScript API stable: the facade wraps the injector configuration instead of replacing it.
- Use this facade as the main seam for new tests and future migration adapters so that GdUnit and C# harness tests can target consistent service‑shaped entry points.

2.4 Safe Backports from 6.0

Objectives

Bring over behavioural bugfixes from 6.0 into 5.1 only when they are clearly safe and high‑value.

Concrete steps

2.4.1 Maintain a short backport list
- In ROADMAP.md or here, track a list of:
  - Specific 6.0 fixes that have a clear 5.1 analogue.
  - A one‑line summary of the bug and why the fix is safe.
2.4.2 Backport with tests
- For each backport:
  - First write a GdUnit test or scripted repro describing the bug in 5.1.
  - Then apply the minimal fix.
  - Re‑run demo + tests to confirm no regressions.

2.5 Migration Story Support (5.1 → 6.0)

Objectives

Help GDScript users understand how today’s flows map to 6.0, without forcing them to migrate immediately.

Concrete steps

2.5.1 Document flow mapping
- In ROADMAP.md or a dedicated migration note under this folder, briefly describe:
  - A few core 5.1 workflows (e.g., place building, demolish, basic manipulation).
  - The equivalent 6.0 services/adapters that implement the same ideas.
2.5.2 Cross‑link from main 6.0 docs
- From the public 6.0 migration guides, link back to these internal notes so you have a single source of truth for 5.1‑specific nuances.

3. Suggested Execution Order

To keep effort bounded and value high:

Lock in tests & health basics
- Make sure demo + a few core GdUnit suites are runnable.
- Capture current health and top risks in HEALTH.md.
Clarify and freeze the API surface
- Enumerate public vs internal GDScript entrypoints.
- Avoid breaking the public ones.
Tackle 1–2 worst architecture hotspots
- Apply small, well‑scoped refactors where scripts are obviously over‑coupled.
Optionally backport a tiny number of 6.0 fixes
- Only when they clearly reduce risk for 5.1 users.
Update roadmap & health docs
- As you complete items from this list, reflect them in ROADMAP.md and HEALTH.md.

This keeps the 5.1 GDScript line reliable and understandable without sinking time into large rewrites that are better spent on 6.0.

4. 5.1 Demo Triage Snapshot (2025‑12‑09)

Status Update (Dec 2025)
Active remediation of the GridPlacement addon and demo is paused until the 5.1 release is tagged. Editor load warnings and the known error backlog are expected during this pause and are tracked but not blocking. Resume execution only after 5.1 ships and priorities are re-baselined against the release criteria below.

For this pass, we explicitly narrow scope so we can make the GridBuilding 5.1 demo playable with the GDScript plugin without fixing every legacy test.

Bucket A – Core demo / plugin blockers (fix now)
- Canonical plugin export done – demo now uses addons/grid_building as the single canonical plugin location; addons/grid_placement was removed.
- Cursor/icon configuration still broken – addons/grid_building/shared/components/ui_controls/cursor_settings.gd and related settings resources still preload icons via stale UIDs, causing compile errors that cascade into gb_settings, gb_visual_settings, gb_config, and core contexts.
- Shared audio instancer script failing – demos/shared/audio/gb_audio_instancer.gd does not compile cleanly even though its .tscn falls back to valid res:// audio paths.
Bucket B – Legacy / heavy GDScript tests (de‑scoped for this pass)
- Large suites under addons/grid_building/test/grid_building/** and res://test/** with parse errors and outdated patterns.
- These are not required for “demo playable”; we will later select a small, high‑value subset to keep and fix.
Bucket C – UID / font / asset warnings (deferred)
- invalid UID warnings where Godot falls back to res:// paths.
- FreeType font cache warnings.
- These are noisy but not blocking demo runs, and are postponed to a later clean‑up pass.

Goal for this pass:
Project + main demo scenes open and run without hard errors when using the 5.1 GDScript/GridBuilding plugin.
Editor load is “clean enough” to iterate on demos.
Full GDScript test green is explicitly out of scope for this triage round.

5. Clean Demo Load Target (No Errors / Warnings)

Goal: move from “clean enough to iterate” to zero errors and warnings on project + main demo load for the 5.1 GDScript line, without large rewrites.

5.1 Expected Editor Experience

When opening the 5.1 demo project (GridBuilding addon enabled):

No red errors in the Godot editor output.
No yellow warnings attributable to the GridBuilding / GridPlacement addon, including:
- invalid UID or Node not found for UID messages.
- Font / theme / icon warnings caused by broken references in addon scripts.
Main demo scenes open and run without emitting new errors or warnings.

5.2 UID Path‑First Policy for 5.1

To make the addon less brittle and avoid UID‑related warnings, adopt a path‑first policy for authored code in the 5.1 line:

In scripts (GDScript and C#):
- Use preload("res://...") or load("res://...") for assets with stable paths.
- Do not add new preload("uid://...") calls in scripts.
- When touching existing scripts that still use uid:// preloads and the asset has a known path, convert them to res:// paths.
In scenes/resources (.tscn / .tres):
- It is acceptable for Godot to store UIDs internally.
- Avoid manually editing UIDs; rely on the editor (and tooling like the UID fixer) to keep them consistent.
In tests and demo‑only helpers:
- Follow the same rule: prefer res:// paths in code so tests don’t break when UIDs change.

This keeps the code surface resilient to UID churn while still allowing Godot to manage UIDs inside serialized scene/resource files.

5.3 Checklist: Reaching a Clean Load

When you want to push 5.1 to a “no errors / no warnings” state for demo loading, use this checklist:

Start from the canonical addon path
- Confirm the project uses res://addons/grid_building as the single source of truth for the 5.1 addon.
Open project and main demo, capture output once
- Launch the editor and open the main demo scene(s).
- Copy the console output for a single clean load.
Eliminate all UID‑related warnings/errors
- For each invalid UID / UID not found message:
  - Locate the referenced script under addons/grid_building or demo scripts.
  - Replace preload("uid://...") with preload("res://path/to/resource.tres") (or equivalent) when the asset has a stable path.
  - Re‑save the scene/resource if necessary so Godot updates internal references.
Fix font / icon / theme warnings from addon scripts
- For each font/icon warning that originates from GridBuilding scripts:
  - Point script‑level references at concrete res:// assets.
  - Remove or consolidate unused theme files that reference missing resources.
Re‑run editor + demo until clean
- Repeat open→fix cycles until:
  - No errors are emitted when opening the project.
  - No warnings are emitted from the addon or demo scenes.
Update HEALTH.md / ROADMAP.md once achieved
- Record that 5.1 demo load is now warning‑free.
- Note any remaining known noisy areas (if they exist outside the addon) so future triage can ignore them safely.

Reaching this state ensures the 5.1 GDScript line is pleasant to work on: you can open the demo project without noise and safely rely on res:// paths instead of brittle UID preloads in scripts.