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): Tiled tile (GID) objects render as positioned sprites
yhhdffd83023d3f
diff --git a/.github/workflows/build.yml b/.github/workflows/build.ymlindex 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.jsonindex 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.esscenenew file mode 100644index 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.jsonnew file mode 100644index 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.pngnew file mode 100644index 000000000..3f9167c5dBinary files /dev/null and b/desktop/public/scenes/tilemap-gidobj/a.png differdiff --git a/desktop/public/scenes/tilemap-gidobj/map.tmj b/desktop/public/scenes/tilemap-gidobj/map.tmjnew file mode 100644index 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.tsindex 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.tsindex 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 | nullrotation: (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.tsindex 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 Teamimport 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.tsindex 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.tsindex 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,