This guide walks you through setting up GridPlacement 6.0 (C# runtime) and making your first placement in about 10 minutes.

Prerequisites

  • Godot 4.4+ with .NET 8 support enabled
  • A C# Godot project (not GDScript-only)

1. Install the Plugin

Copy addons/grid_placement/ into your Godot project's addons/ folder:

your-godot-project/
└── addons/
    └── grid_placement/
        ├── Godot/                  ← C# Godot adapter layer
        ├── Core/                   ← Core placement logic (no engine deps)
        ├── ECS/                    ← ECS components and systems
        └── plugin.cfg

Enable the addon in Project → Project Settings → Plugins.

2. Create the Provider Resource

GridPlacementProvider is a Godot Resource that owns all placement services. Create one per active runtime:

  1. Create the resource: Right-click in FileSystem → Create New → Resource → search for GridPlacementProvider
  2. Configure it in the Inspector:
    • Set grid dimensions via GridSize
    • Assign your TileMapLayer to TargetTileMap (on the bootstrap node, not the provider)

3. Wire the Scene Hierarchy

The minimum viable scene:

MainLevel (Node2D)
├── TileMapLayer                    ← Your game ground layer
├── GridCursor2D                    ← Cursor input node (see Input & Cursor guide)
│   └── PlacementPreviewLayer       ← Auto-created by cursor
└── MyGameBootstrap (Node)          ← Your composition root

Add [Export] references in your bootstrap:

public partial class MyGameBootstrap : Node
{
    [Export] public GridPlacementProvider? Provider { get; set; }
    [Export] public GridCursor2D? Cursor { get; set; }
}

4. Initialize and Place Your First Building

public override void _Ready()
{
    // Initialize the provider (creates ECS store + PlacementBootstrap internally)
    Provider!.Initialize();

    // Register placeables
    Provider.AddCatalogEntry(new ManipulationEntryData
    {
        Id = "wooden_house",
        Name = "Wooden House",
        Category = "buildings"
    });

    // Wire the cursor to the provider's bootstrap
    if (Cursor != null)
        Cursor.Context = Provider.Bootstrap;

    // Select a placeable for placement
    var entry = new ManipulationEntryData { Id = "wooden_house", Name = "Wooden House" };
    Provider.Bootstrap!.SelectPlaceable(entry);

    // Wire placement events
    Provider.Bootstrap.PlacementSignals.EntityPlaced += (args) =>
        GD.Print($"Placed entity {args.EntityId} at {args.Position}");
}

Cursor input is handled by GridCursor2D — it reads Input Map actions for confirm/cancel/directional movement. See the [Input & Cursor]({{% ref "input-cursor" %}}) guide for full configuration.

5. Game Feel Hooks

GridPlacement handles validation and state. You handle the feedback. Wire these events to make placement feel satisfying:

Placement Events

Provider.Bootstrap.PlacementSignals.EntityPlaced += OnPlacementSuccess;
Provider.Bootstrap.PlacementSignals.PreviewUpdated += OnPreviewUpdated;

Manipulation Events

Provider.Bootstrap.ManipulationSignals.ManipulationStarted += OnManipulationStarted;
Provider.Bootstrap.ManipulationSignals.ManipulationSuccess += OnManipulationSuccess;
Provider.Bootstrap.ManipulationSignals.ManipulationFailed += OnManipulationFailed;
Provider.Bootstrap.ManipulationSignals.ManipulationCancelled += OnManipulationCancelled;

Quick Game Feel Patterns

Effect How
Sound Play placement sound on EntityPlaced, error buzz on rejection
Ghost tint Green when PreviewUpdated.IsValid, red when invalid
Camera bounce Small upward punch on successful place
Tooltip Show rejection reason on invalid preview

See the [Composition + Injection]({{% ref "composition-and-injection" %}}) guide for full event reference.

6. Input Configuration

GridCursor2D uses a CursorInputSettings resource for all input action bindings. Create one and assign it to the cursor's InputSettings export:

var inputSettings = new CursorInputSettings
{
    ConfirmAction = "place",
    CancelAction = "cancel",
    UpAction = "ui_up",
    DownAction = "ui_down",
    LeftAction = "ui_left",
    RightAction = "ui_right"
};
Cursor.InputSettings = inputSettings;

All actions must be defined in Project → Project Settings → Input Map.

What's Next?

  • [Architecture Overview]({{% ref "architecture-overview" %}}) — Understand the Core / ECS / Godot adapter boundary
  • [Input & Cursor]({{% ref "input-cursor" %}}) — Configure cursor, drag-to-place, keyboard input
  • [Catalog Construction]({{% ref "catalog-construction" %}}) — Build placeable catalogs from code, .tres, or JSON
  • [Settings Architecture]({{% ref "settings" %}}) — Configure grid, input, and rules
  • [Placement Rules]({{% ref "placement-rules" %}}) — Configure validation rules
  • API Reference — Full C# API documentation

Last Updated: 2026-06-01