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.
TypeScript 2d-game-engine3d3d-game-engineandroidcppecsgame-editorgame-enginegamedeviostypescriptwebassemblywebglwebgpuwechat-minigame
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.tsindex 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<voiSceneCommands.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.tsindex 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.tsnew file mode 100644index 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.tsindex 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.tsindex 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.tsindex 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.tsnew file mode 100644index 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);+ });+});