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
/**
* @file chunkCodec.ts
* @brief Decode the `tilemap_exportChunks` blob 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 'TMAP' · u16 chunkSize, idMask, flipH, flipV, flipD, reserved
* · u32 chunkCount · per chunk: i32 x, i32 y, u16 tiles[chunkSize²]
* Empty chunks are omitted by the exporter.
*
* A saved map outlives the binary that wrote it, and the ABI hash only
* pairs a binary with a bundle. So the blob says which encoding it was
* written under and a reader whose own differs REFUSES: the same bytes
* would parse and mean other tiles. 'ESTM' is the older magic, which
* carries no header and means exactly the frozen `TILEMAP_V1_*` values.
*/
import {
CHUNK_SIZE, TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D,
TILEMAP_BLOB_MAGIC_V1, TILEMAP_BLOB_MAGIC_V2,
TILEMAP_V1_CHUNK_SIZE, TILEMAP_V1_ID_MASK,
TILEMAP_V1_FLIP_H, TILEMAP_V1_FLIP_V, TILEMAP_V1_FLIP_D,
} from '../wasm/constants.generated';
/**
* Tiles per chunk side, from the C++ `CHUNK_SIZE` that owns it. Generated, so
* this is not a second answer: a chunk decoded at the wrong side length reads a
* saved map into the wrong cells rather than failing to load.
*/
export { CHUNK_SIZE };
const CHUNK_TILES = CHUNK_SIZE * CHUNK_SIZE;
/** The chunk stride and cell split a blob has to have been written under. */
const RUNNING = [CHUNK_SIZE, TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D];
const V1 = [TILEMAP_V1_CHUNK_SIZE, TILEMAP_V1_ID_MASK,
TILEMAP_V1_FLIP_H, TILEMAP_V1_FLIP_V, TILEMAP_V1_FLIP_D];
const V2_HEADER_BYTES = 4 + 2 * 6 + 4;
const V1_HEADER_BYTES = 8;
/**
* One cell from one encoding into another: the id it holds and the three flags
* it carries, at the positions this reader uses. -1 where the id does not FIT a
* narrowed mask — the only honest answers there are the tile or a refusal.
* `from` is `[chunkSize, idMask, flipH, flipV, flipD]`.
*/
export function recodeCell(word: number, from: readonly number[]): number {
const id = word & from[1]!;
if (id > TILE_ID_MASK) return -1;
let next = id;
if (word & from[2]!) next |= TILE_FLIP_H;
if (word & from[3]!) next |= TILE_FLIP_V;
if (word & from[4]!) next |= TILE_FLIP_D;
return next;
}
/** Floor division and its remainder, so a chunk left of the origin lands where
* it belongs rather than rounding toward zero. */
const floorDiv = (a: number, b: number): number => Math.floor(a / b);
const floorMod = (a: number, b: number): number => ((a % b) + b) % b;
/** 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 < V1_HEADER_BYTES) return [];
const dv = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
const magic = dv.getUint32(0, true);
let wrote: number[];
let off: number;
if (magic === TILEMAP_BLOB_MAGIC_V2) {
if (bytes.byteLength < V2_HEADER_BYTES) return [];
wrote = [0, 1, 2, 3, 4].map((i) => dv.getUint16(4 + i * 2, true));
off = V2_HEADER_BYTES;
} else if (magic === TILEMAP_BLOB_MAGIC_V1) {
wrote = V1;
off = V1_HEADER_BYTES;
} else {
return [];
}
const side = wrote[0]!;
if (side <= 0) return [];
const count = dv.getUint32(off - 4, true);
// By WORLD coordinate, which means the same under any chunk size — one path
// whether the map was written under this encoding or an older one, so the
// case that runs every day is the one the migration is tested on.
const chunks = new Map<string, DecodedChunk>();
const perChunk = 8 + side * side * 2;
for (let c = 0; c < count; c++) {
if (off + perChunk > bytes.byteLength) break; // truncated → stop
const cx = dv.getInt32(off, true);
const cy = dv.getInt32(off + 4, true);
let at = off + 8;
for (let i = 0; i < side * side; i++, at += 2) {
const word = dv.getUint16(at, true);
if (word === 0) continue;
const cell = recodeCell(word, wrote);
if (cell < 0) return []; // a narrowed mask cannot carry this tile
const x = cx * side + (i % side);
const y = cy * side + Math.floor(i / side);
const kx = floorDiv(x, CHUNK_SIZE);
const ky = floorDiv(y, CHUNK_SIZE);
const key = `${kx},${ky}`;
let chunk = chunks.get(key);
if (!chunk) {
chunk = { x: kx, y: ky, tiles: new Uint16Array(CHUNK_TILES) };
chunks.set(key, chunk);
}
chunk.tiles[floorMod(y, CHUNK_SIZE) * CHUNK_SIZE + floorMod(x, CHUNK_SIZE)] = cell;
}
off += perChunk;
}
return [...chunks.values()];
}