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): a map saved under another encoding is translated, not refused
esengineee29c2f66952
diff --git a/sdk/src/tilemap/chunkCodec.ts b/sdk/src/tilemap/chunkCodec.tsindex 952df04de..db41ac897 100644--- a/sdk/src/tilemap/chunkCodec.ts+++ b/sdk/src/tilemap/chunkCodec.ts@@ -38,7 +38,25 @@ const V1 = [TILEMAP_V1_CHUNK_SIZE, TILEMAP_V1_ID_MASK,const V2_HEADER_BYTES = 4 + 2 * 6 + 4;const V1_HEADER_BYTES = 8;-const sameEncoding = (a: number[]): boolean => a.every((v, i) => v === RUNNING[i]);+/**+ * 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.+ */+function recodeCell(word: number, from: 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 {@@ -99,18 +117,38 @@ export function decodeTilemapChunks(blob: string): DecodedChunk[] {} else {return [];}- // Refused, not decoded: these bytes would parse into different tiles.- if (!sameEncoding(wrote)) return [];+ const side = wrote[0]!;+ if (side <= 0) return [];const count = dv.getUint32(off - 4, true);- 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 });++ // 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;+ return [...chunks.values()];}diff --git a/sdk/tests/chunk-blob.test.ts b/sdk/tests/chunk-blob.test.tsindex b456f67c1..b0f2b8a95 100644--- a/sdk/tests/chunk-blob.test.ts+++ b/sdk/tests/chunk-blob.test.ts@@ -1,19 +1,21 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team/**- * @file The saved form of a painted map, and what it says about its own+ * @file The saved form of a painted map, and reading one written under another* encoding.*- * A `.esscene` outlives the binary that wrote it, and the ABI layout hash only- * pairs a binary with a bundle. Widening the id mask by one bit leaves every- * byte where it was, so a map painted before it reads as different tiles with- * nothing failing anywhere — which is what these refuse.+ * A `.esscene` outlives the binary that wrote it, and the ABI layout hash pairs+ * a binary with a bundle only. Widening the id mask leaves every byte where it+ * was, so a map painted before it reads as different tiles with nothing failing+ * — and refusing it would break the promise that a MINOR opens what an older+ * one saved. So the blob says what it was written as and the reader migrates.*- * This is the reading half. The engine writes the blob and reads it back- * through the same header, which `tests/tilemap/test_tilemap.cpp` holds: the- * bindings abort headless, so there is no round trip to be had from here.+ * The engine's own reader is C++ and takes the same walk; `test_tilemap.cpp`+ * holds that half, since the bindings abort headless.*/import { describe, it, expect } from 'vitest';+import { readFileSync } from 'node:fs';+import { resolve } from 'node:path';import { decodeTilemapChunks, CHUNK_SIZE } from '../src/tilemap/chunkCodec';import {TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D,@@ -22,7 +24,7 @@ import {TILEMAP_V1_FLIP_H, TILEMAP_V1_FLIP_V, TILEMAP_V1_FLIP_D,} from '../src/wasm/constants.generated';-const TILES = CHUNK_SIZE * CHUNK_SIZE;+const HERE = __dirname;function toBase64Url(buf: ArrayBuffer): string {let bin = '';@@ -30,73 +32,105 @@ function toBase64Url(buf: ArrayBuffer): string {return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_');}-/** The older magic: chunks, and no word about how to read them. */-function v1Blob(tiles: Uint16Array, chunkSize = CHUNK_SIZE): string {- const per = 8 + chunkSize * chunkSize * 2;- const dv = new DataView(new ArrayBuffer(8 + per));- dv.setUint32(0, TILEMAP_BLOB_MAGIC_V1, true);- dv.setUint32(4, 1, true);- dv.setInt32(8, 3, true);- dv.setInt32(12, -2, true);- for (let i = 0; i < chunkSize * chunkSize; i++) dv.setUint16(16 + i * 2, tiles[i] ?? 0, true);- return toBase64Url(dv.buffer);-}--/** The versioned magic, written under whatever encoding is passed. */-function v2Blob(tiles: Uint16Array, enc: number[] = [CHUNK_SIZE, TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D]): string {+/** A blob under any encoding: `[side, idMask, flipH, flipV, flipD]`, and cells+ * by chunk coordinate and local index. */+function blob(enc: number[], chunks: { x: number; y: number; cells: [number, number, number][] }[],+ magic = TILEMAP_BLOB_MAGIC_V2): string {const side = enc[0]!;+ const head = magic === TILEMAP_BLOB_MAGIC_V2 ? 20 : 8;const per = 8 + side * side * 2;- const dv = new DataView(new ArrayBuffer(20 + per));- dv.setUint32(0, TILEMAP_BLOB_MAGIC_V2, true);- for (let i = 0; i < 5; i++) dv.setUint16(4 + i * 2, enc[i]!, true);- dv.setUint16(14, 0, true);- dv.setUint32(16, 1, true);- dv.setInt32(20, 3, true);- dv.setInt32(24, -2, true);- for (let i = 0; i < side * side; i++) dv.setUint16(28 + i * 2, tiles[i] ?? 0, true);+ const dv = new DataView(new ArrayBuffer(head + chunks.length * per));+ dv.setUint32(0, magic, true);+ if (magic === TILEMAP_BLOB_MAGIC_V2) {+ for (let i = 0; i < 5; i++) dv.setUint16(4 + i * 2, enc[i]!, true);+ dv.setUint16(14, 0, true);+ }+ dv.setUint32(head - 4, chunks.length, true);+ let off = head;+ for (const c of chunks) {+ dv.setInt32(off, c.x, true);+ dv.setInt32(off + 4, c.y, true);+ for (const [lx, ly, w] of c.cells) dv.setUint16(off + 8 + (ly * side + lx) * 2, w, true);+ off += per;+ }return toBase64Url(dv.buffer);}-function painted(): Uint16Array {- const tiles = new Uint16Array(TILES);- tiles[0] = 5;- tiles[CHUNK_SIZE + 1] = 7 | TILE_FLIP_H;- return tiles;+/** Every non-empty cell by WORLD coordinate, which is what survives a re-chunk. */+function world(decoded: ReturnType<typeof decodeTilemapChunks>): Map<string, number> {+ const out = new Map<string, number>();+ for (const c of decoded) {+ for (let i = 0; i < c.tiles.length; i++) {+ const w = c.tiles[i]!;+ if (w === 0) continue;+ out.set(`${c.x * CHUNK_SIZE + (i % CHUNK_SIZE)},${c.y * CHUNK_SIZE + Math.floor(i / CHUNK_SIZE)}`, w);+ }+ }+ return out;}-describe('a saved map says which encoding it was painted under', () => {- it('reads the older magic, which is every scene painted so far', () => {- const chunks = decodeTilemapChunks(v1Blob(painted()));- expect(chunks).toHaveLength(1);- expect(chunks[0]).toMatchObject({ x: 3, y: -2 });- expect([chunks[0]!.tiles[0], chunks[0]!.tiles[CHUNK_SIZE + 1]]).toEqual([5, 7 | TILE_FLIP_H]);+const RUNNING = [CHUNK_SIZE, TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D];++describe('a map saved before this engine', () => {+ /**+ * A real blob under the older magic, checked in: the maximum id, each flip+ * alone, all three together, an empty cell, and a chunk wholly in negative+ * space. This is the file the compatibility promise is about.+ */+ it('reads a checked-in v1 blob, cell for cell', () => {+ const golden = readFileSync(resolve(HERE, 'fixtures/tilemap-esscene-v1.blob.txt'), 'utf8').trim();+ expect(world(decodeTilemapChunks(golden))).toEqual(new Map([+ ['0,0', 1],+ ['1,0', TILE_ID_MASK],+ ['2,0', 5 | TILE_FLIP_H],+ ['3,0', 5 | TILE_FLIP_V],+ ['4,0', 5 | TILE_FLIP_D],+ ['5,0', 5 | TILE_FLIP_H | TILE_FLIP_V | TILE_FLIP_D],+ ['-1,-1', 7 | TILE_FLIP_H],+ ]));});- it('reads the versioned magic to the same chunks', () => {- expect(decodeTilemapChunks(v2Blob(painted()))).toEqual(decodeTilemapChunks(v1Blob(painted())));+ it('reads the versioned magic to the same cells', () => {+ const cells: [number, number, number][] = [[0, 0, 1], [2, 0, 5 | TILE_FLIP_H]];+ expect(world(decodeTilemapChunks(blob(RUNNING, [{ x: 0, y: 0, cells }]))))+ .toEqual(new Map([['0,0', 1], ['2,0', 5 | TILE_FLIP_H]]));});/**- * The bit that would be silent. A 14-bit id mask leaves every byte where it- * is: the same blob parses, and each cell that carried a flip flag becomes a- * different tile.+ * The change that would otherwise be silent, and the one the promise is+ * about: the flags sat in other bits, so every byte parses and every cell+ * means something else. Migrated, the tile and its flags come back.*/- it('refuses a map painted under a wider id mask', () => {- const wider = [CHUNK_SIZE, 0x3fff, 0x4000, 0x8000, 0x0000];- expect(decodeTilemapChunks(v2Blob(painted(), wider))).toEqual([]);+ it('migrates a map whose flags sat in other bits', () => {+ const permuted = [CHUNK_SIZE, 0x1fff, 0x8000, 0x2000, 0x4000];+ const cells: [number, number, number][] = [+ [0, 0, 9 | 0x8000], // its H+ [1, 0, 9 | 0x2000], // its V+ [2, 0, 9 | 0x4000], // its D+ [3, 0, 9 | 0x8000 | 0x2000 | 0x4000],+ ];+ expect(world(decodeTilemapChunks(blob(permuted, [{ x: 0, y: 0, cells }])))).toEqual(new Map([+ ['0,0', 9 | TILE_FLIP_H],+ ['1,0', 9 | TILE_FLIP_V],+ ['2,0', 9 | TILE_FLIP_D],+ ['3,0', 9 | TILE_FLIP_H | TILE_FLIP_V | TILE_FLIP_D],+ ]));});- /**- * A LARGER side on purpose: a smaller one runs the reader off the end and- * the truncation guard answers, so that version of this passes with the- * encoding check taken out. At 32 the reader has bytes enough to hand back- * 256 of them as a chunk.- */- it('refuses a map painted at another chunk size', () => {+ /** A stride is not a contract about the world: the same tiles land at the+ * same places, in this engine's chunks. */+ it('re-chunks a map saved at another stride', () => {const wide = [32, TILE_ID_MASK, TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D];- const tiles = new Uint16Array(32 * 32);- tiles[0] = 5;- expect(decodeTilemapChunks(v2Blob(tiles, wide))).toEqual([]);+ const cells: [number, number, number][] = [[0, 0, 3], [31, 31, 4], [17, 2, 5]];+ expect(world(decodeTilemapChunks(blob(wide, [{ x: 0, y: 0, cells }]))))+ .toEqual(new Map([['0,0', 3], ['31,31', 4], ['17,2', 5]]));+ });++ /** The one thing a migration cannot do: a narrower mask has nowhere to put+ * the tile, and putting SOME other tile there is the whole failure. */+ it('refuses a tile this encoding has no room for', () => {+ const wider = [CHUNK_SIZE, 0x3fff, 0x4000, 0x8000, 0x0000];+ expect(decodeTilemapChunks(blob(wider, [{ x: 0, y: 0, cells: [[0, 0, 0x2001]] }]))).toEqual([]);});it('refuses a blob that is not one of ours', () => {@@ -107,8 +141,8 @@ describe('a saved map says which encoding it was painted under', () => {/*** What the older magic MEANT, as literals. Re-pointing these at the live- * constants would make every map painted so far read as whatever the engine- * is now — the one failure this format cannot detect for itself.+ * constants would read every map painted so far as whatever the engine is+ * now — the one thing this format cannot detect for itself.*/it('remembers the older magic as history, not as configuration', () => {expect([TILEMAP_V1_CHUNK_SIZE, TILEMAP_V1_ID_MASK,@@ -116,4 +150,3 @@ describe('a saved map says which encoding it was painted under', () => {.toEqual([16, 0x1fff, 0x2000, 0x4000, 0x8000]);});});-diff --git a/sdk/tests/fixtures/tilemap-esscene-v1.blob.txt b/sdk/tests/fixtures/tilemap-esscene-v1.blob.txtnew file mode 100644index 000000000..40675c155--- /dev/null+++ b/sdk/tests/fixtures/tilemap-esscene-v1.blob.txt@@ -0,0 +1 @@+RVNUTQIAAAAAAAAAAAAAAAEA_x8FIAVABYAF4AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA__________8AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAHIA==diff --git a/src/esengine/bindings/TilemapBindings.cpp b/src/esengine/bindings/TilemapBindings.cppindex c5cb96eb1..b600cac52 100644--- a/src/esengine/bindings/TilemapBindings.cpp+++ b/src/esengine/bindings/TilemapBindings.cpp@@ -260,37 +260,43 @@ bool tilemap_importChunks(u32 entity, const std::string& encoded) {std::vector<u8> raw;if (!base64Decode(encoded, raw)) return false;- if (raw.size() < tilemap::BLOB_HEADER_V1_BYTES) return false;-- auto read = [&raw](usize offset, void* out, usize n) -> bool {- if (offset + n > raw.size()) return false;- std::memcpy(out, raw.data() + offset, n);- return true;- };tilemap::BlobHeader header{};if (!tilemap::parseBlobHeader(raw.data(), raw.size(), header)) return false;- const usize perChunk = sizeof(i32) * 2- + tilemap::CHUNK_SIZE * tilemap::CHUNK_SIZE * sizeof(u16);- if (raw.size() < header.payloadAt + static_cast<usize>(header.chunkCount) * perChunk) return false;+ // One path, migrating or not: a map written under this engine's own+ // encoding takes the same walk as one written under an older one, so the+ // case that runs every day is the case the migration is tested on.+ const tilemap::CellEncoding running = tilemap::runningEncoding();+ const i32 side = static_cast<i32>(tilemap::CHUNK_SIZE);+ tilemap::ChunkData* into = nullptr;+ tilemap::ChunkCoord at{ 0, 0 };+ bool first = true;+ bool lost = false;layer->chunks.clear();- usize cursor = header.payloadAt;- for (u32 i = 0; i < header.chunkCount; ++i) {- i32 cx = 0, cy = 0;- if (!read(cursor, &cx, sizeof(cx))) return false;- cursor += sizeof(cx);- if (!read(cursor, &cy, sizeof(cy))) return false;- cursor += sizeof(cy);-- tilemap::ChunkData chunk;- if (!read(cursor, chunk.tiles, sizeof(chunk.tiles))) return false;- cursor += sizeof(chunk.tiles);- chunk.revision = ++layer->edit_revision;- layer->chunks[tilemap::ChunkCoord{cx, cy}] = chunk;+ const bool walked = tilemap::walkBlobCells(raw.data(), raw.size(), header,+ [&](i32 x, i32 y, u16 word) {+ u16 cell = 0;+ // A narrowed id mask cannot carry the tile, and putting SOME other+ // tile there is the failure this whole header exists to stop.+ if (!tilemap::recodeCell(word, header.wrote, running, cell)) { lost = true; return; }+ const tilemap::ChunkCoord coord{ tilemap::floorDiv(x, side), tilemap::floorDiv(y, side) };+ // Cells arrive along a row, so the chunk they land in changes rarely.+ if (first || coord.x != at.x || coord.y != at.y) {+ auto& chunk = layer->chunks[coord];+ chunk.revision = ++layer->edit_revision;+ into = &chunk;+ at = coord;+ first = false;+ }+ into->tiles[static_cast<usize>(tilemap::floorMod(y, side)) * tilemap::CHUNK_SIZE+ + static_cast<usize>(tilemap::floorMod(x, side))] = cell;+ });+ if (!walked || lost) {+ layer->chunks.clear();+ return false;}-return true;}diff --git a/src/esengine/tilemap/ChunkBlob.hpp b/src/esengine/tilemap/ChunkBlob.hppindex c4803bb2b..542f87540 100644--- a/src/esengine/tilemap/ChunkBlob.hpp+++ b/src/esengine/tilemap/ChunkBlob.hpp@@ -76,10 +76,11 @@ inline CellEncoding v1Encoding() {inline constexpr usize BLOB_HEADER_V1_BYTES = sizeof(u32) * 2;inline constexpr usize BLOB_HEADER_V2_BYTES = sizeof(u32) + sizeof(u16) * 6 + sizeof(u32);-/** Where the chunks begin, and how many of them the header claims. */+/** Where the chunks begin, how many there are, and what they were written as. */struct BlobHeader {usize payloadAt;u32 chunkCount;+ CellEncoding wrote;};inline void appendBlobHeader(std::vector<u8>& out, u32 chunkCount) {@@ -95,33 +96,82 @@ inline void appendBlobHeader(std::vector<u8>& out, u32 chunkCount) {}/**- * The header, or a refusal. A blob written under another encoding parses- * perfectly and means other tiles, so it is refused rather than decoded — and- * the legacy magic carries no header at all, which is why it means v1 and not- * "whatever this engine is now".+ * The header and the encoding it was written under, or false where these bytes+ * are not one of ours. The legacy magic carries no header, which is why it+ * means the frozen v1 values and not "whatever this engine is now".*/inline bool parseBlobHeader(const u8* raw, usize size, BlobHeader& out) {if (size < BLOB_HEADER_V1_BYTES) return false;u32 magic = 0;std::memcpy(&magic, raw, sizeof(magic));- CellEncoding wrote{};if (magic == BLOB_MAGIC_V2) {if (size < BLOB_HEADER_V2_BYTES) return false;u16 fields[5] = {};std::memcpy(fields, raw + sizeof(u32), sizeof(fields));- wrote = { fields[0], fields[1], fields[2], fields[3], fields[4] };+ out.wrote = { fields[0], fields[1], fields[2], fields[3], fields[4] };out.payloadAt = BLOB_HEADER_V2_BYTES;} else if (magic == BLOB_MAGIC_V1) {- wrote = v1Encoding();+ out.wrote = v1Encoding();out.payloadAt = BLOB_HEADER_V1_BYTES;} else {return false;}- if (!(wrote == runningEncoding())) return false;+ if (out.wrote.chunkSize == 0) return false;std::memcpy(&out.chunkCount, raw + out.payloadAt - sizeof(u32), sizeof(out.chunkCount));return true;}+/**+ * One cell from one encoding into another: the id it holds and the three flags+ * it carries, at the positions the reader uses. False where the id does not+ * FIT — a narrowed mask cannot carry it, and the only honest answers there are+ * the tile or a refusal. Everything else is a rename of bit positions.+ */+inline bool recodeCell(u16 word, const CellEncoding& from, const CellEncoding& to, u16& out) {+ const u16 id = static_cast<u16>(word & from.idMask);+ if (id > to.idMask) return false;+ u16 next = id;+ if (word & from.flipH) next = static_cast<u16>(next | to.flipH);+ if (word & from.flipV) next = static_cast<u16>(next | to.flipV);+ if (word & from.flipD) next = static_cast<u16>(next | to.flipD);+ out = next;+ return true;+}++/**+ * Every non-empty cell the payload holds, by WORLD coordinate — the one thing+ * that means the same under any chunk size, so a map saved at one stride reads+ * back at another. `emit(x, y, word)` sees the word as it was written.+ */+template <class Fn>+inline bool walkBlobCells(const u8* raw, usize size, const BlobHeader& header, Fn&& emit) {+ const u32 side = header.wrote.chunkSize;+ const usize perChunk = sizeof(i32) * 2 + static_cast<usize>(side) * side * sizeof(u16);+ if (size < header.payloadAt + static_cast<usize>(header.chunkCount) * perChunk) return false;++ usize at = header.payloadAt;+ for (u32 c = 0; c < header.chunkCount; ++c) {+ i32 cx = 0, cy = 0;+ std::memcpy(&cx, raw + at, sizeof(cx));+ std::memcpy(&cy, raw + at + sizeof(i32), sizeof(cy));+ const u8* cells = raw + at + sizeof(i32) * 2;+ for (u32 i = 0; i < side * side; ++i) {+ u16 word = 0;+ std::memcpy(&word, cells + static_cast<usize>(i) * sizeof(u16), sizeof(word));+ if (word == EMPTY_TILE) continue;+ emit(static_cast<i32>(cx * static_cast<i32>(side) + static_cast<i32>(i % side)),+ static_cast<i32>(cy * static_cast<i32>(side) + static_cast<i32>(i / side)), word);+ }+ at += perChunk;+ }+ return true;+}++/** Floor division and its remainder, so a chunk left of the origin lands where+ * it belongs rather than rounding toward zero. */+inline i32 floorDiv(i32 a, i32 b) { return (a >= 0 ? a : a - (b - 1)) / b; }+inline i32 floorMod(i32 a, i32 b) { const i32 m = a % b; return m < 0 ? m + b : m; }+} // namespace tilemap} // namespace esenginediff --git a/tests/tilemap/test_tilemap.cpp b/tests/tilemap/test_tilemap.cppindex ccc19c908..93165ab3b 100644--- a/tests/tilemap/test_tilemap.cpp+++ b/tests/tilemap/test_tilemap.cpp@@ -5,6 +5,9 @@#include <esengine/tilemap/TileFlip.hpp>#include <esengine/tilemap/ChunkBlob.hpp>+#include <tuple>+#include <vector>+using namespace esengine;using namespace esengine::tilemap;@@ -436,9 +439,10 @@ TEST_CASE("tilemap_blob_header") {REQUIRE(parseBlobHeader(raw.data(), raw.size(), header));CHECK(header.chunkCount == 7);CHECK(header.payloadAt == BLOB_HEADER_V2_BYTES);+ CHECK(header.wrote == runningEncoding());}- SUBCASE("the older magic means the encoding it was written under, and still reads") {+ SUBCASE("the older magic means the encoding it was written under") {std::vector<u8> raw(BLOB_HEADER_V1_BYTES);const u32 count = 3;std::memcpy(raw.data(), &BLOB_MAGIC_V1, sizeof(u32));@@ -448,20 +452,7 @@ TEST_CASE("tilemap_blob_header") {REQUIRE(parseBlobHeader(raw.data(), raw.size(), header));CHECK(header.chunkCount == 3);CHECK(header.payloadAt == BLOB_HEADER_V1_BYTES);- // Which is only sound while the frozen values ARE the running ones.- CHECK(v1Encoding() == runningEncoding());- }-- // The bit that would otherwise be silent: a wider id mask leaves every byte- // where it is, so the blob parses and each flipped cell becomes another tile.- SUBCASE("a map painted under another encoding is refused, not decoded") {- std::vector<u8> raw;- appendBlobHeader(raw, 1);- u16 wider = 0x3FFF;- std::memcpy(raw.data() + sizeof(u32) + sizeof(u16), &wider, sizeof(wider));-- BlobHeader header{};- CHECK_FALSE(parseBlobHeader(raw.data(), raw.size(), header));+ CHECK(header.wrote == v1Encoding());}SUBCASE("a blob that is not one of ours, and one that stops mid-header") {@@ -478,3 +469,92 @@ TEST_CASE("tilemap_blob_header") {CHECK_FALSE(parseBlobHeader(cut.data(), cut.size(), header));}}++// A map outlives the binary that wrote it, and a MINOR has to open what an+// older one saved. The header says what the cells mean, so they are TRANSLATED+// rather than refused — the bits move, the tile and its flags do not.+TEST_CASE("tilemap_cell_migration") {+ const CellEncoding here = runningEncoding();++ SUBCASE("flags written in other bits come back in these") {+ const CellEncoding permuted{ 16, 0x1FFF, 0x8000, 0x2000, 0x4000 };+ u16 out = 0;+ REQUIRE(recodeCell(static_cast<u16>(9 | 0x8000), permuted, here, out));+ CHECK(out == static_cast<u16>(9 | TILE_FLIP_H));+ REQUIRE(recodeCell(static_cast<u16>(9 | 0x2000), permuted, here, out));+ CHECK(out == static_cast<u16>(9 | TILE_FLIP_V));+ REQUIRE(recodeCell(static_cast<u16>(9 | 0x8000 | 0x2000 | 0x4000), permuted, here, out));+ CHECK(out == static_cast<u16>(9 | TILE_FLIP_H | TILE_FLIP_V | TILE_FLIP_D));+ }++ SUBCASE("an identity migration leaves every cell alone") {+ u16 out = 0;+ const u16 cell = static_cast<u16>(TILE_ID_MASK | TILE_FLIP_V);+ REQUIRE(recodeCell(cell, here, here, out));+ CHECK(out == cell);+ }++ // The one thing a migration cannot do: putting SOME other tile there is the+ // failure the header exists to stop.+ SUBCASE("a tile with no room in this mask is refused, not truncated") {+ const CellEncoding wider{ 16, 0x3FFF, 0x4000, 0x8000, 0x0000 };+ u16 out = 0;+ CHECK_FALSE(recodeCell(0x2001, wider, here, out));+ CHECK(recodeCell(0x0FFF, wider, here, out));+ }+}++// A stride is not a contract about the world: cells are walked by the position+// they occupy, so a map saved at one chunk size reads back at another.+TEST_CASE("tilemap_blob_walk") {+ const u32 side = 32;+ const usize per = sizeof(i32) * 2 + static_cast<usize>(side) * side * sizeof(u16);+ std::vector<u8> raw(BLOB_HEADER_V2_BYTES + per, 0);+ const u32 magic = BLOB_MAGIC_V2;+ const u16 fields[6] = { static_cast<u16>(side), TILE_ID_MASK,+ TILE_FLIP_H, TILE_FLIP_V, TILE_FLIP_D, 0 };+ const u32 count = 1;+ std::memcpy(raw.data(), &magic, sizeof(magic));+ std::memcpy(raw.data() + sizeof(u32), fields, sizeof(fields));+ std::memcpy(raw.data() + BLOB_HEADER_V2_BYTES - sizeof(u32), &count, sizeof(count));++ const i32 cx = -1, cy = 2;+ u8* chunk = raw.data() + BLOB_HEADER_V2_BYTES;+ std::memcpy(chunk, &cx, sizeof(cx));+ std::memcpy(chunk + sizeof(i32), &cy, sizeof(cy));+ const u16 corner = 3;+ const u16 far = static_cast<u16>(4 | TILE_FLIP_D);+ std::memcpy(chunk + sizeof(i32) * 2, &corner, sizeof(corner)); // local (0,0)+ std::memcpy(chunk + sizeof(i32) * 2 + (31 * side + 31) * sizeof(u16), &far, sizeof(far));++ BlobHeader header{};+ REQUIRE(parseBlobHeader(raw.data(), raw.size(), header));+ CHECK(header.wrote.chunkSize == side);++ std::vector<std::tuple<i32, i32, u16>> seen;+ REQUIRE(walkBlobCells(raw.data(), raw.size(), header,+ [&](i32 x, i32 y, u16 w) { seen.emplace_back(x, y, w); }));+ REQUIRE(seen.size() == 2);+ // World, not local: the chunk left of the origin starts at -32.+ CHECK(std::get<0>(seen[0]) == -32);+ CHECK(std::get<1>(seen[0]) == 64);+ CHECK(std::get<2>(seen[0]) == corner);+ CHECK(std::get<0>(seen[1]) == -1);+ CHECK(std::get<1>(seen[1]) == 95);+ CHECK(std::get<2>(seen[1]) == far);++ SUBCASE("and a payload that stops short is refused rather than read past") {+ std::vector<u8> cut(raw.begin(), raw.end() - 4);+ CHECK_FALSE(walkBlobCells(cut.data(), cut.size(), header, [](i32, i32, u16) {}));+ }+}++TEST_CASE("tilemap_chunk_floor") {+ // A chunk left of the origin belongs to -1, not to 0: rounding toward zero+ // puts two different columns in one chunk and loses one of them.+ CHECK(floorDiv(-1, 16) == -1);+ CHECK(floorDiv(-16, 16) == -1);+ CHECK(floorDiv(-17, 16) == -2);+ CHECK(floorMod(-1, 16) == 15);+ CHECK(floorMod(-16, 16) == 0);+}diff --git a/tools/lib/contractFacts.mjs b/tools/lib/contractFacts.mjsindex 8ceee4cab..e535bec8f 100644--- a/tools/lib/contractFacts.mjs+++ b/tools/lib/contractFacts.mjs@@ -204,18 +204,23 @@ export const FACTS = [},{id: 'tilemapBlobFormat',- what: 'The saved form of a painted map, and the cell encoding it says it was painted under.',+ what: 'The saved form of a painted map, the cell encoding it was written under, and how one'+ + ' written under another is read.',surface: 'project-asset-format',// A saved map outlives both halves the ABI hash pairs, so it carries the- // encoding it was painted under and a reader whose own differs refuses- // it. The frozen `V1_*` values are what the older magic MEANT.+ // encoding it was painted under and a reader whose own differs+ // TRANSLATES it — a MINOR opens what an older one saved. The frozen+ // `V1_*` values are what the older magic MEANT.authors: [{ path: 'src/esengine/tilemap/ChunkBlob.hpp', probe: /BLOB_MAGIC_V2/, kind: 'semantic' },],projections: ['sdk/src/wasm/constants.generated.ts'],verification: [- { path: 'tests/tilemap/test_tilemap.cpp', how: 'test', probe: /tilemap_blob_header/ },- { path: 'sdk/tests/chunk-blob.test.ts', how: 'test', probe: /refuses a map painted/ },+ { path: 'tests/tilemap/test_tilemap.cpp', how: 'test', probe: /tilemap_cell_migration/ },+ { path: 'sdk/tests/chunk-blob.test.ts', how: 'test', probe: /migrates a map whose flags/ },+ // The corpus the promise is actually about: a blob written before+ // any of this, decoded cell for cell.+ { path: 'sdk/tests/chunk-blob.test.ts', how: 'test', probe: /checked-in v1 blob/ },],digest: { name: 'eht-abi-layout-hash', path: 'tools/eht/constants.py', probe: /CONST /},},