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:

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:

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:

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.

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 simvx.core.tilemap for the complete tilemap API.