GridPlacement Class Mapping (Legacy GDScript ↔ v6 C#)
GridPlacement Class Mapping — Legacy (GDScript / v5) ↔ v6 C#
This document mirrors the structure of WORLD_TIME_CLASS_MAPPING.md and acts as the
canonical type mapping for GridPlacement (formerly GridBuilding).
Use it when:
- Porting legacy GDScript tests → C# Core / Godot tests.
- Fixing missing-type errors during the v5→v6 migration.
- Interpreting references in
LEGACY_GDSCRIPT_GDUNIT_MIGRATION.mdandGRIDBUILDING_TEST_HEALTH.md.
1. Building → Placement Domain (Tests note)
| Legacy Concept (GDScript / v5) | v6 C# Core Type(s) | Godot / Engine Layer | Notes |
|---|---|---|---|
BuildingSystem (systems/building/**) | Placement system logic under GridBuilding.Core.Systems.Placement (e.g. PlacementWorkflowOrchestrator, IPlacementService) | Godot wrappers in GridBuilding.Godot.Systems.Placement.* | v6 treats “building” as placement; new work should target placement services/state, not a separate building system. |
placement_workflow_orchestrator.gd (systems/orchestrator/placement_workflow_orchestrator.gd) | GridBuilding.Core.Systems.Placement.PlacementWorkflowOrchestrator | Godot nodes call into orchestrator and apply returned effects | Non-Node application-layer orchestrator. Coordinates placement validation + indicators + commit, but should not own engine nodes. |
manipulation_workflow_orchestrator.gd (systems/orchestrator/manipulation_workflow_orchestrator.gd) | (planned) GridBuilding.Core.Systems.Manipulation.ManipulationWorkflowOrchestrator | Godot nodes call into orchestrator and apply returned effects | Mirrors the GDScript workflow orchestrator pattern for move/rotate/demolish. If/when ported, keep it non-Node + session-scoped. |
BuildingService | GridBuilding.Core.Services.Placement.IPlacementService, PlacementService | Godot adapters that call into IPlacementService | Service responsible for validating and executing placement operations. |
BuildingState (GDScript) | GridBuilding.Core.State.Placement.PlacementState (replaces deprecated BuildingState) | Godot nodes that visualize placement state | v6 canonical state is PlacementState; legacy BuildingState remains only as an obsolete shim. |
BuildingMode, ManipulationMode enums | GridBuilding.Core.Types.GridMode | UI flows/events driven by GridMode | Replace UI/state listeners on BuildingMode/ManipulationMode with GridMode; modes map 1:1 (Build→Place, Move→Move, Demolish/Remove→Remove, Info/Inspect→Inspect). |
GBEnums.Mode (GDScript) | GridBuilding.Core.Types.GridMode | N/A | 5.1 intentionally keeps GBEnums (GDScript) as the stable public enum surface to avoid class_name flood. 6.0 C# has no GBEnums shim; reference GridMode directly. Preferred mapping: GBEnums.Mode.OFF→GridMode.Off, INFO→Info, BUILD→Place, MOVE→Move, DEMOLISH→Remove. |
Godot BuildingBehavior, IBuildingService, BuildingService | PlacementWorkflowOrchestrator + IPlacementService | Godot placement-focused behaviors | Replace Godot building behaviors/services with placement workflow orchestrator + service calls; remove Godot building service registrations. |
2. Dependency Injection & Composition
| Legacy Concept | v5 Location | v6 C# Core Concept | v6 Godot Concept | Notes |
|---|---|---|---|---|
GBCompositionContainer (GDScript resource) | core/resources/gb_composition_container.gd | GridBuilding.Core.Interfaces.ICompositionContainer, GridBuilding.Core.Services.DI.ServiceRegistry | GridBuilding.Godot.Services.DI.CompositionContainer | In v6 C#, composition is handled by C# DI/service registries. The Godot CompositionContainer class is a thin adapter around core DI and should not contain game logic. |
Injectable factories / Injectable attribute | gb_injectable_factory.gd, Injectable attributes | DI helpers under Services.DI (constructor injection + ServiceRegistry) | GridBuilding.Godot.Infrastructure.GBInjectableFactory, InjectorSystem | GDScript 5.1 intentionally keeps the GB InjectorSystem model for simplicity. v6 C# prefers constructor injection and explicit service registration; GB Injector concepts are kept only as legacy shims on the C# side. |
Godot DI shims (SystemsComponent, IGodotControl, IGodotNode, IGodotSystem) | Various Godot base/iface files | Service composition via ServiceRegistry | Obsolete ResolveGbDependencies(CompositionContainer) methods kept as shims | New C# code and tests should obtain services via ServiceCompositionRoot + ServiceRegistry or explicit constructor/property injection. The ResolveGbDependencies methods are marked [Obsolete] and exist only for migration. |
InjectorSystem, GBInjectableFactory.Create*, Godot Injectable base | GDScript/Godot DI helpers | Constructor injection + ServiceCompositionRoot/ServiceRegistry | Godot nodes resolve via ServiceCompositionRoot.GetGlobalRegistry() | For GDScript 5.1, this remains the primary pattern. For C# 6.0, treat these as legacy only and wire new integrations via the registry and explicit constructors/properties. |
When a Godot file references CompositionContainer and the type is missing:
- Prefer wiring through core services (
IPlacementService,IGridTargetingSystem, etc.). - Only keep
CompositionContainerwhere it serves as a simple DI adapter over the core.
3. Logging & Debug Settings
| Legacy Concept | v5 Location | v6 C# Core Type(s) | Godot / Engine Layer | Notes |
|---|---|---|---|---|
gb_logger + debug flags | core/logging/gb_logger.gd, project settings | GridBuilding.Core.Logging.DebugSettings, ILogger and friends | GridBuilding.Godot.Logging.Logger, GridBuilding.Godot.Engine.Debug.GridTargetingDebugTextTemplate | Core DebugSettings is now the canonical configuration object for log levels and debug behavior. Godot logging nodes should depend on IDebugSettings / ILogger rather than hard-coded flags. |
| Per-suite debug toggles in tests | Various GdUnit tests | DebugSettings instances passed into services under test | N/A | When porting, prefer constructing DebugSettings in tests instead of manipulating engine globals or singletons. |
Key v6 type:
GridBuilding.Core.Logging.DebugSettingsimplementsIDebugSettingsand controls which log levels are enabled, including verbose/trace behavior. It is pure C# and safe to use in Core tests.
4. Actions & Input Layer
| Legacy Concept | v5 Location | v6 C# Core Type(s) | Godot / Engine Layer | Notes |
|---|---|---|---|---|
Actions (GDScript helper for action names / validation) | Core/State/Actions.gd (and various UI scripts) | GridBuilding.Core.Contexts.Actions (placeholder), future input/command abstractions | GridBuilding.Godot.Systems.UI.Actions.* (ActionBar, ActionButton, ActionLog) | The v6 Actions class is currently a placeholder; input handling is being refactored toward clearer command/services interfaces. |
Input adapter wiring (GDScript / Godot)
- Prefer explicit
preload()of adapter scripts (path-first) when you need a type reference. - Prefer absolute
res://...preload paths for shared addon code (avoids fragile relative-path behavior). - Avoid relying on
class_namefor adapter types unless you have verified there are no duplicate global script classes in the project.- Godot will emit errors like
Class "X" hides a global script classwhen duplicates exist.
- Godot will emit errors like
- If you see filesystem errors like
too many levels of symbolic linkswhen opening adapter scripts, it usually indicates a symlink loop in the addon folder; fix the loop before attempting to standardize preloads.
When you see missing Actions references in Godot code:
- Prefer mapping those behaviors to placement/manipulation commands and explicit service calls.
- UI nodes (e.g.
ActionBar) should call command/services that live in Core rather than relying on a fatActionsbag-of-strings.
5. Owner & Contexts
| Legacy / Bridge Concept | v5 Location | v6 C# Core Type(s) | Godot / Engine Layer | Notes |
|---|---|---|---|---|
owner_context (GDScript) | core/contexts/owner_context.gd | GridBuilding.Core.Domain.State.IOwner, IOwnerContext, Owner helper + OwnerContext | Godot owner nodes (player, camera, etc.) passed in via adapters | Owner information is now modeled as a small core interface (IOwner) and context (Owner/OwnerContext), decoupled from Godot Node. Tests should mock IOwner instead of using real nodes. |
gb_contexts (GDScript aggregate) | core/contexts/gb_contexts.gd | GridBuilding.Core.Domain.State.Contexts (obsolete but still available) + separate IndicatorContext, OwnerContext, SystemsContext | Godot integration should prefer IUserScope + services instead of Contexts bundles | The Contexts aggregate is marked [Obsolete] in v6 but still used in some tests; new code should favor IUserScope and explicit context/services. |
GBUser (GDScript bridge) | core/contexts/gb_user.gd | GridBuilding.Core.Domain.State.Owner, IOwner | Godot node attached to player/agent roots | 5.1 bridge name that matches 6.0 “user” terminology while reusing the legacy GBOwner implementation. Prefer GBUser for new GDScript code; keep GBOwner for backwards compatibility. |
GBUserScope (GDScript bridge) | core/contexts/gb_user_scope.gd | GridBuilding.Core.Interfaces.IUserScope, GridBuilding.Core.Types.UserId | Per-user scope/state in GDScript | Bridge alias over GBOwnerContext that uses the 6.0 user-scope naming. Prefer this type name in new docs/tests when referring to per-user scope. |
GBSession (GDScript bridge) | core/resources/gb_session.gd | GridBuilding.Core.Interfaces.IGridBuildingSession, IServiceContext | Session/composition adapter on the Godot side | Thin alias over GBCompositionContainer that uses the 6.0 “session” terminology for a single match/world. New docs and examples can talk in terms of sessions while continuing to use the same underlying resource. |
6. Where to Update When Types Move
Whenever you rename/move a type that comes from the legacy GridBuilding plugin, update all of the following:
- Class mapping document (this file) – add or adjust the row so the mapping stays canonical.
- Legacy GDScript migration table
- GridPlacement test health doc
- Quarantine status
7. Test migration & deletion rules (summary)
- Use
LEGACY_GDSCRIPT_GDUNIT_MIGRATION.md+GRIDBUILDING_TEST_HEALTH.mdas the canonical source for test value scores and migration status. - When a legacy test scores < 8/10, prefer:
- Deleting it (if behavior is obsolete), or
- Replacing it with a smaller, clearer test over the mapped v6 types.
- When a test is deleted or rewritten around new types:
- Update the corresponding mapping rows here if types changed.
- Ensure new tests reference the v6 Core types in this table, not legacy GDScript-only types or bridge-layer shims.
8. GDScript class_name docstring convention
- For each GDScript file that declares a
class_namein the 5.1 bridge:- Add a brief docstring above the
class_namethat:- Points back to this mapping file, and
- Names the canonical C# type(s) it corresponds to.
- Add a brief docstring above the
9. Targeting Positioner naming (v6 parity)
- Canonical naming for the grid targeting positioner logic is
PositionerService2D(GDScript) and should remain the equivalent of the C# 2D positioning core once ported. - Godot-side Nodes remain adapters/controllers (e.g.
GridPositioner2D,GridPositionerAdapter2D,TargetingController2D). - Best-pattern input wiring is:
ServiceRegistry(C#) / injector (GDScript) → input routing → positioner adapter signals → pure logic service.