Grid Placement

GridPlacement GDScript Docs (5.0 / 5.1 Legacy Track)

This folder is the canonical internal home for GridBuilding 5.0 / 5.1 GDScript documentation related to the GridPlacement / GridBuilding plugins.

Scope:

  • Docs specifically about GDScript APIs, demos, and behavior in the 5.0/5.1 line.
  • Internal notes about how 5.1 behaves today and how it relates to 6.0 (C#‑first).
  • Roadmap and health documents for the 5.1 GDScript track.
  • Forward‑looking notes about a potential 6.x GDScript story (kept here as planning docs, not commitments).

Out of scope:

  • 6.0 C#‑first architecture docs (those live under the main GridPlacement docs and internal architecture docs).

Structure

Workflow entrypoints (do this first)

The GDScript 5.1 track is validated via short, repo-local workflow scripts (so you don’t have to remember long commands).

1
2
3
4
5

# GDScript demo + plugin “doctor” (scan + smoke/full)
./scripts/testing/demo_doctor.sh --help

# Typical daily gate
./scripts/testing/demo_doctor.sh all

Configuration lives here:

  • scripts/testing/demo_doctor.yaml

5.1 (current legacy GDScript line)

  • ROADMAP.md – 5.0 / 5.1 GDScript‑specific roadmap (uses the /roadmap workflow format).
  • HEALTH.md – 5.0 / 5.1 GDScript track health score and notes (uses the /health workflow format).
  • GDSCRIPT_5_1_REMAINING_WORK.md – concrete, high‑value remaining work for the 5.1 GDScript line.

6.x (future / planning only)

  • GDSCRIPT_6_0_PLAN.md – forward‑looking 6.x GDScript plan (addon + migration tooling), scoped as optional and secondary to the 6.x C# line.

  • Additional 5.0/5.1 GDScript docs should be migrated or referenced here over time so this folder remains the single source of truth for internal GDScript documentation.

When adding or updating GDScript docs for 5.0/5.1:

  • Prefer placing them in this folder (or subfolders) instead of scattering them across other doc trees.
  • Cross‑link from public docs (if needed) back to these internal notes when extra detail is helpful.

Canonical naming and addon path (5.1)

  • Product / plugin name (docs, config, UI): Grid Placement.
  • Godot addon folder path (for 5.1 and 6.0): res://addons/grid_building.
  • Keep the folder name grid_building for compatibility with existing demos and projects.
  • Use Grid Placement as the canonical name in web docs, configuration, and any new references.
  • Canonical repo edit location (runtime addon): plugins/gameplay/GridPlacement/gdscript/grid_building (and plugins/gameplay/GridPlacementInventory/gdscript/grid_building_inventory for inventory).
  • Demo consumers (do not treat as canonical source):
    • Demo runtime addon: demos/grid_building_dev/godot/addons/grid_building
    • Demo inventory addon: demos/grid_building_dev/godot/addons/grid_building_inventory
    • These are updated from the plugin sources via export/copy/sync scripts.

Global script classes (class_name) and mirrors

  • Define and edit global script classes (class_name) in the canonical plugin sources under plugins/gameplay/GridPlacement/gdscript/grid_building and plugins/gameplay/GridPlacementInventory/gdscript/grid_building_inventory.
  • The mirrored plugin scripts under plugins/gameplay/GridPlacement/gdscript/grid_building and plugins/gameplay/GridPlacementInventory/gdscript/grid_building_inventory may appear as duplicate global classes to IDE language servers when both the demo and plugin workspaces are open. Treat this as tooling noise, not a signal to edit the mirrors.
  • When renaming or adjusting a global script class, change the canonical plugin script first, then re-sync the demo copy; do not hot-patch only the demo copy.
  • If an editor reports “Class X hides a global script class” while working in the plugin tree, double-check that you are editing the demo copy. Fixes and refactors belong in the canonical addon, not in the mirror.

Pattern: do not preload() class_name scripts

  • Prefer calling global script classes by their class_name symbol directly (for example IndicatorSetupUtils.some_static_call()), instead of preloading the .gd just to access static functions.
  • Rationale: this keeps the codebase consistent with Godot’s global class model and avoids unnecessary path coupling.

Fixing “Class X hides a global script class” in the editor

  • This is commonly caused by having multiple copies of the same addon indexed (for example both the demo addon and the canonical plugin sources), or by stale .godot class caches.
  • Preferred fix: ensure you only have one active addon copy being indexed by your editor.
  • If the issue persists in a Godot project, deleting the project cache (the .godot/ folder) typically resolves it.

Support policy (5.1 vs 6.0)

  • GridPlacement 5.1 GDScript is a legacy, maintenance‑mode track: bugfix‑only, no new features.
  • GridPlacement 6.0 C# is the canonical implementation for new projects and long‑term support.
  • When planning changes:
    • Prefer investing in the 6.0 C# line unless a bug directly affects existing 5.1 users.
    • Use the 5.1 docs here as operational history and maintenance guidance, not a roadmap for new features.
  • Related documentation:
    • 5.1 roadmap: docs/content/gridbuilding/GRIDBUILDING_5_1_GDSCRIPT_ROADMAP.md.
    • GDScript → C# migration overview: docs/content/gridbuilding/GDSCRIPT_TO_CSHARP_MIGRATION.md.
  • Demo projects may use symlinks for fast iteration.
  • Anything intended to be portable (zip exports, release artifacts) must not ship symlinks.
  • Runbook: demos/grid_building_dev/godot/README_ADDON_WORKFLOW.md.