Tile Placement Mode Guide

This guide explains how to configure and switch between tile placement modes using the GridMode enum.

What is a Placement Mode?

A placement mode determines what action the player can perform on the grid. The GridMode enum defines all available modes:

ModePurposeTypical Workflow
OffSystem disabledNo interactions
InfoHover to inspectTooltip display
PlacePlace new objectsSelect blueprint → click to place
MoveRelocate and/or rotate existing objectsDrag to move, click to rotate
RemoveDelete objectsClick object to demolish
EditModify propertiesSelect → edit panel
SelectMulti-selectClick + drag selection
InspectDetailed viewRich UI panel
ResizeChange dimensionsDrag handles
RotateRotate objectsClick to cycle 90°
PaintTerrain paintingBrush strokes

Switching Modes

1
2
3
4
5

// Via IModeService
modeService.SetMode(GridMode.Place);

// Or via PlacementBootstrap
placementBootstrap.ModeService.SetMode(GridMode.Place);

Mode-Service Architecture

The IModeService interface manages mode transitions:

1
2
3
4
5
6

public interface IModeService
{
    GridMode CurrentMode { get; }
    void SetMode(GridMode mode);
    event EventHandler<ModeChangedEvent>? ModeChanged;
}

Context Wiring

Each mode requires different services to be wired in PlacementContext:

1
2
3
4
5

// Place mode needs: Catalog, PlacementSystem, TerrainProvider
context.ModeService.SetMode(GridMode.Place);

// Move mode needs: ManipulationService, GridOccupancy
context.ModeService.SetMode(GridMode.Move);

Mode-Specific Configuration

Place Mode

1
2
3

[Export] public IPlaceableCatalogAdapter? Catalog { get; set; }
[Export] public PlacementSettings? Settings { get; set; }
[Export] public TerrainPlaceabilityMap? TerrainSettings { get; set; }

Move Mode

1
2

[Export] public IManipulationService? ManipulationService { get; set; }
[Export] public IGridOccupancy? GridOccupancy { get; set; }

Remove Mode

1
2

[Export] public PlacementSettings? Settings { get; set; }
// No terrain validation needed - just check occupancy

Terrain-Aware Placement

When Place mode is active, terrain validation ensures objects are only placed on valid terrain:

1
2
3
4
5
6
7

// TerrainPlaceabilityMap defines allowed terrain IDs
var terrainMap = new TerrainPlaceabilityMap
{
    AllowedTerrainIds = new[] { 0, 1, 3 }  // Grass, Dirt, Stone
};

context.TerrainSettings = terrainMap;

The TerrainTypeRule validates placement:

1
2
3

var tileData = tileMap.GetCellTileData(cell);
int terrainId = tileData.Terrain;
bool isValid = terrainMap.IsTerrainAllowed(terrainId);

UI Button Wiring

1
2
3
4
5
6
7
8
9

public partial class ModeToggleButton : Button
{
    [Export] public GridMode TargetMode { get; set; }

    public override void _Pressed()
    {
        PlacementSignals.ModeChanged?.Invoke(this, TargetMode);
    }
}