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): a prepared cell knows which shader variants it will need, before it has entities
esengine730ae73d43d7
diff --git a/bench/residency/heavy.mjs b/bench/residency/heavy.mjsindex d338d7036..690c8e47c 100755--- a/bench/residency/heavy.mjs+++ b/bench/residency/heavy.mjs@@ -222,6 +222,13 @@ function main() {// bookkeeping shows in the first, first visibility in the second.['blind', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },profile('published', 'Digit1'), profile('revealed', 'Digit4')]],+ // Does a PREPARED cell know what a published one needs? Both derivations+ // run on the same cell and their key SETS are compared — a count that+ // matched by luck would not be an equivalence.+ ['equivalence', [{ do: 'step', frames: 30 }, { do: 'tap', key: 'Digit3', frames: 10 },+ profile('published', 'Digit1'),+ { do: 'prewarm', as: 'document', cell: CELL_NAME, from: 'document' },+ { do: 'prewarm', as: 'entities', cell: CELL_NAME }]],// The same walk, with the programs readied while the camera is still// away. If first visibility then costs what a warm frame costs, the// hitch was the compile and readying it early is where it belongs.@@ -229,6 +236,13 @@ function main() {profile('published', 'Digit1'),{ do: 'prewarm', as: 'ready', cell: CELL_NAME },profile('revealed', 'Digit4')]],+ // The real shape: readied while the cell is only PREPARED, from its own+ // document, before a single entity of it exists. Then demanded, which on+ // this path publishes and becomes visible in the same frame.+ ['readied', [{ do: 'step', frames: 30 },+ { do: 'arrive', as: 'primed', key: 'Digit2' },+ { do: 'prewarm', as: 'ready', cell: CELL_NAME, from: 'document' },+ profile('arrival', 'Digit1')]],];for (const [arm, steps] of arms) {@@ -236,12 +250,26 @@ function main() {for (const [as, { frames, delivery }] of runs) {report(`${arm}${runs.size > 1 ? `/${as}` : ''}`, frames, delivery);}- const ready = prewarmed.get(arm);- if (ready) {- console.log(`\n readying ${arm}'s programs early took ${ready.ms.toFixed(2)} ms`+ for (const [as, ready] of prewarmed.get(arm) ?? []) {+ console.log(`\n readying ${arm}/${as} took ${ready.ms.toFixed(2)} ms`+ ` — ${ready.compiles} compile(s) of ${ready.uniqueKeys} unique key(s)`- + ` over ${ready.asks} ask(s) for ${ready.entities} entit(ies);`- + ` ${ready.materialCompiles} material compile(s) of ${ready.materialAsks} ask(s)`);+ + ` over ${ready.asks} ask(s) for ${ready.entities} renderable(s);`+ + ` ${ready.materialCompiles} material compile(s) of ${ready.materialAsks} ask(s)`+ + ` keys ${keySet(ready)}`);+ }+ const both = prewarmed.get(arm);+ if (both?.has('document') && both.has('entities')) {+ const doc = both.get('document');+ const live = both.get('entities');+ const same = doc.keysLo === live.keysLo && doc.keysHi === live.keysHi;+ failedTotal += same ? 0 : 1;+ console.log(`\n ${same ? '✓' : '✗'} what a PREPARED cell knows it will need equals`+ + ` what its published entities ask for`+ + ` — ${keySet(doc)} from the document, ${keySet(live)} from the world`);+ const materials = doc.materialAsks === live.materialAsks;+ failedTotal += materials ? 0 : 1;+ console.log(` ${materials ? '✓' : '✗'} and the material-owned path is enumerated the`+ + ` same both ways — ${doc.materialAsks} against ${live.materialAsks} ask(s)`);}}console.log('');@@ -269,7 +297,10 @@ function drive(out, name, steps) {for (const line of (run.stdout || '').split('\n')) {const ready = /^prewarm ([^:]+): (.*)$/.exec(line);if (ready) {- try { prewarmed.set(name, JSON.parse(ready[2])); } catch { /* partial */ }+ try {+ if (!prewarmed.has(name)) prewarmed.set(name, new Map());+ prewarmed.get(name).set(ready[1], JSON.parse(ready[2]));+ } catch { /* partial */ }continue;}const match = /^(profile|delivery) ([^:]+): /.exec(line);@@ -293,6 +324,16 @@ function drive(out, name, steps) {return runs;}+/**+ * What may be left unnamed before an instrument is not closed.+ *+ * PER FRAME for the frame accounting, because the residual IS the per-frame cost+ * outside every system accumulated over the window — a fixed budget would pass a+ * short window and fail a long one for the same engine.+ */+const RESIDUAL_MS = 0.6;+const RESIDUAL_MS_PER_FRAME = 0.15;+function report(arm, frames, delivery) {console.log(`\n${'='.repeat(78)}\nheavy cell, ${arm.toUpperCase()} — `@@ -372,13 +413,16 @@ function report(arm, frames, delivery) {console.log(' What demand pays whatever prefetch did, and it is NOT all of what demand pays:');printTree(half(false), ' ');const published = sum(half(false));- const witness = arm === 'hit'+ // Decided by the STREAMER's verdict, not the arm's name: a hit publishes+ // inside the frame that asked, so wall time there spans the whole frame.+ // Keying it on the arm made a third hitting arm read the wrong clock.+ const witness = v.outcome === 'hit'? { ms: sceneExcess, what: "the frame profiler's `scene` domain" }: { ms: v.publishMs, what: 'publish → resident wall time' };console.log(` ${'= accounted'.padEnd(22)}${published.toFixed(2).padStart(7)} ms`);console.log(` ${'against'.padEnd(22)}${witness.ms.toFixed(2).padStart(7)} ms`+ ` from ${witness.what} (${pct(published, witness.ms)})`);- if (arm === 'hit') {+ if (v.outcome === 'hit') {console.log(` ${'(publish → resident'.padEnd(22)}${v.publishMs.toFixed(2).padStart(7)} ms`+ ` wall, which on a hit spans the whole frame — not the transaction.)`);}@@ -402,9 +446,10 @@ function report(arm, frames, delivery) {+ `parent, ${deepest.name} — reported, not a criterion: sub-phases partition their `+ `parent by construction.)`);}- check(prepared >= v.prepareMs * 0.95,+ check(v.prepareMs - prepared <= RESIDUAL_MS,'and so is the preparation prefetch hides',- `${pct(prepared, v.prepareMs)} of ${v.prepareMs.toFixed(2)} ms accounted`);+ `${(v.prepareMs - prepared).toFixed(2)} ms unnamed of ${v.prepareMs.toFixed(2)} ms `+ + `(${pct(prepared, v.prepareMs)})`);}console.log(`\n realization — ECS-visible → actually drawn. Steady state ${baseline.toFixed(2)} ms/frame, `@@ -455,12 +500,17 @@ function report(arm, frames, delivery) {realization(window, frames[arrivalAt]);console.log('');- check(window.length > 0 && systemExcess >= wallExcess * 0.95,- 'and what the arrival ADDS to those frames is explained by the systems that ran',- `${pct(systemExcess, wallExcess)} of ${wallExcess.toFixed(2)} ms of excess over `- + `${window.length} frames (raw: ${pct(accounted, wall)} of ${wall.toFixed(2)} ms, `- + `which carries ${((baseline - baselineSystems) * window.length).toFixed(2)} ms of `- + `per-frame overhead outside every system)`);+ // The RESIDUAL, not the ratio: at an excess of 2.7 ms the same 0.2 ms of+ // per-frame overhead reads as 93%, so a ratio would measure how cheap the+ // arrival was. A truncated breakdown still fails this, leaving 3.6 ms.+ const residual = wallExcess - systemExcess;+ if (arrived) {+ check(residual <= RESIDUAL_MS_PER_FRAME * window.length,+ 'and what the arrival ADDS to those frames is explained by the systems that ran',+ `${residual.toFixed(2)} ms unnamed of ${wallExcess.toFixed(2)} ms of excess over `+ + `${window.length} frames, against ${(RESIDUAL_MS_PER_FRAME * window.length).toFixed(2)}`+ + ` ms of known per-frame overhead (${pct(systemExcess, wallExcess)})`);+ }const first = Object.values(delivery ?? {})[0];const publicationCost = first@@ -482,11 +532,13 @@ function report(arm, frames, delivery) {const HEADROOM = 1000 / 60 / 2;const spike = firstVisibleFrameCost - baseline;const fits = spike <= HEADROOM;- console.log(` ${fits ? '✓' : '✗'} BUDGET — a heavy arrival leaves the game its half of the frame`- + ` — ${spike.toFixed(2)} ms of arrival work against ${HEADROOM.toFixed(2)} ms of headroom`);- if (!fits) failed++;+ console.log('');+ // Through `check`: this verdict was incrementing a tally the exit code does+ // not read, so a run that printed the violation still exited 0.+ check(fits, 'BUDGET — a heavy arrival leaves the game its half of the frame',+ `${spike.toFixed(2)} ms of arrival work against ${HEADROOM.toFixed(2)} ms of headroom`);- void failed;+ void failed; // every verdict goes through `check`const spikes = frames.map((f, i) => ({ i, f })).filter(({ f }) => f.ms > baseline + 4).sort((a, b) => b.f.ms - a.f.ms).slice(0, 6);@@ -659,6 +711,16 @@ function realization(window, arrival) {}}+/** The variant keys a prewarm derived, as a set a reader can compare by eye. */+function keySet(r) {+ const keys = [];+ for (let i = 0; i < 32; i++) {+ if (r.keysLo & (1 << i)) keys.push(i);+ if (r.keysHi & (1 << i)) keys.push(i + 32);+ }+ return `{${keys.join(', ')}}`;+}+/** What one frame cost, by the domain that owns each system. */function byDomain(frame) {return new Map(Object.entries(frame.domains ?? {}));diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.tsindex ee5eb3b3d..05cfc7d63 100644--- a/pipeline/src/runtime/gameHost.ts+++ b/pipeline/src/runtime/gameHost.ts@@ -141,6 +141,17 @@ 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 readPrewarm = (heap: Uint32Array, ptr: number): Record<string, number> => {+ const o = heap.subarray(ptr >> 2, (ptr >> 2) + 7);+ return {+ asks: o[0], compiles: o[1], uniqueKeys: o[2],+ materialAsks: o[3], materialCompiles: o[4],+ keysLo: o[5], keysHi: o[6],+ };+ };+/*** Ready the shader programs a resident cell's meshes will be asked for,* drawing none of them. Attached only where the engine answers it.@@ -160,7 +171,7 @@ async function boot(): Promise<void> {outPtr: number): void;};const entityPtr = m._malloc(entities.length * 4);- const outPtr = m._malloc(5 * 4);+ const outPtr = m._malloc(7 * 4);try {m.HEAPU32.set(entities, entityPtr >> 2);// Around the call ALONE: reading the counts back is this probe's cost,@@ -169,18 +180,58 @@ async function boot(): Promise<void> {m.engine_prewarmMeshVariants(app.world.getCppRegistry(), entityPtr, entities.length,outPtr);const ms = performance.now() - began;- const out = m.HEAPU32.subarray(outPtr >> 2, (outPtr >> 2) + 5);- return {- ms, entities: entities.length,- asks: out[0], compiles: out[1], uniqueKeys: out[2],- materialAsks: out[3], materialCompiles: out[4],- };+ return { ms, entities: entities.length, ...readPrewarm(m.HEAPU32, outPtr) };} finally {m._free(entityPtr);m._free(outPtr);}};+ /**+ * The same readiness from the cell's DOCUMENT and the assets its preparation+ * decoded — no entity is consulted. Whether those facts SUFFICE is a claim+ * about the two derivations being equal, not about this call succeeding.+ */+ const prewarmMeshVariantsFromDocument = async (cell: string): Promise<Record<string, number>> => {+ const found = worlds.flatMap((w) => w.cells).find((c) => c.name === cell);+ if (!found) throw new Error(`[estella] no cooked cell "${cell}"`);+ const doc = (await (await fetch(`./${found.path}`)).json()) as SceneData;+ const assets = app.getResource(Assets);+ // The same channel preparation loads through, so the handles are the ones+ // it already acquired rather than a second decode.+ const resolved = await assets.preloadSceneAssets(doc);+ assets.resolveSceneAssetPaths(doc, resolved);+ const rows: number[] = [];+ for (const entity of doc.entities) {+ const parts = (entity as { components?: Array<{ type: string; data: Record<string, unknown> }> }).components;+ const renderer = parts?.find((c) => c.type === 'MeshRenderer');+ if (!renderer) continue;+ const skin = parts?.find((c) => c.type === 'MeshSkin');+ const joints = (skin?.data.joints as unknown[] | undefined)?.length ?? 0;+ rows.push(Number(renderer.data.mesh) || 0, renderer.data.lit ? 1 : 0,+ Number(renderer.data.normalMap) || 0, joints,+ Number(renderer.data.material) || 0);+ }+ const m = module as unknown as {+ _malloc(n: number): number;+ _free(p: number): void;+ HEAPU32: Uint32Array;+ engine_prewarmMeshVariantsFromDocument(rowsPtr: number, count: number, outPtr: number): void;+ };+ const rowsPtr = m._malloc(rows.length * 4);+ const outPtr = m._malloc(7 * 4);+ try {+ m.HEAPU32.set(rows, rowsPtr >> 2);+ const began = performance.now();+ m.engine_prewarmMeshVariantsFromDocument(rowsPtr, rows.length / 5, outPtr);+ const ms = performance.now() - began;+ return { ms, entities: rows.length / 5, ...readPrewarm(m.HEAPU32, outPtr) };+ } finally {+ m._free(rowsPtr);+ m._free(outPtr);+ }+ };+const cooked: Record<string, unknown> = {capture(): { width: number; height: number; rgba: Uint8Array } {const w = canvas.width, h = canvas.height;@@ -581,6 +632,7 @@ async function boot(): Promise<void> {if (typeof (module as unknown as Record<string, unknown>).engine_prewarmMeshVariants=== 'function') {cooked.prewarmMeshVariants = prewarmMeshVariants;+ cooked.prewarmMeshVariantsFromDocument = prewarmMeshVariantsFromDocument;}(window as unknown as { __estellaCooked?: unknown }).__estellaCooked = cooked;}diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cppindex 83ff6df8b..edee200ca 100644--- a/src/esengine/bindings/RendererBindings.cpp+++ b/src/esengine/bindings/RendererBindings.cpp@@ -739,17 +739,32 @@ std::string engine_getCpuScopes() {}#ifdef ES_ENABLE_TEST_PROBES-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 < 5; ++i) out[i] = 0;- if (!g_initialized || !g_renderFrame) return;- const auto* entities = reinterpret_cast<const Entity*>(static_cast<uintptr_t>(entitiesPtr));- const RenderPrewarmResult r = g_renderFrame->prewarmPrograms(registry, entities, count);+/** Seven words: five counts and the 64-bit key set, which is what an equality+ * claim between two derivations needs. */+static void writePrewarm(u32* out, const RenderPrewarmResult& r) {out[0] = r.asks;out[1] = r.compiles;out[2] = r.uniqueKeys;out[3] = r.materialAsks;out[4] = r.materialCompiles;+ out[5] = static_cast<u32>(r.keys & 0xFFFFFFFFull);+ out[6] = static_cast<u32>(r.keys >> 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;+ 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));+}++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;+ 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));}#endifdiff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hppindex a9411f536..5c89be248 100644--- a/src/esengine/bindings/RendererBindings.hpp+++ b/src/esengine/bindings/RendererBindings.hpp@@ -147,6 +147,10 @@ std::string engine_getCpuScopes();* to @p outPtr; JSON here would put an allocation inside the measurement.*/void engine_prewarmMeshVariants(ecs::Registry& registry, u32 entitiesPtr, u32 count, u32 outPtr);++/** @brief The same, from a prepared cell's own description — five words per+ * renderable at @p rowsPtr, and no entity of it need exist. */+void engine_prewarmMeshVariantsFromDocument(u32 rowsPtr, u32 count, u32 outPtr);#endifstd::string engine_getCounters();std::string engine_getGpuScopes();diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 8670a3d5f..f0a11056c 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -720,6 +720,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("engine_getCpuScopes", &esengine::engine_getCpuScopes);#ifdef ES_ENABLE_TEST_PROBESemscripten::function("engine_prewarmMeshVariants", &esengine::engine_prewarmMeshVariants);+ emscripten::function("engine_prewarmMeshVariantsFromDocument",+ &esengine::engine_prewarmMeshVariantsFromDocument);#endifemscripten::function("engine_getCounters", &esengine::engine_getCounters);emscripten::function("engine_getGpuScopes", &esengine::engine_getGpuScopes);diff --git a/src/esengine/renderer/RenderTypePlugin.hpp b/src/esengine/renderer/RenderTypePlugin.hppindex 7c9c0dc32..5e1217e18 100644--- a/src/esengine/renderer/RenderTypePlugin.hpp+++ b/src/esengine/renderer/RenderTypePlugin.hpp@@ -105,6 +105,32 @@ inline CameraView computeCameraView(const glm::mat4& viewProjection) {return view;}+/**+ * @brief What a renderable's program key is made of, with no say in where the+ * facts came from — a live entity's components, or a PREPARED cell's+ * document. One combination, so the two can be shown to agree.+ */+/**+ * @brief One renderable as a PREPARED cell knows it: document fields plus the+ * handles its preparation decoded. Five words, so the boundary that+ * carries it needs no encoding.+ */+struct MeshDocumentRecord {+ u32 meshHandle = 0;+ u32 lit = 0;+ u32 normalMapHandle = 0;+ u32 jointCount = 0;+ u32 materialId = 0;+};++struct MeshProgramFacts {+ bool hasNormals = false;+ bool lit = false;+ u32 normalTextureId = 0;+ bool skinned = false;+ u32 materialId = 0;+};+/** @brief What readying a set of renderables' programs found. Counts, not JSON:* this crosses no boundary and pays for no encoding. */struct RenderPrewarmResult {@@ -114,6 +140,8 @@ struct RenderPrewarmResult {u32 uniqueKeys = 0;u32 materialAsks = 0;u32 materialCompiles = 0;+ /** Which keys, not how many: an equality claim needs the set. 64 variants. */+ u64 keys = 0;RenderPrewarmResult& operator+=(const RenderPrewarmResult& other) {asks += other.asks;@@ -121,6 +149,7 @@ struct RenderPrewarmResult {uniqueKeys += other.uniqueKeys;materialAsks += other.materialAsks;materialCompiles += other.materialCompiles;+ keys |= other.keys;return *this;}};@@ -327,6 +356,20 @@ public:return {};}+ /**+ * @brief The same readiness, asked of a PREPARED cell's own description.+ *+ * @details The second fact source. What it derives must equal what `prewarm`+ * derives from the live entities, which is a claim a criterion holds+ * rather than a comment.+ */+ virtual RenderPrewarmResult prewarmDocument(RenderFrameContext& ctx,+ const MeshDocumentRecord* rows, u32 count,+ bool shadowPasses) {+ (void)ctx; (void)rows; (void)count; (void)shadowPasses;+ return {};+ }+/*** @brief What this plugin's collect is called in a frame profile.*diff --git a/src/esengine/renderer/frame/RenderFrame.cpp b/src/esengine/renderer/frame/RenderFrame.cppindex 6d2a7a006..665607fb3 100644--- a/src/esengine/renderer/frame/RenderFrame.cpp+++ b/src/esengine/renderer/frame/RenderFrame.cpp@@ -1590,6 +1590,14 @@ RenderPrewarmResult RenderFrame::prewarmPrograms(ecs::Registry& registry,return out;}+RenderPrewarmResult RenderFrame::prewarmDocument(const MeshDocumentRecord* rows, u32 count) {+ auto ctx = makeContext();+ const bool shadowPasses = !shadow_casters_.empty();+ RenderPrewarmResult out;+ for (auto& plugin : plugins_) out += plugin->prewarmDocument(ctx, rows, count, shadowPasses);+ return out;+}+void RenderFrame::collectAll(ecs::Registry& registry) {ES_PROFILE_SCOPE("render.collect");// Split because "collect is expensive" names no mechanism: planning shadows,diff --git a/src/esengine/renderer/frame/RenderFrame.hpp b/src/esengine/renderer/frame/RenderFrame.hppindex 2c747fa58..33eb1a06a 100644--- a/src/esengine/renderer/frame/RenderFrame.hpp+++ b/src/esengine/renderer/frame/RenderFrame.hpp@@ -414,6 +414,10 @@ public:* WASM adapter that lets a driver call it from outside.*/RenderPrewarmResult prewarmPrograms(ecs::Registry& registry, const Entity* entities, u32 count);++ /** @brief The same readiness, from a prepared cell's own description — no+ * entity of it need exist. */+ RenderPrewarmResult prewarmDocument(const MeshDocumentRecord* rows, u32 count);void collectAll(ecs::Registry& registry);/**diff --git a/src/esengine/renderer/plugins/MeshPlugin.cpp b/src/esengine/renderer/plugins/MeshPlugin.cppindex a7949be7b..4a33bfa50 100644--- a/src/esengine/renderer/plugins/MeshPlugin.cpp+++ b/src/esengine/renderer/plugins/MeshPlugin.cpp@@ -46,27 +46,53 @@ u32 mulColor(u32 a, u32 b) {*//*** @brief How many joints this entity would be posed by; 0 when it draws unskinned.+ * Separated from posing: the key needs the ANSWER, not the matrices, and a+ * re-derived one would disagree with the predicate that draws.+ */+/**+ * @brief Whether a mesh posed by @p joints joints draws skinned.*- * @details Separated from posing because the variant key needs the ANSWER and not- * the matrices: a caller that re-derived "is this skinned" would be a- * second predicate free to disagree with the one that draws.+ * @details Takes the joint count from wherever the caller found it: a live+ * `MeshSkin`, or a prepared document with no entities yet.*/-u32 skinJointCount(ecs::Registry& registry, Entity entity, const Mesh& mesh, bool& warnedBones) {- if (!mesh.isSkinned()) return 0;- const auto* skin = registry.tryGet<ecs::MeshSkin>(entity);- if (!skin || skin->joints.size() != mesh.inverseBind.size()) return 0;+u32 skinnedBy(const Mesh& mesh, usize joints, bool& warnedBones) {+ if (!mesh.isSkinned() || joints != mesh.inverseBind.size()) return 0;// Posing the first MESH_MAX_BONES leaves the rest indexing a matrix this// draw never uploads — the wrong-matrix read the count check above already// rejects, so it takes the same answer. For files no importer here wrote.- if (skin->joints.size() > MESH_MAX_BONES) {+ if (joints > MESH_MAX_BONES) {if (!warnedBones) {warnedBones = true;ES_LOG_WARN("MeshSkin: {} joints exceeds the {} one draw can be posed by; drawing the"- " bind pose", skin->joints.size(), MESH_MAX_BONES);+ " bind pose", joints, MESH_MAX_BONES);}return 0;}- return static_cast<u32>(skin->joints.size());+ return static_cast<u32>(joints);+}++u32 skinJointCount(ecs::Registry& registry, Entity entity, const Mesh& mesh, bool& warnedBones) {+ const auto* skin = registry.tryGet<ecs::MeshSkin>(entity);+ return skin ? skinnedBy(mesh, skin->joints.size(), warnedBones) : 0;+}++/** @brief The facts a PREPARED cell answers with: its document's fields, and the+ * assets its preparation already decoded. No entity is consulted. */+MeshProgramFacts meshFactsFromDocument(RenderFrameContext& ctx, const MeshDocumentRecord& row,+ bool& warnedBones) {+ MeshProgramFacts facts;+ const Mesh* resident = row.meshHandle != 0+ ? ctx.resources.getMesh(resource::MeshHandle(row.meshHandle)) : nullptr;+ facts.hasNormals = resident && resident->hasNormals;+ facts.lit = row.lit != 0;+ facts.materialId = row.materialId;+ if (row.normalMapHandle != 0 && facts.lit && facts.hasNormals) {+ if (Texture* tex = ctx.resources.getTexture(resource::TextureHandle(row.normalMapHandle))) {+ facts.normalTextureId = tex->getId();+ }+ }+ facts.skinned = resident && skinnedBy(*resident, row.jointCount, warnedBones) > 0;+ return facts;}u32 skinPose(ecs::Registry& registry, Entity entity, const Mesh& mesh,@@ -189,21 +215,37 @@ struct MeshDrawKeys {u32 normalTextureId = 0;};-MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entity entity,- const ecs::MeshRenderer& mesh, const Mesh* resident, bool shadowDepth,- bool& warnedBones) {- MeshDrawKeys out;+u32 meshVariantFrom(const MeshProgramFacts& facts, bool envMapped, bool shadowDepth) {+ return meshVariant(facts.hasNormals, facts.lit && !shadowDepth,+ facts.normalTextureId != 0 && !shadowDepth, facts.skinned, shadowDepth,+ envMapped);+}++/** @brief The facts a LIVE entity answers with: its components and its mesh. */+MeshProgramFacts meshFactsFromEntity(RenderFrameContext& ctx, ecs::Registry& registry,+ Entity entity, const ecs::MeshRenderer& mesh,+ const Mesh* resident, bool& warnedBones) {+ MeshProgramFacts facts;+ facts.hasNormals = resident && resident->hasNormals;+ facts.lit = mesh.lit;+ facts.materialId = mesh.material;// Only meaningful with normals to perturb AND a draw that takes light.if (mesh.normalMap.isValid() && mesh.lit && resident && resident->hasNormals) {if (Texture* tex = ctx.resources.getTexture(mesh.normalMap)) {- out.normalTextureId = tex->getId();+ facts.normalTextureId = tex->getId();}}- const bool skinned = resident && skinJointCount(registry, entity, *resident, warnedBones) > 0;- out.variant = meshVariant(resident && resident->hasNormals, mesh.lit && !shadowDepth,- out.normalTextureId != 0 && !shadowDepth, skinned, shadowDepth,- ctx.environment_texture_id != 0);- return out;+ facts.skinned = resident && skinJointCount(registry, entity, *resident, warnedBones) > 0;+ return facts;+}++MeshDrawKeys meshDrawFor(RenderFrameContext& ctx, ecs::Registry& registry, Entity entity,+ const ecs::MeshRenderer& mesh, const Mesh* resident, bool shadowDepth,+ bool& warnedBones) {+ const MeshProgramFacts facts =+ meshFactsFromEntity(ctx, registry, entity, mesh, resident, warnedBones);+ return { meshVariantFrom(facts, ctx.environment_texture_id != 0, shadowDepth),+ facts.normalTextureId };}} // namespace@@ -287,38 +329,31 @@ u32 MeshPlugin::meshProgram(RenderFrameContext& ctx, u32 variant) {return mesh_programs_[variant];}-RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry& registry,- const Entity* entities, u32 count, bool shadowPasses) {+RenderPrewarmResult MeshPlugin::prewarmFacts(RenderFrameContext& ctx,+ const MeshProgramFacts* facts, u32 count,+ bool shadowPasses, bool residentGeometry) {RenderPrewarmResult out;- u64 seen = 0;const u32 materialsBefore = ctx.materials ? ctx.materials->builtVariantCount() : 0;+ const bool envMapped = ctx.environment_texture_id != 0;for (u32 i = 0; i < count; ++i) {- const Entity entity = entities[i];- const auto* mesh = registry.tryGet<ecs::MeshRenderer>(entity);- if (!mesh || !mesh->enabled) continue;- if (mesh->indices.empty() && !mesh->mesh.isValid()) continue;- const Mesh* resident = mesh->mesh.isValid() ? ctx.resources.getMesh(mesh->mesh) : nullptr;// Both purposes when the scene draws depth too: the same renderable is// asked for twice with different keys, and readying only the camera's// leaves the first shadow map to pay for the other.for (u32 pass = 0; pass < 2; ++pass) {const bool shadowDepth = pass == 1;- if (shadowDepth && (!shadowPasses || !resident)) continue;- const u32 variant =- meshDrawFor(ctx, registry, entity, *mesh, resident, shadowDepth,- warned_bones_).variant;+ if (shadowDepth && (!shadowPasses || !residentGeometry)) continue;+ const u32 variant = meshVariantFrom(facts[i], envMapped, shadowDepth);++out.asks;- if ((seen & (1ull << variant)) == 0) { seen |= 1ull << variant; ++out.uniqueKeys; }+ if ((out.keys & (1ull << variant)) == 0) { out.keys |= 1ull << variant; ++out.uniqueKeys; }if (!mesh_compiled_[variant]) ++out.compiles;meshProgram(ctx, variant);}// The second lazily-compiled path. A fixture without materials would let// readiness look complete while a material-shaded world still hitched.- if (mesh->material != 0 && ctx.materials && resident) {+ if (facts[i].materialId != 0 && ctx.materials) {++out.materialAsks;- ctx.materials->meshProgram(mesh->material, ctx.resources, resident->hasNormals,- skinJointCount(registry, entity, *resident, warned_bones_) > 0,- ctx.environment_texture_id != 0);+ ctx.materials->meshProgram(facts[i].materialId, ctx.resources, facts[i].hasNormals,+ facts[i].skinned, envMapped);}}if (ctx.materials) {@@ -328,6 +363,41 @@ RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry&return out;}+RenderPrewarmResult MeshPlugin::prewarmDocument(RenderFrameContext& ctx,+ const MeshDocumentRecord* rows, u32 count,+ bool shadowPasses) {+ std::vector<MeshProgramFacts> facts;+ facts.reserve(count);+ bool anyResident = false;+ for (u32 i = 0; i < count; ++i) {+ if (rows[i].meshHandle == 0) continue;+ anyResident = anyResident+ || ctx.resources.getMesh(resource::MeshHandle(rows[i].meshHandle)) != nullptr;+ facts.push_back(meshFactsFromDocument(ctx, rows[i], warned_bones_));+ }+ return prewarmFacts(ctx, facts.data(), static_cast<u32>(facts.size()), shadowPasses,+ anyResident);+}++RenderPrewarmResult MeshPlugin::prewarm(RenderFrameContext& ctx, ecs::Registry& registry,+ const Entity* entities, u32 count, bool shadowPasses) {+ std::vector<MeshProgramFacts> facts;+ facts.reserve(count);+ bool anyResident = false;+ for (u32 i = 0; i < count; ++i) {+ const Entity entity = entities[i];+ const auto* mesh = registry.tryGet<ecs::MeshRenderer>(entity);+ if (!mesh || !mesh->enabled) continue;+ if (mesh->indices.empty() && !mesh->mesh.isValid()) continue;+ const Mesh* resident = mesh->mesh.isValid() ? ctx.resources.getMesh(mesh->mesh) : nullptr;+ anyResident = anyResident || resident != nullptr;+ facts.push_back(+ meshFactsFromEntity(ctx, registry, entity, *mesh, resident, warned_bones_));+ }+ return prewarmFacts(ctx, facts.data(), static_cast<u32>(facts.size()), shadowPasses,+ anyResident);+}+void MeshPlugin::collect(RenderCollectContext& collect_ctx) {auto& registry = collect_ctx.registry;auto& frustum = collect_ctx.frustum;diff --git a/src/esengine/renderer/plugins/MeshPlugin.hpp b/src/esengine/renderer/plugins/MeshPlugin.hppindex 142fcf7a1..ae5fd1d05 100644--- a/src/esengine/renderer/plugins/MeshPlugin.hpp+++ b/src/esengine/renderer/plugins/MeshPlugin.hpp@@ -27,6 +27,12 @@ public:void collect(RenderCollectContext& ctx) override;RenderPrewarmResult prewarm(RenderFrameContext& ctx, ecs::Registry& registry,const Entity* entities, u32 count, bool shadowPasses) override;+ /** @brief Ready programs from facts already gathered — the door a PREPARED+ * cell comes through, before any entity of it exists. */+ RenderPrewarmResult prewarmFacts(RenderFrameContext& ctx, const MeshProgramFacts* facts,+ u32 count, bool shadowPasses, bool residentGeometry);+ RenderPrewarmResult prewarmDocument(RenderFrameContext& ctx, const MeshDocumentRecord* rows,+ u32 count, bool shadowPasses) override;const char* collectScope() const override { return "render.collect.mesh"; }private:diff --git a/tools/launchers/residency-run.mjs b/tools/launchers/residency-run.mjsindex 8d01d2625..f413d5541 100644--- a/tools/launchers/residency-run.mjs+++ b/tools/launchers/residency-run.mjs@@ -243,10 +243,13 @@ async function main() {// Absent capability is a FAILED run, never a quiet pass: a probe that was// not built reads as "nothing needed compiling", which is the answer the// experiment is trying to earn.- const has = await exec('typeof window.__estellaCooked.prewarmMeshVariants === "function"');+ const has = await exec('typeof window.__estellaCooked.prewarmMeshVariants === "function"'+ + ' && typeof window.__estellaCooked.prewarmMeshVariantsFromDocument === "function"');if (!has) { stop(); server.close(); return fail('this build has no prewarm probe', 2); }- const r = await exec(`window.__estellaCooked.prewarmMeshVariants(${JSON.stringify(step.cell)})`);- console.log(`prewarm ${step.as}: ${JSON.stringify(r)}`);+ const call = step.from === 'document'+ ? `window.__estellaCooked.prewarmMeshVariantsFromDocument(${JSON.stringify(step.cell)})`+ : `window.__estellaCooked.prewarmMeshVariants(${JSON.stringify(step.cell)})`;+ console.log(`prewarm ${step.as}: ${JSON.stringify(await exec(call))}`);continue;}if (step.do === 'frames') {