GridPlacement GDScript 6.x – Forward Plan

Scope: planning only. This file does not commit to implementing a 6.x GDScript line, but captures what it would look like if/when you decide it is worth doing.
Primary reality: 6.0+ is C#‑first. The existing 5.1 GDScript plugin under addons/grid_building remains the supported legacy line.

1. Positioning

Canonical future:
- Runtime, tests, and tooling are centered on GridPlacement 6.x C#.
- GDScript is treated as a legacy compatibility story, not a primary implementation language.
What this plan covers:
- A possible 6.x‑era GDScript addon installed as addons/grid_placement.
- A GDScript→GDScript migration tool to move existing addons/grid_building users to the new addon, if it ships.
What this plan does not require:
- You do not need to ship a 6.x GDScript addon for 6.0 to be production‑ready.
- You do not need to port all C# features back into GDScript.

2. High‑Level Goals

G1 – Keep 6.x C# canonical
- Behaviour, rules, and APIs are defined in C#.
- Any GDScript 6.x story should be a thin adapter or subset, not a second full implementation.
G2 – Provide a clean GDScript landing zone if it’s worth it
- If you decide to ship a 6.x GDScript addon, it should:
  - Install as res://addons/grid_placement.
  - Use clearer naming and boundaries aligned with the 6.x design.
  - Avoid re‑introducing legacy architecture problems.
G3 – Smooth migration for existing 5.0/5.1 GDScript users
- Offer a GDScript→GDScript migration tool that:
  - Takes a project using addons/grid_building.
  - Produces a project using addons/grid_placement (and any new script names) with behaviour preserved where possible.
  - Runs with dry‑run, backups, and clear reporting.

3. Future Addon Layout – `addons/grid_placement`

If you choose to ship a 6.x‑era GDScript addon, the proposed layout is:

Addon root: res://addons/grid_placement
- Mirrors the 6.x C# mental model (“GridPlacement” as the platform name).
- Distinct from the historical res://addons/grid_building used by 5.x.
Key principles:
- P1 – Thin wrapper over C# where possible
  - Prefer calling into C# services (via nodes or bindings) rather than re‑implementing complex rules in GDScript.
  - Keep GDScript focused on wiring, UI glue, and simple adapters.
- P2 – Minimal public API surface
  - Expose a small, documented set of entrypoints (nodes, autoloads, signals) that users are expected to touch.
  - Resist adding “convenience” APIs that duplicate C# capabilities unless they are obviously high value.
- P3 – Co‑existence with legacy 5.1
  - 5.1 GDScript continues to live under addons/grid_building for existing projects and demos.
  - Any 6.x GDScript addon under addons/grid_placement is treated as a new major line, not an in‑place upgrade.

4. GDScript→GDScript Migration Tool (grid_building → grid_placement)

If you ship addons/grid_placement, you will need a migration path for existing GDScript projects:

4.1 Objectives

O1 – Mechanical rename + path update
- Update all project references from addons/grid_building → addons/grid_placement.
- Adjust script paths and plugin config as needed.
O2 – Behavioural stability where possible
- Maintain existing gameplay flows; focus on non‑breaking transforms.
- Document any intentional behaviour changes as breaking.
O3 – Safety first
- Provide dry‑run, backup, and detailed reporting.
- Refuse to execute if the project doesn’t match expected patterns (e.g., heavily customized forks).

4.2 Input & Output

Input project:
- Uses the 5.x GDScript addon under res://addons/grid_building.
- Scripts, scenes, and resources may reference that path directly.
Output project (ideal):
- Uses a new 6.x‑era GDScript addon under res://addons/grid_placement.
- All references updated to new paths and script names.
- Optionally, some nodes updated to call into C# 6.x services instead of legacy internals.

4.3 Core Transformations

A first‑pass migration tool should support at least:

Addon path rewrites
- In .tscn, .tres, .gd, .cs (if any):
  - Replace res://addons/grid_building/ → res://addons/grid_placement/.
Plugin config updates
- New addons/grid_placement/plugin.cfg with:
  - Updated name (e.g. “GridPlacement” or “Grid Placement”).
  - Correct script path and any new entrypoint script.
Autoload and tool script wiring
- If the 5.1 addon registered autoloads or tool scripts:
  - Update project.godot plugin/autoload entries to point at the new addon location.
Optional script renames / namespaces
- Optionally migrate class names and script filenames to align better with 6.x naming, only when the mapping is clear and high‑value.

4.4 Tool Design Notes

Implementation language
- The tool can be implemented in C# (preferred) or GDScript, but it operates on GDScript projects.
- It should follow the safety model already used by the existing migration tooling:
  - Dry‑run by default.
  - Explicit “execute”/“apply” flag.
  - Clear console and file‑based reports.
Modes
- Discovery / report only
  - Scan a project and list all references to addons/grid_building and key 5.1 classes.
- Dry‑run migration
  - Show exactly which files would change and how.
- Execute migration
  - Apply the transformations, create backups, and emit a summary report.
Failure conditions
- Abort on:
  - Missing or inconsistent 5.1 addon layout.
  - Heavy divergence from the expected plugin structure (user‑forked layouts).
- In these cases, fall back to manual migration guidance instead of trying to be clever.

5. Relationship to 6.0 C# Migration

The primary recommended path for serious projects is still:
- addons/grid_building (5.0/5.1 GDScript) → GridPlacement 6.x C# (core + Godot C#).
A 6.x GDScript addon under addons/grid_placement would be:
- An optional compatibility layer for teams that must stay on GDScript.
- A possible stepping stone: GDScript project → addons/grid_placement → gradually adopt C# services.
Any work on this plan should:
- Avoid blocking or complicating the C# migration and test story.
- Reuse existing migration tooling patterns where practical.

6. Suggested Execution Order (If Approved)

If you decide this is worth doing in a future release cycle:

Finalize decision & scope
- Decide whether a 6.x GDScript addon is in or out of scope for the next major.
- If “in”, decide whether it is a thin adapter over C# or a parallel subset implementation.
Design the addons/grid_placement addon skeleton
- Define minimal public entrypoints and scenes.
- Align naming and structure with 6.x C# concepts.
Specify migration mappings
- Document concrete grid_building → grid_placement path and class name mappings.
- Keep the list small and focused.
Implement the migration tool
- Start with discovery + dry‑run mode.
- Add execute mode only after you trust the reports.
Pilot on the demo project
- Run against demos/grid_building_dev/godot and verify behaviour.
- Adjust mappings until the demo works end‑to‑end.
Document and ship
- Add a user‑facing guide for:
  - When to use the migration tool.
  - How to run it safely.
  - Known limitations and breaking changes.

This keeps the GDScript 6.x story clearly secondary to C# while still giving you a well‑defined path if you decide to invest there later.