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): a map saved under another encoding is translated, not refused

esengineee29c2f66952
diff --git a/sdk/src/tilemap/chunkCodec.ts b/sdk/src/tilemap/chunkCodec.ts
index 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.ts
index 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.txt
new file mode 100644
index 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.cpp
index 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.hpp
index 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 esengine
diff --git a/tests/tilemap/test_tilemap.cpp b/tests/tilemap/test_tilemap.cpp
index 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.mjs
index 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 /},
},