Tilemaps

The tilemap system lets you paint tile-based worlds using auto-tiling masks, multiple layers, and wall extrusion with built-in collision generation.

Adding a Tilemap

Add a Tilemap_Component to any entity. The tilemap is centered on the entity's position and spans a grid of chunks (each 32×32 tiles). The total size in tiles is width_in_chunks × 32 by height_in_chunks × 32.

Tilemap Properties

Property	Description
Width / Height in Chunks	Size of the tile grid. Each chunk is 32×32 tiles. A 10×10 tilemap gives 320×320 tiles.

Layers are configured individually once you enter editing mode (see below).

Editing Mode

Select the tilemap entity and click the Edit button in the inspector to enter tilemap editing mode. Click Cancel to exit. Editing mode deactivates automatically if you deselect the entity.

While editing, a red border outlines the tilemap bounds and a grid overlay is drawn in the scene view.

Tools

The tilemap editor has three tool modes, switched via hotkeys:

Tool	Hotkey	Description
Brush	B/W	Paint tiles by clicking and dragging.
Eraser	E	Remove tiles by clicking and dragging.
Stamp	S/R	Select a region to copy, then paste it elsewhere.

You can also hold Shift while in Brush mode to temporarily erase.

Brush Painting

Click and drag to paint tiles on the selected layer. The brush uses Bresenham line interpolation between frames so you never skip tiles even when moving fast.

Brush size is adjusted with [ and ] (range 1–32). The brush is circular — tiles within the radius are affected.

Alt+click draws a straight line from your last click position to the current tile, useful for long straight edges.

Ctrl+drag switches to rectangle fill mode — drag to define a rectangle, and all tiles in the region are filled (or erased if Shift is also held) when you release.

Layers

Each tilemap supports multiple layers. Click a layer in the inspector to select it for painting. The selected layer is highlighted in blue.

Adding and Removing Layers

• Click Add Layer at the bottom to create a new layer.

• Click Remove Layer inside a layer's panel to delete it.

Layer Properties

Property	Description
Kind	Ground or Wall. Ground tiles are flat; Wall tiles extrude vertically.
Layer Mode	Default uses automatic layering (ground behind player, walls Y-sorted). Manual lets you set a fixed render layer value.
Manual Layer	Only shown in Manual mode. The explicit render layer value.
Tile Size	Visual size of each tile in world units.
Textures	One or more textures with weights for randomized variety. The engine hashes tile coordinates to deterministically pick a texture per tile based on the weights.
Mask	An 8×8 grid texture used for auto-tiling. Each cell corresponds to a different adjacency configuration (edges, corners, isolated, etc.). A default map is included $AO/tile_mask.png
Outline	Color for tile outlines (alpha 0 = no outline).

Multi-Texture Variety

Each layer can have multiple textures with weights. Tiles deterministically select a texture variant based on a hash of their grid coordinates, so the pattern is stable across saves and doesn't shift when you add/remove tiles.

Adjust the weight value next to each texture to control how frequently it appears relative to others.

Auto-Tiling

Tiles automatically select the correct mask cell based on their 8-directional neighbor configuration. The system:

1. Checks all 8 neighbors (N, NE, E, SE, S, SW, W, NW).

2. Diagonal neighbors only count if both adjacent cardinal neighbors are present (prevents visual artifacts at corners).

3. Maps the resulting 8-bit adjacency mask to one of 64 cells in the 8×8 mask texture.

This means you only need to paint tile presence — the correct edge, corner, and interior visuals are computed automatically.

Wall Layers

Setting a layer's kind to Wall enables vertical extrusion. Wall tiles are placed on the grid like ground tiles, but each placed tile generates a column of body tiles extending upward by the Wall Height.

Wall Properties

Property	Description
Wall Height	Number of tiles tall each wall column is (minimum 2).
Top Texture	Separate texture for the top row of the wall (the "cap").
Top Mask	Mask texture for the wall top (uses the same 8-neighbor auto-tiling as ground).
Top Outline	Outline color for the wall top tiles.

Wall body tiles use the layer's main texture and a separate neighbor mask computed within each row's ownership. Wall tops use the adjacency of the base placement row, giving clean cap edges.

Walls are Y-sorted by their base row, so players walk behind walls above them and in front of walls below.

Wall Collision

Property	Description
Collision	Enable/disable physics collision generation for this wall layer.
Inset	Shrinks collision edges inward from tile boundaries for tighter-fitting collision.
Offset	Shifts all collision edges by a fixed amount.
Debug Draw	Draws green collision edges in the scene view for debugging.

When collision is enabled, the engine automatically:

1. Generates edge segments along exposed tile boundaries.

2. Merges collinear edges to minimize segment count.

3. Groups connected edges into closed shapes.

4. Creates Box2D segment shapes at runtime (editor shows debug visualization only).

Stamp Tool (Copy & Paste)

Press S to switch to Stamp mode. This enables a region selection workflow:

1. Select: Click and drag to highlight a rectangular region. The selected tiles are copied to the clipboard. A "Copied" popup confirms the action.

2. Paste: Press Ctrl+V to enter ghost mode. A translucent preview of the clipboard follows your cursor.

3. Rotate: Scroll the mouse wheel to rotate the ghost preview in 90-degree increments.

4. Place: Click to stamp the tiles. Hold Shift while clicking to place multiple copies without exiting ghost mode.

5. Cancel: Press Escape to exit ghost mode without placing.

Hold Ctrl while starting a stamp selection to copy tiles from all layers at once, preserving multi-layer structures.

Keyboard Shortcuts Summary

Shortcut	Action
B	Switch to Brush tool
E	Switch to Eraser tool
S	Switch to Stamp tool
Shift (held)	Temporarily erase while in Brush mode
[ / ]	Decrease / increase brush size
Ctrl+drag	Rectangle fill (or erase with Shift)
Alt+click	Draw straight line from last click
Ctrl+V	Enter paste/ghost mode
Scroll wheel	Rotate ghost preview (in ghost mode)
Shift+click	Place multiple copies (in ghost mode)
Escape	Cancel ghost mode