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): the device generation guards the claim, it is not part of it
esengine39c0dcfc7d88
diff --git a/bench/residency/readiness.mjs b/bench/residency/readiness.mjsindex 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.tsindex 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.mdindex 11eb55c4e..ce6bd098b 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -364,6 +364,7 @@ renderer_captureNextFrame: () => voidrenderer_createSkeletalPreview: (w: number, h: number) => numberrenderer_createTarget: (width: number, height: number, flags: number) => numberrenderer_destroySkeletalPreview: (preview: number) => void+renderer_deviceGeneration: (() => number) | undefinedrenderer_diagnose: () => voidrenderer_end: () => voidrenderer_endFrame: (() => void) | undefineddiff --git a/sdk/src/ecs/bridge/nativeEngineApi.generated.ts b/sdk/src/ecs/bridge/nativeEngineApi.generated.tsindex 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.tsindex 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.cppindex 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 covoid 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.hppindex 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.cppindex 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.tsindex 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 todiff --git a/tools/render-host/run.mjs b/tools/render-host/run.mjsindex 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;