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): image-collection tilesets fold into a grid atlas at load
yhh5bd9845c54a3
diff --git a/desktop/electron/cookAssets.ts b/desktop/electron/cookAssets.tsindex bec4667c4..afb3ad682 100644--- a/desktop/electron/cookAssets.ts+++ b/desktop/electron/cookAssets.ts@@ -165,6 +165,12 @@ function rewriteTilemapRefs(for (const ts of tilesets) {if (typeof ts.image === 'string') ts.image = rewrite(ts.image); // inline tileset imageif (typeof ts.source === 'string') ts.source = rewrite(ts.source); // external .tsj tileset+ if (Array.isArray(ts.tiles)) {+ // Image-collection tileset: one image per tile.+ for (const t of ts.tiles as Record<string, unknown>[]) {+ if (typeof t?.image === 'string') t.image = rewrite(t.image);+ }+ }}return new TextEncoder().encode(JSON.stringify(json, null, 2) + '\n');}diff --git a/docs/astro/src/content/docs/guides/tilemap.mdx b/docs/astro/src/content/docs/guides/tilemap.mdxindex f4a2d608e..631a71b55 100644--- a/docs/astro/src/content/docs/guides/tilemap.mdx+++ b/docs/astro/src/content/docs/guides/tilemap.mdx@@ -68,6 +68,12 @@ const loadLevel = defineSystem([Commands()], (cmds) => {|---|---|---|---|| `source` | asset | `''` | The Tiled map file (`tilemap` asset). |+Grid tilesets (one atlas image), external `.tsj` tilesets, and **image-collection+tilesets** (Tiled's "collection of images" — one loose image per tile) all load.+Collection tiles are folded into a single grid atlas at load time, so they render+exactly like a hand-authored tileset; each image must match the map's tile size+(anything else fails loud with the fix).+## The `TilemapLayer` componentEach layer (loaded from Tiled, or spawned by you) carries its visual metadata. Thediff --git a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdxindex 246f43ad6..c9496fd1b 100644--- a/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx+++ b/docs/astro/src/content/docs/zh-cn/guides/tilemap.mdx@@ -61,6 +61,11 @@ const loadLevel = defineSystem([Commands()], (cmds) => {|---|---|---|---|| `source` | asset | `''` | Tiled 地图文件(`tilemap` 资源)。 |+网格 tileset(单张图集图)、外部 `.tsj` tileset、以及 **image-collection tileset**+(Tiled 的"图片集合"——每个瓦片一张松散图片)都能加载。collection 瓦片在加载时+折叠进一张网格图集,渲染上与手工图集 tileset 完全一致;每张图片必须与地图瓦片+尺寸一致(否则硬错误并给出修法)。+## `TilemapLayer` 组件每个图层(从 Tiled 加载,或你自己生成)携带它的视觉元数据。渲染器实时读取这些,所以动画化diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex c10dfac08..a4bf00a76 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -6060,6 +6060,7 @@ width: number## TiledTilesetData — interface```+collectionTiles: TiledCollectionTile[] | undefinedcolumns: numberfirstGid: numberimage: stringdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex b2d8d1abd..343b5f3cd 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -6055,6 +6055,7 @@ width: number## TiledTilesetData — interface```+collectionTiles: TiledCollectionTile[] | undefinedcolumns: numberfirstGid: numberimage: stringdiff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.tsindex b02c14618..43e1eb04e 100644--- a/sdk/src/asset/AssetLoader.ts+++ b/sdk/src/asset/AssetLoader.ts@@ -69,6 +69,20 @@ export interface LoadContext {loadTexture(path: string, flipY?: boolean): Promise<TextureResult>;loadText(path: string): Promise<string>;loadBinary(path: string): Promise<ArrayBuffer>;+ /**+ * Decode a texture ref to top-first RGBA pixels through the platform's ONE+ * decode path (a runtime-injected pixel decoder when present, else the+ * shared fetch→ImageBitmap route). For loaders that COMPOSE textures — the+ * tilemap loader folding an image-collection tileset into a grid atlas —+ * rather than uploading refs 1:1. Optional: minimal providers may lack it;+ * consumers fail loud.+ */+ decodePixels?(path: string): Promise<{ width: number; height: number; pixels: Uint8Array }>;+ /** Upload raw top-first RGBA as a texture (TextureLoader.loadFromPixels).+ * Optional, same caveat as {@link decodePixels}. */+ createTextureFromPixels?(+ width: number, height: number, pixels: Uint8Array, flipY: boolean,+ ): Promise<TextureResult>;/*** Audio API for the owning app, resolved lazily so that* AudioPlugin / AssetPlugin can be installed in either order.diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex fe5075540..cd504e7e2 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -30,6 +30,7 @@ import type { SpineModuleController } from '../spine/SpineController';import { getAssetFields } from './AssetFieldRegistry';import { getComponentDefaults } from '../component';import { discoverSceneAssets } from './discoverAssets';+import { fetchDecodePixels } from './imageDecode';import type { SceneData } from '../scene';import { SceneHandle, type ReleaseCallback } from './SceneHandle';import type { AssetRegistry } from './AssetRegistry';@@ -1156,6 +1157,16 @@ export class Assets {async loadBinary(path: string): Promise<ArrayBuffer> {return self.backend.fetchBinary(self.backend.resolveUrl(path));},+ async decodePixels(path: string) {+ // The platform's one decode path: the runtime-injected pixel+ // decoder when present (wechat / playable), else fetch→bitmap.+ const decoder = self.textureLoader_.pixelDecoder;+ if (decoder) return decoder(path, false);+ return fetchDecodePixels(self.backend.resolveUrl(self.catalog.getBuildPath(path)));+ },+ async createTextureFromPixels(width, height, pixels, flipY) {+ return self.textureLoader_.loadFromPixels(width, height, pixels, flipY);+ },getAudio() {return self.getAudio_();},diff --git a/sdk/src/asset/loaders/TextureLoader.ts b/sdk/src/asset/loaders/TextureLoader.tsindex 65b0a735d..c26b25863 100644--- a/sdk/src/asset/loaders/TextureLoader.ts+++ b/sdk/src/asset/loaders/TextureLoader.ts@@ -102,6 +102,7 @@ export class TextureLoader implements AssetLoader<TextureResult> {* default URL `<img>` decode path (editor / app Assets, unchanged). */private pixelDecoder_: TexturePixelDecoder | null = null;setPixelDecoder(decoder: TexturePixelDecoder | null): void { this.pixelDecoder_ = decoder; }+ get pixelDecoder(): TexturePixelDecoder | null { return this.pixelDecoder_; }private ensureCanvas_(): { canvas: HTMLCanvasElement | OffscreenCanvas; ctx: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D } {if (this.canvas_ && this.ctx_) return { canvas: this.canvas_, ctx: this.ctx_ };diff --git a/sdk/src/asset/loaders/TilemapAssetLoader.ts b/sdk/src/asset/loaders/TilemapAssetLoader.tsindex dea076562..3094d6a56 100644--- a/sdk/src/asset/loaders/TilemapAssetLoader.ts+++ b/sdk/src/asset/loaders/TilemapAssetLoader.ts@@ -1,8 +1,11 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport type { AssetLoader, LoadContext, TilemapResult } from '../AssetLoader';-import { parseTmjWithExternals, resolveRelativePath } from '../../tilemap/tiledLoader';-import { registerTilemapSource } from '../../tilemap/tilesetCache';+import {+ packCollectionGrid, parseTmjWithExternals, resolveRelativePath,+ type TiledMapData, type TiledTilesetData,+} from '../../tilemap/tiledLoader';+import { registerTilemapSource, type LoadedTilemapTileset } from '../../tilemap/tilesetCache';import { log } from '../../logger';export class TilemapAssetLoader implements AssetLoader<TilemapResult> {@@ -30,6 +33,12 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {const tilesets = [];for (const ts of mapData.tilesets) {+ // Image-collection tileset: fold the loose per-tile images into one+ // grid atlas — from here on it IS a grid tileset to everyone.+ if (ts.collectionTiles?.length) {+ tilesets.push(await this.foldCollection_(path, ts, mapData, ctx));+ continue;+ }const imagePath = resolveRelativePath(path, ts.image);let textureHandle = 0;try {@@ -71,6 +80,37 @@ export class TilemapAssetLoader implements AssetLoader<TilemapResult> {return { sourceId: path };}+ /**+ * Fold an image-collection tileset into one grid atlas: decode every tile+ * image through the platform's single decode path, pack them into a+ * near-square grid keyed by local id (packCollectionGrid), upload once.+ * Uniform tiles matching the map grid only — anything else has no meaning+ * on the fixed-grid renderer yet, so it fails loud with the fix.+ */+ private async foldCollection_(+ mapPath: string, ts: TiledTilesetData, mapData: TiledMapData, ctx: LoadContext,+ ): Promise<LoadedTilemapTileset> {+ if (!ctx.decodePixels || !ctx.createTextureFromPixels) {+ throw new Error(+ `[tilemap] "${mapPath}": tileset "${ts.name}" is an image collection, but this `+ + 'asset provider cannot decode/compose pixels — load it through the app Assets channel.');+ }+ const tiles = await Promise.all(ts.collectionTiles!.map(async (tile) => {+ const decoded = await ctx.decodePixels!(resolveRelativePath(mapPath, tile.image));+ if (decoded.width !== mapData.tileWidth || decoded.height !== mapData.tileHeight) {+ throw new Error(+ `[tilemap] "${mapPath}": collection tile "${tile.image}" is `+ + `${decoded.width}x${decoded.height}, but the map grid is `+ + `${mapData.tileWidth}x${mapData.tileHeight} — collection tiles must match the `+ + 'grid (resize them, or author a grid tileset image instead).');+ }+ return { id: tile.id, pixels: decoded.pixels };+ }));+ const grid = packCollectionGrid(tiles, mapData.tileWidth, mapData.tileHeight);+ const tex = await ctx.createTextureFromPixels(grid.width, grid.height, grid.pixels, true);+ return { textureHandle: tex.handle, columns: grid.columns, rows: grid.rows, firstId: ts.firstGid };+ }+unload(_asset: TilemapResult): void {// Tilemap sources registered globally}diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.tsindex 721094c6d..306e879dd 100644--- a/sdk/src/tilemap/index.ts+++ b/sdk/src/tilemap/index.ts@@ -8,8 +8,9 @@ export {parseTmjJson, parseTmjWithExternals, loadTiledMap, loadTiledCollisionObjects,generateTileCollision, generateLayerCollision, generateChunkCollision,generateChunkPolygonCollision, generateObjectCollision, isCollisionObjectGroup,- polygonLocalVerts, resolveRelativePath,+ polygonLocalVerts, resolveRelativePath, packCollectionGrid,type TiledMapData, type TiledLayerData, type TiledTilesetData,+ type TiledCollectionTile, type CollectionGridTile,type TiledObjectData, type TiledObjectGroupData, type TiledObjectShape,type TiledAnimFrame, type TilemapLoadOptions,} from './tiledLoader';diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.tsindex 2bbfb72a2..e3e0ebcfc 100644--- a/sdk/src/tilemap/tiledLoader.ts+++ b/sdk/src/tilemap/tiledLoader.ts@@ -74,6 +74,21 @@ export interface TiledTilesetData {tileHeight: number;columns: number;tileCount: number;+ /** Image-collection tileset (Tiled "collection of images"): one image per+ * tile, no top-level `image`. The loader folds these into ONE grid atlas+ * at load time, so the renderer never sees the difference. Local ids may+ * be sparse (deleted tiles leave holes). */+ collectionTiles?: TiledCollectionTile[];+}++export interface TiledCollectionTile {+ /** Local tile id (gid = firstGid + id). */+ id: number;+ /** Image ref, document-relative like a grid tileset's `image`. */+ image: string;+ /** Declared size (0 when the document omits it — the decode is the truth). */+ width: number;+ height: number;}export type TiledObjectShape = 'rect' | 'ellipse' | 'polygon' | 'polyline' | 'point';@@ -258,6 +273,18 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | nullif (rawTilesets) {for (const ts of rawTilesets) {+ // Image-collection tileset: no top-level image, per-tile images.+ const rawTiles = ts.tiles as Array<Record<string, unknown>> | undefined;+ const collectionTiles = !ts.image && rawTiles?.some((t) => typeof t.image === 'string')+ ? rawTiles+ .filter((t) => typeof t.image === 'string' && t.image)+ .map((t) => ({+ id: (t.id as number) ?? 0,+ image: t.image as string,+ width: (t.imagewidth as number) ?? 0,+ height: (t.imageheight as number) ?? 0,+ }))+ : undefined;tilesets.push({name: (ts.name as string) ?? '',image: (ts.image as string) ?? '',@@ -266,6 +293,7 @@ export function parseTmjJson(json: Record<string, unknown>): TiledMapData | nulltileHeight: (ts.tileheight as number) ?? tileHeight,columns: (ts.columns as number) ?? 1,tileCount: (ts.tilecount as number) ?? 0,+ ...(collectionTiles?.length ? { collectionTiles } : {}),});}}@@ -458,6 +486,16 @@ export async function parseTmjWithExternals(if (typeof external.image === 'string' && external.image) {external = { ...external, image: resolveRelativePath(ts.source, external.image) };}+ // Collection tilesets carry per-tile images — rewrite those too.+ if (Array.isArray(external.tiles)) {+ external = {+ ...external,+ tiles: (external.tiles as Array<Record<string, unknown>>).map((t) =>+ typeof t?.image === 'string' && t.image+ ? { ...t, image: resolveRelativePath(ts.source as string, t.image) }+ : t),+ };+ }return { ...external, firstgid: ts.firstgid };}));json = { ...json, tilesets: merged };@@ -470,6 +508,44 @@ export async function parseTmjWithExternals(// without pulling the loader's engine deps. Re-exported here for existing importers.export { resolveRelativePath };+export interface CollectionGridTile {+ /** Local tile id — also the grid slot, so gid → cell stays the identity+ * even when ids are sparse (deleted tiles leave transparent holes). */+ id: number;+ /** Top-first RGBA, exactly tileWidth × tileHeight. */+ pixels: Uint8Array;+}++/**+ * Fold an image-collection tileset's decoded tiles into ONE grid-atlas pixel+ * buffer (near-square, one slot per local id, transparent holes for sparse+ * ids). The result is indistinguishable from a hand-authored grid tileset, so+ * the renderer's uv math needs no collection special case. Pure — unit-tested+ * apart from the decode/upload plumbing.+ */+export function packCollectionGrid(+ tiles: CollectionGridTile[], tileWidth: number, tileHeight: number,+): { pixels: Uint8Array; columns: number; rows: number; width: number; height: number } {+ const slots = tiles.reduce((m, t) => Math.max(m, t.id), 0) + 1;+ const columns = Math.max(1, Math.ceil(Math.sqrt(slots)));+ const rows = Math.max(1, Math.ceil(slots / columns));+ const width = columns * tileWidth;+ const height = rows * tileHeight;+ const pixels = new Uint8Array(width * height * 4);+ const rowBytes = tileWidth * 4;+ for (const t of tiles) {+ const cellX = (t.id % columns) * tileWidth;+ const cellY = Math.floor(t.id / columns) * tileHeight;+ for (let y = 0; y < tileHeight; y++) {+ pixels.set(+ t.pixels.subarray(y * rowBytes, (y + 1) * rowBytes),+ ((cellY + y) * width + cellX) * 4,+ );+ }+ }+ return { pixels, columns, rows, width, height };+}+export interface TilemapLoadOptions {generateObjectCollision?: boolean;collisionTileIds?: number[];diff --git a/sdk/tests/tilemap.test.ts b/sdk/tests/tilemap.test.tsindex 3c98584b0..525bb2ac5 100644--- a/sdk/tests/tilemap.test.ts+++ b/sdk/tests/tilemap.test.ts@@ -16,6 +16,7 @@ import {import {loadTiledMap, parseTmjJson, parseTmjWithExternals, resolveRelativePath, loadTiledCollisionObjects,generateLayerCollision, generateObjectCollision, isCollisionObjectGroup, decodeTiledGid,+ packCollectionGrid,type TiledObjectData, type TiledObjectGroupData,} from '../src/tilemap/tiledLoader';import type { TiledMapData } from '../src/tilemap/tiledLoader';@@ -89,6 +90,123 @@ describe('Tilemap Components', () => {});});+describe('image-collection tilesets fold into a grid atlas', () => {+ const tilePixels = (r: number, w = 2, h = 2): Uint8Array => {+ const px = new Uint8Array(w * h * 4);+ for (let i = 0; i < w * h; i++) { px[i * 4] = r; px[i * 4 + 3] = 255; }+ return px;+ };++ it('parseTmjJson carries collection tiles (sparse ids, no top-level image)', () => {+ const map = parseTmjJson({+ width: 1, height: 1, tilewidth: 2, tileheight: 2,+ tilesets: [{+ firstgid: 1, name: 'props', columns: 0, tilecount: 2,+ tiles: [+ { id: 0, image: 'rock.png', imagewidth: 2, imageheight: 2 },+ { id: 3, image: 'bush.png', imagewidth: 2, imageheight: 2 }, // sparse+ ],+ }],+ layers: [{ type: 'tilelayer', width: 1, height: 1, data: [1] }],+ })!;+ expect(map.tilesets[0].image).toBe('');+ expect(map.tilesets[0].collectionTiles).toEqual([+ { id: 0, image: 'rock.png', width: 2, height: 2 },+ { id: 3, image: 'bush.png', width: 2, height: 2 },+ ]);+ });++ it('external .tsj collection tiles get their images rewritten map-relative', async () => {+ const map = await parseTmjWithExternals({+ width: 1, height: 1, tilewidth: 2, tileheight: 2,+ tilesets: [{ firstgid: 1, source: 'tilesets/props.tsj' }],+ layers: [{ type: 'tilelayer', width: 1, height: 1, data: [1] }],+ }, async () => JSON.stringify({+ name: 'props', columns: 0, tilecount: 1,+ tiles: [{ id: 0, image: '../textures/rock.png', imagewidth: 2, imageheight: 2 }],+ }))!;+ expect(map!.tilesets[0].collectionTiles![0].image).toBe('textures/rock.png');+ });++ it('packCollectionGrid packs by local id with transparent holes', () => {+ const grid = packCollectionGrid([+ { id: 0, pixels: tilePixels(10) },+ { id: 3, pixels: tilePixels(30) }, // ids 1-2 deleted in Tiled+ ], 2, 2);+ expect({ columns: grid.columns, rows: grid.rows }).toEqual({ columns: 2, rows: 2 });+ expect({ width: grid.width, height: grid.height }).toEqual({ width: 4, height: 4 });+ expect(grid.pixels[0]).toBe(10); // id 0 → cell (0,0)+ expect(grid.pixels[(2 * 4 + 2) * 4]).toBe(30); // id 3 → cell (1,1)+ expect(grid.pixels[(0 * 4 + 2) * 4 + 3]).toBe(0); // id 1 hole: transparent+ });++ it('the loader folds a collection into one uploaded grid tileset', async () => {+ const loader = new TilemapAssetLoader();+ const uploads: Array<{ width: number; height: number }> = [];+ const sources = new Map<string, string>([['maps/level.tmj', JSON.stringify({+ width: 1, height: 1, tilewidth: 2, tileheight: 2,+ tilesets: [{+ firstgid: 5, name: 'props', columns: 0, tilecount: 2,+ tiles: [+ { id: 0, image: '../tiles/rock.png', imagewidth: 2, imageheight: 2 },+ { id: 1, image: '../tiles/bush.png', imagewidth: 2, imageheight: 2 },+ ],+ }],+ layers: [{ type: 'tilelayer', name: 'ground', width: 1, height: 1, data: [5] }],+ })]]);+ const ctx = {+ catalog: { getBuildPath: (p: string) => p },+ loadText: async (p: string) => sources.get(p)!,+ decodePixels: async (p: string) => ({+ width: 2, height: 2, pixels: tilePixels(p.includes('rock') ? 10 : 30),+ }),+ createTextureFromPixels: async (width: number, height: number) => {+ uploads.push({ width, height });+ return { handle: 77, width, height };+ },+ } as unknown as LoadContext;++ await loader.load('maps/level.tmj', ctx);+ expect(uploads).toEqual([{ width: 4, height: 2 }]); // ONE folded 2x1 page+ const src = getTilemapSource('maps/level.tmj')!;+ expect(src.tilesets[0]).toEqual({ textureHandle: 77, columns: 2, rows: 1, firstId: 5 });+ });++ it('a collection tile off the map grid fails loud with the fix', async () => {+ const loader = new TilemapAssetLoader();+ const ctx = {+ catalog: { getBuildPath: (p: string) => p },+ loadText: async () => JSON.stringify({+ width: 1, height: 1, tilewidth: 2, tileheight: 2,+ tilesets: [{+ firstgid: 1, name: 'props', columns: 0, tilecount: 1,+ tiles: [{ id: 0, image: 'big.png', imagewidth: 4, imageheight: 4 }],+ }],+ layers: [{ type: 'tilelayer', width: 1, height: 1, data: [1] }],+ }),+ decodePixels: async () => ({ width: 4, height: 4, pixels: new Uint8Array(64) }),+ createTextureFromPixels: async () => ({ handle: 1, width: 4, height: 4 }),+ } as unknown as LoadContext;+ await expect(loader.load('maps/level.tmj', ctx)).rejects.toThrow(/match the\s+grid/);+ });++ it('a provider without pixel plumbing fails loud, not silently white', async () => {+ const loader = new TilemapAssetLoader();+ const ctx = {+ catalog: { getBuildPath: (p: string) => p },+ loadText: async () => JSON.stringify({+ width: 1, height: 1, tilewidth: 2, tileheight: 2,+ tilesets: [{+ firstgid: 1, name: 'props', columns: 0, tilecount: 1,+ tiles: [{ id: 0, image: 'rock.png', imagewidth: 2, imageheight: 2 }],+ }],+ layers: [{ type: 'tilelayer', width: 1, height: 1, data: [1] }],+ }),+ } as unknown as LoadContext;+ await expect(loader.load('maps/level.tmj', ctx)).rejects.toThrow(/image collection/);+ });+});+describe('TilemapAssetLoader — .tmx fails loud with the fix', () => {it('a Tiled XML map errors with the JSON-export guidance, not a JSON syntax error', async () => {const loader = new TilemapAssetLoader();