# TileMap

SimVX provides grid-based 2D level design through three classes: `TileSet` (tile definitions), `TileMapLayer` (a single grid layer), and `TileMap` (a Node2D container with multiple layers).

## TileData

Each tile in a `TileSet` is described by a `TileData` dataclass:

| Field | Type | Description |
|-------|------|-------------|
| `texture_region` | `(x, y, w, h)` | Rectangle in the texture atlas |
| `collision_shapes` | `list` | Polygon vertices for collision |
| `navigation_polygon` | `list \| None` | Walkable polygon for pathfinding |
| `custom_data` | `dict` | Arbitrary per-tile metadata |
| `animation_frames` | `list[int] \| None` | Tile IDs for animated tiles |
| `animation_speed` | `float` | Animation FPS (default 5.0) |
| `terrain_type` | `str` | Terrain label for auto-tiling |
| `terrain_set` | `int` | Which terrain set this tile belongs to |
| `terrain_bits` | `int` | Bitmask for auto-tile neighbor matching |

## TileSet

A `TileSet` holds tile definitions and terrain auto-tile rules:

```python
from simvx.core import TileSet, TileData

ts = TileSet(tile_size=(16, 16))

# Add tiles manually
grass = ts.add_tile(TileData(texture_region=(0, 0, 16, 16), terrain_type="grass"))
water = ts.add_tile(TileData(texture_region=(16, 0, 16, 16), terrain_type="water"))

# Or auto-create from a grid atlas (256x256 image, 16x16 tiles)
tile_ids = ts.create_from_grid(atlas_width=256, atlas_height=256)
```

## TileMapLayer

A `TileMapLayer` stores tiles in 32x32 chunks for efficient large-map support:

```python
from simvx.core import TileMapLayer

layer = TileMapLayer("Ground")
layer.set_cell(5, 3, grass)       # Place tile at grid (5, 3)
tid = layer.get_cell(5, 3)        # Returns tile ID (-1 if empty)
layer.erase_cell(5, 3)            # Remove tile

cells = layer.get_used_cells()    # All non-empty (x, y) positions
rect = layer.get_used_rect()      # Bounding (x, y, w, h) of used cells
```

## TileMap Node

`TileMap` is a `Node2D` that manages multiple layers and provides coordinate conversion:

```python
from simvx.core import TileMap, TileSet, TileData

ts = TileSet(tile_size=(16, 16))
ground = ts.add_tile(TileData(texture_region=(0, 0, 16, 16)))
wall = ts.add_tile(TileData(texture_region=(16, 0, 16, 16)))

tilemap = TileMap(tile_set=ts, cell_size=(16, 16))

# Paint on layer 0 (created automatically)
tilemap.set_cell(0, 0, 0, ground)
tilemap.set_cell(0, 1, 0, wall)

# Add a second layer
overlay = tilemap.add_layer("Decoration")
tilemap.set_cell(overlay, 0, 0, ground)

# Coordinate conversion
grid_pos = tilemap.world_to_map((48.0, 32.0))   # -> (3, 2)
world_pos = tilemap.map_to_world((3, 2))          # -> (56.0, 40.0) center of cell
```

## Terrain Auto-Tiling

Auto-tiling selects tile variants based on a 4-bit neighbor bitmask (up=1, right=2, down=4, left=8). Neighbors match when they share the same `terrain_type`.

```python
ts.add_terrain_set(0)
ts.set_terrain_tile(0, 0b0000, lone_tile)   # No matching neighbors
ts.set_terrain_tile(0, 0b0101, vertical)    # Up + down
ts.set_terrain_tile(0, 0b1010, horizontal)  # Right + left
ts.set_terrain_tile(0, 0b1111, center)      # All four neighbors

# Apply auto-tiling at a cell
tilemap.auto_tile(layer=0, x=5, y=3, terrain_set=0)
```

## API Reference

See {py:mod}`simvx.core.tilemap` for the complete tilemap API.