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 asset loader + resolved-tileset cache (tileset unification, stage 3)

yhhde4270e7e7b3
diff --git a/sdk/src/asset/AssetFieldRegistry.ts b/sdk/src/asset/AssetFieldRegistry.ts
index 7d9d0a4bd..f26e13d04 100644
--- a/sdk/src/asset/AssetFieldRegistry.ts
+++ b/sdk/src/asset/AssetFieldRegistry.ts
@@ -1,6 +1,6 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
-export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'tilemap' | 'timeline';
+export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'tilemap' | 'tileset' | 'timeline';
export interface AssetFieldDescriptor {
field: string;
diff --git a/sdk/src/asset/AssetLoader.ts b/sdk/src/asset/AssetLoader.ts
index 10d2fa8bd..d386f20b0 100644
--- a/sdk/src/asset/AssetLoader.ts
+++ b/sdk/src/asset/AssetLoader.ts
@@ -41,6 +41,11 @@ export interface TilemapResult {
sourceId: string;
}
+export interface TilesetResult {
+ /** The `.estileset` path the resolved tileset is cached under. */
+ tilesetId: string;
+}
+
export interface TimelineResult {
timelineId: string;
}
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 3b6382bc7..e3ff3af0c 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -5,7 +5,7 @@ import { Catalog, type AtlasFrameInfo } from './Catalog';
import type {
AssetLoader, LoadContext, TextureResult, SpineResult,
MaterialResult, FontResult, AudioResult, AnimClipResult,
- TilemapResult, TimelineResult, PrefabResult,
+ TilemapResult, TilesetResult, TimelineResult, PrefabResult,
} from './AssetLoader';
import { AsyncCache } from './AsyncCache';
import type { ESEngineModule } from '../wasm';
@@ -19,6 +19,7 @@ import { FontAssetLoader } from './loaders/FontAssetLoader';
import { AudioAssetLoader } from './loaders/AudioAssetLoader';
import { AnimClipAssetLoader } from './loaders/AnimClipAssetLoader';
import { TilemapAssetLoader } from './loaders/TilemapAssetLoader';
+import { TilesetAssetLoader } from './loaders/TilesetAssetLoader';
import { TimelineAssetLoader } from './loaders/TimelineAssetLoader';
import { PrefabAssetLoader } from './loaders/PrefabAssetLoader';
import type { SpineModuleController } from '../spine/SpineController';
@@ -255,6 +256,10 @@ export class Assets {
return this.loadTyped('tilemap', ref);
}
+ async loadTileset(ref: string): Promise<TilesetResult> {
+ return this.loadTyped('tileset', ref);
+ }
+
async loadTimeline(ref: string): Promise<TimelineResult> {
return this.loadTyped('timeline', ref);
}
@@ -389,6 +394,7 @@ export class Assets {
const animClipPaths = discovered.byType.get('anim-clip') ?? new Set<string>();
const audioPaths = discovered.byType.get('audio') ?? new Set<string>();
const tilemapPaths = discovered.byType.get('tilemap') ?? new Set<string>();
+ const tilesetPaths = discovered.byType.get('tileset') ?? new Set<string>();
const timelinePaths = discovered.byType.get('timeline') ?? new Set<string>();
const spinePairs = discovered.spines;
@@ -453,6 +459,7 @@ export class Assets {
}
pushFireAndForget(animClipPaths, p => this.loadAnimClip(p), 'anim-clip');
pushFireAndForget(tilemapPaths, p => this.loadTilemap(p), 'tilemap');
+ pushFireAndForget(tilesetPaths, p => this.loadTileset(p), 'tileset');
pushFireAndForget(timelinePaths, p => this.loadTimeline(p), 'timeline');
pushFireAndForget(audioPaths, p => this.loadAudio(p), 'audio');
@@ -767,6 +774,7 @@ export class Assets {
this.register(new AudioAssetLoader());
this.register(new AnimClipAssetLoader());
this.register(new TilemapAssetLoader());
+ this.register(new TilesetAssetLoader());
this.register(new TimelineAssetLoader());
this.register(new PrefabAssetLoader());
}
diff --git a/sdk/src/asset/loaders/TilesetAssetLoader.ts b/sdk/src/asset/loaders/TilesetAssetLoader.ts
new file mode 100644
index 000000000..db2a8e38f
--- /dev/null
+++ b/sdk/src/asset/loaders/TilesetAssetLoader.ts
@@ -0,0 +1,42 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Runtime `.estileset` loader — parses the tileset asset and loads its
+ * atlas texture, caching the resolved tileset so the tilemap sync can
+ * derive the render table + collision + animations LIVE (no baking).
+ * Mirrors {@link TilemapAssetLoader} (the `.tmj` path).
+ */
+import type { AssetLoader, LoadContext, TilesetResult } from '../AssetLoader';
+import { parseTileset } from '../../tilemap/tilesetAsset';
+import { registerResolvedTileset } from '../../tilemap/tilesetCache';
+import { log } from '../../logger';
+
+export class TilesetAssetLoader implements AssetLoader<TilesetResult> {
+ readonly type = 'tileset';
+ readonly extensions = ['.estileset'];
+
+ async load(path: string, ctx: LoadContext): Promise<TilesetResult> {
+ const buildPath = ctx.catalog.getBuildPath(path);
+ const text = await ctx.loadText(buildPath);
+ const asset = parseTileset(JSON.parse(text));
+
+ // The atlas is a `@uuid:` ref inside the .estileset; loadTexture resolves it.
+ let textureHandle = 0;
+ if (asset.texture) {
+ try {
+ const tex = await ctx.loadTexture(asset.texture, true);
+ textureHandle = tex.handle;
+ } catch (e) {
+ log.warn('asset', `Failed to load tileset atlas: ${asset.texture}`, e);
+ }
+ }
+
+ registerResolvedTileset(path, { asset, textureHandle });
+ return { tilesetId: path };
+ }
+
+ unload(_asset: TilesetResult): void {
+ // Resolved tilesets live in the module cache (cleared on scene reset); the
+ // atlas texture is ref-counted by the texture loader. Nothing per-asset here.
+ }
+}
diff --git a/sdk/src/scene.ts b/sdk/src/scene.ts
index e325f6e74..ceb1c2c3c 100644
--- a/sdk/src/scene.ts
+++ b/sdk/src/scene.ts
@@ -105,7 +105,7 @@ export class MissingAssetsError extends Error {
// Asset Field Types
// =============================================================================
-export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'tilemap' | 'timeline';
+export type AssetFieldType = 'texture' | 'material' | 'font' | 'anim-clip' | 'audio' | 'tilemap' | 'tileset' | 'timeline';
// =============================================================================
// Component Query Helpers (read from self-describing ComponentDef)
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.ts
index a3f9dbe76..0937aa0f6 100644
--- a/sdk/src/tilemap/index.ts
+++ b/sdk/src/tilemap/index.ts
@@ -22,6 +22,7 @@ export {
} from './tilesetResolve';
export {
registerTilemapSource, getTilemapSource, clearTilemapSourceCache,
+ registerResolvedTileset, getResolvedTileset, clearResolvedTilesetCache,
type LoadedTilemapSource, type LoadedTilemapLayer, type LoadedTilemapTileset,
} from './tilesetCache';
export { getTextureDimensions, type TextureDimensions } from '../resourceManager';
diff --git a/sdk/src/tilemap/tilesetCache.ts b/sdk/src/tilemap/tilesetCache.ts
index ab3b2f279..917b25e68 100644
--- a/sdk/src/tilemap/tilesetCache.ts
+++ b/sdk/src/tilemap/tilesetCache.ts
@@ -1,5 +1,7 @@
// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import type { ResolvedTileset } from './tilesetResolve';
+
export interface LoadedTilemapChunk {
x: number;
y: number;
@@ -48,3 +50,21 @@ export function getTilemapSource(path: string): LoadedTilemapSource | undefined
export function clearTilemapSourceCache(): void {
tilemapCache_.clear();
}
+
+// — Resolved `.estileset` tilesets (parsed asset + loaded atlas texture) —
+// The runtime tileset loader registers here; the tilemap sync resolves a layer's
+// tileset(s) into the render table + collision + animations LIVE off these (no
+// columns copied onto the layer, no collision baked at author-time).
+const resolvedTilesetCache_ = new Map<string, ResolvedTileset>();
+
+export function registerResolvedTileset(path: string, data: ResolvedTileset): void {
+ resolvedTilesetCache_.set(path, data);
+}
+
+export function getResolvedTileset(path: string): ResolvedTileset | undefined {
+ return resolvedTilesetCache_.get(path);
+}
+
+export function clearResolvedTilesetCache(): void {
+ resolvedTilesetCache_.clear();
+}