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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
feat(tilemap): hexagonal grid — the last missing Tiled orientation
yhh1ec4dab06951
diff --git a/desktop/package.json b/desktop/package.jsonindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.tmjnew file mode 100644index 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.pngnew file mode 100644index 000000000..1e14612f2Binary files /dev/null and b/desktop/public/scenes/tilemap-hex/tiles.png differdiff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.cppindex 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.cppindex 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.cppindex 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.hppindex 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 shiftstd::unordered_map<ChunkCoord, ChunkData, ChunkCoordHash> chunks;bool infinite = false;diff --git a/tests/tilemap/test_tilemap.cpp b/tests/tilemap/test_tilemap.cppindex 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);+ }+}