tilemap.h

#include <modkit/tilemap.h>15 functions · 4 structs · 2 enums · 7 typedefs · 2 macros

Tile map rendering, autotiling and Tiled import (opt-in).

An OPT-IN package (MODKIT_ENABLE_TILEMAP, default OFF) that requires MODKIT_ENABLE_SPRITE. When disabled every symbol here still links and returns an invalid handle, false, or MK_ERROR_UNSUPPORTED. A tilemap is a fixed grid of layers over a single tileset texture. Tiles are baked into per-chunk static vertex buffers and rebuilt only when edited, so static maps cost nothing per frame and edited ones only pay for the chunks that changed. Drawing goes through an open canvas, which keeps painter order with the rest of your 2D content. Typical use:

Functions

mk_autotile_maskfunction

uint32_t mk_autotile_mask(const bool neighbours[MK_NEIGHBOUR_COUNT], mk_autotile_kind kind)

Canonical variant index for a neighbourhood.

Pure function of the neighbour bits, exposed so callers can drive their own tile selection without owning a tilemap. Returns < 16 for EDGE_16 and < 47 for BLOB_47.

Parameter	Type	Description
neighbours	const bool	Occupancy in mk_neighbour order.
kind	mk_autotile_kind	Autotile rule used to canonicalize the mask

Returns The resulting value.

mk_tilemap_autotilefunction

mk_result mk_tilemap_autotile(mk_tilemap_t map, uint32_t layer, const mk_terrain_desc *terrain)

Rewrite every non-empty tile of a layer to the terrain variant that fits.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.
terrain	const mk_terrain_desc *	Value for terrain.

Returns MK_SUCCESS or an error result.

mk_tilemap_clear_layerfunction

void mk_tilemap_clear_layer(mk_tilemap_t map, uint32_t layer)

Clear the layer for the tilemap.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.

mk_tilemap_createfunction

mk_tilemap_t mk_tilemap_create(const mk_tilemap_desc *desc)

Create tilemap.

Parameter	Type	Description
desc	const mk_tilemap_desc *	Configuration descriptor.

Returns The resulting handle or value.

mk_tilemap_destroyfunction

void mk_tilemap_destroy(mk_tilemap_t map)

Destroy the tilemap.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.

mk_tilemap_drawfunction

uint32_t mk_tilemap_draw(mk_tilemap_t map, mk_canvas_t canvas, const mk_camera2d *camera)

Draw every visible layer into an open canvas.

Must be called between mk_begin_pass()/mk_end_pass() on a painter-ordered 2D pass, with the canvas in drawing mode. Pass the camera to cull off-screen chunks, or NULL to draw them all.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
canvas	mk_canvas_t	Value for canvas.
camera	const mk_camera2d *	Value for camera.

Returns Number of chunks submitted (0 when fully culled or unavailable).

mk_tilemap_get_tilefunction

mk_tile_t mk_tilemap_get_tile(mk_tilemap_t map, uint32_t layer, uint32_t x, uint32_t y)

Get tile from the tilemap.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.
x	uint32_t	Value for x.
y	uint32_t	Value for y.

Returns The resulting handle or value.

mk_tilemap_heightfunction

uint32_t mk_tilemap_height(mk_tilemap_t map)

Perform the tilemap height operation.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.

Returns The resulting value.

mk_tilemap_is_validfunction

bool mk_tilemap_is_valid(mk_tilemap_t map)

Test whether the tilemap is valid.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.

Returns True when the condition holds.

mk_tilemap_layer_countfunction

uint32_t mk_tilemap_layer_count(mk_tilemap_t map)

Perform the tilemap layer count operation.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.

Returns The resulting value.

mk_tilemap_layer_visiblefunction

bool mk_tilemap_layer_visible(mk_tilemap_t map, uint32_t layer)

Perform the tilemap layer visible operation.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.

Returns True when the operation succeeds.

mk_tilemap_load_tiledfunction

mk_tilemap_t mk_tilemap_load_tiled(const char *tmj_path, const mk_tileset_desc *tileset_override)

Load an orthogonal map from Tiled's JSON export (.tmj).

Handles tile layers with array or CSV data, embedded and external (.tsj) tilesets, and the flip bits Tiled packs into each GID. Returns MK_TILEMAP_INVALID for infinite maps, isometric/hexagonal orientations, and base64/compressed layer data rather than misreading them.

Parameter	Type	Description
tmj_path	const char *	Path to the .tmj file.
tileset_override	const mk_tileset_desc *	Use this tileset instead of the one named in the file; pass NULL to resolve the file's own tileset image relative to the .tmj.

