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(renderer): readiness names what it readied, not how much

esengine2bcb63cbe1e5
diff --git a/bench/residency/readiness.mjs b/bench/residency/readiness.mjs
index 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.ts
index 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.cpp
index 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 co
void 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.hpp
index 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.cpp
index 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);
}