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
// SPDX-License-Identifier: Apache-2.0
// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team
import { withMalloc } from '../wasm/wasmScratch';
import { WasmBridge } from '../wasm/WasmBridge';
import type { EngineApi } from '../ecs/bridge/engineApi';
import { defineResource } from '../ecs/resource';
/**
* The tilemap entry points as a core that HAS tilemaps answers them — the shape
* this file drives, spelled once. Both cores answer these names (embind on the
* web, EHT-generated QuickJS wrappers on a device), and both carry the heap the
* tile arrays cross through, so the toolkit below is core-agnostic.
*/
interface TilemapModule {
tilemap_initLayer(entity: number, width: number, height: number,
tileWidth: number, tileHeight: number): void;
tilemap_destroyLayer(entity: number): void;
tilemap_setTile(entity: number, x: number, y: number, tileId: number): void;
tilemap_getTile(entity: number, x: number, y: number): number;
tilemap_fillRect(entity: number, x: number, y: number,
w: number, h: number, tileId: number): void;
tilemap_setTiles(entity: number, tilesPtr: number, count: number): void;
tilemap_setTilesets(entity: number, dataPtr: number, count: number): void;
tilemap_hasLayer(entity: number): boolean;
tilemap_setRenderProps(entity: number, textureHandle: number, tilesetColumns: number,
uvTileW: number, uvTileH: number,
sortLayer: number, depth: number,
parallaxX: number, parallaxY: number): void;
tilemap_setTint(entity: number, r: number, g: number, b: number, a: number,
opacity: number): void;
tilemap_setVisible(entity: number, visible: boolean): void;
tilemap_setOriginEntity(layerKey: number, originEntity: number): void;
tilemap_setTileAnimation(entity: number, tileId: number,
framesPtr: number, frameCount: number): void;
tilemap_clearTileAnimations(entity: number): void;
tilemap_advanceAnimations(entity: number, dtMs: number): void;
tilemap_setTileProperty(entity: number, tileId: number,
key: string, value: string): void;
tilemap_getTileProperty(entity: number, x: number, y: number,
key: string): string;
tilemap_flipTile(entity: number, x: number, y: number,
flipH: boolean, flipV: boolean, flipD: boolean): void;
tilemap_rotateTile(entity: number, x: number, y: number, degrees: number): void;
tilemap_setGridType(entity: number, type: number): void;
tilemap_setHexParams(entity: number, sideLength: number, staggerAxisX: number, staggerIndexEven: number): void;
tilemap_initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void;
tilemap_initInfinite?(entity: number, tileWidth: number, tileHeight: number): void;
tilemap_exportChunks?(entity: number): string;
tilemap_importChunks?(entity: number, encoded: string): boolean;
tilemap_setChunkTiles(entity: number, chunkX: number, chunkY: number,
tilesPtr: number, width: number, height: number): void;
tilemap_removeChunk?(entity: number, chunkX: number, chunkY: number): void;
tilemap_tileToWorld(entity: number, tx: number, ty: number,
originX: number, originY: number): number;
tilemap_worldToTile(entity: number, wx: number, wy: number,
originX: number, originY: number): number;
HEAPF32: Float32Array;
HEAPU8: Uint8Array;
_malloc(size: number): number;
_free(ptr: number): void;
}
/** Guarded view of the core: after a wasm abort a call throws instead of reaching
* a dead module. A native host's bindings pass through the same channel and
* simply never abort. */
class TilemapBridge extends WasmBridge<NonNullable<EngineApi>> {
protected readonly label = 'tilemap';
}
const bridge = new TilemapBridge();
let module_: TilemapModule | null = null;
const legacyOwner = {};
const bindings: Array<{ owner: object; engine: NonNullable<EngineApi> }> = [];
/** @internal Wired by the engine plugins — not part of the public API.
* Takes whichever core is present (see ecs/engineApi.ts); the plugin only calls
* this once it has checked that the core compiles tilemaps, which is what makes
* the narrowing below sound. */
export function initTilemapAPI(engine: NonNullable<EngineApi>, owner: object = legacyOwner): void {
const previous = bindings.findIndex(binding => binding.owner === owner);
if (previous >= 0) bindings.splice(previous, 1);
bindings.push({ owner, engine });
bridge.connect(engine);
module_ = bridge.module as unknown as TilemapModule;
}
/** @internal Wired by the engine plugins — not part of the public API. */
export function shutdownTilemapAPI(owner?: object): void {
if (owner) {
const index = bindings.findIndex(binding => binding.owner === owner);
if (index < 0) return;
const wasCurrent = index === bindings.length - 1;
bindings.splice(index, 1);
if (!wasCurrent) return;
const current = bindings[bindings.length - 1];
if (current) {
bridge.connect(current.engine);
module_ = bridge.module as unknown as TilemapModule;
return;
}
} else bindings.length = 0;
bridge.disconnect();
module_ = null;
}
/**
* The static tilemap toolkit — chunk/tile accessors over the wasm module,
* addressed by runtime layer handle. Contract: game code reads this as the
* `Res(Tilemaps)` resource like every other subsystem; direct `TilemapAPI.*`
* calls are the host/tooling surface (the editor's tile tools, tests) where no
* App is in scope. Both names are the same object.
*/
/**
* u32s per slot in the `tilemap_setTilesets` buffer, in the order
* [firstId, textureHandle, columns, margin, spacing, extrude]. Two files unpack
* it and no generator spans them, so the number is named on both sides —
* `TilemapBindings.cpp` is the other half.
*/
export const TILESET_SLOT_STRIDE = 6;
/**
* The tilemap toolkit over ONE engine core.
*
* A factory rather than a singleton: an editor world and a play world are two
* apps with two cores, and a module-level `module_` answered both with whichever
* initialised last — so one app's reads went to the other's engine.
*/
function tilemapAPI(moduleOf: () => TilemapModule | null) {
return {
initLayer(entity: number, width: number, height: number,
tileWidth: number, tileHeight: number): void {
moduleOf()?.tilemap_initLayer(entity, width, height, tileWidth, tileHeight);
},
destroyLayer(entity: number): void {
moduleOf()?.tilemap_destroyLayer(entity);
},
setTile(entity: number, x: number, y: number, tileId: number): void {
moduleOf()?.tilemap_setTile(entity, x, y, tileId);
},
getTile(entity: number, x: number, y: number): number {
if (!moduleOf()) return 0;
return moduleOf()!.tilemap_getTile(entity, x, y);
},
fillRect(entity: number, x: number, y: number,
w: number, h: number, tileId: number): void {
moduleOf()?.tilemap_fillRect(entity, x, y, w, h, tileId);
},
setTiles(entity: number, tiles: Uint16Array): void {
const m = moduleOf();
if (!m) return;
const bytes = tiles.byteLength;
withMalloc(m, bytes, ptr => {
new Uint16Array(m.HEAPU8.buffer, ptr, tiles.length).set(tiles);
m.tilemap_setTiles(entity, ptr, tiles.length);
});
},
/**
* Replace the layer's multi-tileset table. Empty array reverts to single-tileset.
*
* The packed field ORDER is the contract with `tilemap_setTilesets`, and it is
* written down here and read there — see TILESET_SLOT_STRIDE.
*/
setTilesets(entity: number, slots: {
firstId: number; textureHandle: number; columns: number;
margin?: number; spacing?: number; extrude?: number;
}[]): void {
const m = moduleOf();
if (!m) return;
const STRIDE = TILESET_SLOT_STRIDE;
const packed = new Uint32Array(slots.length * STRIDE);
for (let i = 0; i < slots.length; i++) {
packed[i * STRIDE] = slots[i].firstId;
packed[i * STRIDE + 1] = slots[i].textureHandle;
packed[i * STRIDE + 2] = slots[i].columns;
packed[i * STRIDE + 3] = slots[i].margin ?? 0;
packed[i * STRIDE + 4] = slots[i].spacing ?? 0;
packed[i * STRIDE + 5] = slots[i].extrude ?? 0;
}
withMalloc(m, packed.byteLength, ptr => {
new Uint32Array(m.HEAPU8.buffer, ptr, packed.length).set(packed);
m.tilemap_setTilesets(entity, ptr, slots.length);
});
},
hasLayer(entity: number): boolean {
if (!moduleOf()) return false;
return moduleOf()!.tilemap_hasLayer(entity);
},
setRenderProps(entity: number, textureHandle: number, tilesetColumns: number,
uvTileW: number, uvTileH: number,
sortLayer: number, depth: number,
parallaxX: number, parallaxY: number): void {
moduleOf()?.tilemap_setRenderProps(entity, textureHandle, tilesetColumns,
uvTileW, uvTileH, sortLayer, depth, parallaxX, parallaxY);
},
setTint(entity: number, r: number, g: number, b: number, a: number,
opacity: number): void {
moduleOf()?.tilemap_setTint(entity, r, g, b, a, opacity);
},
setVisible(entity: number, visible: boolean): void {
moduleOf()?.tilemap_setVisible(entity, visible);
},
setOriginEntity(layerKey: number, originEntity: number): void {
moduleOf()?.tilemap_setOriginEntity(layerKey, originEntity);
},
setTileAnimation(entity: number, tileId: number,
frames: { tileId: number; duration: number }[]): void {
const m = moduleOf();
if (!m || frames.length === 0) return;
const buf = new Uint32Array(frames.length * 2);
for (let i = 0; i < frames.length; i++) {
buf[i * 2] = frames[i].tileId;
buf[i * 2 + 1] = frames[i].duration;
}
const bytes = buf.byteLength;
withMalloc(m, bytes, ptr => {
new Uint32Array(m.HEAPU8.buffer, ptr, buf.length).set(buf);
m.tilemap_setTileAnimation(entity, tileId, ptr, frames.length);
});
},
/** Drop every tile animation on the layer (a tileset swap re-adds the new set's). */
clearTileAnimations(entity: number): void {
moduleOf()?.tilemap_clearTileAnimations(entity);
},
advanceAnimations(entity: number, dtMs: number): void {
moduleOf()?.tilemap_advanceAnimations(entity, dtMs);
},
setTileProperty(entity: number, tileId: number,
key: string, value: string): void {
moduleOf()?.tilemap_setTileProperty(entity, tileId, key, value);
},
getTileProperty(entity: number, x: number, y: number, key: string): string {
if (!moduleOf()) return '';
return moduleOf()!.tilemap_getTileProperty(entity, x, y, key);
},
flipTile(entity: number, x: number, y: number,
flipH: boolean, flipV: boolean, flipD: boolean): void {
moduleOf()?.tilemap_flipTile(entity, x, y, flipH, flipV, flipD);
},
rotateTile(entity: number, x: number, y: number, degrees: number): void {
moduleOf()?.tilemap_rotateTile(entity, x, y, degrees);
},
initInfiniteLayer(entity: number, tileWidth: number, tileHeight: number): void {
// Prefer the idempotent binding so a second call doesn't wipe tiles.
const m = moduleOf();
if (m?.tilemap_initInfinite) {
m.tilemap_initInfinite(entity, tileWidth, tileHeight);
return;
}
moduleOf()?.tilemap_initInfiniteLayer(entity, tileWidth, tileHeight);
},
setChunkTiles(entity: number, chunkX: number, chunkY: number,
tiles: Uint16Array, width: number, height: number): void {
const m = moduleOf();
if (!m) return;
const bytes = tiles.byteLength;
withMalloc(m, bytes, ptr => {
new Uint16Array(m.HEAPU8.buffer, ptr, tiles.length).set(tiles);
m.tilemap_setChunkTiles(entity, chunkX, chunkY, ptr, width, height);
});
},
/**
* Takes one chunk (16 by 16 tiles, in chunk coordinates) out of a layer, tiles and drawn mesh both. A world that is streamed in as it is walked
* calls this for the chunks it has left behind, so the layer holds the ones near and not every one it ever held.
*/
removeChunk(entity: number, chunkX: number, chunkY: number): void {
moduleOf()?.tilemap_removeChunk?.(entity, chunkX, chunkY);
},
setGridType(entity: number, type: number): void {
moduleOf()?.tilemap_setGridType(entity, type);
},
/** Hexagonal-grid layout inputs (Tiled hexsidelength/staggeraxis/staggerindex);
* only read when the layer's grid type is Hexagonal (3). */
setHexParams(entity: number, sideLength: number, staggerAxisX: boolean, staggerIndexEven: boolean): void {
moduleOf()?.tilemap_setHexParams(entity, sideLength, staggerAxisX ? 1 : 0, staggerIndexEven ? 1 : 0);
},
/** Grid anchor in world pixels; rotation is the layer's world Z angle in radians. */
tileToWorld(entity: number, tx: number, ty: number,
originX: number, originY: number, rotation = 0): { x: number; y: number } {
if (!moduleOf()) return { x: 0, y: 0 };
const m0 = moduleOf()!;
const ptr = m0.tilemap_tileToWorld(entity, tx, ty, rotation === 0 ? originX : 0, rotation === 0 ? originY : 0);
const floats = new Float32Array(m0.HEAPU8.buffer, ptr, 2);
if (rotation === 0) return { x: floats[0], y: floats[1] };
const c = Math.cos(rotation), s = Math.sin(rotation);
return { x: originX + c * floats[0] - s * floats[1], y: originY + s * floats[0] + c * floats[1] };
},
/** Invert the layer origin and world Z rotation before reading its grid. */
worldToTile(entity: number, wx: number, wy: number,
originX: number, originY: number, rotation = 0): { x: number; y: number } {
if (!moduleOf()) return { x: 0, y: 0 };
const m0 = moduleOf()!;
const dx = wx - originX, dy = wy - originY, c = Math.cos(rotation), s = Math.sin(rotation);
const ptr = rotation === 0
? m0.tilemap_worldToTile(entity, wx, wy, originX, originY)
: m0.tilemap_worldToTile(entity, dx * c + dy * s, -dx * s + dy * c, 0, 0);
const floats = new Float32Array(m0.HEAPU8.buffer, ptr, 2);
return { x: floats[0], y: floats[1] };
},
exportChunks(entity: number): string {
return moduleOf()?.tilemap_exportChunks?.(entity) ?? '';
},
importChunks(entity: number, encoded: string): boolean {
return moduleOf()?.tilemap_importChunks?.(entity, encoded) ?? false;
},
};
}
/** The tilemap toolkit's shape, however it was bound. */
export type TilemapToolkit = ReturnType<typeof tilemapAPI>;
/**
* The host/tooling seam: the editor's tile tools and tests reach the core that
* {@link initTilemapAPI} bound, where no App is in scope. Game code reads
* `Res(Tilemaps)`, which is its own app's.
*/
export const TilemapAPI: TilemapToolkit = tilemapAPI(() => module_);
/** @internal One toolkit per App, over that app's core. */
export function createTilemapAPI(engine: NonNullable<EngineApi>): TilemapToolkit {
const own = new TilemapBridge();
own.connect(engine);
const module = own.module as unknown as TilemapModule;
return tilemapAPI(() => module);
}
/**
* The canonical game-code accessor: `Res(Tilemaps)`, same shape as every other
* subsystem resource. The tilemap plugin inserts its app's own toolkit; the
* default is the host seam above, for a world with no tilemap plugin built.
*/
export const Tilemaps = defineResource<TilemapToolkit>(TilemapAPI, 'Tilemaps');