Engine Integration Guide

GridPlacement 6.0 is built on a Dual-Layer Architecture that separates pure simulation logic from engine-specific presentation. This guide explains how to bridge these layers effectively.

1. The Integration Boundary

The boundary between the Core and the Engine is managed through Bridges and Adapters.

sequenceDiagram
    participant UI as Godot UI/Input
    participant Bridge as Engine Bridge (Node)
    participant Adapter as Logic Adapter (C#)
    participant Workflow as Core Workflow (POCO)
    participant Service as Domain Service

    UI->>Bridge: Input Event
    Bridge->>Adapter: Translate to Core Types
    Adapter->>Workflow: Execute Request
    Workflow->>Service: Algorithmic Task
    Service-->>Workflow: Result
    Workflow-->>Adapter: Data Snapshot
    Adapter-->>Bridge: Domain Event
    Bridge-->>UI: Godot Signal / Visual Update

2. Key Integration Components

GPUserScopeRoot (Composition Root)

In Godot, the GPUserScopeRoot node serves as the primary entry point. It:

• Initializes the ServiceRegistry.
• Registers core modules (Targeting, Placement, Manipulation).
• Manages the IUserScope for multitenancy (e.g., local split-screen or multiple independent grids).

Engine Bridges

Bridges are engine-specific components (e.g., Godot Nodes) that sit in the scene tree. Their primary job is:

• Conversion: Converting Vector2 to CoreVector2, InputEvent to InputEventData.
• Lifecycle: Forwarding _process or _physics_process ticks to the logic layer.
• Signals: Translating C# Domain Events into engine-native signals.

3. Communication: C# Events to Godot Signals

The Core layer is reactive. When a building is placed or a target changes, the Core publishes a Domain Event.

Example Integration (GDScript)

1
2
3
4
5
6
7

# Connecting to a Bridge node
func _ready():
    var placement_bridge = get_node("PlacementBridge")
    placement_bridge.placement_executed.connect(_on_placement_confirmed)

func _on_placement_confirmed(report):
    print("Object placed successfully at: ", report.position)

4. First-Class Identity & Sessions

6.0 treats identity as a core concern.

• GPUserId: A unique identifier for a controller or player.
• IUserScope: An isolated container for state belonging to that ID.
• IGridBuildingSession: Manages the lifetime of a specific placement/manipulation session.

This allows the same Core DLL to handle multiple players or complex UI-preview scenarios without state leakage.

5. Implementation Checklist

1. Scene Setup: Ensure GPUserScopeRoot is at the top of your gameplay subtree.
2. Configuration: Assign your GridTargetingSettings resource to the appropriate bridge.
3. Input Mapping: Define your logical actions in an InputConfiguration.
4. Event Wiring: Connect your UI and VFX systems to the GPEventBus or specific Bridge signals.

Last updated: 2025-12-22