UI Components (6.0)

Overview

This guide shows how to use the Placeable Selection UI in the GridPlacement 6.0 C# plugin.

The goal is to:

• Display a list/grid of available placeables (single items and upgrade sequences).
• Let the player pick a placeable.
• Enter build mode for the selected placeable using the 6.0 services.

The implementation uses:

• Core services:
  • IPlaceableCatalog: The source of truth for available items.
  • SelectionAdapter: Pure C# logic for filtering and selecting items.
  • PlacementModeService: Tracks “which thing am I trying to place?”.
• Godot adapters:
  • PlaceableSelectionPanel: A Godot Control node that wraps the SelectionAdapter.

1. Prerequisites

Ensure a GPUserScopeRoot is in your scene (see Quick Start). This node initializes the ServiceRegistry required by the UI components.

2. Add a PlaceableSelectionPanel

In your UI scene (e.g. HUD or build menu):

1. Create a Control node.
2. Attach the C# script GridPlacement.Godot.UI.PlaceableSelectionPanel.
3. (Optional) Set InitialCategoryFilter in the inspector, e.g. buildings.

On _Ready, the panel will:

• Resolve ServiceRegistry from GPUserScopeRoot.
• Resolve IPlaceableCatalog and PlacementModeService.
• Create a SelectionAdapter and call Initialize().
• Apply the optional InitialCategoryFilter.

Note: The panel does not create buttons automatically. It exposes the catalog data and selection signal so you can build your own UI layout (buttons, grid cells, etc.).

3. Building your UI

From GDScript or C# (Godot side), you can:

• Read the available items: panel.Adapter.AvailableItems.
• Read filtered items: panel.Adapter.FilteredItems.
• Connect to PlaceableSelected to react when a player picks something.

Example (C#)

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37

using Godot;
using GridPlacement.Godot.UI;
using GridPlacement.Core.Catalog;

public partial class BuildMenu : Control
{
    private PlaceableSelectionPanel? _panel;

    public override void _Ready()
    {
        _panel = GetNode<PlaceableSelectionPanel>("PlaceableSelectionPanel");
        
        // Wait for panel to initialize if needed, or ensure order of execution
        if (_panel?.Adapter == null)
        {
            GD.PushError("BuildMenu: PlaceableSelectionPanel not initialized.");
            return;
        }

        _panel.PlaceableSelected += OnPlaceableSelected;

        // Create buttons for each item
        foreach (var entry in _panel.Adapter.FilteredItems)
        {
            var btn = new Button();
            btn.Text = entry.DisplayName;
            btn.Pressed += () => _panel.SelectPlaceable(entry.Id);
            AddChild(btn);
        }
    }

    private void OnPlaceableSelected(string placeableId)
    {
        GD.Print($"BuildMenu: Player selected {placeableId}, entering build mode.");
        // The PlacementModeService is automatically updated by the SelectionAdapter.
    }
}

4. Interaction with Placement

• SelectionAdapter calls PlacementModeService.BeginPlacement(placeableId).
• PlacementModeService stores CurrentPlaceableId and sets IsInPlacementMode = true.
• Your targeting / manipulation systems should query PlacementModeService to know what to preview.

5. Customizing the Catalog

The default catalog is populated by PlaceableCatalogBootstrap. For a real game, you will likely want to register your own IPlaceableCatalog implementation in the ServiceRegistry before the UI initializes, or populate the default one with your own data.