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(renderer): readiness names what it readied, not how much
esengine2bcb63cbe1e5
diff --git a/bench/residency/readiness.mjs b/bench/residency/readiness.mjsindex 47a53de15..7f1cc413f 100644--- a/bench/residency/readiness.mjs+++ b/bench/residency/readiness.mjs@@ -176,9 +176,12 @@ function main() {console.log('\nreadiness coverage — the two facts the heavy cell never exercises\n');- for (const [name, options] of [['shadow', { shadows: true }],+ const runs = new Map();+ for (const [name, options] of [['plain', {}],+ ['shadow', { shadows: true }],['material', { material: true }]]) {const r = drive(name, options);+ runs.set(name, r);const doc = r.get('document');const live = r.get('entities');const docKeys = keySet(doc);@@ -199,7 +202,18 @@ function main() {check(live.compiles === 0,`${name}: and readying from the document left nothing for them to compile`,`${live.compiles} late compile(s)`);- if (name === 'shadow') {+ // The stamp, both halves: derived twice by different routes over the same+ // content, it has to name the same requirement set under the same epoch.+ check(doc.digestLo === live.digestLo && doc.digestHi === live.digestHi,+ `${name}: the requirement digest is the same from the document and the entities`,+ `${doc.digestHi.toString(16)}${doc.digestLo.toString(16)}`+ + ` against ${live.digestHi.toString(16)}${live.digestLo.toString(16)}`);+ check(doc.programEpoch === live.programEpoch,+ `${name}: and both were taken under the same program epoch`,+ `${doc.programEpoch} against ${live.programEpoch}`);+ if (name === 'plain') {+ // nothing fixture-specific: this one exists to be compared against.+ } else if (name === 'shadow') {check(docKeys.some((k) => (k & 16) !== 0),'shadow: the depth-pass variant is a requirement, not a possibility',`keys {${docKeys.join(', ')}} — bit 16 is depthOnly`);@@ -212,6 +226,23 @@ function main() {`${live.materialCompiles} late material compile(s)`);}}+ // The claim `keys` alone cannot make: same geometry, same stock variants, one+ // shaded by a material. A digest blind to that path would call the two+ // worlds identical and let a stamp from one vouch for the other.+ const plain = runs.get('plain').get('document');+ const shaded = runs.get('material').get('document');+ console.log('');+ check(plain.keysLo === shaded.keysLo && plain.keysHi === shaded.keysHi,+ 'the plain and material worlds need the SAME stock variants',+ `{${keySet(plain).join(', ')}} against {${keySet(shaded).join(', ')}}`);+ check(plain.materialAsks === 0 && shaded.materialAsks > 0,+ 'and differ only in the material-owned path',+ `${plain.materialAsks} against ${shaded.materialAsks} ask(s)`);+ check(plain.digestLo !== shaded.digestLo || plain.digestHi !== shaded.digestHi,+ 'so the digest must tell them apart — the stock key set cannot',+ `${plain.digestHi.toString(16)}${plain.digestLo.toString(16)}`+ + ` against ${shaded.digestHi.toString(16)}${shaded.digestLo.toString(16)}`);+console.log('');process.exit(failed === 0 ? 0 : 1);}diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex 05cfc7d63..b6c474926 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -141,14 +141,18 @@ async function boot(): Promise<void> {if (headless) {let statsOn = false;- /** Seven words out: five counts and the key SET, which is what an equality- * claim between two derivations needs. */+ const PREWARM_WORDS = 11;+ /** Eleven words out: five counts, the stock key SET, and the readiness stamp+ * — the digest over BOTH program paths, and the epoch it was taken under.+ * A digest alone cannot say whether it is still true. */const readPrewarm = (heap: Uint32Array, ptr: number): Record<string, number> => {- const o = heap.subarray(ptr >> 2, (ptr >> 2) + 7);+ const o = heap.subarray(ptr >> 2, (ptr >> 2) + PREWARM_WORDS);return {asks: o[0], compiles: o[1], uniqueKeys: o[2],materialAsks: o[3], materialCompiles: o[4],keysLo: o[5], keysHi: o[6],+ digestLo: o[7], digestHi: o[8],+ programEpoch: o[9] + o[10] * 0x100000000,};};@@ -171,7 +175,7 @@ async function boot(): Promise<void> {outPtr: number): void;};const entityPtr = m._malloc(entities.length * 4);- const outPtr = m._malloc(7 * 4);+ const outPtr = m._malloc(PREWARM_WORDS * 4);try {m.HEAPU32.set(entities, entityPtr >> 2);// Around the call ALONE: reading the counts back is this probe's cost,@@ -219,7 +223,7 @@ async function boot(): Promise<void> {engine_prewarmMeshVariantsFromDocument(rowsPtr: number, count: number, outPtr: number): void;};const rowsPtr = m._malloc(rows.length * 4);- const outPtr = m._malloc(7 * 4);+ const outPtr = m._malloc(PREWARM_WORDS * 4);try {m.HEAPU32.set(rows, rowsPtr >> 2);const began = performance.now();diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 3ae751f0c..8bf2cfe1b 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -822,8 +822,9 @@ std::string engine_getCpuScopes() {}#ifdef ES_ENABLE_TEST_PROBES-/** Seven words: five counts and the 64-bit key set, which is what an equality- * claim between two derivations needs. */+/** Eleven words: five counts, the 64-bit stock key set, the requirement digest+ * that also covers the material programs, and the epoch the digest was taken+ * under — a digest without its epoch cannot say whether it is still true. */static void writePrewarm(u32* out, const RenderPrewarmResult& r) {out[0] = r.asks;out[1] = r.compiles;@@ -832,11 +833,18 @@ static void writePrewarm(u32* out, const RenderPrewarmResult& r) {out[4] = r.materialCompiles;out[5] = static_cast<u32>(r.keys & 0xFFFFFFFFull);out[6] = static_cast<u32>(r.keys >> 32);+ const u64 digest = r.requirementDigest();+ out[7] = static_cast<u32>(digest & 0xFFFFFFFFull);+ out[8] = static_cast<u32>(digest >> 32);+ const auto* rc = ctx().tryGet<RenderContext>();+ const u64 epoch = rc ? rc->programEpoch() : 0;+ out[9] = static_cast<u32>(epoch & 0xFFFFFFFFull);+ out[10] = static_cast<u32>(epoch >> 32);}void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 count, u32 outPtr) {auto* out = reinterpret_cast<u32*>(static_cast<uintptr_t>(outPtr));- for (u32 i = 0; i < 7; ++i) out[i] = 0;+ for (u32 i = 0; i < 11; ++i) out[i] = 0;if (!g_initialized || !g_renderFrame) return;const auto* entities = reinterpret_cast<const Entity*>(static_cast<uintptr_t>(entitiesPtr));writePrewarm(out, g_renderFrame->prewarmPrograms(registry, entities, count));@@ -844,7 +852,7 @@ void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 covoid engine_prewarmMeshVariantsFromDocument(u32 rowsPtr, u32 count, u32 outPtr) {auto* out = reinterpret_cast<u32*>(static_cast<uintptr_t>(outPtr));- for (u32 i = 0; i < 7; ++i) out[i] = 0;+ for (u32 i = 0; i < 11; ++i) out[i] = 0;if (!g_initialized || !g_renderFrame) return;const auto* rows = reinterpret_cast<const MeshDocumentRecord*>(static_cast<uintptr_t>(rowsPtr));writePrewarm(out, g_renderFrame->prewarmDocument(rows, count));diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex 5e1217e18..3a456f04b 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -22,7 +22,9 @@#include <glm/gtc/quaternion.hpp>#include <cmath>+#include <algorithm>#include <unordered_set>+#include <vector>namespace esengine {@@ -142,6 +144,45 @@ struct RenderPrewarmResult {u32 materialCompiles = 0;/** Which keys, not how many: an equality claim needs the set. 64 variants. */u64 keys = 0;+ /** The material programs the content needs, by identity rather than count.+ * A material world whose shading changed must not digest the same as the+ * one before it, and `materialAsks` alone cannot say that. */+ std::vector<u64> materialKeys;++ /** @brief What a material program is asked for, as one comparable value. */+ static u64 materialKey(u32 materialId, bool normals, bool skinned, bool envMapped) {+ return (static_cast<u64>(materialId) << 3) | (normals ? 4u : 0u)+ | (skinned ? 2u : 0u) | (envMapped ? 1u : 0u);+ }++ void addMaterialKey(u64 key) {+ if (std::find(materialKeys.begin(), materialKeys.end(), key) == materialKeys.end()) {+ materialKeys.push_back(key);+ }+ }++ /**+ * @brief A stable name for the SET of program requirements described here.+ *+ * @details Order-independent and duplicate-insensitive, because the question+ * is which programs are needed and not how often each was asked+ * for. Two derivations of the same content therefore agree, and a+ * requirement arriving or leaving is what changes the answer.+ */+ u64 requirementDigest() const {+ std::vector<u64> sorted(materialKeys);+ std::sort(sorted.begin(), sorted.end());+ u64 h = 1469598103934665603ull; // FNV-1a offset basis+ auto mix = [&h](u64 v) {+ for (u32 b = 0; b < 8; ++b) {+ h ^= (v >> (b * 8)) & 0xFFull;+ h *= 1099511628211ull;+ }+ };+ mix(keys);+ for (u64 k : sorted) mix(k);+ return h;+ }RenderPrewarmResult& operator+=(const RenderPrewarmResult& other) {asks += other.asks;@@ -150,6 +191,9 @@ struct RenderPrewarmResult {materialAsks += other.materialAsks;materialCompiles += other.materialCompiles;keys |= other.keys;+ // A union, so combining two plugins' answers cannot depend on the order+ // they ran in — the digest above rests on that.+ for (u64 k : other.materialKeys) addMaterialKey(k);return *this;}};diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex 442eceb4e..86e2dc4e9 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -361,6 +361,8 @@ RenderPrewarmResult MeshPlugin::prewarmFacts(RenderFrameContext& ctx,// readiness look complete while a material-shaded world still hitched.if (facts[i].materialId != 0 && ctx.materials) {++out.materialAsks;+ out.addMaterialKey(RenderPrewarmResult::materialKey(+ facts[i].materialId, facts[i].hasNormals, facts[i].skinned, envMapped));ctx.materials->meshProgram(facts[i].materialId, ctx.resources, facts[i].hasNormals,facts[i].skinned, envMapped);}