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): rebuild native collision after live map edits

yhh044dccd002c6
diff --git a/CHANGELOG.md b/CHANGELOG.md
index b4b7ba82e..c3b3da3b0 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **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.
+
- **Unchanged tile writes preserve chunk caches.** Repainting a tile with its existing value no longer advances the chunk revision or forces geometry rebuilding. Erasing untouched empty space does not allocate empty chunks, including negative coordinates in infinite maps.
- **Audio sources distinguish interrupted voices from completed clips.** A refused or preempted voice lowers `playing` without setting the natural-completion latch. Only a backend end signal for a non-looping source marks it `finished`; existing backend completion callbacks remain attached and replays clear the latch.
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 3a0eddca6..30413c168 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -242,6 +242,7 @@ export interface NativeEngineApi {
tilemap_exportChunks?(entity: number): string;
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_getTile?(entity: number, x: number, y: number): number;
tilemap_getTileProperty?(entity: number, x: number, y: number, key: string): string;
tilemap_hasLayer?(entity: number): boolean;
@@ -524,6 +525,7 @@ export function createNativeEngineApi(
bind('tilemap_exportChunks', 'es_tilemap_exportChunks', false);
bind('tilemap_fillRect', 'es_tilemap_fillRect', false);
bind('tilemap_flipTile', 'es_tilemap_flipTile', false);
+ bind('tilemap_getEditRevision', 'es_tilemap_getEditRevision', 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 a2e168aba..1b764e99f 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -35,6 +35,17 @@ const GRID_TYPE_MAP: Record<string, number> = {
const GRID_STAGGERED = 2;
const GRID_HEXAGONAL = 3;
+interface CollisionInputs {
+ revision: number;
+ width: number;
+ height: number;
+ x: number;
+ y: number;
+ pixelsPerUnit: number;
+ ids: number[] | undefined;
+ shapes: Map<number, ResolvedTileCollision> | undefined;
+}
+
/**
* One app's tilemap runtime: every derived layer, collider, animation and
* resolved tileset it is holding.
@@ -43,6 +54,7 @@ const GRID_HEXAGONAL = 3;
* entities from 1, and a shared instance cannot tell them apart.
*/
export class TilemapRuntime {
+ private collisionInputs_ = new Map<number, CollisionInputs>();
private applyTilesetRefs_: ((entity: number, refs: readonly string[]) => void) | null = null;
private initializedLayers_ = new Set<number>();
/** TilemapLayer entity → the tile size last pushed to its C++ layer (`w*K+h`).
@@ -118,7 +130,13 @@ export class TilemapRuntime {
const applyTilesetRefs = (entity: number, refs: readonly string[]): void => {
const clean = refs.filter((r): r is string => typeof r === 'string' && r !== '');
if (clean.length > 0) tilesetRefs.set(entity, clean.slice());
- else tilesetRefs.delete(entity);
+ else {
+ if (tilesetRefs.has(entity)) {
+ nativeCollisionIds.delete(entity);
+ nativeTileShapes.delete(entity);
+ }
+ tilesetRefs.delete(entity);
+ }
liveResolved.delete(entity);
};
this.applyTilesetRefs_ = applyTilesetRefs;
@@ -192,6 +210,7 @@ export class TilemapRuntime {
const animatedLayers = this.animatedLayers_;
const sourceLayerEntities = this.sourceLayerEntities_;
const collisionEntities = this.collisionEntities_;
+ const collisionInputs = this.collisionInputs_;
const tilemapSyncSystem: SystemDef = {
_id: Symbol('TilemapSyncSystem'),
@@ -215,6 +234,7 @@ export class TilemapRuntime {
for (const e of ents) world.despawn(e);
}
collisionEntities.clear();
+ collisionInputs.clear();
}
const layerEntities = world.getEntitiesWithComponents(
@@ -226,6 +246,7 @@ export class TilemapRuntime {
if (!currentLayerSet.has(entity)) {
TilemapAPI.destroyLayer(entity);
initializedLayers.delete(entity);
+ collisionInputs.delete(entity);
appliedCellSize.delete(entity);
appliedGrid.delete(entity);
nativeCollisionIds.delete(entity);
@@ -251,7 +272,12 @@ export class TilemapRuntime {
const refs = tilesetRefs.get(entity);
// A layer needs either a copied texture (legacy) or .estileset ref(s).
- if (!layerData.tileset && (!refs || refs.length === 0)) continue;
+ if (!layerData.tileset && (!refs || refs.length === 0)) {
+ for (const collider of collisionEntities.get(entity) ?? []) world.despawn(collider);
+ collisionEntities.delete(entity);
+ collisionInputs.delete(entity);
+ continue;
+ }
// RC2a: the TilemapLayer component is the single source of visual
// metadata; the C++ renderer reads tint/opacity/tileset/columns/
@@ -360,19 +386,30 @@ export class TilemapRuntime {
}
}
- // Native path: collidable tiles spawn static colliders once in play mode
- // — plain solid boxes greedy-merged, rich shapes (polygon/circle/one-way/
- // material) one collider each — using the live `.estileset` shapes when
- // resolved, else the baked id set.
+ // Rebuild native collision when its content or geometry changes;
+ // merge solid boxes and preserve individual rich shapes.
const collIds = nativeCollisionIds.get(entity);
const tileShapes = nativeTileShapes.get(entity);
const hasBox = collIds != null && collIds.length > 0;
const hasShapes = tileShapes != null && tileShapes.size > 0;
+ const tf = world.tryGet(entity, Transform) as { position: { x: number; y: number } } | null;
+ const ox = tf?.position.x ?? 0;
+ const oy = tf?.position.y ?? 0;
+ const revision = playMode && (hasBox || hasShapes)
+ ? engine.tilemap_getEditRevision?.(entity) ?? 0
+ : 0;
+ const previous = collisionInputs.get(entity);
+ const changed = !previous || 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;
+ if (playMode && collisionEntities.has(entity) && (changed || (!hasBox && !hasShapes))) {
+ for (const collider of collisionEntities.get(entity)!) world.despawn(collider);
+ collisionEntities.delete(entity);
+ collisionInputs.delete(entity);
+ }
if (playMode && (hasBox || hasShapes) && !collisionEntities.has(entity)) {
const chunks = decodeTilemapChunks(TilemapAPI.exportChunks(entity));
- const tf = world.tryGet(entity, Transform) as { position: { x: number; y: number } } | null;
- const ox = tf?.position.x ?? 0;
- const oy = tf?.position.y ?? 0;
const spawned: Entity[] = [];
if (hasBox) {
spawned.push(...generateChunkCollision(
@@ -387,6 +424,9 @@ export class TilemapRuntime {
));
}
collisionEntities.set(entity, spawned);
+ collisionInputs.set(entity, { revision, width: layerData.cellSize.x,
+ height: layerData.cellSize.y, x: ox, y: oy, pixelsPerUnit,
+ ids: collIds, shapes: tileShapes });
}
}
@@ -735,6 +775,7 @@ export class TilemapRuntime {
this.sourceDerivedFrom_.clear();
// Collider entities die with the world on reset/teardown; just drop our bookkeeping.
this.collisionEntities_.clear();
+ this.collisionInputs_.clear();
this.nativeCollisionIds_.clear();
this.nativeTileShapes_.clear();
this.tilesetRefs_.clear();
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index e11fe1c31..75b6fc09a 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -611,6 +611,7 @@ export interface ESEngineModule {
w: number, h: number, tileId: number): void;
tilemap_setTiles?(entity: number, tilesPtr: number, count: number): void;
tilemap_hasLayer?(entity: number): boolean;
+ tilemap_getEditRevision?(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
new file mode 100644
index 000000000..8e68aa447
--- /dev/null
+++ b/sdk/tests/tilemap-live-collision-wasm.test.ts
@@ -0,0 +1,72 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { HAS_WASM, loadWasmModule } from './helpers/loadWasm';
+import { App } from '../src/app/app';
+import { Transform, TilemapLayer } from '../src/ecs/component';
+import { TilemapPlugin, TilemapRuntimeState } from '../src/tilemap/tilemapPlugin';
+import { TilemapAPI, Tilemaps } from '../src/tilemap/tilemapAPI';
+
+let engine: import('../src/wasm').ESEngineModule;
+const registries: Array<{ delete(): void }> = [];
+const apps: App[] = [];
+afterEach(() => {
+ vi.restoreAllMocks();
+ for (const app of apps.splice(0)) app.quit();
+ for (const registry of registries.splice(0)) registry.delete();
+});
+
+describe.skipIf(!HAS_WASM)('live native tile collision', () => {
+ beforeAll(async () => {
+ engine = await loadWasmModule();
+ engine.setActiveContext(null);
+ expect(typeof engine.tilemap_getEditRevision).toBe('function');
+ });
+ async function scene() {
+ const registry = new engine.Registry(); registries.push(registry as unknown as { delete(): void });
+ const app = App.new(); app.connectCpp(registry, engine); app.addPlugin(new TilemapPlugin()); apps.push(app);
+ const entity = app.world.spawn();
+ app.world.insert(entity, Transform);
+ app.world.insert(entity, TilemapLayer, { cellSize: { x: 16, y: 16 } });
+ const tiles = app.getResource(Tilemaps);
+ app.getResource(TilemapRuntimeState).setLayerTilesets(entity, ['builtin:collision']);
+ tiles.initInfiniteLayer(entity, 16, 16);
+ const emptyBlob = tiles.exportChunks(entity);
+ tiles.setTile(entity, 0, 0, 1);
+ await app.tick(1 / 60);
+ const colliders = () => (app.getResource(TilemapRuntimeState) as unknown as { collisionEntities_: Map<number, import('../src/types').Entity[]> }).collisionEntities_.get(entity)!;
+ return { app, entity, tiles, colliders, emptyBlob };
+ }
+ it('retains unchanged colliders and removes them after erasing their tile', async () => {
+ const { app, entity, tiles, colliders } = await scene();
+ const original = [...colliders()]; expect(original.length).toBeGreaterThan(0);
+ const exports = vi.spyOn(TilemapAPI, 'exportChunks');
+ for (let i = 0; i < 20; i++) { tiles.setTile(entity, 0, 0, 1); await app.tick(1 / 60); }
+ expect(colliders()).toEqual(original);
+ expect(exports).not.toHaveBeenCalled();
+ tiles.setTile(entity, 0, 0, 0); await app.tick(1 / 60);
+ expect(colliders()).toHaveLength(0);
+ expect(exports).toHaveBeenCalledTimes(1);
+ for (const id of original) expect(app.world.valid(id)).toBe(false);
+ tiles.setTile(entity, -1, -1, 1); await app.tick(1 / 60);
+ expect(colliders().length).toBeGreaterThan(0);
+ });
+ it('updates collision after a layer move and palette removal', async () => {
+ const { app, entity, colliders } = await scene();
+ const original = [...colliders()];
+ app.world.update(entity, Transform, value => { value.position.x = 32; });
+ await app.tick(1 / 60);
+ expect(colliders()).not.toEqual(original);
+ for (const id of original) expect(app.world.valid(id)).toBe(false);
+ app.getResource(TilemapRuntimeState).setLayerTilesets(entity, []);
+ await app.tick(1 / 60);
+ expect(colliders() ?? []).toHaveLength(0);
+ });
+ it('removes old collision when importing an empty map', async () => {
+ const { app, entity, tiles, colliders, emptyBlob } = await scene();
+ expect(colliders().length).toBeGreaterThan(0);
+ expect(tiles.importChunks(entity, emptyBlob)).toBe(true);
+ await app.tick(1 / 60);
+ expect(colliders()).toHaveLength(0);
+ });
+});
diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cpp
index b600cac52..0b8852bbd 100644
--- a/src/esengine/bindings/TilemapBindings.cpp
+++ b/src/esengine/bindings/TilemapBindings.cpp
@@ -116,6 +116,11 @@ bool tilemap_hasLayer(u32 entity) {
return getTilemapSystem().hasLayer(Entity::fromRaw(entity));
}
+u32 tilemap_getEditRevision(u32 entity) {
+ const auto* layer = getTilemapSystem().getLayerData(Entity::fromRaw(entity));
+ return layer ? layer->edit_revision : 0;
+}
+
void tilemap_setRenderProps(u32 entity, u32 textureHandle, u32 tilesetColumns,
f32 uvTileW, f32 uvTileH,
i32 sortLayer, f32 depth,
@@ -274,6 +279,7 @@ bool tilemap_importChunks(u32 entity, const std::string& encoded) {
bool first = true;
bool lost = false;
+ if (!layer->chunks.empty()) ++layer->edit_revision;
layer->chunks.clear();
const bool walked = tilemap::walkBlobCells(raw.data(), raw.size(), header,
[&](i32 x, i32 y, u16 word) {
diff --git a/src/esengine/bindings/TilemapBindings.hpp b/src/esengine/bindings/TilemapBindings.hpp
index e034ab668..8551d6a7f 100644
--- a/src/esengine/bindings/TilemapBindings.hpp
+++ b/src/esengine/bindings/TilemapBindings.hpp
@@ -38,6 +38,7 @@ void tilemap_initInfinite(u32 entity, f32 tileWidth, f32 tileHeight);
void tilemap_initInfiniteLayer(u32 entity, f32 tileWidth, f32 tileHeight);
void tilemap_destroyLayer(u32 entity);
bool tilemap_hasLayer(u32 entity);
+u32 tilemap_getEditRevision(u32 entity);
// — Tiles —
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 1bd1d8e72..53173d29b 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -625,6 +625,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("tilemap_setTiles", &esengine::tilemap_setTiles);
emscripten::function("tilemap_setTilesets", &esengine::tilemap_setTilesets);
emscripten::function("tilemap_hasLayer", &esengine::tilemap_hasLayer);
+ emscripten::function("tilemap_getEditRevision", &esengine::tilemap_getEditRevision);
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/tilemap/TilemapSystem.cpp b/src/esengine/tilemap/TilemapSystem.cpp
index cd42a45b4..56a82dcd6 100644
--- a/src/esengine/tilemap/TilemapSystem.cpp
+++ b/src/esengine/tilemap/TilemapSystem.cpp
@@ -74,6 +74,7 @@ inline void writeTile(TilemapSystem::LayerData& layer, i32 x, i32 y, u16 value)
// Tiled finite-layer load: chunk a flat row-major array, storing only non-empty chunks.
void buildChunksFromFlat(TilemapSystem::LayerData& layer,
const u16* tiles, u32 width, u32 height, u32 count) {
+ if (!layer.chunks.empty()) ++layer.edit_revision;
layer.chunks.clear();
const u32 chunksX = (width + CHUNK_SIZE - 1) / CHUNK_SIZE;
const u32 chunksY = (height + CHUNK_SIZE - 1) / CHUNK_SIZE;
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 98a5b3c92..346223fa2 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): rebuild native collision after live map edits':
+ { note: 'Native tilemap collisions follow live edits.' },
'perf(tilemap): skip unchanged tile writes and empty chunk allocation':
{ note: 'Unchanged tile writes preserve chunk caches.' },
'fix(audio): distinguish source completion from interrupted voices':