Returns The resulting handle or value.

mk_tilemap_set_layer_visiblefunction

void mk_tilemap_set_layer_visible(mk_tilemap_t map, uint32_t layer, bool visible)

Set layer visible on the tilemap.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.
visible	bool	Value for visible.

mk_tilemap_set_tilefunction

mk_result mk_tilemap_set_tile(mk_tilemap_t map, uint32_t layer, uint32_t x, uint32_t y, mk_tile_t tile)

Set tile on the tilemap.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.
layer	uint32_t	Value for layer.
x	uint32_t	Value for x.
y	uint32_t	Value for y.
tile	mk_tile_t	Value for tile.

Returns MK_SUCCESS or an error result.

mk_tilemap_widthfunction

uint32_t mk_tilemap_width(mk_tilemap_t map)

Perform the tilemap width operation.

Parameter	Type	Description
map	mk_tilemap_t	Value for map.

Returns The resulting value.

Structs

mk_terrain_descstruct

Data for terrain desc.

Field	Type	Description
kind	mk_autotile_kind	The kind.
variants	const uint32_t *	Tile indices, indexed by the canonical mask.
variant_count	uint32_t	16 for EDGE_16, 47 for BLOB_47.
solid_min	uint32_t	Tiles in [solid_min, solid_max] count as terrain.
solid_max	uint32_t	0 => any non-empty tile counts.
out_of_bounds_solid	bool	Treat off-map as terrain (usual for ground).

mk_tilestruct

One cell of a layer.

index is 1-based; 0 means empty.

Field	Type	Description
index	uint32_t	The index.
flip	uint8_t	Bitmask of mk_flip_t.

mk_tilemap_descstruct

Data for tilemap desc.

Field	Type	Description
width	uint32_t	Map width in tiles.
height	uint32_t	Map height in tiles.
layer_count	uint32_t	0 => 1.
tileset	mk_tileset_desc	The tileset.
chunk_size	uint16_t	Tiles per chunk edge.
tile_world_w	float	World units per tile.
tile_world_h	float	The tile world h.

mk_tileset_descstruct

How a tileset texture is cut into tiles.

Field	Type	Description
texture	mk_texture_t	The texture.
tile_w	uint16_t	Tile width in pixels.
tile_h	uint16_t	Tile height in pixels.
margin	uint16_t	Border around the whole grid, in pixels.
spacing	uint16_t	Gap between adjacent tiles, in pixels.
columns	uint16_t	0 = derive from texture width.

Enums

mk_autotile_kindenum

Which neighbour bits a terrain set is indexed by.

Value	Description
MK_AUTOTILE_EDGE_16	4 edge neighbours -> 16 variants.
MK_AUTOTILE_BLOB_47	8 neighbours reduced to 47 variants.

mk_neighbourenum

Neighbour order for mk_autotile_mask(), clockwise from north.

Value	Description
MK_NEIGHBOUR_N	Selects n.
MK_NEIGHBOUR_NE	Selects ne.
MK_NEIGHBOUR_E	Selects e.
MK_NEIGHBOUR_SE	Selects se.
MK_NEIGHBOUR_S	Selects s.
MK_NEIGHBOUR_SW	Selects sw.
MK_NEIGHBOUR_W	Selects w.
MK_NEIGHBOUR_NW	Selects nw.
MK_NEIGHBOUR_COUNT	Selects count.

Typedefs

mk_autotile_kindtypedef

typedef enum mk_autotile_kind mk_autotile_kind

Which neighbour bits a terrain set is indexed by.

mk_neighbourtypedef

typedef enum mk_neighbour mk_neighbour

Neighbour order for mk_autotile_mask(), clockwise from north.

mk_terrain_desctypedef

typedef struct mk_terrain_desc mk_terrain_desc

Data for terrain desc.

mk_tile_ttypedef

typedef struct mk_tile mk_tile_t

One cell of a layer.

index is 1-based; 0 means empty.

mk_tilemap_desctypedef

typedef struct mk_tilemap_desc mk_tilemap_desc

Data for tilemap desc.

mk_tilemap_ttypedef

typedef mk_tilemap_handle_t mk_tilemap_t

Type used for tilemap.

mk_tileset_desctypedef

typedef struct mk_tileset_desc mk_tileset_desc

How a tileset texture is cut into tiles.

Macros

MK_TILE_EMPTYdefine

MK_TILE_EMPTY

Constant for tile empty.

MK_TILEMAP_INVALIDdefine

MK_TILEMAP_INVALID

Invalid sentinel for tilemap.