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): the device generation guards the claim, it is not part of it

esengine39c0dcfc7d88
diff --git a/bench/residency/readiness.mjs b/bench/residency/readiness.mjs
index 7f1cc413f..2073fc09b 100644
--- a/bench/residency/readiness.mjs
+++ b/bench/residency/readiness.mjs
@@ -211,6 +211,11 @@ function main() {
check(doc.programEpoch === live.programEpoch,
`${name}: and both were taken under the same program epoch`,
`${doc.programEpoch} against ${live.programEpoch}`);
+ // The guard, not a third truth: had the device been rebuilt between the
+ // two derivations, neither reading would describe the live one.
+ check(doc.deviceGeneration === live.deviceGeneration,
+ `${name}: on one device generation, so neither reading is stale`,
+ `${doc.deviceGeneration} against ${live.deviceGeneration}`);
if (name === 'plain') {
// nothing fixture-specific: this one exists to be compared against.
} else if (name === 'shadow') {
diff --git a/pipeline/src/runtime/gameHost.ts b/pipeline/src/runtime/gameHost.ts
index b6c474926..089178611 100644
--- a/pipeline/src/runtime/gameHost.ts
+++ b/pipeline/src/runtime/gameHost.ts
@@ -141,10 +141,10 @@ async function boot(): Promise<void> {
if (headless) {
let statsOn = false;
- 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 PREWARM_WORDS = 13;
+ /** Thirteen words out: five counts, the stock key SET, the readiness stamp
+ * (digest over BOTH program paths plus the epoch it was taken under), and
+ * the device generation that guards it — never part of the claim itself. */
const readPrewarm = (heap: Uint32Array, ptr: number): Record<string, number> => {
const o = heap.subarray(ptr >> 2, (ptr >> 2) + PREWARM_WORDS);
return {
@@ -153,6 +153,7 @@ async function boot(): Promise<void> {
keysLo: o[5], keysHi: o[6],
digestLo: o[7], digestHi: o[8],
programEpoch: o[9] + o[10] * 0x100000000,
+ deviceGeneration: o[11] + o[12] * 0x100000000,
};
};
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 11eb55c4e..ce6bd098b 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -364,6 +364,7 @@ renderer_captureNextFrame: () => void
renderer_createSkeletalPreview: (w: number, h: number) => number
renderer_createTarget: (width: number, height: number, flags: number) => number
renderer_destroySkeletalPreview: (preview: number) => void
+renderer_deviceGeneration: (() => number) | undefined
renderer_diagnose: () => void
renderer_end: () => void
renderer_endFrame: (() => void) | undefined
diff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
index 60aff1315..6238b2d56 100644
--- a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
+++ b/sdk/src/ecs/bridge/nativeEngineApi.generated.ts
@@ -121,6 +121,7 @@ export interface NativeEngineApi {
renderer_createSkeletalPreview?(w: number, h: number): number;
renderer_createTarget?(width: number, height: number, flags: number): number;
renderer_destroySkeletalPreview?(preview: number): void;
+ renderer_deviceGeneration?(): number;
renderer_diagnose?(): void;
renderer_end?(): void;
renderer_endFrame?(): void;
@@ -380,6 +381,7 @@ export function createNativeEngineApi(
bind('renderer_createSkeletalPreview', 'es_renderer_createSkeletalPreview', false);
bind('renderer_createTarget', 'es_renderer_createTarget', false);
bind('renderer_destroySkeletalPreview', 'es_renderer_destroySkeletalPreview', false);
+ bind('renderer_deviceGeneration', 'es_renderer_deviceGeneration', false);
bind('renderer_diagnose', 'es_renderer_diagnose', false);
bind('renderer_end', 'es_renderer_end', false);
bind('renderer_endFrame', 'es_renderer_endFrame', false);
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 4450b7455..ae11c9c57 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -279,6 +279,13 @@ export interface ESEngineModule {
* Optional: absent on an older wasm build.
*/
renderer_programEpoch?(): number;
+ /**
+ * Which generation of the GPU device is current, advanced by every successful
+ * rebuild. Never part of a readiness claim — the guard that says the claim
+ * was derived and readied on ONE device.
+ * Optional: absent on an older wasm build.
+ */
+ renderer_deviceGeneration?(): number;
/** Release a mesh and the buffers it owns. */
mesh_release?(meshHandle: number): void;
/**
diff --git a/src/esengine/bindings/RendererBindings.cpp b/src/esengine/bindings/RendererBindings.cpp
index 8bf2cfe1b..9fb7ccb37 100644
--- a/src/esengine/bindings/RendererBindings.cpp
+++ b/src/esengine/bindings/RendererBindings.cpp
@@ -840,11 +840,17 @@ static void writePrewarm(u32* out, const RenderPrewarmResult& r) {
const u64 epoch = rc ? rc->programEpoch() : 0;
out[9] = static_cast<u32>(epoch & 0xFFFFFFFFull);
out[10] = static_cast<u32>(epoch >> 32);
+ // Not a third truth in the stamp: the guard that says the two above were
+ // read on one device. A generation that moved mid-derivation invalidates the
+ // whole readying rather than being recorded alongside it.
+ const u64 generation = g_device ? g_device->deviceGeneration() : 0;
+ out[11] = static_cast<u32>(generation & 0xFFFFFFFFull);
+ out[12] = static_cast<u32>(generation >> 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 < 11; ++i) out[i] = 0;
+ for (u32 i = 0; i < 13; ++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));
@@ -852,7 +858,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 < 11; ++i) out[i] = 0;
+ for (u32 i = 0; i < 13; ++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));
@@ -883,6 +889,10 @@ f64 renderer_programEpoch() {
return 0.0;
}
+f64 renderer_deviceGeneration() {
+ return g_device ? static_cast<f64>(g_device->deviceGeneration()) : 0.0;
+}
+
void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a) {
ctx().state().clear_color = glm::vec4(r, g, b, a);
}
diff --git a/src/esengine/bindings/RendererBindings.hpp b/src/esengine/bindings/RendererBindings.hpp
index bdfbda2ac..f2acdcb7e 100644
--- a/src/esengine/bindings/RendererBindings.hpp
+++ b/src/esengine/bindings/RendererBindings.hpp
@@ -155,6 +155,10 @@ f64 renderer_getTextureBytes();
/** @brief The renderer's current program-readiness epoch. A readiness record
* stamped with an older one names programs that may be gone. */
f64 renderer_programEpoch();
+
+/** @brief Which generation of the GPU device is current. Not part of a readiness
+ * claim — the guard that says the claim was taken on one device. */
+f64 renderer_deviceGeneration();
void renderer_setClearColor(f32 r, f32 g, f32 b, f32 a);
void renderer_setViewport(i32 x, i32 y, i32 w, i32 h);
void renderer_setYSortLayers(u32 mask);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index d661b273a..846d75b58 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -734,6 +734,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("engine_getGpuScopes", &esengine::engine_getGpuScopes);
emscripten::function("renderer_getTextureBytes", &esengine::renderer_getTextureBytes);
emscripten::function("renderer_programEpoch", &esengine::renderer_programEpoch);
+ emscripten::function("renderer_deviceGeneration", &esengine::renderer_deviceGeneration);
emscripten::function("renderer_setClearColor", &esengine::renderer_setClearColor);
emscripten::function("renderer_setViewport", &esengine::renderer_setViewport);
emscripten::function("renderer_setYSortLayers", &esengine::renderer_setYSortLayers);
diff --git a/tools/render-host/host.ts b/tools/render-host/host.ts
index 4e312d2b6..9a0b33c39 100644
--- a/tools/render-host/host.ts
+++ b/tools/render-host/host.ts
@@ -692,6 +692,8 @@ window.__estellaHeadless = {
// programs that were ready before still are.
programEpoch: () => (module as unknown as
{ renderer_programEpoch?(): number } | null)?.renderer_programEpoch?.() ?? -1,
+ deviceGen: () => (module as unknown as
+ { renderer_deviceGeneration?(): number } | null)?.renderer_deviceGeneration?.() ?? -1,
meshesOwed: () => app?.getResource(Assets)?.meshesAwaitingRematerialization() ?? [],
// Emscripten's GL tables hold wrappers minted against the dead context;
// counting them says whether a rebuild refilled them or merely added to
diff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjs
index d49e3571b..b4a110597 100644
--- a/tools/render-host/run.mjs
+++ b/tools/render-host/run.mjs
@@ -183,8 +183,13 @@ function finish(result, server) {
// stale. Without this, a stamp from the dead generation keeps vouching for
// programs nothing holds, and the first frame that needs one pays for it.
const epochOk = !dl || dl.epochBefore < 0 || dl.epochAfterFull > dl.epochBefore;
+ // The two are independent on purpose. A rebuilt device that left readiness
+ // untouched, or readiness invalidated on a device that never moved, are both
+ // states nothing downstream could reason about.
+ const genOk = !dl || dl.genBefore === undefined || dl.genBefore < 0
+ || dl.mode === 'auto' || dl.genAfterFull > dl.genBefore;
const deviceLossOk = lossSeen && cameBack && drivenSteps && growthOk && meshIdentityOk
- && epochOk;
+ && epochOk && genOk;
// Freezing nothing would pass every pixel assertion by not having changed the
// scene — the shape of a check that cannot fail.
const meshOk = (!result.meshResident || result.meshResident.frozen > 0)
@@ -528,7 +533,7 @@ app.whenReady().then(async () => {
const d = window.__estellaHeadless.device;
const api = window.__estellaHeadless.api;
const out = { meshesBefore: d.meshes(), epochBefore: d.programEpoch(),
- supported: d.lose() };
+ genBefore: d.deviceGen(), supported: d.lose() };
if (!out.supported) return out;
// The browser reports the loss asynchronously and the engine polls on its
@@ -572,6 +577,7 @@ app.whenReady().then(async () => {
out.meshesAfterFull = d.meshes();
out.meshesOwedAfterFull = d.meshesOwed();
out.epochAfterFull = d.programEpoch();
+ out.genAfterFull = d.deviceGen();
await api.step(${STEPS}, 1 / 60);
out.drawCallsAfterRecover = api.getStats ? api.getStats().drawCalls : -1;
return out;