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): runtime .estileset → tileset model resolver (tileset unification, stage 2)

yhh2b048b86eb38
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.ts
index d1dbb5fa7..a3f9dbe76 100644
--- a/sdk/src/tilemap/index.ts
+++ b/sdk/src/tilemap/index.ts
@@ -16,6 +16,10 @@ export {
TILESET_FORMAT_VERSION, parseTileset, serializeTileset, createTileset, collidableTileIds,
type TilesetAsset, type TilesetTile, type TilesetCollision, type TilesetAnimFrame,
} from './tilesetAsset';
+export {
+ resolveTilesetModel,
+ type ResolvedTileset, type TilesetModel, type TilesetModelSlot,
+} from './tilesetResolve';
export {
registerTilemapSource, getTilemapSource, clearTilemapSourceCache,
type LoadedTilemapSource, type LoadedTilemapLayer, type LoadedTilemapTileset,
diff --git a/sdk/src/tilemap/tilesetResolve.ts b/sdk/src/tilemap/tilesetResolve.ts
new file mode 100644
index 000000000..afe501bfd
--- /dev/null
+++ b/sdk/src/tilemap/tilesetResolve.ts
@@ -0,0 +1,89 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file tilesetResolve.ts
+ * @brief Derive the runtime tileset model from `.estileset` assets — LIVE.
+ *
+ * The unification keystone: a `.estileset` (atlas grid + per-tile collision /
+ * animation) is the single source of truth. This turns one or more resolved
+ * `.estileset`s into the SAME runtime model the Tiled importer produces — a
+ * render table (`{firstId, textureHandle, columns}` per tileset), tile
+ * animations, and collidable tile ids — with NO columns copied onto the layer
+ * and NO collision baked at author-time. Edit the tileset, re-resolve, done.
+ *
+ * Tile ids are global and contiguous across tilesets (firstId[0]=1,
+ * firstId[i]=firstId[i-1]+count[i-1]), matching the multi-tileset render table
+ * (`TilesetTable`/`tilemap_setTilesets`) and the Tiled GID convention — so a
+ * single TilemapLayer can mix tilesets and painted/imported maps converge.
+ */
+import type { TilesetAsset } from './tilesetAsset';
+
+/** A `.estileset` parsed + its atlas texture loaded (handle resolved by the caller). */
+export interface ResolvedTileset {
+ asset: TilesetAsset;
+ textureHandle: number;
+}
+
+/** One render-table slot: a tileset's global id base, atlas texture, and grid width. */
+export interface TilesetModelSlot {
+ firstId: number;
+ textureHandle: number;
+ columns: number;
+}
+
+/** The runtime tileset model derived from `.estileset`(s) — global tile-id space. */
+export interface TilesetModel {
+ /** Render table (sorted by firstId), fed to `tilemap_setTilesets`. */
+ slots: TilesetModelSlot[];
+ /** Animations keyed by GLOBAL tile id → frames (frame tile ids are global too). */
+ animations: Map<number, { tileId: number; duration: number }[]>;
+ /** Global tile ids flagged collidable (sorted). */
+ collidableTileIds: number[];
+}
+
+/** Tiles in a tileset: explicit `tileCount`, else the highest authored tile id. */
+function tilesetCount(asset: TilesetAsset): number {
+ if (typeof asset.tileCount === 'number' && asset.tileCount > 0) return asset.tileCount;
+ let max = 0;
+ for (const k of Object.keys(asset.tiles)) max = Math.max(max, Number(k));
+ return max; // local ids are 1-based, so the max id == count of the spanned range
+}
+
+/**
+ * Derive the runtime tileset model from resolved `.estileset`s. The per-tile
+ * collision/animation metadata is read straight off each `.estileset` (live) and
+ * re-keyed into the global id space.
+ */
+export function resolveTilesetModel(tilesets: ResolvedTileset[]): TilesetModel {
+ const slots: TilesetModelSlot[] = [];
+ const animations = new Map<number, { tileId: number; duration: number }[]>();
+ const collidable: number[] = [];
+
+ let firstId = 1;
+ for (const { asset, textureHandle } of tilesets) {
+ slots.push({ firstId, textureHandle, columns: asset.columns });
+
+ // Local tile ids are 1-based; global id = firstId + (localId - 1).
+ for (const key of Object.keys(asset.tiles)) {
+ const localId = Number(key);
+ if (!Number.isInteger(localId) || localId <= 0) continue;
+ const globalId = firstId + localId - 1;
+ const tile = asset.tiles[localId];
+ if (tile.collision) collidable.push(globalId);
+ if (tile.animation && tile.animation.length > 0) {
+ animations.set(
+ globalId,
+ tile.animation.map((f) => ({
+ tileId: firstId + f.tile - 1,
+ duration: f.durationMs,
+ })),
+ );
+ }
+ }
+
+ firstId += Math.max(1, tilesetCount(asset));
+ }
+
+ collidable.sort((a, b) => a - b);
+ return { slots, animations, collidableTileIds: collidable };
+}
diff --git a/sdk/tests/tileset-resolve.test.ts b/sdk/tests/tileset-resolve.test.ts
new file mode 100644
index 000000000..5f6b0a3ee
--- /dev/null
+++ b/sdk/tests/tileset-resolve.test.ts
@@ -0,0 +1,76 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { describe, it, expect } from 'vitest';
+import { resolveTilesetModel, type ResolvedTileset } from '../src/tilemap/tilesetResolve';
+import type { TilesetAsset } from '../src/tilemap/tilesetAsset';
+
+function tileset(over: Partial<TilesetAsset>): TilesetAsset {
+ return {
+ version: '1', texture: '@uuid:tex', tileWidth: 16, tileHeight: 16,
+ columns: 4, margin: 0, spacing: 0, tiles: {}, ...over,
+ };
+}
+
+describe('resolveTilesetModel', () => {
+ it('single tileset → one slot at firstId 1, collidable ids live', () => {
+ const rt: ResolvedTileset = {
+ textureHandle: 100,
+ asset: tileset({
+ columns: 4, tileCount: 8,
+ tiles: { 2: { collision: { type: 'box' } }, 7: { collision: { type: 'polygon', points: [[0, 16], [16, 16], [0, 0]] } } },
+ }),
+ };
+ const m = resolveTilesetModel([rt]);
+ expect(m.slots).toEqual([{ firstId: 1, textureHandle: 100, columns: 4 }]);
+ expect(m.collidableTileIds).toEqual([2, 7]);
+ expect(m.animations.size).toBe(0);
+ });
+
+ it('two tilesets → contiguous global ids; collision re-keyed to global', () => {
+ const a: ResolvedTileset = {
+ textureHandle: 100,
+ asset: tileset({ columns: 4, tileCount: 8, tiles: { 2: { collision: { type: 'box' } } } }),
+ };
+ const b: ResolvedTileset = {
+ textureHandle: 200,
+ asset: tileset({ columns: 4, tileCount: 4, tiles: { 1: { collision: { type: 'box' } }, 2: { collision: { type: 'box' } } } }),
+ };
+ const m = resolveTilesetModel([a, b]);
+ // tileset B starts at firstId 1 + 8 = 9
+ expect(m.slots).toEqual([
+ { firstId: 1, textureHandle: 100, columns: 4 },
+ { firstId: 9, textureHandle: 200, columns: 4 },
+ ]);
+ // A local 2 → global 2; B locals 1,2 → globals 9,10
+ expect(m.collidableTileIds).toEqual([2, 9, 10]);
+ });
+
+ it('animations re-key both the tile and its frames to global ids', () => {
+ const a: ResolvedTileset = { textureHandle: 1, asset: tileset({ tileCount: 8 }) };
+ const b: ResolvedTileset = {
+ textureHandle: 2,
+ asset: tileset({
+ columns: 2, tileCount: 4,
+ tiles: { 1: { animation: [{ tile: 1, durationMs: 100 }, { tile: 2, durationMs: 150 }] } },
+ }),
+ };
+ const m = resolveTilesetModel([a, b]);
+ // B starts at 9 → animated tile global 9, frames global 9 & 10
+ expect(m.animations.get(9)).toEqual([
+ { tileId: 9, duration: 100 },
+ { tileId: 10, duration: 150 },
+ ]);
+ });
+
+ it('tileCount falls back to the highest authored tile id', () => {
+ const a: ResolvedTileset = {
+ textureHandle: 1,
+ asset: tileset({ columns: 4, tiles: { 3: { collision: { type: 'box' } } } }), // no tileCount
+ };
+ const b: ResolvedTileset = { textureHandle: 2, asset: tileset({ tileCount: 4, tiles: { 1: { collision: { type: 'box' } } } }) };
+ const m = resolveTilesetModel([a, b]);
+ // a's count falls back to max id 3 → b starts at firstId 4
+ expect(m.slots[1].firstId).toBe(4);
+ expect(m.collidableTileIds).toEqual([3, 4]); // a tile 3 → 3; b tile 1 → global 4
+ });
+});