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): Tiled tile (GID) objects render as positioned sprites

yhhdffd83023d3f
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 97918cada..4ccdd7870 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -235,6 +235,13 @@ jobs:
ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json \
ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 \
'ESTELLA_VERIFY_EXPECT=[{"x":0.40,"y":0.36,"rgb":[255,0,0]},{"x":0.60,"y":0.36,"rgb":[0,255,0]},{"x":0.40,"y":0.58,"rgb":[0,0,255]},{"x":0.60,"y":0.58,"rgb":[255,255,0]}]'
+ # Tiled tile (GID) object: an object-layer object with a gid renders as a
+ # positioned Sprite (bottom-left anchor, tileset UV) — the green tile centered.
+ run_scene tilemap-gidobj \
+ ESTELLA_VERIFY_SCENE=/scenes/tilemap-gidobj.esscene \
+ ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-gidobj.textures.json \
+ ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 \
+ 'ESTELLA_VERIFY_EXPECT=[{"x":0.5,"y":0.5,"rgb":[0,255,0],"tol":40},{"x":0.5,"y":0.12,"rgb":[0,0,0],"tol":30}]'
run_scene ui-mask \
ESTELLA_VERIFY_SCENE=/scenes/ui-list-mask.esscene \
ESTELLA_VERIFY_MANIFEST=/scenes/ui-list-mask.textures.json \
diff --git a/desktop/package.json b/desktop/package.json
index 71aa7aba8..99181499a 100644
--- a/desktop/package.json
+++ b/desktop/package.json
@@ -34,6 +34,7 @@
"verify:render:tilemap": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-flip.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-flip.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:transform": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-transform.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-transform.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,255,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,0,0]}]\" electron scripts/headless-verify.mjs",
"verify:render:tilemap:multiset": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-multiset.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-multiset.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=6 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.40,\\\"y\\\":0.36,\\\"rgb\\\":[255,0,0]},{\\\"x\\\":0.60,\\\"y\\\":0.36,\\\"rgb\\\":[0,255,0]},{\\\"x\\\":0.40,\\\"y\\\":0.58,\\\"rgb\\\":[0,0,255]},{\\\"x\\\":0.60,\\\"y\\\":0.58,\\\"rgb\\\":[255,255,0]}]\" electron scripts/headless-verify.mjs",
+ "verify:render:tilemap:gidobj": "vite build && ESTELLA_VERIFY_SCENE=/scenes/tilemap-gidobj.esscene ESTELLA_VERIFY_MANIFEST=/scenes/tilemap-gidobj.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=10 ESTELLA_VERIFY_EXPECT='[{\"x\":0.5,\"y\":0.5,\"rgb\":[0,255,0],\"tol\":40},{\"x\":0.5,\"y\":0.12,\"rgb\":[0,0,0],\"tol\":30}]' electron scripts/headless-verify.mjs",
"verify:render:material": "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_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[255,0,0],\\\"tol\\\":40}]\" electron scripts/headless-verify.mjs",
"verify:render:ktx2": "vite build && ESTELLA_VERIFY_SCENE=/scenes/ktx2-sprite.esscene ESTELLA_VERIFY_MANIFEST=/scenes/ktx2-sprite.textures.json ESTELLA_VERIFY_W=256 ESTELLA_VERIFY_H=256 ESTELLA_VERIFY_STEPS=2 ESTELLA_VERIFY_EXPECT=\"[{\\\"x\\\":0.5,\\\"y\\\":0.5,\\\"rgb\\\":[0,180,0],\\\"tol\\\":50}]\" electron scripts/headless-verify.mjs",
"verify:render:cooked": "vite build && ESTELLA_COOK_FIXTURE=1 vitest run tests/cooked-verify-fixture.test.ts && electron scripts/headless-cooked-verify.mjs",
diff --git a/desktop/public/scenes/tilemap-gidobj.esscene b/desktop/public/scenes/tilemap-gidobj.esscene
new file mode 100644
index 000000000..054b76260
--- /dev/null
+++ b/desktop/public/scenes/tilemap-gidobj.esscene
@@ -0,0 +1,28 @@
+{
+ "version": "1.0",
+ "name": "TilemapGidObject",
+ "entities": [
+ {
+ "id": 0,
+ "name": "Camera",
+ "parent": null,
+ "children": [],
+ "components": [
+ { "type": "Transform", "data": { "position": { "x": 8, "y": -8, "z": 10 } } },
+ { "type": "Camera", "data": { "projectionType": 1, "orthoSize": 16, "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-gidobj/map.tmj" } }
+ ],
+ "visible": true
+ }
+ ]
+}
diff --git a/desktop/public/scenes/tilemap-gidobj.textures.json b/desktop/public/scenes/tilemap-gidobj.textures.json
new file mode 100644
index 000000000..0967ef424
--- /dev/null
+++ b/desktop/public/scenes/tilemap-gidobj.textures.json
@@ -0,0 +1 @@
+{}
diff --git a/desktop/public/scenes/tilemap-gidobj/a.png b/desktop/public/scenes/tilemap-gidobj/a.png
new file mode 100644
index 000000000..3f9167c5d
Binary files /dev/null and b/desktop/public/scenes/tilemap-gidobj/a.png differ
diff --git a/desktop/public/scenes/tilemap-gidobj/map.tmj b/desktop/public/scenes/tilemap-gidobj/map.tmj
new file mode 100644
index 000000000..565663a34
--- /dev/null
+++ b/desktop/public/scenes/tilemap-gidobj/map.tmj
@@ -0,0 +1,34 @@
+{
+ "type": "map",
+ "version": "1.10",
+ "orientation": "orthogonal",
+ "renderorder": "right-down",
+ "width": 4,
+ "height": 4,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "infinite": false,
+ "layers": [
+ {
+ "type": "objectgroup",
+ "name": "Decor",
+ "visible": true,
+ "objects": [
+ { "id": 1, "name": "greentile", "x": 0, "y": 16, "width": 16, "height": 16, "gid": 2, "rotation": 0 }
+ ]
+ }
+ ],
+ "tilesets": [
+ {
+ "firstgid": 1,
+ "name": "a",
+ "image": "a.png",
+ "imagewidth": 32,
+ "imageheight": 16,
+ "tilewidth": 16,
+ "tileheight": 16,
+ "columns": 2,
+ "tilecount": 2
+ }
+ ]
+}
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index 1d828c62a..35a708d89 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -30,7 +30,8 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
} catch (e) {
log.warn('asset', `Failed to load tileset texture: ${imagePath}`, e);
}
- tilesets.push({ textureHandle, columns: ts.columns, firstId: ts.firstGid });
+ const rows = ts.columns > 0 ? Math.max(1, Math.ceil(ts.tileCount / ts.columns)) : 1;
+ tilesets.push({ textureHandle, columns: ts.columns, rows, firstId: ts.firstGid });
}
registerTilemapSource(path, {
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index 91cc7ac34..53046c508 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -92,6 +92,10 @@ export interface TiledObjectData {
rotation: number;
vertices: number[] | null;
properties: Map<string, unknown>;
+ /** A tile (GID) object: the raw Tiled global tile id + flip flags. When set, the
+ * object is a positioned tile rendered as a sprite (see decodeTiledGid); absent
+ * for the shape objects (rect/ellipse/polygon/polyline/point). */
+ gid?: number;
}
export interface TiledObjectGroupData {
@@ -173,6 +177,18 @@ function convertGid(gid: number): number {
return globalId | flags;
}
+/** Split a Tiled tile-object GID into its global tile id + H/V/D flip flags. Unlike
+ * convertGid (which truncates to the engine's 13-bit tile-layer id), this keeps the
+ * full 29-bit global id so the object's tileset can be resolved by firstgid. */
+export function decodeTiledGid(gid: number): { globalId: number; flipH: boolean; flipV: boolean; flipD: boolean } {
+ return {
+ globalId: gid & TILED_GID_MASK,
+ flipH: (gid & TILED_FLIP_H) !== 0,
+ flipV: (gid & TILED_FLIP_V) !== 0,
+ flipD: (gid & TILED_FLIP_D) !== 0,
+ };
+}
+
/**
* Flatten Tiled `group` layers (which nest child layers) into one list, in
* document order — matching how tile/object layers are consumed.
@@ -348,6 +364,7 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
rotation: (obj.rotation as number) ?? 0,
vertices,
properties: props,
+ gid: typeof obj.gid === 'number' ? obj.gid : undefined,
});
}
const groupProps = new Map<string, unknown>();
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index 823f8e855..84cb4f81e 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -2,7 +2,7 @@
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import type { App, Plugin } from '../app';
import type { ESEngineModule } from '../wasm';
-import { Transform, TilemapLayer, Canvas, RuntimeOnly, type TilemapLayerData } from '../component';
+import { Transform, TilemapLayer, Sprite, Canvas, RuntimeOnly, type TilemapLayerData } from '../component';
import { Schedule } from '../system';
import type { SystemDef } from '../system';
import { initTilemapAPI, shutdownTilemapAPI, TilemapAPI } from './tilemapAPI';
@@ -12,7 +12,7 @@ import { getTilemapSource, getResolvedTileset } from './tilesetCache';
import { resolveTilesetModel } from './tilesetResolve';
import {
generateLayerCollision, generateChunkCollision, generateChunkPolygonCollision,
- generateObjectCollision, isCollisionObjectGroup,
+ generateObjectCollision, isCollisionObjectGroup, decodeTiledGid,
} from './tiledLoader';
import { decodeTilemapChunks } from './chunkCodec';
import { Assets } from '../asset/AssetPlugin';
@@ -329,6 +329,52 @@ export class TilemapPlugin implements Plugin {
children.push(child);
initializedLayers.add(child);
}
+
+ // Tile (GID) objects — a positioned tile rendered as a Sprite,
+ // in edit + play mode like the tile layers. Parented to the
+ // tilemap entity, so the sprite's local position is the object's
+ // offset within the map (pixels). H/V flip → flipX/flipY;
+ // diagonal flip + rotation are follow-ups.
+ for (const group of cached.objectGroups ?? []) {
+ if (group.visible === false) continue;
+ for (const obj of group.objects) {
+ if (obj.gid === undefined || obj.visible === false) continue;
+ const dec = decodeTiledGid(obj.gid);
+ // Resolve the tileset by global id (largest firstId <= id).
+ let ts: (typeof cached.tilesets)[number] | undefined;
+ for (const cand of cached.tilesets) {
+ if (cand.textureHandle && cand.firstId <= dec.globalId &&
+ (!ts || cand.firstId > ts.firstId)) ts = cand;
+ }
+ if (!ts) continue;
+ const localId = dec.globalId - ts.firstId;
+ const cols = ts.columns || 1;
+ const rows = ts.rows || 1;
+ const uvW = 1 / cols, uvH = 1 / rows;
+ const col = localId % cols;
+ const row = Math.floor(localId / cols);
+ const w = obj.width || cached.tileWidth;
+ const h = obj.height || cached.tileHeight;
+ // Tiled tile-objects anchor BOTTOM-LEFT, y-down; the
+ // sprite is centered, and world Y is up.
+ const tileChild = world.spawn(obj.name || `TileObject_${obj.id}`);
+ world.insert(tileChild, Transform, {
+ position: { x: obj.x + w / 2, y: -(obj.y - h / 2), z: 0 },
+ });
+ world.insert(tileChild, Sprite, {
+ texture: ts.textureHandle,
+ size: { x: w, y: h },
+ uvOffset: { x: col * uvW, y: 1 - (row + 1) * uvH },
+ uvScale: { x: uvW, y: uvH },
+ flipX: dec.flipH,
+ flipY: dec.flipV,
+ layer: cached.layers.length,
+ });
+ world.insert(tileChild, RuntimeOnly, {});
+ world.setParent(tileChild, entity);
+ children.push(tileChild);
+ }
+ }
sourceLayerEntities.set(entity, children);
}
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index 43e42c596..ce8e202b5 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -23,6 +23,9 @@ export interface LoadedTilemapLayer {
export interface LoadedTilemapTileset {
textureHandle: number;
columns: number;
+ /** Tile rows (= ceil(tileCount / columns)); with columns it gives the normalized
+ * UV cell size (1/columns × 1/rows) for tile (GID) objects. */
+ rows: number;
firstId: number; // global tile-id at which this tileset begins (Tiled firstgid)
}
diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.ts
index 6f566acbf..96214cb11 100644
--- a/sdk/tests/tilemap.test.ts
+++ b/sdk/tests/tilemap.test.ts
@@ -15,7 +15,7 @@ import {
} from '../src/tilemap/tilesetCache';
import {
loadTiledMap, parseTmjJson, parseTmjWithExternals, resolveRelativePath, loadTiledCollisionObjects,
- generateLayerCollision, generateObjectCollision, isCollisionObjectGroup,
+ generateLayerCollision, generateObjectCollision, isCollisionObjectGroup, decodeTiledGid,
type TiledObjectData, type TiledObjectGroupData,
} from '../src/tilemap/tiledLoader';
import type { TiledMapData } from '../src/tilemap/tiledLoader';
@@ -95,7 +95,7 @@ describe('TilemapSource cache', () => {
tileWidth: 16,
tileHeight: 16,
layers: [{ name: 'Ground', width: 10, height: 10, tiles: new Uint16Array([1, 2, 3]) }],
- tilesets: [{ textureHandle: 42, columns: 8, firstId: 1 }],
+ tilesets: [{ textureHandle: 42, columns: 8, rows: 8, firstId: 1 }],
};
registerTilemapSource('maps/level1.tmj', source);
expect(getTilemapSource('maps/level1.tmj')).toBe(source);
@@ -589,6 +589,33 @@ describe('parseTmjJson — Phase B: objectgroup parsing', () => {
expect(result!.objectGroups[0].objects).toHaveLength(2);
});
+ it('should carry the gid of a tile (GID) object', () => {
+ const json = {
+ width: 10, height: 10, tilewidth: 32, tileheight: 32,
+ tilesets: [],
+ layers: [{
+ type: 'objectgroup',
+ name: 'Decor',
+ objects: [
+ { id: 1, x: 96, y: 128, width: 32, height: 32, gid: 5, rotation: 0 },
+ { id: 2, x: 0, y: 0, width: 32, height: 32, rotation: 0 }, // shape object, no gid
+ ],
+ }],
+ };
+ const result = parseTmjJson(json)!;
+ expect(result.objectGroups[0].objects[0].gid).toBe(5);
+ expect(result.objectGroups[0].objects[1].gid).toBeUndefined();
+ });
+
+ it('decodeTiledGid splits the global id + H/V/D flip flags', () => {
+ expect(decodeTiledGid(5)).toEqual({ globalId: 5, flipH: false, flipV: false, flipD: false });
+ // Tiled packs flips in the high bits: H=0x80000000, V=0x40000000, D=0x20000000.
+ const flipped = 5 | 0x80000000 | 0x40000000;
+ expect(decodeTiledGid(flipped)).toEqual({ globalId: 5, flipH: true, flipV: true, flipD: false });
+ // A large global id (multi-tileset) survives — not truncated to 13 bits.
+ expect(decodeTiledGid(9000).globalId).toBe(9000);
+ });
+
it('should detect ellipse objects', () => {
const json = {
width: 10, height: 10, tilewidth: 32, tileheight: 32,