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.

docs(examples/tilemap): add isometric, staggered & hexagonal showcase scenes

yhh3bcc69e2de35
diff --git a/examples/tilemap-demo/README.md b/examples/tilemap-demo/README.md
index 5c36c1bdd..30011e227 100644
--- a/examples/tilemap-demo/README.md
+++ b/examples/tilemap-demo/README.md
@@ -1,14 +1,28 @@
# Tilemap Demo
Estella's tilemap system, shown two ways — **a Tiled `.tmj` import** and **an
-engine-native `.estileset`** — over the same Kenney Pixel Platformer art. Both are
-drawn by the built-in tilemap plugin with **no gameplay code**; the level lives
-entirely in the scene/assets.
+engine-native `.estileset`** — over the same Kenney Pixel Platformer art, plus
+three **orientation showcases** (isometric, staggered, hexagonal) painted natively
+in the editor. Everything is drawn by the built-in tilemap plugin with **no
+gameplay code**; the levels live entirely in the scene/assets.
| Scene | Authoring path | What it shows |
| --- | --- | --- |
| `assets/scenes/tiled-map.esscene` *(default)* | `Tilemap { source: "…/level.tmj" }` | Imports a real [Tiled](https://www.mapeditor.org/) map: **two embedded tilesets** (`terrain` + `props`, global GIDs), a **parallax** background of clouds, **animated** water, and **per-tile collision** — the map is auto-loaded when the scene opens. |
| `assets/scenes/native-map.esscene` | `TilemapLayer` → `.estileset` | References the engine's first-class tileset asset. Collision and the water animation are **derived live at runtime** from the tileset — nothing is baked into the scene but the tile chunks. |
+| `assets/scenes/iso-map.esscene` | `TilemapLayer` · **isometric** | A diamond-grid island — water border, sand beach, grass, forest, and a stone clearing. |
+| `assets/scenes/staggered-map.esscene` | `TilemapLayer` · **staggered** | The same diamond tiles in a staggered-isometric layout, with a river winding across the patchwork. |
+| `assets/scenes/hex-map.esscene` | `TilemapLayer` · **hexagonal** | A pointy-top hex strategy map — a lake with a sandy shore, forest, and a snow-capped mountain range. |
+
+## Orientations
+
+Isometric, staggered, and hexagonal maps are authored **natively in the editor** —
+no external tool needed. Create one with **Entity → New Tilemap**, pick the
+orientation (and, for hex/staggered, the stagger axis/index and hex side length),
+then paint. The viewport draws the matching diamond or hex grid, and the map's
+orientation is switchable any time from the **Tilemap Layer** inspector. The three
+scenes above were built exactly this way; open any of them to see the shaped grid
+and paint on it.
## One runtime model
@@ -30,10 +44,13 @@ live collision and animation data. So:
| `assets/textures/props.png` | A few of its tiles repacked as a second tileset (gem, heart, coin box, key, foliage). |
| `assets/maps/level.tmj` | The Tiled map (both tilesets embedded, CSV layer data). |
| `assets/tilesets/terrain.estileset` | The engine-native tileset: atlas grid + per-tile collision + water animation. |
+| `assets/tilesets/iso-tiles.png` + `iso.estileset` | Six 64×32 **isometric** diamond terrain tiles (grass/water/sand/stone/dirt/forest). |
+| `assets/tilesets/hex-tiles.png` + `hex.estileset` | Six 64×64 pointy-top **hexagon** terrain tiles (grass/water/sand/forest/mountain/snow). |
-Art is **Kenney [Pixel Platformer](https://kenney.nl/assets/pixel-platformer)
+The platformer art is **Kenney [Pixel Platformer](https://kenney.nl/assets/pixel-platformer)
(CC0)** — reuse it freely, including commercially. See
-[../ASSETS.md](../ASSETS.md).
+[../ASSETS.md](../ASSETS.md). The isometric and hexagonal tiles are simple
+procedurally-generated terrain shapes, CC0 as well.
## Running
diff --git a/examples/tilemap-demo/assets/scenes/hex-map.esscene b/examples/tilemap-demo/assets/scenes/hex-map.esscene
new file mode 100644
index 000000000..bbbd0a3e1
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/hex-map.esscene
@@ -0,0 +1,118 @@
+{
+ "version": "1.0",
+ "name": "Tilemap Demo",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 336,
+ "y": -224,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 210,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ },
+ "worldPosition": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldRotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldScale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "TilemapLayer",
+ "data": {
+ "cellSize": {
+ "x": 64,
+ "y": 64
+ },
+ "orientation": 3,
+ "hexSideLength": 0,
+ "staggerAxis": 0,
+ "staggerIndex": 0,
+ "originOffset": {
+ "x": 0,
+ "y": 0
+ },
+ "tileset": 0,
+ "tilesetColumns": 1,
+ "tilesetRows": 1,
+ "renderLayer": 0,
+ "tintColor": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "opacity": 1,
+ "parallaxFactor": {
+ "x": 1,
+ "y": 1
+ },
+ "visible": true,
+ "tilesetAssets": [
+ "@uuid:e69568b0-2a2e-4607-ae6f-e41480e199ad"
+ ],
+ "tilesetAsset": "@uuid:e69568b0-2a2e-4607-ae6f-e41480e199ad",
+ "chunks": "RVNUTQEAAAAAAAAAAAAAAAQABAABAAEAAQABAAEABgAGAAYAAAAAAAAAAAAAAAAAAQABAAEABAABAAQAAQAGAAYABgAAAAAAAAAAAAAAAAABAAEAAwADAAMAAQABAAUABQAFAAAAAAAAAAAAAAAAAAEAAwACAAIAAgADAAEABQAFAAUAAAAAAAAAAAAAAAAAAQADAAIAAgACAAMAAQABAAEAAQAAAAAAAAAAAAAAAAAEAAMAAgACAAIAAwABAAEAAQABAAAAAAAAAAAAAAAAAAEAAwACAAIAAgADAAEAAQABAAEAAAAAAAAAAAAAAAAAAQADAAIAAgACAAMAAQABAAEAAQAAAAAAAAAAAAAAAAABAAEAAwADAAMAAQABAAEAAQABAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/tilemap-demo/assets/scenes/hex-map.esscene.meta b/examples/tilemap-demo/assets/scenes/hex-map.esscene.meta
new file mode 100644
index 000000000..f3dee1ce0
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/hex-map.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "d98eea0a-7be5-42cb-8260-2e79be2e46f5",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/tilemap-demo/assets/scenes/iso-map.esscene b/examples/tilemap-demo/assets/scenes/iso-map.esscene
new file mode 100644
index 000000000..86b079f9f
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/iso-map.esscene
@@ -0,0 +1,118 @@
+{
+ "version": "1.0",
+ "name": "Tilemap Demo",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 32,
+ "y": -120,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 200,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ },
+ "worldPosition": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldRotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldScale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "TilemapLayer",
+ "data": {
+ "cellSize": {
+ "x": 64,
+ "y": 32
+ },
+ "orientation": 1,
+ "hexSideLength": 0,
+ "staggerAxis": 0,
+ "staggerIndex": 0,
+ "originOffset": {
+ "x": 0,
+ "y": 0
+ },
+ "tileset": 0,
+ "tilesetColumns": 1,
+ "tilesetRows": 1,
+ "renderLayer": 0,
+ "tintColor": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "opacity": 1,
+ "parallaxFactor": {
+ "x": 1,
+ "y": 1
+ },
+ "visible": true,
+ "tilesetAssets": [
+ "@uuid:9591fbfd-314a-41cd-aa59-1fb2feafdcdf"
+ ],
+ "tilesetAsset": "@uuid:9591fbfd-314a-41cd-aa59-1fb2feafdcdf",
+ "chunks": "RVNUTQEAAAAAAAAAAAAAAAIAAgACAAIAAgACAAIAAgACAAIAAgAAAAAAAAAAAAAAAgADAAMAAwADAAMAAwADAAMAAwACAAAAAAAAAAAAAAACAAMABgAGAAEAAQABAAEAAQADAAIAAAAAAAAAAAAAAAIAAwAGAAEAAQABAAYAAQABAAMAAgAAAAAAAAAAAAAAAgADAAYAAQAEAAQABQABAAEAAwACAAAAAAAAAAAAAAACAAMAAQAGAAUABAABAAEAAQADAAIAAAAAAAAAAAAAAAIAAwAGAAEAAQABAAEAAQABAAMAAgAAAAAAAAAAAAAAAgADAAMAAwADAAMAAwADAAMAAwACAAAAAAAAAAAAAAACAAIAAgACAAIAAgACAAIAAgACAAIAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/tilemap-demo/assets/scenes/iso-map.esscene.meta b/examples/tilemap-demo/assets/scenes/iso-map.esscene.meta
new file mode 100644
index 000000000..dc8131f3b
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/iso-map.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "b5a95ceb-d96b-4231-b764-f93d5a43ffb0",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/tilemap-demo/assets/scenes/staggered-map.esscene b/examples/tilemap-demo/assets/scenes/staggered-map.esscene
new file mode 100644
index 000000000..b3b10d7c9
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/staggered-map.esscene
@@ -0,0 +1,118 @@
+{
+ "version": "1.0",
+ "name": "Tilemap Demo",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "visible": true,
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 400,
+ "y": -88,
+ "z": 10
+ }
+ }
+ },
+ {
+ "type": "Camera",
+ "data": {
+ "projectionType": 1,
+ "orthoSize": 240,
+ "isActive": true,
+ "priority": 0
+ }
+ }
+ ]
+ },
+ {
+ "id": 1,
+ "name": "Tilemap",
+ "parent": null,
+ "children": [],
+ "components": [
+ {
+ "type": "Transform",
+ "data": {
+ "position": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "rotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "scale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ },
+ "worldPosition": {
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldRotation": {
+ "w": 1,
+ "x": 0,
+ "y": 0,
+ "z": 0
+ },
+ "worldScale": {
+ "x": 1,
+ "y": 1,
+ "z": 1
+ }
+ }
+ },
+ {
+ "type": "TilemapLayer",
+ "data": {
+ "cellSize": {
+ "x": 64,
+ "y": 32
+ },
+ "orientation": 2,
+ "hexSideLength": 0,
+ "staggerAxis": 0,
+ "staggerIndex": 0,
+ "originOffset": {
+ "x": 0,
+ "y": 0
+ },
+ "tileset": 0,
+ "tilesetColumns": 1,
+ "tilesetRows": 1,
+ "renderLayer": 0,
+ "tintColor": {
+ "r": 1,
+ "g": 1,
+ "b": 1,
+ "a": 1
+ },
+ "opacity": 1,
+ "parallaxFactor": {
+ "x": 1,
+ "y": 1
+ },
+ "visible": true,
+ "tilesetAssets": [
+ "@uuid:9591fbfd-314a-41cd-aa59-1fb2feafdcdf"
+ ],
+ "tilesetAsset": "@uuid:9591fbfd-314a-41cd-aa59-1fb2feafdcdf",
+ "chunks": "RVNUTQEAAAAAAAAAAAAAAAEAAwACAAIAAwAGAAYABgAGAAYAAQABAAAAAAAAAAAAAQAGAAMAAgACAAMAAQABAAYAAQABAAYAAAAAAAAAAAABAAYAAwACAAIAAgADAAQABgABAAEAAQAAAAAAAAAAAAEABgABAAMAAgACAAIAAwABAAYAAQABAAAAAAAAAAAABgABAAYAAQADAAIAAgADAAEABgAEAAEAAAAAAAAAAAABAAEAAQABAAEAAwACAAIAAwABAAEAAQAAAAAAAAAAAAEAAQABAAEABgABAAMAAgACAAMAAQABAAAAAAAAAAAAAQABAAEAAQABAAEAAwACAAIAAgADAAEAAAAAAAAAAAAGAAYAAQABAAEAAQAGAAMAAgACAAIAAwAAAAAAAAAAAAEABgAGAAYAAQABAAEAAQADAAIAAgADAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
+ }
+ }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/examples/tilemap-demo/assets/scenes/staggered-map.esscene.meta b/examples/tilemap-demo/assets/scenes/staggered-map.esscene.meta
new file mode 100644
index 000000000..f3613230f
--- /dev/null
+++ b/examples/tilemap-demo/assets/scenes/staggered-map.esscene.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "c5b54ca8-0fd8-4255-a6b3-9de98ba72ea7",
+ "version": "2.0",
+ "type": "scene",
+ "importer": {}
+}
diff --git a/examples/tilemap-demo/assets/tilesets/hex-tiles.png b/examples/tilemap-demo/assets/tilesets/hex-tiles.png
new file mode 100644
index 000000000..f15369bc5
Binary files /dev/null and b/examples/tilemap-demo/assets/tilesets/hex-tiles.png differ
diff --git a/examples/tilemap-demo/assets/tilesets/hex-tiles.png.meta b/examples/tilemap-demo/assets/tilesets/hex-tiles.png.meta
new file mode 100644
index 000000000..ddf265174
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/hex-tiles.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "4117ecce-de7c-4ec8-84c0-9e6d892d6db1",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "nearest",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/tilemap-demo/assets/tilesets/hex.estileset b/examples/tilemap-demo/assets/tilesets/hex.estileset
new file mode 100644
index 000000000..be7df69f6
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/hex.estileset
@@ -0,0 +1,11 @@
+{
+ "version": "1",
+ "texture": "@uuid:4117ecce-de7c-4ec8-84c0-9e6d892d6db1",
+ "tileWidth": 64,
+ "tileHeight": 64,
+ "columns": 6,
+ "margin": 0,
+ "spacing": 0,
+ "tileCount": 6,
+ "tiles": {}
+}
diff --git a/examples/tilemap-demo/assets/tilesets/hex.estileset.meta b/examples/tilemap-demo/assets/tilesets/hex.estileset.meta
new file mode 100644
index 000000000..2b0bd367b
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/hex.estileset.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "e69568b0-2a2e-4607-ae6f-e41480e199ad",
+ "version": "2.0",
+ "type": "tileset",
+ "importer": {}
+}
diff --git a/examples/tilemap-demo/assets/tilesets/iso-tiles.png b/examples/tilemap-demo/assets/tilesets/iso-tiles.png
new file mode 100644
index 000000000..ca23e5b95
Binary files /dev/null and b/examples/tilemap-demo/assets/tilesets/iso-tiles.png differ
diff --git a/examples/tilemap-demo/assets/tilesets/iso-tiles.png.meta b/examples/tilemap-demo/assets/tilesets/iso-tiles.png.meta
new file mode 100644
index 000000000..59caf0332
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/iso-tiles.png.meta
@@ -0,0 +1,17 @@
+{
+ "uuid": "79acea81-9631-48a0-adcf-921654279f00",
+ "version": "2.0",
+ "type": "texture",
+ "importer": {
+ "maxSize": 2048,
+ "filterMode": "nearest",
+ "wrapMode": "clamp",
+ "premultiplyAlpha": false,
+ "sliceBorder": {
+ "left": 0,
+ "right": 0,
+ "top": 0,
+ "bottom": 0
+ }
+ }
+}
diff --git a/examples/tilemap-demo/assets/tilesets/iso.estileset b/examples/tilemap-demo/assets/tilesets/iso.estileset
new file mode 100644
index 000000000..af735e406
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/iso.estileset
@@ -0,0 +1,11 @@
+{
+ "version": "1",
+ "texture": "@uuid:79acea81-9631-48a0-adcf-921654279f00",
+ "tileWidth": 64,
+ "tileHeight": 32,
+ "columns": 6,
+ "margin": 0,
+ "spacing": 0,
+ "tileCount": 6,
+ "tiles": {}
+}
diff --git a/examples/tilemap-demo/assets/tilesets/iso.estileset.meta b/examples/tilemap-demo/assets/tilesets/iso.estileset.meta
new file mode 100644
index 000000000..70b5c0a0f
--- /dev/null
+++ b/examples/tilemap-demo/assets/tilesets/iso.estileset.meta
@@ -0,0 +1,6 @@
+{
+ "uuid": "9591fbfd-314a-41cd-aa59-1fb2feafdcdf",
+ "version": "2.0",
+ "type": "tileset",
+ "importer": {}
+}