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(rc6): content-hash module (XXH64) — single-source asset identity (B1)

yhh7ddaa97e7694
diff --git a/sdk/src/asset/AddressableManifest.ts b/sdk/src/asset/AddressableManifest.ts
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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}$/);
+ }
+ });
+});