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): runtime .estileset → tileset model resolver (tileset unification, stage 2)
yhh2b048b86eb38
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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+ });+});