tile-grid

Programmatic Tile Grid

Use this skill when the grid is created at runtime in C#, not loaded from a .tmx file. Typical cases: city builders, procedural dungeons, puzzle games, cellular automata.

If you have a designer-authored level in Tiled, use the levels and tmx skills instead. For axial pointy-top or flat-top cells, use the hex-grid skill; the square-grid coordinate arithmetic below does not apply.

---

Data / Visual Split (Required Pattern)

Keep the authoritative state in a C# array and the visuals as a separate layer. Never derive game logic from what's drawn on screen.

// Data layer — the truth:
public enum TileType { Empty, Road, ZoneR, ZoneC, ZoneI, PowerPlant, WaterTower }

private TileType[,] _tiles;        // [col, row] indexed
private int _cols, _rows;
private float _tileSize;
private Vector2 _gridOrigin;       // world position of tile (0,0) center

// Visual layer — one RectangleRuntime per visible tile:
private RectangleRuntime?[,] _visuals;

Always update _tiles first, then sync the visual. Never infer tile type from the visual's color.

---

Grid Setup

_cols       = 128;
_rows       = 128;
_tileSize   = 16f;
// Center the grid at world origin:
_gridOrigin = new Vector2(-(_cols * _tileSize) / 2f + _tileSize / 2f,
                          -(_rows * _tileSize) / 2f + _tileSize / 2f);

_tiles   = new TileType[_cols, _rows];
_visuals = new RectangleRuntime[_cols, _rows];

_gridOrigin is the center of tile (0,0). Add col * _tileSize / row * _tileSize to get centers of other tiles.

---

World ↔ Tile Coordinate Conversion

This is the most-called math in any tile game. Use Math.Floor — not (int) cast — to handle negative world coordinates correctly.

// World position → tile indices (returns false if out of bounds):
bool WorldToTile(Vector2 worldPos, out int col, out int row)
{
    col = (int)Math.Floor((worldPos.X - _gridOrigin.X + _tileSize / 2f) / _tileSize);
    row = (int)Math.Floor((worldPos.Y - _gridOrigin.Y + _tileSize / 2f) / _tileSize);
    return col >= 0 && col < _cols && row >= 0 && row < _rows;
}

// Tile indices → world center position:
Vector2 TileToWorld(int col, int row)
    => new Vector2(_gridOrigin.X + col * _tileSize,
                   _gridOrigin.Y + row * _tileSize);