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): wire Tiled multi-tileset imports through the tileset table (part 2)

yhhf2f931b9b94e
diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.ts
index 0e4c43e5e..17c91d0ae 100644
--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts
+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts
@@ -27,7 +27,7 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {
} catch (e) {
log.warn('asset', `Failed to load tileset texture: ${imagePath}`, e);
}
- tilesets.push({ textureHandle, columns: ts.columns });
+ tilesets.push({ textureHandle, columns: ts.columns, firstId: ts.firstGid });
}
registerTilemapSource(path, {
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.ts
index e68089e8f..1a046e13e 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -286,7 +286,7 @@ async function loadTilemaps(
} catch (e) {
log.warn('runtime', `Failed to load tileset texture: ${imagePath}`, e);
}
- tilesets.push({ textureHandle, columns: ts.columns });
+ tilesets.push({ textureHandle, columns: ts.columns, firstId: ts.firstGid });
}
registerTilemapSource(tmjPath, {
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index a244d7894..1c1de1147 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -68,6 +68,7 @@ export interface TiledLayerData {
export interface TiledTilesetData {
name: string;
image: string;
+ firstGid: number; // global tile-id at which this tileset begins
tileWidth: number;
tileHeight: number;
columns: number;
@@ -147,14 +148,17 @@ function parseTintColor(hex: string | undefined): { r: number; g: number; b: num
return { r: 1, g: 1, b: 1, a: 1 };
}
-function convertGid(gid: number, firstGid: number): number {
+// Keep the global GID as the engine tile-id (Tiled GIDs are contiguous across
+// tilesets); the runtime tileset table resolves it to (tileset, local). For a
+// single-tileset map (firstgid 1) this equals the old local id + 1.
+function convertGid(gid: number): number {
if (gid === 0) return 0;
let flags = 0;
if (gid & TILED_FLIP_H) flags |= ENGINE_FLIP_H;
if (gid & TILED_FLIP_V) flags |= ENGINE_FLIP_V;
if (gid & TILED_FLIP_D) flags |= ENGINE_FLIP_D;
- const localId = (gid & TILED_GID_MASK) - firstGid;
- return (localId + 1) | flags;
+ const globalId = (gid & TILED_GID_MASK) & 0x1FFF;
+ return globalId | flags;
}
export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null {
@@ -166,15 +170,13 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
const rawTilesets = json.tilesets as Array<Record<string, unknown>> | undefined;
const tilesets: TiledTilesetData[] = [];
- const firstGids: number[] = [];
if (rawTilesets) {
for (const ts of rawTilesets) {
- const firstGid = (ts.firstgid as number) ?? 1;
- firstGids.push(firstGid);
tilesets.push({
name: (ts.name as string) ?? '',
image: (ts.image as string) ?? '',
+ firstGid: (ts.firstgid as number) ?? 1,
tileWidth: (ts.tilewidth as number) ?? tileWidth,
tileHeight: (ts.tileheight as number) ?? tileHeight,
columns: (ts.columns as number) ?? 1,
@@ -196,9 +198,8 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
const tiles = new Uint16Array(lw * lh);
if (rawData) {
- const firstGid = firstGids[0] ?? 1;
for (let i = 0; i < rawData.length && i < tiles.length; i++) {
- tiles[i] = convertGid(rawData[i], firstGid);
+ tiles[i] = convertGid(rawData[i]);
}
}
@@ -290,12 +291,14 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | null
if (rawTiles) {
for (const tile of rawTiles) {
const localId = (tile.id as number);
- const engineId = localId + 1;
+ // Global engine id = tileset-local id + firstGid (matches the
+ // global GIDs stored in the layer). firstgid 1 -> localId + 1.
+ const engineId = localId + firstGid;
const rawAnim = tile.animation as Array<Record<string, unknown>> | undefined;
if (rawAnim && rawAnim.length > 0) {
const frames: TiledAnimFrame[] = rawAnim.map(f => ({
- tileId: ((f.tileid as number) ?? 0) + 1,
+ tileId: ((f.tileid as number) ?? 0) + firstGid,
duration: (f.duration as number) ?? 100,
}));
tileAnimations.set(engineId, frames);
@@ -455,6 +458,7 @@ export async function parseTiledMap(
result.tilesets.push({
name: api.tiled_getTilesetName(handle, i),
image: api.tiled_getTilesetImage(handle, i),
+ firstGid: api.tiled_getTilesetFirstGid ? api.tiled_getTilesetFirstGid(handle, i) : 1,
tileWidth: api.tiled_getTilesetTileWidth(handle, i),
tileHeight: api.tiled_getTilesetTileHeight(handle, i),
columns: api.tiled_getTilesetColumns(handle, i),
diff --git a/sdk/src/tilemap/tilemapAPI.ts b/sdk/src/tilemap/tilemapAPI.ts
index 216cbaba3..1c325e338 100644
--- a/sdk/src/tilemap/tilemapAPI.ts
+++ b/sdk/src/tilemap/tilemapAPI.ts
@@ -13,6 +13,7 @@ interface TilemapModule {
tilemap_fillRect(entity: number, x: number, y: number,
w: number, h: number, tileId: number): void;
tilemap_setTiles(entity: number, tilesPtr: number, count: number): void;
+ tilemap_setTilesets(entity: number, dataPtr: number, count: number): void;
tilemap_hasLayer(entity: number): boolean;
tilemap_setRenderProps(entity: number, textureHandle: number, tilesetColumns: number,
uvTileW: number, uvTileH: number,
@@ -72,6 +73,7 @@ interface TilemapModule {
tiled_getTilesetTileHeight(handle: number, index: number): number;
tiled_getTilesetColumns(handle: number, index: number): number;
tiled_getTilesetTileCount(handle: number, index: number): number;
+ tiled_getTilesetFirstGid?(handle: number, index: number): number;
tiled_getLayerOpacity(handle: number, index: number): number;
tiled_getLayerTintColor(handle: number, index: number): number;
@@ -143,6 +145,22 @@ export const TilemapAPI = {
});
},
+ /** Replace the layer's multi-tileset table. Empty array reverts to single-tileset. */
+ setTilesets(entity: number, slots: { firstId: number; textureHandle: number; columns: number }[]): void {
+ const m = module_;
+ if (!m) return;
+ const packed = new Uint32Array(slots.length * 3);
+ for (let i = 0; i < slots.length; i++) {
+ packed[i * 3] = slots[i].firstId;
+ packed[i * 3 + 1] = slots[i].textureHandle;
+ packed[i * 3 + 2] = slots[i].columns;
+ }
+ withMalloc(m, packed.byteLength, ptr => {
+ new Uint32Array(m.HEAPU8.buffer, ptr, packed.length).set(packed);
+ m.tilemap_setTilesets(entity, ptr, slots.length);
+ });
+ },
+
hasLayer(entity: number): boolean {
if (!module_) return false;
return module_.tilemap_hasLayer(entity);
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index 4a95e0bb9..6366db4e7 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -11,7 +11,6 @@ import { registerSceneComponentCodec } from '../scene';
import { getTilemapSource } from './tilesetCache';
import { generateLayerCollision, generateChunkCollision } from './tiledLoader';
import { decodeTilemapChunks } from './chunkCodec';
-import { getTextureDimensions } from '../resourceManager';
import { Time } from '../resource';
import { playModeOnly } from '../env';
import type { Entity } from '../types';
@@ -204,19 +203,21 @@ export class TilemapPlugin implements Plugin {
}
}
- const tileset = cached.tilesets[0];
- if (tileset) {
- const dims = getTextureDimensions(tileset.textureHandle);
- if (dims) {
- TilemapAPI.setRenderProps(
- key, tileset.textureHandle, tileset.columns,
- cached.tileWidth / dims.width,
- cached.tileHeight / dims.height,
- i, 0, 1, 1,
- );
- TilemapAPI.setTint(key, 1, 1, 1, 1, 1);
- TilemapAPI.setVisible(key, true);
- }
+ // Multi-tileset: push the full tileset table (firstId +
+ // texture + columns). The renderer batches per texture and
+ // derives UVs from texture size; setRenderProps still carries
+ // the non-tileset metadata (render layer, parallax).
+ const slots = cached.tilesets
+ .filter(t => t.textureHandle)
+ .map(t => ({ firstId: t.firstId, textureHandle: t.textureHandle, columns: t.columns }));
+ if (slots.length > 0) {
+ TilemapAPI.setTilesets(key, slots);
+ TilemapAPI.setRenderProps(
+ key, slots[0].textureHandle, slots[0].columns,
+ 0, 0, i, 0, 1, 1,
+ );
+ TilemapAPI.setTint(key, 1, 1, 1, 1, 1);
+ TilemapAPI.setVisible(key, true);
}
keys.push(key);
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index a2e222f24..ab3b2f279 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -20,6 +20,7 @@ export interface LoadedTilemapLayer {
export interface LoadedTilemapTileset {
textureHandle: number;
columns: number;
+ firstId: number; // global tile-id at which this tileset begins (Tiled firstgid)
}
export interface LoadedTilemapSource {
diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.ts
index 065cd329b..45d118280 100644
--- a/sdk/tests/tilemap.test.ts
+++ b/sdk/tests/tilemap.test.ts
@@ -91,7 +91,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 }],
+ tilesets: [{ textureHandle: 42, columns: 8, firstId: 1 }],
};
registerTilemapSource('maps/level1.tmj', source);
expect(getTilemapSource('maps/level1.tmj')).toBe(source);
@@ -168,6 +168,24 @@ describe('parseTmjJson', () => {
expect(result!.layers[0].tiles[1]).toBe(3);
});
+ it('should keep global GIDs across multiple tilesets and expose firstGid', () => {
+ const json = {
+ width: 3, height: 1, tilewidth: 16, tileheight: 16,
+ tilesets: [
+ { firstgid: 1, name: 'a', image: 'a.png', tilewidth: 16, tileheight: 16, columns: 4, tilecount: 4 },
+ { firstgid: 5, name: 'b', image: 'b.png', tilewidth: 16, tileheight: 16, columns: 4, tilecount: 4 },
+ ],
+ layers: [{ type: 'tilelayer', name: 'L', width: 3, height: 1, visible: true, data: [1, 5, 8] }],
+ };
+ const result = parseTmjJson(json)!;
+ // Tiles keep the global GID (not collapsed to a per-tileset local id), so the
+ // runtime tileset table can resolve which tileset each tile belongs to.
+ expect(Array.from(result.layers[0].tiles)).toEqual([1, 5, 8]);
+ expect(result.tilesets).toHaveLength(2);
+ expect(result.tilesets[0].firstGid).toBe(1);
+ expect(result.tilesets[1].firstGid).toBe(5);
+ });
+
it('should skip non-tilelayer layers', () => {
const json = {
width: 10, height: 10, tilewidth: 32, tileheight: 32,
diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cpp
index 139952956..aacb077f4 100644
--- a/src/esengine/bindings/TilemapBindings.cpp
+++ b/src/esengine/bindings/TilemapBindings.cpp
@@ -406,6 +406,12 @@ u32 tiled_getTilesetColumns(u32 handle, u32 index) {
return map->tilesets[index].columns;
}
+u32 tiled_getTilesetFirstGid(u32 handle, u32 index) {
+ const auto* map = getTiledLoader().getMap(handle);
+ if (!map || index >= map->tilesets.size()) return 0;
+ return map->tilesets[index].first_gid;
+}
+
u32 tiled_getTilesetTileCount(u32 handle, u32 index) {
const auto* map = getTiledLoader().getMap(handle);
if (!map || index >= map->tilesets.size()) return 0;
@@ -723,6 +729,7 @@ EMSCRIPTEN_BINDINGS(esengine_tilemap) {
emscripten::function("tiled_getTilesetTileWidth", &esengine::tiled_getTilesetTileWidth);
emscripten::function("tiled_getTilesetTileHeight", &esengine::tiled_getTilesetTileHeight);
emscripten::function("tiled_getTilesetColumns", &esengine::tiled_getTilesetColumns);
+ emscripten::function("tiled_getTilesetFirstGid", &esengine::tiled_getTilesetFirstGid);
emscripten::function("tiled_getTilesetTileCount", &esengine::tiled_getTilesetTileCount);
emscripten::function("tiled_getObjectGroupCount", &esengine::tiled_getObjectGroupCount);
emscripten::function("tiled_getObjectGroupName", &esengine::tiled_getObjectGroupName);
diff --git a/src/esengine/tilemap/TiledMapLoader.cpp b/src/esengine/tilemap/TiledMapLoader.cpp
index 89570d9e5..89beb7f49 100644
--- a/src/esengine/tilemap/TiledMapLoader.cpp
+++ b/src/esengine/tilemap/TiledMapLoader.cpp
@@ -121,20 +121,15 @@ u16 TiledMapLoader::convertGid(int gid, const std::vector<TiledTilesetInfo>& til
int flipH = 0, flipV = 0, flipD = 0;
cute_tiled_get_flags(gid, &flipH, &flipV, &flipD);
int rawGid = cute_tiled_unset_flags(gid);
-
- u16 localId = 0;
- for (auto it = tilesets.rbegin(); it != tilesets.rend(); ++it) {
- if (static_cast<u32>(rawGid) >= it->first_gid) {
- localId = static_cast<u16>(rawGid - static_cast<int>(it->first_gid) + 1);
- break;
- }
- }
-
- if (localId == 0) {
+ if (rawGid <= 0) {
return EMPTY_TILE;
}
- u16 result = localId & TILE_ID_MASK;
+ // Keep the global GID as the engine tile-id (Tiled GIDs are contiguous across
+ // tilesets); the runtime tileset table resolves it back to (tileset, local).
+ // For a single-tileset map (first_gid == 1) this equals the old local id + 1.
+ (void)tilesets;
+ u16 result = static_cast<u16>(rawGid) & TILE_ID_MASK;
if (flipH) { result |= TILE_FLIP_H; }
if (flipV) { result |= TILE_FLIP_V; }
if (flipD) { result |= TILE_FLIP_D; }