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.

perf(tilemap): synchronize collision by changed chunk

yhh558e8e4431d7
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 965d342f5..ee9cf95f3 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -16,6 +16,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Tile edits preserve unaffected collision chunks and contacts.** Runtime collision reuses native chunk revisions and replaces only changed chunk bodies, retaining other body identities and resting contacts. Frame and fixed-step edits derive before physics, while tile animation advances once per rendered frame. The editor and runtime share owned chunk readback that survives WASM memory growth and releases temporary buffers; older or failed readback falls back to content comparison. Layout, cell dimensions, material and lifetime changes still rebuild the affected geometry.
+
- **Moving static collision uses a shared batch pose channel.** The engine exports composed 2D poses for selected active entities and physics applies them in one call, skipping unchanged solver poses. Web modules copy populated rows between their heaps; native hosts use their shared arena. Batch rows share a generated C++ stride, lazy world fields are decomposed before export, temporary buffers are released on failure, and hosts without the new calls keep the scalar path.
- **Static physics synchronization skips unchanged body groups.** Authored Transform writes select individual static bodies, while each immediate parent's composed frame selects only its affected children. Unrelated dynamic or authored motion avoids per-body change checks and pose reads. Reparenting, re-enabling and pixels-per-unit edits refresh the correct bodies. Paused simulations release write history and refresh poses on resume; plugin cleanup releases the reader and frame/despawn observers.
diff --git a/desktop b/desktop
index f3952833a..b62e074dc 160000
--- a/desktop
+++ b/desktop
@@ -1 +1 @@
-Subproject commit f3952833ac056881d749174c8526bd95013fa557
+Subproject commit b62e074dca9516dcb2f969cd4a644ce458d0b84f
diff --git a/docs/astro/src/data/apiStability.generated.json b/docs/astro/src/data/apiStability.generated.json
index 62083a3ae..ef8d54604 100644
--- a/docs/astro/src/data/apiStability.generated.json
+++ b/docs/astro/src/data/apiStability.generated.json
@@ -3,10 +3,10 @@
"counts": {
"public": 115,
"beta": 103,
- "experimental": 2200,
+ "experimental": 2203,
"deprecated": 3
},
- "total": 2418,
+ "total": 2421,
"subsystems": [
{
"id": "mobile-controls",
diff --git a/sdk/etc/tilemap.api.md b/sdk/etc/tilemap.api.md
index d379cef6e..9ef25874a 100644
--- a/sdk/etc/tilemap.api.md
+++ b/sdk/etc/tilemap.api.md
@@ -1,7 +1,7 @@
# API surface — esengine/tilemap
<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->
-Symbols: 0 public · 5 beta · 138 experimental · 0 deprecated
+Symbols: 0 public · 5 beta · 141 experimental · 0 deprecated
## BuildNavGridOptions — interface @experimental
```
@@ -28,6 +28,15 @@ CollisionBrush[]
"builtin:collision"
```
+## ChunkReadCore — interface @experimental
+```
+HEAPU8: Uint8Array<ArrayBufferLike> | undefined
+_free: ((ptr: number) => void) | undefined
+_malloc: ((bytes: number) => number) | undefined
+tilemap_readChunkIndex: ((entity: number, rowsPtr: number, capacity: number) => number) | undefined
+tilemap_readChunkTiles: ((entity: number, x: number, y: number, tilesPtr: number, capacity: number) => boolean) | undefined
+```
+
## CollectionGridTile — interface @experimental
```
id: number
@@ -41,6 +50,11 @@ id: number
key: string
```
+## CollisionChunkSnapshot — type @experimental
+```
+DecodedChunk & { revision: number }
+```
+
## CollisionMaterial — interface @experimental
```
density: number | undefined
@@ -771,6 +785,11 @@ tileTerrain: Map<number, number>
(norm: ReadonlyArray<readonly [number, number]>, tileW: number, tileH: number, flipH: boolean, flipV: boolean, flipD: boolean): { x: number; y: number; }[]
```
+## readCollisionChunks — function @experimental
+```
+(core: ChunkReadCore | null, entity: number, previous: ReadonlyMap<string, CollisionChunkSnapshot> | null): Map<string, CollisionChunkSnapshot> | null
+```
+
## resolveAutotile — function @experimental
```
(index: TerrainIndex, neighbors: readonly boolean[]): number
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.ts
index b78164f33..4a16579e1 100644
--- a/sdk/src/tilemap/index.ts
+++ b/sdk/src/tilemap/index.ts
@@ -27,6 +27,7 @@ export {
} from './tileGeometry';
export { mergeCollisionTiles, type MergedRect } from './collisionMerge';
export { decodeTilemapChunks, CHUNK_SIZE, type DecodedChunk } from './chunkCodec';
+export { readCollisionChunks, type ChunkReadCore, type CollisionChunkSnapshot } from './nativeCollisionChunks';
export {
TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D, TILE_FLAGS_MASK,
encodeTile, tileIdOf, tileFlagsOf, orientationPerm,
diff --git a/sdk/src/tilemap/nativeCollisionChunks.ts b/sdk/src/tilemap/nativeCollisionChunks.ts
new file mode 100644
index 000000000..0814b67f9
--- /dev/null
+++ b/sdk/src/tilemap/nativeCollisionChunks.ts
@@ -0,0 +1,55 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { CHUNK_SIZE, type DecodedChunk } from './chunkCodec';
+
+/**
+ * Native chunk readback capability.
+ * @experimental
+ */
+export interface ChunkReadCore {
+ tilemap_readChunkIndex?(entity: number, rowsPtr: number, capacity: number): number;
+ tilemap_readChunkTiles?(entity: number, x: number, y: number, tilesPtr: number, capacity: number): boolean;
+ _malloc?(bytes: number): number;
+ _free?(ptr: number): void;
+ HEAPU8?: Uint8Array;
+}
+/**
+ * Owned cells and their native edit revision.
+ * @experimental
+ */
+export type CollisionChunkSnapshot = DecodedChunk & { revision: number };
+const EMPTY_TILES = new Uint16Array(0);
+
+/** Copies changed chunks while retaining independent JS arrays for unchanged ones.
+ * Empty chunks share a zero-length marker and do not reach geometry. Temporary
+ * buffers belong to this call, so no retired core is kept alive.
+ * @experimental
+ */
+export function readCollisionChunks(core: ChunkReadCore | null, entity: number,
+ previous: ReadonlyMap<string, CollisionChunkSnapshot> | null): Map<string, CollisionChunkSnapshot> | null {
+ if (!core?.tilemap_readChunkIndex || !core.tilemap_readChunkTiles || !core._malloc || !core._free || !core.HEAPU8) return null;
+ const count = core.tilemap_readChunkIndex(entity, 0, 0);
+ if (!Number.isSafeInteger(count) || count < 0) return null;
+ if (count === 0) return new Map();
+ const indexBytes = count * 12, tileBytes = CHUNK_SIZE ** 2 * 2;
+ const ptr = core._malloc(indexBytes + tileBytes);
+ if (!ptr) return null;
+ try {
+ if (core.tilemap_readChunkIndex(entity, ptr, count) !== count) return null;
+ const rows = new DataView(core.HEAPU8.buffer, ptr, indexBytes);
+ // Chunk reads may grow memory and detach this view; own the index first.
+ const index = Array.from({ length: count }, (_, i) => ({ x: rows.getInt32(i * 12, true),
+ y: rows.getInt32(i * 12 + 4, true), revision: rows.getUint32(i * 12 + 8, true) }));
+ const next = new Map<string, CollisionChunkSnapshot>();
+ for (const { x, y, revision } of index) {
+ const key = `${x},${y}`, old = previous?.get(key);
+ if (old?.revision === revision) { next.set(key, old); continue; }
+ if (!core.tilemap_readChunkTiles(entity, x, y, ptr + indexBytes, CHUNK_SIZE ** 2)) return null;
+ const tiles = new Uint16Array(CHUNK_SIZE ** 2);
+ const input = new DataView(core.HEAPU8.buffer, ptr + indexBytes, tileBytes);
+ for (let cell = 0; cell < tiles.length; cell++) tiles[cell] = input.getUint16(cell * 2, true);
+ next.set(key, { x, y, tiles: tiles.some(tile => tile !== 0) ? tiles : EMPTY_TILES, revision });
+ }
+ return next;
+ } finally { core._free(ptr); }
+}
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index d9c724b67..e10db275a 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -18,7 +18,8 @@ import {
generateChunkCollision, generateChunkTileShapes,
spawnObjectRegion, isCollisionObjectGroup, decodeTiledGid, tiledLayerComponent, tiledGridLayout,
} from './tiledLoader';
-import { decodeTilemapChunks } from './chunkCodec';
+import { decodeTilemapChunks, type DecodedChunk } from './chunkCodec';
+import { readCollisionChunks, type CollisionChunkSnapshot } from './nativeCollisionChunks';
import { Assets, type AssetsData } from '../asset/AssetPlugin';
import { resolveAssetKey } from '../asset/resolveAssetKey';
import { LazyTilesetLoads } from './lazyTilesetLoads';
@@ -34,8 +35,9 @@ interface CollisionInputs {
gridKey: string;
originX: number;
originY: number;
- generation: number;
- revision: number;
+ generation: number | undefined;
+ revision: number | undefined;
+ native: Map<string, CollisionChunkSnapshot> | null;
width: number;
height: number;
pixelsPerUnit: number;
@@ -74,7 +76,8 @@ export class TilemapRuntime {
* and rendered the stale parse forever). */
private sourceDerivedFrom_ = new Map<number, LoadedTilemapSource>();
/** tilemap entity → the static collider entities derived from its collidable tiles (play-mode only). */
- private collisionEntities_ = new Map<number, Entity[]>();
+ private collisionEntities_ = new Map<number, Set<Entity>>();
+ private collisionChunks_ = new Map<number, Map<string, { chunk: DecodedChunk; entities: Entity[] }>>();
/** TilemapLayer entity → its baked collidable tile ids (out-of-band scene data; drives native collision). */
private nativeCollisionIds_ = new Map<number, number[]>();
/** TilemapLayer entity → per-tile rich collision shapes (global id → resolved
@@ -212,7 +215,6 @@ 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'),
@@ -238,11 +240,7 @@ export class TilemapRuntime {
if (c?.pixelsPerUnit) { pixelsPerUnit = c.pixelsPerUnit; break; }
}
if (!playMode && collisionEntities.size > 0) {
- for (const [, ents] of collisionEntities) {
- for (const e of ents) world.despawn(e);
- }
- collisionEntities.clear();
- collisionInputs.clear();
+ for (const entity of collisionEntities.keys()) this.clearLayerCollision_(world, entity);
}
const layerEntities = world.getEntitiesWithComponents(
@@ -254,7 +252,7 @@ export class TilemapRuntime {
|| !world.has(entity as Entity, Transform)) {
TilemapAPI.destroyLayer(entity);
initializedLayers.delete(entity);
- collisionInputs.delete(entity);
+ this.clearLayerCollision_(world, entity);
appliedCellSize.delete(entity);
appliedGrid.delete(entity);
nativeCollisionIds.delete(entity);
@@ -268,11 +266,6 @@ export class TilemapRuntime {
animatedLayers.delete(entity);
this.queryTableCache_.delete(entity);
this.derivedLayers_.delete(entity);
- const colliders = collisionEntities.get(entity);
- if (colliders) {
- for (const e of colliders) world.despawn(e);
- collisionEntities.delete(entity);
- }
}
}
@@ -292,9 +285,7 @@ export class TilemapRuntime {
const refs = tilesetRefs.get(entity);
// A layer needs either a copied texture (legacy) or .estileset ref(s).
if (!this.derivedLayers_.has(entity) && !layerData.tileset && (!refs || refs.length === 0)) {
- for (const collider of collisionEntities.get(entity) ?? []) world.despawn(collider);
- collisionEntities.delete(entity);
- collisionInputs.delete(entity);
+ this.clearLayerCollision_(world, entity);
continue;
}
@@ -635,16 +626,24 @@ export class TilemapRuntime {
|| world.has(entity as Entity, TilemapLayer)) this.teardownDerived_(world, entity);
}
- if (animatedLayers.size > 0) {
- const dtMs = app.getResource(Time).delta * 1000;
- for (const key of animatedLayers) {
- if (world.isEntityActive(key as Entity)) TilemapAPI.advanceAnimations(key, dtMs);
- }
- }
},
};
- app.addSystemToSchedule(Schedule.PreUpdate, tilemapSyncSystem);
+ // Frame edits and fixed-step edits derive before physics. Animation
+ // advances once per rendered frame, independently of catch-up steps.
+ app.addSystemToSchedule(Schedule.First, tilemapSyncSystem);
+ app.addSystemToSchedule(Schedule.FixedUpdate, {
+ ...tilemapSyncSystem, _id: Symbol('TilemapPhysicsSyncSystem'), _name: 'TilemapPhysicsSyncSystem',
+ }, { runBefore: ['CharacterController2DSystem', 'PhysicsStepSystem'], runIf: playModeOnly });
+ app.addSystemToSchedule(Schedule.PreUpdate, {
+ _id: Symbol('TilemapAnimationSystem'), _name: 'TilemapAnimationSystem', _params: [],
+ _fn: () => {
+ const dtMs = app.getResource(Time).delta * 1000;
+ for (const key of animatedLayers) {
+ if (world.isEntityActive(key as Entity)) TilemapAPI.advanceAnimations(key, dtMs);
+ }
+ },
+ });
}
private attachCollision_(world: World, owner: Entity, colliders: Entity[]): void {
@@ -660,43 +659,69 @@ export class TilemapRuntime {
const hasBoxes = !!ids?.length, hasShapes = !!shapes?.size;
const current = this.collisionEntities_.get(entity);
if (!hasBoxes && !hasShapes) {
- for (const collider of current ?? []) if (world.valid(collider)) world.despawn(collider);
- this.collisionEntities_.delete(entity); this.collisionInputs_.delete(entity);
+ this.clearLayerCollision_(world, entity);
return;
}
const engine = worldEngineApi(world), tiles = this.toolkit_;
if (!engine) return;
- const generation = engine.tilemap_getGeneration?.(entity) ?? 0;
- const revision = engine.tilemap_getEditRevision?.(entity) ?? 0;
+ const generation = engine.tilemap_getGeneration?.(entity);
+ const revision = engine.tilemap_getEditRevision?.(entity);
const gridKey = `${layer.orientation ?? 0}|${layer.hexSideLength ?? 0}|${layer.staggerAxis ?? 0}|${layer.staggerIndex ?? 0}`;
const originX = layer.originOffset?.x ?? 0, originY = layer.originOffset?.y ?? 0;
const previous = this.collisionInputs_.get(entity);
- const changed = !previous || previous.generation !== generation || previous.revision !== revision
+ const rebuild = !previous || previous.generation !== generation
|| previous.gridKey !== gridKey || previous.width !== layer.cellSize.x || previous.height !== layer.cellSize.y
|| previous.pixelsPerUnit !== ppu || previous.ids !== ids || previous.shapes !== shapes;
- if (current && changed) {
- for (const collider of current) if (world.valid(collider)) world.despawn(collider);
- this.collisionEntities_.delete(entity); this.collisionInputs_.delete(entity);
- } else if (current && previous && (previous.originX !== originX || previous.originY !== originY)) {
+ const sameContent = previous && generation !== undefined && revision !== undefined
+ && previous.generation === generation && previous.revision === revision;
+ const moved = !!previous && (previous.originX !== originX || previous.originY !== originY);
+ if (!rebuild && sameContent && !moved) return;
+ const retained = previous && generation !== undefined && previous.generation === generation
+ && revision !== undefined && previous.revision !== undefined && revision >= previous.revision ? previous.native : null;
+ const native = sameContent ? previous.native : readCollisionChunks(engine, entity, retained);
+ const oldChunks = this.collisionChunks_.get(entity);
+ const chunks = sameContent && oldChunks ? [...oldChunks.values()].map(value => value.chunk)
+ : native ? [...native.values()].filter(chunk => chunk.tiles.length > 0) : decodeTilemapChunks(tiles.exportChunks(entity));
+ if (rebuild) this.clearLayerCollision_(world, entity);
+ else if (current && moved) {
const dx = originX - previous.originX, dy = originY - previous.originY;
for (const collider of current) world.update(collider, Transform, value => {
value.position.x += dx; value.position.y += dy;
});
- previous.originX = originX; previous.originY = originY;
}
- if (this.collisionEntities_.has(entity)) return;
const layout = { orientation: layer.orientation ?? 0, hexSideLength: layer.hexSideLength ?? 0,
staggerAxisX: layer.staggerAxis === 1, staggerIndexEven: layer.staggerIndex === 1 };
- const chunks = decodeTilemapChunks(tiles.exportChunks(entity));
- const spawned: Entity[] = [];
- if (hasBoxes) spawned.push(...generateChunkCollision(world, chunks, new Set(ids), layer.cellSize.x, layer.cellSize.y,
- originX, originY, ppu, layout));
- if (hasShapes) spawned.push(...generateChunkTileShapes(world, chunks, shapes!, layer.cellSize.x, layer.cellSize.y,
- originX, originY, ppu, layout));
- this.attachCollision_(world, entity, spawned);
- this.collisionEntities_.set(entity, spawned);
+ const groups = this.collisionChunks_.get(entity) ?? new Map<string, { chunk: DecodedChunk; entities: Entity[] }>();
+ const all = this.collisionEntities_.get(entity) ?? new Set<Entity>(), keys = new Set<string>();
+ const remove = (group: { entities: Entity[] }) => {
+ for (const collider of group.entities) { all.delete(collider); if (world.valid(collider)) world.despawn(collider); }
+ };
+ const boxIds = new Set(ids);
+ for (const chunk of chunks) {
+ const key = `${chunk.x},${chunk.y}`; keys.add(key);
+ const old = groups.get(key);
+ if (old && (old.chunk.tiles === chunk.tiles || old.chunk.tiles.length === chunk.tiles.length
+ && old.chunk.tiles.every((value, index) => value === chunk.tiles[index]))) continue;
+ if (old) remove(old);
+ const spawned: Entity[] = [];
+ if (hasBoxes) for (const collider of generateChunkCollision(world, [chunk], boxIds, layer.cellSize.x, layer.cellSize.y,
+ originX, originY, ppu, layout)) spawned.push(collider);
+ if (hasShapes) for (const collider of generateChunkTileShapes(world, [chunk], shapes!, layer.cellSize.x, layer.cellSize.y,
+ originX, originY, ppu, layout)) spawned.push(collider);
+ this.attachCollision_(world, entity, spawned);
+ for (const collider of spawned) all.add(collider);
+ groups.set(key, { chunk, entities: spawned });
+ }
+ for (const [key, old] of groups) if (!keys.has(key)) { remove(old); groups.delete(key); }
+ this.collisionChunks_.set(entity, groups);
+ this.collisionEntities_.set(entity, all);
this.collisionInputs_.set(entity, { generation, revision, gridKey, originX, originY,
- width: layer.cellSize.x, height: layer.cellSize.y, pixelsPerUnit: ppu, ids, shapes });
+ width: layer.cellSize.x, height: layer.cellSize.y, pixelsPerUnit: ppu, ids, shapes, native });
+ }
+
+ private clearLayerCollision_(world: { valid(e: Entity): boolean; despawn(e: Entity): void }, entity: number): void {
+ for (const collider of this.collisionEntities_.get(entity) ?? []) if (world.valid(collider)) world.despawn(collider);
+ this.collisionEntities_.delete(entity); this.collisionInputs_.delete(entity); this.collisionChunks_.delete(entity);
}
/** Drop ONE tilemap entity's derived artifacts (child layer entities +
@@ -717,6 +742,7 @@ export class TilemapRuntime {
this.derivedLayers_.delete(child);
this.nativeCollisionIds_.delete(child); this.nativeTileShapes_.delete(child);
this.collisionEntities_.delete(child); this.collisionInputs_.delete(child);
+ this.collisionChunks_.delete(child);
this.appliedCellSize_.delete(child); this.appliedGrid_.delete(child);
// An owner despawn cascades to its children; only a component
// removal leaves them alive to clean up here.
@@ -750,6 +776,7 @@ export class TilemapRuntime {
// Collider entities die with the world on reset/teardown; just drop our bookkeeping.
this.collisionEntities_.clear();
this.collisionInputs_.clear();
+ this.collisionChunks_.clear();
this.nativeCollisionIds_.clear();
this.nativeTileShapes_.clear();
this.tilesetRefs_.clear();
diff --git a/sdk/tests/tilemap-grid-collision-wasm.test.ts b/sdk/tests/tilemap-grid-collision-wasm.test.ts
index a7de8133a..7dcc905a5 100644
--- a/sdk/tests/tilemap-grid-collision-wasm.test.ts
+++ b/sdk/tests/tilemap-grid-collision-wasm.test.ts
@@ -29,7 +29,7 @@ function scene() {
return { app, world: app.world, tiles: app.getResource(Tilemaps), runtime: app.getResource(TilemapRuntimeState) };
}
function generated(app: App, layer: number) {
- return (app.getResource(TilemapRuntimeState) as unknown as { collisionEntities_: Map<number, number[]> }).collisionEntities_.get(layer)!;
+ return [...(app.getResource(TilemapRuntimeState) as unknown as { collisionEntities_: Map<number, Set<number>> }).collisionEntities_.get(layer)!];
}
describe.skipIf(!HAS_WASM)('projected tile collision ownership', () => {
beforeAll(async () => { core = await loadWasmModule(); });
@@ -48,7 +48,7 @@ describe.skipIf(!HAS_WASM)('projected tile collision ownership', () => {
expect(world.get(original[0], Transform).position).toMatchObject({ x: expected.x + 7, y: expected.y - 3 });
world.update(layer, TilemapLayer, value => { value.orientation = (orientation + 1) % 4; });
await app.tick(1 / 60);
- expect(generated(app, layer)).not.toEqual(original); expect(exported).toHaveBeenCalledOnce();
+ expect(generated(app, layer)).not.toEqual(original); expect(exported).not.toHaveBeenCalled();
expect(world.valid(original[0])).toBe(false);
const next = tileCellCenter({ orientation: (orientation + 1) % 4, tileWidth: 16, tileHeight: 24, hexSideLength: 6 }, 3, 2);
expect(world.get(generated(app, layer)[0], Transform).position).toMatchObject({ x: next.x + 7, y: next.y - 3 });
diff --git a/sdk/tests/tilemap-incremental-collision-wasm.test.ts b/sdk/tests/tilemap-incremental-collision-wasm.test.ts
new file mode 100644
index 000000000..8399d9689
--- /dev/null
+++ b/sdk/tests/tilemap-incremental-collision-wasm.test.ts
@@ -0,0 +1,112 @@
+// SPDX-License-Identifier: Apache-2.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+import { afterEach, beforeAll, describe, expect, it, vi } from 'vitest';
+import { App } from '../src/app/app';
+import { Transform, TilemapLayer, Parent } from '../src/ecs/component';
+import { Schedule, defineSystem } from '../src/ecs/system';
+import { TilemapPlugin, TilemapRuntimeState } from '../src/tilemap/tilemapPlugin';
+import { Tilemaps } from '../src/tilemap/tilemapAPI';
+import { tileCellCenter } from '../src/tilemap/tileGeometry';
+import { Physics2DPlugin, Physics2DEvents } from '../src/physics/Physics2DPlugin';
+import { Physics2DRuntime } from '../src/physics/Physics2DRuntime';
+import { Physics2D } from '../src/physics/Physics2D';
+import { RigidBody2D, BoxCollider2D, BodyType } from '../src/physics/PhysicsComponents';
+import type { ESEngineModule } from '../src/wasm';
+import type { PhysicsWasmModule } from '../src/physics/PhysicsModuleLoader';
+import { HAS_WASM, hasSideModule, loadSideModule, loadWasmModule } from './helpers/loadWasm';
+
+let core: ESEngineModule;
+const apps: App[] = [];
+afterEach(() => { for (const app of apps.splice(0)) app.quit(); vi.restoreAllMocks(); });
+
+async function scene(orientation = 0, physicsFirst = false, gravity = 0) {
+ core.setActiveContext(null);
+ const app = App.new(); apps.push(app); app.connectCpp(new core.Registry(), core, { ownedRegistry: true });
+ const module = await loadSideModule<PhysicsWasmModule>('physics');
+ const physics = new Physics2DPlugin('', { gravity: { x: 0, y: gravity }, fixedTimestep: 1 / 60 }, async () => module);
+ if (physicsFirst) { app.addPlugin(physics); await app.getResource(Physics2DRuntime).initPromise; }
+ app.addPlugin(new TilemapPlugin());
+ if (!physicsFirst) { app.addPlugin(physics); await app.getResource(Physics2DRuntime).initPromise; }
+ const world = app.world, layer = world.spawn(), tiles = app.getResource(Tilemaps);
+ world.insert(layer, Transform); world.insert(layer, TilemapLayer, { cellSize: { x: 16, y: 24 }, orientation, hexSideLength: 6 });
+ app.getResource(TilemapRuntimeState).setLayerTilesets(layer, ['builtin:collision']); tiles.initInfiniteLayer(layer, 16, 24);
+ const bodies = () => world.getEntitiesWithComponents([RigidBody2D, Parent]).filter(id => world.get(id, Parent).entity === layer);
+ const at = (x: number, y: number) => tileCellCenter({ orientation, tileWidth: 16, tileHeight: 24, hexSideLength: 6 }, x, y);
+ const hits = (x: number, y: number) => {
+ const point = at(x, y);
+ return app.getResource(Physics2D).raycast({ x: point.x, y: point.y + 20 }, { x: 0, y: -1 }, 40);
+ };
+ return { app, world, layer, tiles, module, bodies, at, hits };
+}
+
+describe.skipIf(!HAS_WASM || !hasSideModule('physics'))('incremental tile collision before simulation', () => {
+ beforeAll(async () => { core = await loadWasmModule(); });
+
+ it.each([0, 1, 2, 3])('replaces only the edited chunk and keeps other physics bodies alive (layout=%s)', async orientation => {
+ const { app, world, layer, tiles, module, bodies, at, hits } = await scene(orientation);
+ for (const [x, y] of [[3, 2], [20, 2], [-17, -3]]) tiles.setTile(layer, x, y, 1);
+ await app.tick(1 / 60); expect(module._physics_getBodyCount()).toBe(3);
+ const original = bodies(), target = at(3, 2);
+ const changed = original.find(id => Math.hypot(world.get(id, Transform).position.x - target.x, world.get(id, Transform).position.y - target.y) < .001)!;
+ const stable = original.filter(id => id !== changed), copies = vi.spyOn(core, 'tilemap_readChunkTiles'), exports = vi.spyOn(tiles, 'exportChunks');
+ tiles.setTile(layer, 3, 2, 0); await app.tick(1 / 60);
+ expect(world.valid(changed)).toBe(false);
+ expect(bodies()).toEqual(stable); expect(module._physics_getBodyCount()).toBe(2);
+ for (const id of stable) expect(module._physics_hasBody(id)).toBe(1);
+ expect(copies).toHaveBeenCalledOnce(); expect(exports).not.toHaveBeenCalled();
+ expect(hits(3, 2)).toHaveLength(0);
+ tiles.setTile(layer, 3, 2, 8); await app.tick(1 / 60);
+ expect(bodies()).toHaveLength(3); expect(hits(3, 2)).toHaveLength(1);
+ for (const id of stable) expect(module._physics_hasBody(id)).toBe(1);
+ });
+
+ it.each(['missing-stamps', 'failed-readback'] as const)('retains unchanged bodies through %s fallback', async mode => {
+ const { app, world, layer, tiles, bodies } = await scene();
+ if (mode === 'missing-stamps') {
+ vi.spyOn(core, 'tilemap_getGeneration').mockReturnValue(undefined as never);
+ vi.spyOn(core, 'tilemap_getEditRevision').mockReturnValue(undefined as never);
+ }
+ tiles.setTile(layer, 0, 0, 1); tiles.setTile(layer, 20, 0, 1); await app.tick(1 / 60);
+ const stable = bodies().find(id => world.get(id, Transform).position.x > 100)!;
+ if (mode === 'failed-readback') vi.spyOn(core, 'tilemap_readChunkTiles').mockReturnValue(false);
+ tiles.setTile(layer, 0, 0, 2); await app.tick(1 / 60);
+ expect(world.valid(stable)).toBe(true); expect(bodies()).toHaveLength(2);
+ const current = bodies(); await app.stepFrames(3, 1 / 60); expect(bodies()).toEqual(current);
+ });
+
+ it.each([false, true])('sees fixed-step edits in the same physics step regardless of plugin order (physics first=%s)', async physicsFirst => {
+ const { app, layer, tiles, hits } = await scene(0, physicsFirst);
+ await app.tick(1 / 60);
+ let solid = false; const observed: boolean[] = [];
+ app.addSystemToSchedule(Schedule.FixedPreUpdate, defineSystem([], () => { solid = !solid; tiles.setTile(layer, 0, 0, solid ? 1 : 0); }, { name: 'PaintTile' }));
+ app.addSystemToSchedule(Schedule.FixedPostUpdate, defineSystem([], () => { observed.push(hits(0, 0).length > 0); expect(observed.at(-1)).toBe(solid); }, { name: 'ProbeTile' }));
+ vi.spyOn(performance, 'now').mockReturnValue(0);
+ await app.tick(1 / 30); expect(observed).toEqual([true, false]);
+ });
+
+ it('keeps a resting contact when a distant chunk changes', async () => {
+ const { app, world, layer, tiles, bodies } = await scene(0, false, -9.81);
+ tiles.setTile(layer, 0, 0, 1); tiles.setTile(layer, 20, 0, 1); await app.tick(1 / 60);
+ const floor = bodies().find(id => world.get(id, Transform).position.x > 100)!;
+ const actor = world.spawn(); world.insert(actor, Transform, { position: { x: 328, y: 40, z: 0 } });
+ world.insert(actor, RigidBody2D, { bodyType: BodyType.Dynamic }); world.insert(actor, BoxCollider2D, { halfExtents: { x: .03, y: .03 } });
+ await app.stepFrames(120, 1 / 60);
+ const resting = world.get(actor, Transform).worldPosition.y; expect(resting).toBeGreaterThan(0); expect(resting).toBeLessThan(10);
+ for (let i = 0; i < 8; i++) {
+ tiles.setTile(layer, 0, 0, i % 2); await app.tick(1 / 60);
+ expect(world.valid(floor)).toBe(true);
+ expect(app.getResource(Physics2DEvents).collisionExits.some(event => event.entityA === floor && event.entityB === actor || event.entityA === actor && event.entityB === floor)).toBe(false);
+ }
+ expect(world.get(actor, Transform).worldPosition.y).toBeCloseTo(resting, 2);
+ });
+
+ it('advances native tile animation once while two fixed steps run', async () => {
+ const { app, layer, tiles } = await scene(); await app.tick(1 / 60);
+ tiles.setTileAnimation(layer, 1, [{ tileId: 1, duration: 100 }, { tileId: 2, duration: 100 }]);
+ (app.getResource(TilemapRuntimeState) as unknown as { animatedLayers_: Set<number> }).animatedLayers_.add(layer);
+ const advance = vi.spyOn(core, 'tilemap_advanceAnimations');
+ vi.spyOn(performance, 'now').mockReturnValue(0);
+ await app.tick(1 / 30);
+ expect(advance).toHaveBeenCalledOnce(); expect(advance.mock.calls[0][1]).toBeCloseTo(1000 / 30, 5);
+ });
+});
diff --git a/sdk/tests/tilemap-live-collision-wasm.test.ts b/sdk/tests/tilemap-live-collision-wasm.test.ts
index a769d6760..4ae92c616 100644
--- a/sdk/tests/tilemap-live-collision-wasm.test.ts
+++ b/sdk/tests/tilemap-live-collision-wasm.test.ts
@@ -35,7 +35,7 @@ describe.skipIf(!HAS_WASM)('live native tile collision', () => {
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)!;
+ const colliders = () => [...((app.getResource(TilemapRuntimeState) as unknown as { collisionEntities_: Map<number, Set<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 () => {
@@ -47,7 +47,7 @@ describe.skipIf(!HAS_WASM)('live native tile collision', () => {
expect(exports).not.toHaveBeenCalled();
tiles.setTile(entity, 0, 0, 0); await app.tick(1 / 60);
expect(colliders()).toHaveLength(0);
- expect(exports).toHaveBeenCalledTimes(1);
+ expect(exports).not.toHaveBeenCalled();
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);
diff --git a/sdk/tests/tilemap-multi-app-wasm.test.ts b/sdk/tests/tilemap-multi-app-wasm.test.ts
index c355c8f36..0d67e57e6 100644
--- a/sdk/tests/tilemap-multi-app-wasm.test.ts
+++ b/sdk/tests/tilemap-multi-app-wasm.test.ts
@@ -121,18 +121,18 @@ describe.skipIf(!HAS_WASM)('tilemap runtimes in independent apps', () => {
expect(preview.tiles.getTile(preview.entity, 0, 0)).toBe(2);
preview.tiles.setTile(preview.entity, 0, 0, 1); await preview.app.tick(1 / 60);
expect(previewCore.tilemap_hasLayer!(preview.entity)).toBe(true);
- const colliders = (preview.runtime as unknown as { collisionEntities_: Map<number, number[]> })
+ const colliders = (preview.runtime as unknown as { collisionEntities_: Map<number, Set<number>> })
.collisionEntities_.get(preview.entity);
- expect(colliders?.length).toBeGreaterThan(0);
+ expect(colliders?.size).toBeGreaterThan(0);
});
it('quitting the preview lets the main runtime keep rebuilding collision', async () => {
const main = await scene(mainCore, 1), preview = await scene(previewCore, 2);
preview.app.quit();
main.tiles.setTile(main.entity, 0, 0, 0); await main.app.tick(1 / 60);
main.tiles.setTile(main.entity, -1, -1, 1); await main.app.tick(1 / 60);
- const colliders = (main.runtime as unknown as { collisionEntities_: Map<number, number[]> })
+ const colliders = (main.runtime as unknown as { collisionEntities_: Map<number, Set<number>> })
.collisionEntities_.get(main.entity);
- expect(colliders?.length).toBeGreaterThan(0);
+ expect(colliders?.size).toBeGreaterThan(0);
expect(main.tiles.getTile(main.entity, -1, -1)).toBe(1);
expect(TilemapAPI.getTile(main.entity, -1, -1)).toBe(1);
expect(isTileSolid(main.entity, -1, -1)).toBe(true);
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 3a02ab497..89ebe4bd9 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,10 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'perf(tilemap): synchronize collision by changed chunk':
+ { note: 'Tile edits preserve unaffected collision chunks and contacts.' },
+ 'refactor(editor): use shared tile collision chunk readback':
+ { note: 'Tile edits preserve unaffected collision chunks and contacts.' },
'perf(physics): batch composed static body poses across hosts':
{ note: 'Moving static collision uses a shared batch pose channel.' },
'fix(physics): release static pose history while time is frozen':