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.

fix(tilemap): invalidate caches when a layer is recreated

yhhaca8c28d2775
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0f21ad9d0..9849f2e51 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Recreated tilemap layers discard old geometry and collision.** A layer generation distinguishes replacement from ordinary edits, even when the same entity and edit count are reused. Reinitializing or immediately recreating a layer releases its old chunk meshes and rebuilds collision from the replacement; unchanged layers retain their caches.
+
- **Tilemap runtimes and saved chunks stay with their own worlds.** Closing a preview or an older App no longer destroys another core's same-numbered layers or disables its collision updates. Scene codecs serialize each world's own tiles; closing the current runtime restores the previous live tooling interface and collision lookup, and releases the retired codec.
- **Native tilemap collisions follow live edits.** Changing painted tiles, importing an empty map, moving a layer or removing its collision palette replaces obsolete runtime colliders. A native content revision keeps unchanged frames and repeated writes from exporting the map or rebuilding collision.
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 38b0f1d6b..6516ac549 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -495,6 +495,7 @@ tilemap_destroyLayer: ((entity: number) => void) | undefined
tilemap_exportChunks: ((entity: number) => string) | undefined
tilemap_fillRect: ((entity: number, x: number, y: number, w: number, h: number, tileId: number) => void) | undefined
tilemap_getEditRevision: ((entity: number) => number) | undefined
+tilemap_getGeneration: ((entity: number) => number) | undefined
tilemap_getTile: ((entity: number, x: number, y: number) => number) | undefined
tilemap_hasLayer: ((entity: number) => boolean) | undefined
tilemap_importChunks: ((entity: number, encoded: string) => boolean) | undefined
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 30413c168..a9704f6df 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -243,6 +243,7 @@ export interface NativeEngineApi {
tilemap_fillRect?(entity: number, x: number, y: number, w: number, h: number, tileId: number): void;
tilemap_flipTile?(entity: number, x: number, y: number, flipH: boolean, flipV: boolean, flipD: boolean): void;
tilemap_getEditRevision?(entity: number): number;
+ tilemap_getGeneration?(entity: number): number;
tilemap_getTile?(entity: number, x: number, y: number): number;
tilemap_getTileProperty?(entity: number, x: number, y: number, key: string): string;
tilemap_hasLayer?(entity: number): boolean;
@@ -526,6 +527,7 @@ export function createNativeEngineApi(
bind('tilemap_fillRect', 'es_tilemap_fillRect', false);
bind('tilemap_flipTile', 'es_tilemap_flipTile', false);
bind('tilemap_getEditRevision', 'es_tilemap_getEditRevision', false);
+ bind('tilemap_getGeneration', 'es_tilemap_getGeneration', false);
bind('tilemap_getTile', 'es_tilemap_getTile', false);
bind('tilemap_getTileProperty', 'es_tilemap_getTileProperty', false);
bind('tilemap_hasLayer', 'es_tilemap_hasLayer', false);
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index 93298c1da..2b0961171 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -36,6 +36,7 @@ const GRID_STAGGERED = 2;
const GRID_HEXAGONAL = 3;
interface CollisionInputs {
+ generation: number;
revision: number;
width: number;
height: number;
@@ -402,8 +403,11 @@ export class TilemapRuntime {
const revision = playMode && (hasBox || hasShapes)
? engine.tilemap_getEditRevision?.(entity) ?? 0
: 0;
+ const generation = playMode && (hasBox || hasShapes)
+ ? engine.tilemap_getGeneration?.(entity) ?? 0
+ : 0;
const previous = collisionInputs.get(entity);
- const changed = !previous || previous.revision !== revision
+ const changed = !previous || previous.generation !== generation || previous.revision !== revision
|| previous.width !== layerData.cellSize.x || previous.height !== layerData.cellSize.y
|| previous.x !== ox || previous.y !== oy || previous.pixelsPerUnit !== pixelsPerUnit
|| previous.ids !== collIds || previous.shapes !== tileShapes;
@@ -428,7 +432,7 @@ export class TilemapRuntime {
));
}
collisionEntities.set(entity, spawned);
- collisionInputs.set(entity, { revision, width: layerData.cellSize.x,
+ collisionInputs.set(entity, { generation, revision, width: layerData.cellSize.x,
height: layerData.cellSize.y, x: ox, y: oy, pixelsPerUnit,
ids: collIds, shapes: tileShapes });
}
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 75b6fc09a..13736b511 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -612,6 +612,7 @@ export interface ESEngineModule {
tilemap_setTiles?(entity: number, tilesPtr: number, count: number): void;
tilemap_hasLayer?(entity: number): boolean;
tilemap_getEditRevision?(entity: number): number;
+ tilemap_getGeneration?(entity: number): number;
tilemap_exportChunks?(entity: number): string;
tilemap_importChunks?(entity: number, encoded: string): boolean;
renderer_setStage(stage: number): void;
diff --git a/sdk/tests/tilemap-live-collision-wasm.test.ts b/sdk/tests/tilemap-live-collision-wasm.test.ts
index 4f795dd56..4a3a012a8 100644
--- a/sdk/tests/tilemap-live-collision-wasm.test.ts
+++ b/sdk/tests/tilemap-live-collision-wasm.test.ts
@@ -69,4 +69,15 @@ describe.skipIf(!HAS_WASM)('live native tile collision', () => {
await app.tick(1 / 60);
expect(colliders()).toHaveLength(0);
});
+ it.each(['reinitialize', 'recreate'])('replaces collision after layer %s with the same edit count', async mode => {
+ const { app, entity, tiles, colliders } = await scene();
+ const original = [...colliders()];
+ if (mode === 'recreate') tiles.destroyLayer(entity);
+ tiles.initLayer(entity, 2, 2, 16, 16);
+ tiles.setTile(entity, 1, 0, 1);
+ await app.tick(1 / 60);
+ expect(colliders()).not.toEqual(original);
+ expect(app.world.get(colliders()[0], Transform).position.x).toBe(24);
+ for (const id of original) expect(app.world.valid(id)).toBe(false);
+ });
});
diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cpp
index 0b8852bbd..c14fca342 100644
--- a/src/esengine/bindings/TilemapBindings.cpp
+++ b/src/esengine/bindings/TilemapBindings.cpp
@@ -121,6 +121,11 @@ u32 tilemap_getEditRevision(u32 entity) {
return layer ? layer->edit_revision : 0;
}
+u32 tilemap_getGeneration(u32 entity) {
+ const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
+ return layer ? layer->generation : 0;
+}
+
void tilemap_setRenderProps(u32 entity, u32 textureHandle, u32 tilesetColumns,
f32 uvTileW, f32 uvTileH,
i32 sortLayer, f32 depth,
diff --git a/src/esengine/bindings/TilemapBindings.hpp b/src/esengine/bindings/TilemapBindings.hpp
index 8551d6a7f..5f3487776 100644
--- a/src/esengine/bindings/TilemapBindings.hpp
+++ b/src/esengine/bindings/TilemapBindings.hpp
@@ -39,6 +39,7 @@ void tilemap_initInfiniteLayer(u32 entity, f32 tileWidth, f32 tileHeight);
void tilemap_destroyLayer(u32 entity);
bool tilemap_hasLayer(u32 entity);
u32 tilemap_getEditRevision(u32 entity);
+u32 tilemap_getGeneration(u32 entity);
// — Tiles —
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 53173d29b..627fc59fc 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -626,6 +626,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("tilemap_setTilesets", &esengine::tilemap_setTilesets);
emscripten::function("tilemap_hasLayer", &esengine::tilemap_hasLayer);
emscripten::function("tilemap_getEditRevision", &esengine::tilemap_getEditRevision);
+ emscripten::function("tilemap_getGeneration", &esengine::tilemap_getGeneration);
emscripten::function("tilemap_setRenderProps", &esengine::tilemap_setRenderProps);
emscripten::function("tilemap_setTint", &esengine::tilemap_setTint);
emscripten::function("tilemap_setVisible", &esengine::tilemap_setVisible);
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
index b30577466..226b6f96f 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.cpp
@@ -160,6 +160,11 @@ void TilemapRenderPlugin::collect(RenderCollectContext& collect_ctx) {
const CameraView& cam = collect_ctx.camera;
for (const auto& [entity, layer] : layers) {
+ auto cachedLayer = layer_caches_.find(entity);
+ if (cachedLayer != layer_caches_.end() && cachedLayer->second.generation != layer.generation) {
+ layer_caches_.erase(cachedLayer);
+ cachedLayer = layer_caches_.end();
+ }
if (registry.valid(entity) && !registry.isEntityActive(entity)) continue;
// The TilemapLayer component is the single source of a layer's visual
// metadata — the renderer reads it live each frame (so animated
@@ -308,7 +313,9 @@ void TilemapRenderPlugin::collect(RenderCollectContext& collect_ctx) {
if (minCX >= maxCX || minCY >= maxCY) continue;
- auto& chunkCaches = layer_caches_[entity];
+ auto& layerCache = cachedLayer != layer_caches_.end() ? cachedLayer->second : layer_caches_[entity];
+ layerCache.generation = layer.generation;
+ auto& chunkCaches = layerCache.chunks;
// Per-slot merged geometry for this layer (one draw call per slot/texture).
if (slot_vertices_scratch_.size() < slots.size()) {
diff --git a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
index d0c7347a9..9a7b3f82d 100644
--- a/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
+++ b/src/esengine/renderer/plugins/TilemapRenderPlugin.hpp
@@ -76,7 +76,11 @@ private:
};
using ChunkMap = std::unordered_map<tilemap::ChunkCoord, ChunkCache, tilemap::ChunkCoordHash>;
- using LayerChunkMap = std::unordered_map<Entity, ChunkMap>;
+ struct LayerCache {
+ u32 generation = 0;
+ ChunkMap chunks;
+ };
+ using LayerChunkMap = std::unordered_map<Entity, LayerCache>;
void rebuildChunk(const tilemap::TilemapSystem::LayerData& layer,
const tilemap::ChunkData& chunk, tilemap::ChunkCoord coord,
diff --git a/src/esengine/tilemap/TilemapSystem.cpp b/src/esengine/tilemap/TilemapSystem.cpp
index 56a82dcd6..ed2342eee 100644
--- a/src/esengine/tilemap/TilemapSystem.cpp
+++ b/src/esengine/tilemap/TilemapSystem.cpp
@@ -107,6 +107,7 @@ void buildChunksFromFlat(TilemapSystem::LayerData& layer,
void TilemapSystem::initLayer(Entity entity, u32 width, u32 height,
f32 tileWidth, f32 tileHeight) {
LayerData layer;
+ layer.generation = ++next_generation_;
layer.width = width;
layer.height = height;
layer.tile_width = tileWidth;
@@ -116,6 +117,7 @@ void TilemapSystem::initLayer(Entity entity, u32 width, u32 height,
void TilemapSystem::initInfiniteLayer(Entity entity, f32 tileWidth, f32 tileHeight) {
LayerData layer;
+ layer.generation = ++next_generation_;
layer.width = 0;
layer.height = 0;
layer.tile_width = tileWidth;
diff --git a/src/esengine/tilemap/TilemapSystem.hpp b/src/esengine/tilemap/TilemapSystem.hpp
index afc87db1e..fa445324b 100644
--- a/src/esengine/tilemap/TilemapSystem.hpp
+++ b/src/esengine/tilemap/TilemapSystem.hpp
@@ -114,6 +114,7 @@ public:
void setHexParams(Entity entity, f32 sideLength, bool staggerAxisX, bool staggerIndexEven);
struct LayerData {
+ u32 generation = 0;
u32 width = 0; // finite-layer bounds (0 = infinite); tiles live in `chunks`.
u32 height = 0;
f32 tile_width = 0;
@@ -191,6 +192,7 @@ public:
const LayerMap& allLayers() const { return layers_; }
private:
+ u32 next_generation_ = 0;
LayerMap layers_;
};
diff --git a/tests/tilemap/test_tilemap.cpp b/tests/tilemap/test_tilemap.cpp
index 86d0e15fe..93f213a2c 100644
--- a/tests/tilemap/test_tilemap.cpp
+++ b/tests/tilemap/test_tilemap.cpp
@@ -13,6 +13,20 @@ using namespace esengine::tilemap;
static Entity E(u32 idx) { return Entity::make(idx, 1); }
+TEST_CASE("tilemap_replacement_has_a_distinct_generation") {
+ TilemapSystem sys;
+ sys.initLayer(E(0), 2, 2, 16, 16);
+ const auto first = sys.getLayerData(E(0))->generation;
+ sys.setTile(E(0), 0, 0, 1);
+ CHECK(sys.getLayerData(E(0))->generation == first);
+ sys.initInfiniteLayer(E(0), 16, 16);
+ const auto second = sys.getLayerData(E(0))->generation;
+ CHECK(second > first);
+ sys.destroyLayer(E(0));
+ sys.initLayer(E(0), 2, 2, 16, 16);
+ CHECK(sys.getLayerData(E(0))->generation > second);
+}
+
TEST_CASE("tilemap_unchanged_writes_preserve_sparse_storage_and_revision") {
TilemapSystem sys;
sys.initInfiniteLayer(E(0), 16.0f, 16.0f);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index ca13c6e9c..3d6eca146 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(tilemap): invalidate caches when a layer is recreated':
+ { note: 'Recreated tilemap layers discard old geometry and collision.' },
'fix(tilemap): isolate runtime tools and scene codecs per world':
{ note: 'Tilemap runtimes and saved chunks stay with their own worlds.' },
'fix(tilemap): rebuild native collision after live map edits':