Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

feat(tilemap): hexagonal grid — the last missing Tiled orientation

yhh1ec4dab06951
diff --git a/desktop/package.json b/desktop/package.json
index 6a3f47cf3..c92cd04c6 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -52,7 +52,8 @@
"verify:render:material:preview": "vite build && ESTELLA_VERIFY_SCENE=/scenes/mat-tint.esscene ESTELLA_VERIFY_MANIFEST=/scenes/mat-tint.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_PREVIEW=\"{\\\"w\\\":64,\\\"h\\\":64,\\\"rgb\\\":[255,0,0],\\\"tol\\\":45}\" electron scripts/headless-verify.mjs",
"verify:smoke": "vite build && electron scripts/headless-smoke.mjs",
"mcp": "electron electron/mcp/server.mjs",
- "mcp:smoke": "vite build && node electron/mcp/smoke.mjs"
+ "mcp:smoke": "vite build && node electron/mcp/smoke.mjs",
+ "verify:render:tilemap:hex": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-hex.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-hex.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.40,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.40,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.50,\\\"y\\\":0.55,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.70,\\\"y\\\":0.55,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs"
},
"dependencies": {
"@modelcontextprotocol/sdk": "^1.29.0",
diff --git a/desktop/public/scenes/tilemap-hex.esscene b/desktop/public/scenes/tilemap-hex.esscene
new file mode 100644
index 000000000..21fd9e227
--- /dev/null
+++ b/desktop/public/scenes/tilemap-hex.esscene
@@ -0,0 +1,28 @@
+{
+ "version": "1.0",
+ "name": "TilemapHex",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 16, "y": -16, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 40, "isActive": true, "priority": 0 } }
+ ],
+ "visible": true
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 0, "y": 0, "z": 0 } } },
+ { "type": "Tilemap", "data": { "source": "/scenes/tilemap-hex/map.tmj" } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/tilemap-hex.textures.json b/desktop/public/scenes/tilemap-hex.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/tilemap-hex.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/tilemap-hex/map.tmj b/desktop/public/scenes/tilemap-hex/map.tmj
new file mode 100644
index 000000000..ff9aaca6c
--- /dev/null
+++ b/desktop/public/scenes/tilemap-hex/map.tmj
@@ -0,0 +1,38 @@
+{
+ "type": "map",
+ "version": "1.10",
+ "orientation": "hexagonal",
+ "renderorder": "right-down",
+ "width": 2,
+ "height": 2,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "hexsidelength": 8,
+ "staggeraxis": "y",
+ "staggerindex": "odd",
+ "infinite": false,
+ "layers": [
+ {
+ "type": "tilelayer",
+ "name": "main",
+ "width": 2,
+ "height": 2,
+ "visible": true,
+ "opacity": 1,
+ "data": [1, 2, 3, 4]
+ }
+ ],
+ "tilesets": [
+ {
+ "firstgid": 1,
+ "name": "tiles",
+ "image": "tiles.png",
+ "imagewidth": 64,
+ "imageheight": 16,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "columns": 4,
+ "tilecount": 4
+ }
+ ]
+}
diff --git a/desktop/public/scenes/tilemap-hex/tiles.png b/desktop/public/scenes/tilemap-hex/tiles.png
new file mode 100644
index 000000000..1e14612f2
Binary files /dev/null and b/desktop/public/scenes/tilemap-hex/tiles.png differ
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index ea2eaad0d..f99cdd8be 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -38,6 +38,9 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
// asset-loaded maps rendered flat, tile animations never ran, and tilemaps had
// no physics collision (the B2-1 gap).
orientation: mapData.orientation,
+ hexSideLength: mapData.hexSideLength,
+ staggerAxis: mapData.staggerAxis,
+ staggerIndex: mapData.staggerIndex,
layers: mapData.layers.map(l => ({
name: l.name,
width: l.width,
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index ba085c0a8..52c4f9519 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -105,6 +105,10 @@ export interface TiledMapData {
tileWidth: number;
tileHeight: number;
orientation: string;
+ /** Hexagonal maps: Tiled's hexsidelength / staggeraxis / staggerindex. */
+ hexSideLength: number;
+ staggerAxis: string;
+ staggerIndex: string;
layers: TiledLayerData[];
tilesets: TiledTilesetData[];
objectGroups: TiledObjectGroupData[];
@@ -325,9 +329,13 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
}
const orientation = (json.orientation as string) ?? 'orthogonal';
+ const hexSideLength = (json.hexsidelength as number) ?? 0;
+ const staggerAxis = (json.staggeraxis as string) ?? 'y';
+ const staggerIndex = (json.staggerindex as string) ?? 'odd';
return {
width, height, tileWidth, tileHeight, orientation,
+ hexSideLength, staggerAxis, staggerIndex,
layers, tilesets, objectGroups, collisionTileIds,
tileAnimations, tileProperties,
};
@@ -405,6 +413,9 @@ export async function parseTiledMap(
tileWidth: api.tiled_getMapTileWidth(handle),
tileHeight: api.tiled_getMapTileHeight(handle),
orientation: 'orthogonal',
+ hexSideLength: 0,
+ staggerAxis: 'y',
+ staggerIndex: 'odd',
layers: [],
tilesets: [],
objectGroups: [],
diff --git a/sdk/src/tilemap/tilemapAPI.ts b/sdk/src/tilemap/tilemapAPI.ts
index 08b582f5e..7d8ed0495 100644
--- a/sdk/src/tilemap/tilemapAPI.ts
+++ b/sdk/src/tilemap/tilemapAPI.ts
@@ -36,6 +36,7 @@ interface TilemapModule {
flipH: boolean, flipV: boolean, flipD: boolean): void;
tilemap_rotateTile(entity: number, x: number, y: number, degrees: number): void;
tilemap_setGridType(entity: number, type: number): void;
+ tilemap_setHexParams(entity: number, sideLength: number, staggerAxisX: number, staggerIndexEven: number): void;
tilemap_initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void;
tilemap_initInfinite?(entity: number, tileWidth: number, tileHeight: number): void;
tilemap_exportChunks?(entity: number): string;
@@ -251,6 +252,12 @@ export const TilemapAPI = {
module_?.tilemap_setGridType(entity, type);
},
+ /** Hexagonal-grid layout inputs (Tiled hexsidelength/staggeraxis/staggerindex);
+ * only read when the layer's grid type is Hexagonal (3). */
+ setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void {
+ module_?.tilemap_setHexParams(entity, sideLength, staggerAxisX ? 1 : 0, staggerIndexEven ? 1 : 0);
+ },
+
tileToWorld(entity: number, tx: number, ty: number,
originX: number, originY: number): { x: number; y: number } {
if (!module_) return { x: 0, y: 0 };
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index bb5c94891..46c68b167 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -23,7 +23,9 @@ const GRID_TYPE_MAP: Record<string, number> = {
orthogonal: 0,
isometric: 1,
staggered: 2,
+ hexagonal: 3,
};
+const GRID_HEXAGONAL = 3;
export class TilemapPlugin implements Plugin {
name = 'tilemap';
@@ -285,6 +287,12 @@ export class TilemapPlugin implements Plugin {
if (gridType !== 0) {
TilemapAPI.setGridType(child, gridType);
}
+ if (gridType === GRID_HEXAGONAL) {
+ TilemapAPI.setHexParams(
+ child, cached.hexSideLength ?? 0,
+ cached.staggerAxis === 'x', cached.staggerIndex === 'even',
+ );
+ }
if (cached.tileAnimations) {
for (const [tileId, frames] of cached.tileAnimations) {
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index 3e2c23787..a925b100b 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -29,6 +29,10 @@ export interface LoadedTilemapSource {
tileWidth: number;
tileHeight: number;
orientation?: string;
+ /** Hexagonal maps: Tiled's hexsidelength / staggeraxis / staggerindex. */
+ hexSideLength?: number;
+ staggerAxis?: string;
+ staggerIndex?: string;
layers: LoadedTilemapLayer[];
tilesets: LoadedTilemapTileset[];
tileAnimations?: Map<number, { tileId: number; duration: number }[]>;
diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cpp
index e8e4b8c1a..77ee2d2d3 100644
--- a/src/esengine/bindings/TilemapBindings.cpp
+++ b/src/esengine/bindings/TilemapBindings.cpp
@@ -676,6 +676,12 @@ void tilemap_setGridType(u32 entity, u32 type) {
getTilemapSystem().setGridType(e, static_cast<tilemap::GridType>(type));
}
+void tilemap_setHexParams(u32 entity, f32 sideLength, u32 staggerAxisX, u32 staggerIndexEven) {
+ auto e = Entity::fromRaw(entity);
+ if (e == INVALID_ENTITY) return;
+ getTilemapSystem().setHexParams(e, sideLength, staggerAxisX != 0, staggerIndexEven != 0);
+}
+
static f32 s_coordBuffer[2] = {};
uintptr_t tilemap_tileToWorld(u32 entity, i32 tx, i32 ty,
@@ -774,6 +780,7 @@ EMSCRIPTEN_BINDINGS(esengine_tilemap) {
emscripten::function("tilemap_flipTile", &esengine::tilemap_flipTile);
emscripten::function("tilemap_rotateTile", &esengine::tilemap_rotateTile);
emscripten::function("tilemap_setGridType", &esengine::tilemap_setGridType);
+ emscripten::function("tilemap_setHexParams", &esengine::tilemap_setHexParams);
emscripten::function("tilemap_tileToWorld", &esengine::tilemap_tileToWorld);
emscripten::function("tilemap_worldToTile", &esengine::tilemap_worldToTile);
}
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
index f84c3c55d..75ef8239c 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
@@ -80,6 +80,26 @@ void TilemapRenderPlugin::rebuildChunk(
f32 offsetX = (ty & 1) ? hw : 0.0f;
worldX = originX + static_cast<f32>(tx) * layer.tile_width + offsetX + hw;
worldY = originY - static_cast<f32>(ty) * hh - hh;
+ } else if (layer.grid_type == tilemap::GridType::Hexagonal) {
+ // Tiled hexagonal layout: the stagger axis advances by
+ // (tile + hexSideLength)/2, staggered lines shift half a tile
+ // along the other axis — matches Tiled's pixel placement so
+ // imported maps line up 1:1.
+ f32 side = layer.hex_side_length > 0.0f ? layer.hex_side_length
+ : layer.tile_height * 0.5f;
+ if (layer.hex_stagger_axis_x) {
+ f32 colW = (layer.tile_width + side) * 0.5f;
+ bool staggered = ((tx & 1) != 0) != layer.hex_stagger_index_even;
+ worldX = originX + static_cast<f32>(tx) * colW + hw;
+ worldY = originY - static_cast<f32>(ty) * layer.tile_height
+ - (staggered ? hh : 0.0f) - hh;
+ } else {
+ f32 rowH = (layer.tile_height + side) * 0.5f;
+ bool staggered = ((ty & 1) != 0) != layer.hex_stagger_index_even;
+ worldX = originX + static_cast<f32>(tx) * layer.tile_width
+ + (staggered ? hw : 0.0f) + hw;
+ worldY = originY - static_cast<f32>(ty) * rowH - hh;
+ }
} else {
worldX = originX + static_cast<f32>(tx) * layer.tile_width + hw;
worldY = originY - static_cast<f32>(ty) * layer.tile_height - hh;
diff --git a/src/esengine/tilemap/TilemapSystem.cpp b/src/esengine/tilemap/TilemapSystem.cpp
index df8c95b84..cce31a88a 100644
--- a/src/esengine/tilemap/TilemapSystem.cpp
+++ b/src/esengine/tilemap/TilemapSystem.cpp
@@ -334,6 +334,14 @@ void TilemapSystem::setGridType(Entity entity, GridType type) {
layer->grid_type = type;
}
+void TilemapSystem::setHexParams(Entity entity, f32 sideLength, bool staggerAxisX, bool staggerIndexEven) {
+ auto* layer = getLayerDataMut(entity);
+ if (!layer) return;
+ layer->hex_side_length = sideLength;
+ layer->hex_stagger_axis_x = staggerAxisX;
+ layer->hex_stagger_index_even = staggerIndexEven;
+}
+
void TilemapSystem::tileToWorld(Entity entity, i32 tx, i32 ty,
f32 originX, f32 originY,
f32& outX, f32& outY) const {
@@ -354,6 +362,24 @@ void TilemapSystem::tileToWorld(Entity entity, i32 tx, i32 ty,
outY = originY - static_cast<f32>(ty) * th * 0.5f;
break;
}
+ case GridType::Hexagonal: {
+ // Tiled hexagonal layout: the stagger axis advances by
+ // (tile + hexSideLength)/2 and staggered lines shift half a tile
+ // along the other axis (staggerindex picks odd or even lines).
+ f32 side = layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f;
+ if (layer->hex_stagger_axis_x) {
+ f32 colW = (tw + side) * 0.5f;
+ bool staggered = ((tx & 1) != 0) != layer->hex_stagger_index_even;
+ outX = originX + static_cast<f32>(tx) * colW;
+ outY = originY - static_cast<f32>(ty) * th - (staggered ? th * 0.5f : 0.0f);
+ } else {
+ f32 rowH = (th + side) * 0.5f;
+ bool staggered = ((ty & 1) != 0) != layer->hex_stagger_index_even;
+ outX = originX + static_cast<f32>(tx) * tw + (staggered ? tw * 0.5f : 0.0f);
+ outY = originY - static_cast<f32>(ty) * rowH;
+ }
+ break;
+ }
default:
outX = originX + static_cast<f32>(tx) * tw;
outY = originY - static_cast<f32>(ty) * th;
@@ -387,6 +413,25 @@ void TilemapSystem::worldToTile(Entity entity, f32 wx, f32 wy,
outTy = roughY;
break;
}
+ case GridType::Hexagonal: {
+ // Box-approximate like the staggered-iso case: resolve the stagger
+ // line first, then the cell along it (no exact hex hit-test).
+ f32 side = layer->hex_side_length > 0.0f ? layer->hex_side_length : th * 0.5f;
+ if (layer->hex_stagger_axis_x) {
+ f32 colW = (tw + side) * 0.5f;
+ i32 roughX = static_cast<i32>(std::floor(lx / colW));
+ bool staggered = ((roughX & 1) != 0) != layer->hex_stagger_index_even;
+ outTx = roughX;
+ outTy = static_cast<i32>(std::floor((ly - (staggered ? th * 0.5f : 0.0f)) / th));
+ } else {
+ f32 rowH = (th + side) * 0.5f;
+ i32 roughY = static_cast<i32>(std::floor(ly / rowH));
+ bool staggered = ((roughY & 1) != 0) != layer->hex_stagger_index_even;
+ outTy = roughY;
+ outTx = static_cast<i32>(std::floor((lx - (staggered ? tw * 0.5f : 0.0f)) / tw));
+ }
+ break;
+ }
default:
outTx = static_cast<i32>(std::floor(lx / tw));
outTy = static_cast<i32>(std::floor(ly / th));
diff --git a/src/esengine/tilemap/TilemapSystem.hpp b/src/esengine/tilemap/TilemapSystem.hpp
index 6d6961ae6..d84a0d4ee 100644
--- a/src/esengine/tilemap/TilemapSystem.hpp
+++ b/src/esengine/tilemap/TilemapSystem.hpp
@@ -25,6 +25,7 @@ enum class GridType : u8 {
Orthogonal = 0,
Isometric = 1,
StaggeredIsometric = 2,
+ Hexagonal = 3,
};
struct AnimFrame {
@@ -101,6 +102,10 @@ public:
void setGridType(Entity entity, GridType type);
+ /// Hexagonal-grid parameters (Tiled's hexsidelength / staggeraxis /
+ /// staggerindex); only read when the layer's grid type is Hexagonal.
+ void setHexParams(Entity entity, f32 sideLength, bool staggerAxisX, bool staggerIndexEven);
+
struct LayerData {
u32 width = 0; // finite-layer bounds (0 = infinite); tiles live in `chunks`.
u32 height = 0;
@@ -126,6 +131,11 @@ public:
bool visible = true;
Entity origin_entity = INVALID_ENTITY;
GridType grid_type = GridType::Orthogonal;
+ /// Hexagonal layout inputs (see setHexParams). A zero side length falls
+ /// back to tile_height/2 (a regular pointy-top hex).
+ f32 hex_side_length = 0.0f;
+ bool hex_stagger_axis_x = false; ///< true: columns stagger (staggeraxis=x)
+ bool hex_stagger_index_even = false; ///< true: even rows/cols carry the shift
std::unordered_map<ChunkCoord, ChunkData, ChunkCoordHash> chunks;
bool infinite = false;
diff --git a/tests/tilemap/test_tilemap.cpp b/tests/tilemap/test_tilemap.cpp
index 8721f7154..faf3e12c5 100644
--- a/tests/tilemap/test_tilemap.cpp
+++ b/tests/tilemap/test_tilemap.cpp
@@ -272,3 +272,60 @@ TEST_CASE("tilemap_resolve_tileset_slot") {
CHECK_EQ(resolveTilesetSlot(slots, 20), 2);
}
}
+
+TEST_CASE("tilemap_hex_tile_to_world") {
+ TilemapSystem sys;
+ sys.initLayer(E(0), 4, 4, 16.0f, 16.0f);
+ sys.setGridType(E(0), GridType::Hexagonal);
+ sys.setHexParams(E(0), 8.0f, /*staggerAxisX=*/false, /*staggerIndexEven=*/false);
+
+ f32 x = 0, y = 0;
+
+ SUBCASE("stagger axis y, index odd: rows advance by (th+side)/2, odd rows shift half a tile") {
+ sys.tileToWorld(E(0), 0, 0, 0, 0, x, y);
+ CHECK_EQ(x, doctest::Approx(0.0f));
+ CHECK_EQ(y, doctest::Approx(0.0f));
+ sys.tileToWorld(E(0), 1, 0, 0, 0, x, y);
+ CHECK_EQ(x, doctest::Approx(16.0f));
+ sys.tileToWorld(E(0), 0, 1, 0, 0, x, y); // odd row: staggered
+ CHECK_EQ(x, doctest::Approx(8.0f));
+ CHECK_EQ(y, doctest::Approx(-12.0f)); // rowHeight = (16+8)/2
+ sys.tileToWorld(E(0), 0, 2, 0, 0, x, y); // even row: no shift
+ CHECK_EQ(x, doctest::Approx(0.0f));
+ CHECK_EQ(y, doctest::Approx(-24.0f));
+ }
+
+ SUBCASE("stagger index even flips which rows shift") {
+ sys.setHexParams(E(0), 8.0f, false, /*staggerIndexEven=*/true);
+ sys.tileToWorld(E(0), 0, 0, 0, 0, x, y); // even row: staggered now
+ CHECK_EQ(x, doctest::Approx(8.0f));
+ sys.tileToWorld(E(0), 0, 1, 0, 0, x, y);
+ CHECK_EQ(x, doctest::Approx(0.0f));
+ }
+
+ SUBCASE("stagger axis x: columns advance by (tw+side)/2, odd columns shift down") {
+ sys.setHexParams(E(0), 8.0f, /*staggerAxisX=*/true, false);
+ sys.tileToWorld(E(0), 1, 0, 0, 0, x, y); // odd column: staggered
+ CHECK_EQ(x, doctest::Approx(12.0f)); // colWidth = (16+8)/2
+ CHECK_EQ(y, doctest::Approx(-8.0f));
+ sys.tileToWorld(E(0), 2, 0, 0, 0, x, y);
+ CHECK_EQ(x, doctest::Approx(24.0f));
+ CHECK_EQ(y, doctest::Approx(0.0f));
+ }
+
+ SUBCASE("zero side length falls back to a regular hex (side = th/2)") {
+ sys.setHexParams(E(0), 0.0f, false, false);
+ sys.tileToWorld(E(0), 0, 1, 0, 0, x, y);
+ CHECK_EQ(y, doctest::Approx(-12.0f)); // (16+8)/2 with side=8 fallback
+ }
+
+ SUBCASE("worldToTile inverts the cell for on-grid points") {
+ i32 tx = -1, ty = -1;
+ sys.worldToTile(E(0), 8.0f + 4.0f, -12.0f - 4.0f, 0, 0, tx, ty); // inside (0,1)
+ CHECK_EQ(tx, 0);
+ CHECK_EQ(ty, 1);
+ sys.worldToTile(E(0), 4.0f, -4.0f, 0, 0, tx, ty); // inside (0,0)
+ CHECK_EQ(tx, 0);
+ CHECK_EQ(ty, 0);
+ }
+}