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 collision for painted tilemaps + physics gate (REARCH_TILEMAP T4)

esenginee1392c342ecb
diff --git a/desktop/src/tilemap/createTilemap.ts b/desktop/src/tilemap/createTilemap.ts
index 8bf7a738f..948067db6 100644
--- a/desktop/src/tilemap/createTilemap.ts
+++ b/desktop/src/tilemap/createTilemap.ts
@@ -7,8 +7,10 @@
* paintable entity, the tileset is the reusable asset it references.
*/
-import { parseTileset } from 'esengine';
+import { parseTileset, collidableTileIds } from 'esengine';
import { SceneCommands } from '@/engine/SceneCommands';
+import { SceneModel } from '@/engine/SceneModel';
+import { EditorHistory } from '@/engine/EditorHistory';
import { useSelection } from '@/store/selectionStore';
import { useTilemapPaint } from '@/store/tilemapPaintStore';
import { ProjectStore } from '@/project/ProjectStore';
@@ -47,6 +49,18 @@ export async function createTilemapFromTileset(tilesetPath: string): Promise<voi
SceneCommands.setField(sourceId, 'TilemapLayer', 'tilesetAsset', 'string', tilesetRef);
SceneCommands.endGesture();
+ // Bake the tileset's collidable tile ids onto the layer (out-of-band model data the
+ // runtime reads to spawn colliders — T4). Its own undo step so redo restores it.
+ const collIds = collidableTileIds(asset);
+ if (collIds.length > 0) {
+ SceneModel.setField(sourceId, 'TilemapLayer', 'collidableTileIds', collIds);
+ EditorHistory.record(
+ 'Bake Tilemap Collision',
+ () => SceneModel.setField(sourceId, 'TilemapLayer', 'collidableTileIds', collIds),
+ () => SceneModel.setField(sourceId, 'TilemapLayer', 'collidableTileIds', []),
+ );
+ }
+
useSelection.getState().select(sourceId);
useTilemapPaint.getState().setTileset(tilesetPath);
useTilemapPaint.getState().setTool('brush');
diff --git a/sdk/src/runtimeLoader.ts b/sdk/src/runtimeLoader.ts
index 162968bf3..52e465811 100644
--- a/sdk/src/runtimeLoader.ts
+++ b/sdk/src/runtimeLoader.ts
@@ -337,11 +337,16 @@ const PHYSICS_COMPONENT_TYPES = new Set([
'SegmentCollider', 'PolygonCollider', 'ChainCollider',
]);
-/** True if any entity in the scene carries a physics component (content gate). */
+/** True if any entity carries a physics component, or a TilemapLayer that will spawn
+ * colliders at runtime (its baked collidable tiles are invisible to a component scan). */
function sceneUsesPhysics(sceneData: SceneData): boolean {
for (const entity of sceneData.entities ?? []) {
for (const comp of entity.components ?? []) {
if (PHYSICS_COMPONENT_TYPES.has(comp.type)) return true;
+ if (comp.type === 'TilemapLayer') {
+ const ids = (comp.data as Record<string, unknown> | undefined)?.collidableTileIds;
+ if (Array.isArray(ids) && ids.length > 0) return true;
+ }
}
}
return false;
diff --git a/sdk/src/tilemap/chunkCodec.ts b/sdk/src/tilemap/chunkCodec.ts
new file mode 100644
index 000000000..2731bd88c
--- /dev/null
+++ b/sdk/src/tilemap/chunkCodec.ts
@@ -0,0 +1,79 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file chunkCodec.ts
+ * @brief Decode the `tilemap_exportChunks` blob (REARCH_TILEMAP T4) so the SDK can
+ * read painted tiles back — used to derive runtime collision from a tilemap's
+ * collidable tiles. Format (little-endian, base64url):
+ * u32 magic 'ESTM' · u32 chunkCount · per chunk: i32 x, i32 y, u16 tiles[256]
+ * (CHUNK_SIZE = 16; empty chunks are omitted by the exporter.)
+ */
+
+/** Tiles per chunk side (mirrors C++ `tilemap::CHUNK_SIZE`). */
+export const CHUNK_SIZE = 16;
+const CHUNK_TILES = CHUNK_SIZE * CHUNK_SIZE;
+const ESTM_MAGIC = 0x4d545345;
+
+/** One decoded chunk: its chunk-grid coords + the 16×16 row-major tile ids. */
+export interface DecodedChunk {
+ x: number;
+ y: number;
+ tiles: Uint16Array;
+}
+
+// Self-contained base64 decode (no `atob` — it's absent on some targets, e.g. wechat).
+// Accepts both the url-safe (-_) and standard (+/) alphabets; ignores padding/whitespace.
+const B64_ALPHABET = 'ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789';
+const B64_LOOKUP = (() => {
+ const t = new Int16Array(128).fill(-1);
+ for (let i = 0; i < B64_ALPHABET.length; i++) t[B64_ALPHABET.charCodeAt(i)] = i;
+ t[43] = 62; t[45] = 62; // '+' '-'
+ t[47] = 63; t[95] = 63; // '/' '_'
+ return t;
+})();
+
+function base64UrlToBytes(s: string): Uint8Array {
+ const vals: number[] = [];
+ for (let i = 0; i < s.length; i++) {
+ const c = s.charCodeAt(i);
+ const v = c < 128 ? B64_LOOKUP[c] : -1;
+ if (v >= 0) vals.push(v);
+ }
+ const out = new Uint8Array((vals.length * 6) >> 3);
+ let bits = 0, acc = 0, o = 0;
+ for (const v of vals) {
+ acc = (acc << 6) | v;
+ bits += 6;
+ if (bits >= 8) { bits -= 8; out[o++] = (acc >> bits) & 0xff; }
+ }
+ return out;
+}
+
+/** Decode a `tilemap_exportChunks` blob into its non-empty chunks (empty/invalid → []). */
+export function decodeTilemapChunks(blob: string): DecodedChunk[] {
+ if (!blob) return [];
+ let bytes: Uint8Array;
+ try {
+ bytes = base64UrlToBytes(blob);
+ } catch {
+ return [];
+ }
+ if (bytes.byteLength < 8) return [];
+ const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+ let off = 0;
+ if (dv.getUint32(off, true) !== ESTM_MAGIC) return [];
+ off += 4;
+ const count = dv.getUint32(off, true);
+ off += 4;
+ const chunks: DecodedChunk[] = [];
+ const perChunk = 8 + CHUNK_TILES * 2;
+ for (let i = 0; i < count; i++) {
+ if (off + perChunk > bytes.byteLength) break; // truncated → stop
+ const x = dv.getInt32(off, true); off += 4;
+ const y = dv.getInt32(off, true); off += 4;
+ const tiles = new Uint16Array(CHUNK_TILES);
+ for (let t = 0; t < CHUNK_TILES; t++) { tiles[t] = dv.getUint16(off, true); off += 2; }
+ chunks.push({ x, y, tiles });
+ }
+ return chunks;
+}
diff --git a/sdk/src/tilemap/index.ts b/sdk/src/tilemap/index.ts
index 26f2b9896..d1dbb5fa7 100644
--- a/sdk/src/tilemap/index.ts
+++ b/sdk/src/tilemap/index.ts
@@ -5,12 +5,13 @@ export { TilemapAPI, initTilemapAPI, shutdownTilemapAPI } from './tilemapAPI';
export { TilemapPlugin, tilemapPlugin } from './tilemapPlugin';
export {
parseTiledMap, parseTmjJson, loadTiledMap, loadTiledCollisionObjects,
- generateTileCollision, generateLayerCollision, resolveRelativePath,
+ generateTileCollision, generateLayerCollision, generateChunkCollision, resolveRelativePath,
type TiledMapData, type TiledLayerData, type TiledTilesetData,
type TiledObjectData, type TiledObjectGroupData, type TiledObjectShape,
type TiledAnimFrame, type TilemapLoadOptions,
} from './tiledLoader';
export { mergeCollisionTiles, type MergedRect } from './collisionMerge';
+export { decodeTilemapChunks, CHUNK_SIZE, type DecodedChunk } from './chunkCodec';
export {
TILESET_FORMAT_VERSION, parseTileset, serializeTileset, createTileset, collidableTileIds,
type TilesetAsset, type TilesetTile, type TilesetCollision, type TilesetAnimFrame,
diff --git a/sdk/src/tilemap/tiledLoader.ts b/sdk/src/tilemap/tiledLoader.ts
index c94470128..e74ba29dd 100644
--- a/sdk/src/tilemap/tiledLoader.ts
+++ b/sdk/src/tilemap/tiledLoader.ts
@@ -39,6 +39,7 @@ function uploadTiledLayerTiles(entity: Entity, layer: TiledLayerData): void {
}
import { RigidBody, BoxCollider, CircleCollider, BodyType } from '../physics/PhysicsComponents';
import { mergeCollisionTiles } from './collisionMerge';
+import { CHUNK_SIZE } from './chunkCodec';
import { log } from '../logger';
import { withMalloc } from '../wasmScratch';
@@ -605,6 +606,53 @@ export function generateTileCollision(
);
}
+/**
+ * @brief Build static box colliders for an INFINITE (chunked) tilemap layer from its
+ * collidable tiles — the native scene-`TilemapLayer` path (REARCH_TILEMAP T4).
+ *
+ * Each chunk's collidable tiles are greedy-merged independently (no cross-chunk merge); a
+ * merged rect (x0,y0)-(x1,y1) maps to a world AABB by the SAME orthogonal convention
+ * `worldToTile` uses (tile tx covers world-x [origin.x+tx·tw, origin.x+(tx+1)·tw); world-y
+ * grows downward as ty rises), so colliders line up exactly with what the painter placed.
+ * (Isometric/staggered collision is not derived here.)
+ */
+export function generateChunkCollision(
+ world: World,
+ chunks: { x: number; y: number; tiles: Uint16Array }[],
+ collisionIds: Set<number>,
+ tileW: number,
+ tileH: number,
+ originX: number,
+ originY: number,
+): Entity[] {
+ const entities: Entity[] = [];
+ for (const chunk of chunks) {
+ const merged = mergeCollisionTiles(chunk.tiles, CHUNK_SIZE, CHUNK_SIZE, collisionIds);
+ const baseX = chunk.x * CHUNK_SIZE;
+ const baseY = chunk.y * CHUNK_SIZE;
+ for (const rect of merged) {
+ const x0 = baseX + rect.col;
+ const y0 = baseY + rect.row;
+ const x1 = x0 + rect.width - 1;
+ const y1 = y0 + rect.height - 1;
+ const entity = world.spawn();
+ world.insert(entity, Transform, {
+ position: {
+ x: originX + ((x0 + x1 + 1) / 2) * tileW,
+ y: originY - ((y0 + y1 + 1) / 2) * tileH,
+ z: 0,
+ },
+ });
+ world.insert(entity, RigidBody, { bodyType: BodyType.Static });
+ world.insert(entity, BoxCollider, {
+ halfExtents: { x: rect.width * tileW * 0.5, y: rect.height * tileH * 0.5 },
+ });
+ entities.push(entity);
+ }
+ }
+ return entities;
+}
+
export function loadTiledMap(
world: World,
mapData: TiledMapData,
diff --git a/sdk/src/tilemap/tilemapPlugin.ts b/sdk/src/tilemap/tilemapPlugin.ts
index f67bdcaf3..7fea14102 100644
--- a/sdk/src/tilemap/tilemapPlugin.ts
+++ b/sdk/src/tilemap/tilemapPlugin.ts
@@ -9,7 +9,8 @@ import { initTilemapAPI, shutdownTilemapAPI, TilemapAPI } from './tilemapAPI';
import { Tilemap } from './components';
import { registerSceneComponentCodec } from '../scene';
import { getTilemapSource } from './tilesetCache';
-import { generateLayerCollision } from './tiledLoader';
+import { generateLayerCollision, generateChunkCollision } from './tiledLoader';
+import { decodeTilemapChunks } from './chunkCodec';
import { getTextureDimensions } from '../resourceManager';
import { Time } from '../resource';
import { playModeOnly } from '../env';
@@ -41,6 +42,8 @@ export class TilemapPlugin implements Plugin {
}>();
/** tilemap entity → the static collider entities derived from its collidable tiles (play-mode only). */
private collisionEntities_ = new Map<number, Entity[]>();
+ /** TilemapLayer entity → its baked collidable tile ids (out-of-band scene data; drives native collision). */
+ private nativeCollisionIds_ = new Map<number, number[]>();
build(app: App): void {
const module = app.wasmModule as ESEngineModule;
@@ -49,17 +52,28 @@ export class TilemapPlugin implements Plugin {
// Tile chunks live in a C++ blob, not the component's field record, so
// teach the scene (de)serializer to carry them out-of-band instead of
// hardcoding TilemapLayer knowledge in scene.ts.
+ const nativeCollisionIds = this.nativeCollisionIds_;
registerSceneComponentCodec('TilemapLayer', {
exportData: (entity, data) => {
const blob = TilemapAPI.exportChunks(entity);
if (blob) data.chunks = blob;
+ // Carry the baked collidable tile-id set out-of-band (like chunks) so the
+ // runtime can derive collision; it isn't a C++ component field.
+ const ids = nativeCollisionIds.get(entity);
+ if (ids && ids.length > 0) data.collidableTileIds = ids.slice();
},
- outOfBandFields: ['chunks'],
+ outOfBandFields: ['chunks', 'collidableTileIds'],
importData: (entity, outOfBand) => {
const blob = outOfBand.chunks;
if (typeof blob === 'string' && blob !== '') {
TilemapAPI.importChunks(entity, blob);
}
+ const ids = outOfBand.collidableTileIds;
+ if (Array.isArray(ids) && ids.length > 0) {
+ nativeCollisionIds.set(entity, ids.map(Number).filter((n) => Number.isInteger(n)));
+ } else {
+ nativeCollisionIds.delete(entity);
+ }
},
});
@@ -97,6 +111,12 @@ export class TilemapPlugin implements Plugin {
TilemapAPI.destroyLayer(entity);
initializedLayers.delete(entity);
layerState.delete(entity);
+ nativeCollisionIds.delete(entity);
+ const colliders = collisionEntities.get(entity);
+ if (colliders) {
+ for (const e of colliders) world.despawn(e);
+ collisionEntities.delete(entity);
+ }
}
}
@@ -154,6 +174,20 @@ export class TilemapPlugin implements Plugin {
visible: layerData.visible,
});
}
+
+ // Native path: a painted TilemapLayer with collidable tiles (baked from
+ // its .estileset) spawns merged static colliders once in play mode.
+ const collIds = nativeCollisionIds.get(entity);
+ if (playMode && collIds && collIds.length > 0 && !collisionEntities.has(entity)) {
+ const chunks = decodeTilemapChunks(TilemapAPI.exportChunks(entity));
+ const tf = world.tryGet(entity, Transform) as { position: { x: number; y: number } } | null;
+ const spawned = generateChunkCollision(
+ world, chunks, new Set(collIds),
+ layerData.cellSize.x, layerData.cellSize.y,
+ tf?.position.x ?? 0, tf?.position.y ?? 0,
+ );
+ collisionEntities.set(entity, spawned);
+ }
}
const tilemapEntities = world.getEntitiesWithComponents(
@@ -302,6 +336,7 @@ export class TilemapPlugin implements Plugin {
this.layerState_.clear();
// Collider entities die with the world on reset/teardown; just drop our bookkeeping.
this.collisionEntities_.clear();
+ this.nativeCollisionIds_.clear();
}
cleanup(): void {
diff --git a/sdk/tests/chunk-collision.test.ts b/sdk/tests/chunk-collision.test.ts
new file mode 100644
index 000000000..24bbaa300
--- /dev/null
+++ b/sdk/tests/chunk-collision.test.ts
@@ -0,0 +1,90 @@
+// SPDX-License-Identifier: LicenseRef-PolyForm-Noncommercial-1.0.0
+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
+/**
+ * @file Native-path tilemap collision (REARCH_TILEMAP T4): decoding the chunk blob and
+ * deriving merged static colliders from a painted layer's collidable tiles.
+ */
+import { describe, it, expect, vi } from 'vitest';
+import { decodeTilemapChunks, CHUNK_SIZE } from '../src/tilemap/chunkCodec';
+import { generateChunkCollision } from '../src/tilemap/tiledLoader';
+import { BodyType } from '../src/physics/PhysicsComponents';
+import type { World } from '../src/world';
+import type { Entity } from '../src/types';
+
+// Build a `tilemap_exportChunks`-format blob (base64url) for the given chunks.
+function encodeChunks(chunks: { x: number; y: number; tiles: Uint16Array }[]): string {
+ const perChunk = 8 + CHUNK_SIZE * CHUNK_SIZE * 2;
+ const buf = new ArrayBuffer(8 + chunks.length * perChunk);
+ const dv = new DataView(buf);
+ dv.setUint32(0, 0x4d545345, true); // 'ESTM'
+ dv.setUint32(4, chunks.length, true);
+ let off = 8;
+ for (const c of chunks) {
+ dv.setInt32(off, c.x, true); off += 4;
+ dv.setInt32(off, c.y, true); off += 4;
+ for (let i = 0; i < CHUNK_SIZE * CHUNK_SIZE; i++) { dv.setUint16(off, c.tiles[i], true); off += 2; }
+ }
+ let bin = '';
+ for (const b of new Uint8Array(buf)) bin += String.fromCharCode(b);
+ return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_');
+}
+
+interface MockEntity { Transform?: any; RigidBody?: any; BoxCollider?: any }
+function createMockWorld(): { world: World; store: Map<number, MockEntity> } {
+ let nextId = 1;
+ const store = new Map<number, MockEntity>();
+ const world = {
+ spawn: vi.fn(() => { const id = nextId++ as Entity; store.set(id, {}); return id; }),
+ insert: vi.fn((e: Entity, comp: any, data: any) => { (store.get(e) as any)[comp._name] = data; }),
+ } as unknown as World;
+ return { world, store };
+}
+
+describe('decodeTilemapChunks', () => {
+ it('round-trips a chunk (coords + tiles)', () => {
+ const tiles = new Uint16Array(CHUNK_SIZE * CHUNK_SIZE);
+ tiles[0] = 5;
+ tiles[CHUNK_SIZE + 1] = 7; // local (1,1)
+ const chunks = decodeTilemapChunks(encodeChunks([{ x: 2, y: -1, tiles }]));
+ expect(chunks).toHaveLength(1);
+ expect(chunks[0]).toMatchObject({ x: 2, y: -1 });
+ expect(chunks[0].tiles[0]).toBe(5);
+ expect(chunks[0].tiles[CHUNK_SIZE + 1]).toBe(7);
+ });
+
+ it('returns [] for empty or wrong-magic blobs', () => {
+ expect(decodeTilemapChunks('')).toEqual([]);
+ expect(decodeTilemapChunks(btoa('not a tilemap'))).toEqual([]); // valid base64, bad magic
+ });
+});
+
+describe('generateChunkCollision', () => {
+ it('greedy-merges collidable tiles into one centered static box (y grows downward)', () => {
+ const { world, store } = createMockWorld();
+ const tiles = new Uint16Array(CHUNK_SIZE * CHUNK_SIZE);
+ tiles[0] = 1; tiles[1] = 1; // local (0,0)+(1,0) → a 2×1 rect
+ const ents = generateChunkCollision(world, [{ x: 0, y: 0, tiles }], new Set([1]), 16, 16, 0, 0);
+ expect(ents).toHaveLength(1);
+ const e = store.get(ents[0])!;
+ // x0..x1 = 0..1, y0..y1 = 0..0 → center ((0+1+1)/2·16, -(0+0+1)/2·16) = (16, -8)
+ expect(e.Transform.position).toEqual({ x: 16, y: -8, z: 0 });
+ expect(e.BoxCollider.halfExtents).toEqual({ x: 16, y: 8 });
+ expect(e.RigidBody.bodyType).toBe(BodyType.Static);
+ });
+
+ it('offsets by chunk coords and the tilemap world origin', () => {
+ const { world, store } = createMockWorld();
+ const tiles = new Uint16Array(CHUNK_SIZE * CHUNK_SIZE);
+ tiles[0] = 1; // chunk (1,0) local (0,0) → absolute tile (16,0)
+ const ents = generateChunkCollision(world, [{ x: 1, y: 0, tiles }], new Set([1]), 16, 16, 100, 200);
+ // cx = 100 + (16+16+1)/2·16 = 364 ; cy = 200 - (0+0+1)/2·16 = 192
+ expect(store.get(ents[0])!.Transform.position).toEqual({ x: 364, y: 192, z: 0 });
+ });
+
+ it('ignores non-collidable tiles', () => {
+ const { world } = createMockWorld();
+ const tiles = new Uint16Array(CHUNK_SIZE * CHUNK_SIZE);
+ tiles[0] = 2; // not in the collision set
+ expect(generateChunkCollision(world, [{ x: 0, y: 0, tiles }], new Set([1]), 16, 16, 0, 0)).toHaveLength(0);
+ });
+});