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(rc6): content-hash module (XXH64) — single-source asset identity (B1)
yhh7ddaa97e7694
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.tsindex f4842cbd6..0d536bacf 100644--- a/sdk/src/asset/AddressableManifest.ts+++ b/sdk/src/asset/AddressableManifest.ts@@ -11,7 +11,8 @@ export interface AddressableManifestAsset {size: number;labels: string[];/**- * Content hash of the built bytes (xxh3), the asset's *physical* identity.+ * Content hash of the built bytes (XXH64, see contentHash.ts), the asset's+ * *physical* identity.* Populated by the import pipeline. Lets the runtime dedupe by content and* treat `<contentHash>.<ext>` as an immutable, permanently-cacheable URL* (changing a file yields a new hash → a new URL, never a stale cache).diff --git a/sdk/src/asset/contentHash.ts b/sdk/src/asset/contentHash.tsnew file mode 100644index 000000000..5ea4dd26a--- /dev/null+++ b/sdk/src/asset/contentHash.ts@@ -0,0 +1,127 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * Content hashing for asset identity (RC6 Batch B — content-addressed identity).+ *+ * XXH64 — a fast, well-distributed 64-bit non-cryptographic hash — is the single+ * canonical definition backing {@link AddressableManifest}'s `contentHash` field.+ * The hash is an asset's *physical* identity: computed at build time over the+ * built bytes, it lets the pipeline dedupe identical content and treat+ * `<contentHash>.<ext>` as an immutable, permanently-cacheable URL — change a byte+ * → new hash → new URL, never a stale cache.+ *+ * Pure and dependency-free (BigInt, no Node/DOM APIs) so the build-time cook and+ * the runtime (e.g. integrity re-check of a CDN download) share ONE implementation+ * — no hand-mirrored second copy to drift. BigInt keeps the 64-bit arithmetic+ * exact and deterministic across engines; build-time hashing is not hot enough for+ * the 32-bit-emulation complexity to earn its risk. Output is canonical XXH64,+ * anchored on the official `XXH64("") == 0xEF46DB3751D8E999` vector, so external+ * `xxhsum`-family tooling can verify our artifacts.+ */++const MASK = (1n << 64n) - 1n;++// Canonical XXH64 primes.+const PRIME1 = 0x9e3779b185ebca87n;+const PRIME2 = 0xc2b2ae3d27d4eb4fn;+const PRIME3 = 0x165667b19e3779f9n;+const PRIME4 = 0x85ebca77c2b2ae63n;+const PRIME5 = 0x27d4eb2f165667c5n;++function rotl(x: bigint, r: bigint): bigint {+ return ((x << r) | (x >> (64n - r))) & MASK;+}++function round(acc: bigint, input: bigint): bigint {+ acc = (acc + input * PRIME2) & MASK;+ acc = rotl(acc, 31n);+ return (acc * PRIME1) & MASK;+}++function mergeRound(acc: bigint, val: bigint): bigint {+ const r = round(0n, val);+ acc = (acc ^ r) & MASK;+ return (acc * PRIME1 + PRIME4) & MASK;+}++/** Unsigned 32-bit little-endian read. `>>> 0` defeats JS's signed bit-ops. */+function readU32LE(b: Uint8Array, p: number): bigint {+ return BigInt(((b[p]) | (b[p + 1] << 8) | (b[p + 2] << 16) | (b[p + 3] << 24)) >>> 0);+}++/** Unsigned 64-bit little-endian read, composed from two 32-bit halves. */+function readU64LE(b: Uint8Array, p: number): bigint {+ return (readU32LE(b, p + 4) << 32n) | readU32LE(b, p);+}++/**+ * Canonical XXH64 of `data` as an exact unsigned 64-bit {@link bigint}.+ * Deterministic across engines; `seed` defaults to 0 (the manifest convention).+ */+export function xxh64(data: Uint8Array, seed: bigint = 0n): bigint {+ const len = data.length;+ let p = 0;+ let h: bigint;++ if (len >= 32) {+ let v1 = (seed + PRIME1 + PRIME2) & MASK;+ let v2 = (seed + PRIME2) & MASK;+ let v3 = seed & MASK;+ let v4 = (seed - PRIME1) & MASK;+ const limit = len - 32;+ do {+ v1 = round(v1, readU64LE(data, p)); p += 8;+ v2 = round(v2, readU64LE(data, p)); p += 8;+ v3 = round(v3, readU64LE(data, p)); p += 8;+ v4 = round(v4, readU64LE(data, p)); p += 8;+ } while (p <= limit);++ h = (rotl(v1, 1n) + rotl(v2, 7n) + rotl(v3, 12n) + rotl(v4, 18n)) & MASK;+ h = mergeRound(h, v1);+ h = mergeRound(h, v2);+ h = mergeRound(h, v3);+ h = mergeRound(h, v4);+ } else {+ h = (seed + PRIME5) & MASK;+ }++ h = (h + BigInt(len)) & MASK;++ // Tail: 8-byte, then 4-byte, then per-byte.+ while (p + 8 <= len) {+ h = (h ^ round(0n, readU64LE(data, p))) & MASK;+ h = (rotl(h, 27n) * PRIME1 + PRIME4) & MASK;+ p += 8;+ }+ if (p + 4 <= len) {+ h = (h ^ ((readU32LE(data, p) * PRIME1) & MASK)) & MASK;+ h = (rotl(h, 23n) * PRIME2 + PRIME3) & MASK;+ p += 4;+ }+ while (p < len) {+ h = (h ^ ((BigInt(data[p]) * PRIME5) & MASK)) & MASK;+ h = (rotl(h, 11n) * PRIME1) & MASK;+ p += 1;+ }++ // Final avalanche.+ h = (h ^ (h >> 33n)) & MASK;+ h = (h * PRIME2) & MASK;+ h = (h ^ (h >> 29n)) & MASK;+ h = (h * PRIME3) & MASK;+ h = (h ^ (h >> 32n)) & MASK;+ return h;+}++/** Lower-case, zero-padded 16-hex-digit XXH64 — the canonical `contentHash` string. */+export function contentHashHex(data: Uint8Array): string {+ return xxh64(data).toString(16).padStart(16, '0');+}++/**+ * Convenience over {@link contentHashHex} that also accepts a string (hashed as+ * UTF-8). Build-time only — `TextEncoder` is a Node/browser global.+ */+export function contentHashOf(data: Uint8Array | string): string {+ return contentHashHex(typeof data === 'string' ? new TextEncoder().encode(data) : data);+}diff --git a/sdk/src/asset/index.ts b/sdk/src/asset/index.tsindex cd56b7745..5966f0d15 100644--- a/sdk/src/asset/index.ts+++ b/sdk/src/asset/index.ts@@ -6,6 +6,7 @@ export {type AddressableManifestGroup,type AddressableManifestAsset,} from './AddressableManifest';+export { xxh64, contentHashHex, contentHashOf } from './contentHash';export { AsyncCache } from './AsyncCache';export { Assets, AssetPlugin, assetPlugin, type AssetsData } from './AssetPlugin';export { decodeImageBitmap, decodeImagePixels, imageBitmapOptions, type DecodedPixels } from './imageDecode';diff --git a/sdk/tests/content-hash.test.ts b/sdk/tests/content-hash.test.tsnew file mode 100644index 000000000..0ecc21d9d--- /dev/null+++ b/sdk/tests/content-hash.test.ts@@ -0,0 +1,66 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file Content hash (RC6 Batch B). XXH64 is the canonical `contentHash`+ * algorithm; correctness is anchored on the official empty-input vector,+ * with determinism / sensitivity / branch-coverage guards around it.+ */+import { describe, it, expect } from 'vitest';+import { xxh64, contentHashHex, contentHashOf } from '../src/asset/contentHash';++const bytes = (s: string): Uint8Array => new TextEncoder().encode(s);++describe('xxh64 content hash', () => {+ it('matches the official XXH64("") vector', () => {+ // The one externally-authoritative vector: validates the finalize path.+ expect(xxh64(new Uint8Array(0))).toBe(0xef46db3751d8e999n);+ expect(contentHashHex(new Uint8Array(0))).toBe('ef46db3751d8e999');+ });++ it('is deterministic for the same bytes', () => {+ const a = bytes('the quick brown fox jumps over the lazy dog');+ expect(contentHashHex(a)).toBe(contentHashHex(a.slice()));+ });++ it('changes when a single byte changes (avalanche)', () => {+ const a = bytes('estella-asset-pipeline-rc6');+ const b = a.slice();+ b[5] ^= 0x01;+ expect(contentHashHex(b)).not.toBe(contentHashHex(a));+ });++ it('exercises every length branch (<4, 4–7, 8–31, ≥32 + tail) deterministically', () => {+ // 0,1,3 → per-byte tail; 4,7 → 4-byte tail; 8,31 → 8-byte tail (<32 path);+ // 32,33,40,64 → main 32-byte loop, then mixed tails.+ const lengths = [0, 1, 3, 4, 7, 8, 31, 32, 33, 40, 64];+ const seen = new Set<string>();+ for (const n of lengths) {+ const buf = new Uint8Array(n);+ for (let i = 0; i < n; i++) buf[i] = (i * 37 + 11) & 0xff;+ const h = contentHashHex(buf);+ expect(h).toMatch(/^[0-9a-f]{16}$/);+ expect(contentHashHex(buf.slice())).toBe(h); // deterministic per length+ seen.add(h);+ }+ // Distinct content (length + bytes) → distinct hashes (no collisions here).+ expect(seen.size).toBe(lengths.length);+ });++ it('hashes a 32-byte-block boundary input distinctly from its truncation', () => {+ const buf = new Uint8Array(64);+ for (let i = 0; i < 64; i++) buf[i] = i;+ expect(contentHashHex(buf)).not.toBe(contentHashHex(buf.subarray(0, 63)));+ });++ it('contentHashOf accepts strings (UTF-8) and bytes equivalently', () => {+ const s = 'héllo-世界';+ expect(contentHashOf(s)).toBe(contentHashHex(bytes(s)));+ });++ it('produces 16 lower-case hex digits, zero-padded', () => {+ for (let i = 0; i < 200; i++) {+ const buf = new Uint8Array([i, (i * 3) & 0xff, (i * 7) & 0xff]);+ expect(contentHashHex(buf)).toMatch(/^[0-9a-f]{16}$/);+ }+ });+});