# 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                     |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.allout.game/using-the-editor/tilemap.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.