Loads and renders maps authored in Tiled (.tmj) with chunk streaming

Repository: github.com/dekiengine/deki-tiledmapeditor-integration · Latest release: 0.19.0 · Needs engine 0.19.0+ · Requires: deki-2d, deki-rendering

Install with DekiEditor --packages-add deki-tiledmapeditor-integration <project>, or from the Package Manager. The engine's own components and C++ API are in the Deki docs.

Shown in the editor as Tiled Map Editor Integration.

Components

Component	Category	Description
TilemapColliderComponent	Tilemap	Exposes a tilemap layer's per-tile collision shapes for queries.
TilemapComponent	Tilemap	Draws a Tiled map, streaming chunks in around the camera.
TilemapObjectSpawner	Tilemap	Spawns objects from a Tiled map's object layers when the scene loads.

Feature flags

Parts you can leave out of a build. A feature with a define is switched there; the rest are stripped with their components.

Feature	Define	Default
Tilemap Rendering	DEKI_FEATURE_TILEMAP_RENDER	on
Tilemap Collision	DEKI_FEATURE_TILEMAP_COLLISION	on
Object Layers	DEKI_FEATURE_TILEMAP_OBJECTS	on

Component reference

TilemapColliderComponent

Exposes a tilemap layer's per-tile collision shapes for queries.

Inspector name: Tilemap Collider Component · Category: Tilemap · Type: DekiTiledMap::TilemapColliderComponent

Property	Type	Default	Constraints	Description
tilemap	AssetRef (Tilemap)	""		The map whose tiles become solid.
collisionLayer	int32	0		Which layer of the map holds the collision tiles. A tile present on that layer is solid; an empty cell is not.
loopX	bool	false		Repeat the collision horizontally, to match a map that loops.
wrapPeriodX	int32	0	shown when loopX allows	How wide one horizontal repeat is, in tiles. 0 uses the map's own width.
loopY	bool	false		Repeat the collision vertically.
wrapPeriodY	int32	0	shown when loopY allows	How tall one vertical repeat is, in tiles. 0 uses the map's own height.

TilemapComponent

Draws a Tiled map, streaming chunks in around the camera.

Inspector name: Tilemap Component · Category: Tilemap · Type: DekiTiledMap::TilemapComponent

Property	Type	Default	Constraints	Description
tilemap	AssetRef (Tilemap)	""		A map exported from Tiled.
visibleLayerMask	int32	2147483647		Which of the map's layers to draw, one bit per layer. All bits set draws everything.
chunkPadding	int32	1		How many chunks beyond the screen edge to keep loaded and drawn. A little padding stops tiles popping in at the edge while scrolling.
chunkCacheKiB	int32	256	16 to 262144	How much memory this map may keep decoded chunks in, in KiB. Past the budget the least recently drawn chunks are dropped and re-read from storage when they are needed again, so too small shows up as stutter while scrolling rather than as anything missing. 256 suits an ESP32; a desktop can afford far more.
tintColor	Color	"#FFFFFFFF"		Multiplied into every tile. White leaves the map alone.
pixelsPerMeter	float	16	1 to 256	How many of the map's pixels make one meter. This is what lines the map up with everything else in the scene.
loopX	bool	false		Repeat the map horizontally, so scrolling past the edge wraps round.
wrapPeriodX	int32	0	shown when loopX allows	How wide one horizontal repeat is, in tiles. 0 uses the map's own width.
loopY	bool	false		Repeat the map vertically.
wrapPeriodY	int32	0	shown when loopY allows	How tall one vertical repeat is, in tiles. 0 uses the map's own height.

Inherits sortingOrder, ignoreClip, pixelSnap, alphaMode from RendererComponent.

TilemapObjectSpawner

Spawns objects from a Tiled map's object layers when the scene loads.

Inspector name: Tilemap Object Spawner · Category: Tilemap · Type: DekiTiledMap::TilemapObjectSpawner

Property	Type	Default	Constraints	Description
tilemap	AssetRef (Tilemap)	""		The map whose object layer is read. Each object placed in Tiled becomes an object in the scene.
pixelsPerMeter	float	16	1 to 256	How many of the map's pixels make one meter, so spawned objects land where Tiled put them.

Changelog

0.19.0 Changed

minEngine 0.19.0: built against engine 0.19.0, whose component metadata records the package each class is in. A build of this package from before does not load and is rebuilt.

Added

Japanese, Simplified Chinese and Korean: editor/lang/ja.json, zh.json and ko.json translate the names, tooltips and enum values this package's components show in the Inspector.
The package's editor text goes through the editor's translation (Tr), so it shows in the editor's language. Needs the editor release that adds Localization.h; raise minEngine to it when releasing.

0.18.0 Changed

minEngine 0.18.0. Reflection ABI 21: the package must be rebuilt.
Names follow the code style (deki-engine/docs/codestyle): types, functions and enum values are PascalCase, constants kPascalCase, members m_PascalCase, locals and parameters camelCase. The code is formatted with clang-format 22.
The functions the editor finds by name are PascalCase: DekiTilemapRegisterComponents, DekiTilemapGetAutoComponentCount, DekiTilemapEnsureRegistered and the rest. Built against engine ABI 21; a build of this package from before does not load and is rebuilt.
Renamed: AssetTypeName is kAssetTypeName, GID_INDEX_MASK and the other gid flags are kGidIndexMask, ..., CHUNK_FLAG_EMPTY is ChunkFlagEmpty.

Fixed

The Chunk Padding tooltip says it counts chunks; it said tiles.
Builds for ESP32 boards again (0.17.0 did not): the Max Size change called std::max with an int and an int32_t, which is long on Xtensa, and left two members of the tile lookup uninitialised, an error there.
Object properties load. The baker wrote every object's properties, but the loader never read them back, so Properties() was always empty and a TilemapObjectSpawner never found an object's scene_guid. The map header now says where the properties, points and strings are. New: Tilemap::ObjectProperties(object, count).
Polygon and polyline points are written. Objects had a point count but the points themselves were never baked. DTilemapObject::pointOffset is now the object's first point in PolygonPoints(). Maps baked before this have no points until they are baked again.
A map no longer reads its whole object list into memory twice.
Corrupt map and tileset files are refused instead of crashing: every table is checked against the file's size, the per-layer object counts can no longer wrap and overflow the object table, chunk sides must be 1 to 1024 (zero divided by zero in the collider, a huge one overflowed the chunk buffer on 32-bit boards), and a tileset's animation frame counts can no longer wrap.

Removed

Reading maps baked before the header said where the pools are. The editor bakes every map again (asset cache version 5).
The former names from before 0.16.0 (bare class names, and deki-gpio's DekiEsp32::ESP32PinSetup). A scene that old is upgraded with 0.17 first.

Earlier releases: CHANGELOG.md.

Generated from the package's reflection data (engine 0.19.0). Property names are the keys used in scene files. Renames keep an alias (compatibility).