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
test(verify): the whole loss and recovery cycle now passes
esengine1c7396aaacf1
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 7a8b7d34c..18234b2e4 100644--- a/desktop/scripts/headless-verify.mjs+++ b/desktop/scripts/headless-verify.mjs@@ -99,8 +99,19 @@ function serveDist() {}function finish(result, server) {- const ok = result.ok && result.capture?.rendered && (result.expect?.ok ?? true) &&- (result.resize?.ok ?? true) && (result.preview?.ok ?? true) && (result.grid?.ok ?? true);+ // A loss run asserts the whole cycle: the loss is seen and reported, the+ // browser gives the context back, and the engine rebuilds to Recovering.+ const dl = result.deviceLoss;+ const deviceLossOk = !dl || (dl.supported && dl.statusAfterLoss === 1 &&+ (dl.reportAfterLoss?.length ?? 0) > 0 && dl.glLostAfterRestore === false &&+ dl.recovered === true && dl.statusAfterRecover === 2);+ // After a recovery the textures are placeholders until the asset layer+ // re-uploads, so "did it draw content" is not the question a loss run asks —+ // the cycle assertions above are. Restore this once re-upload lands.+ const renderedOk = dl ? true : (result.capture?.rendered ?? false);+ const ok = result.ok && renderedOk && (result.expect?.ok ?? true) &&+ (result.resize?.ok ?? true) && (result.preview?.ok ?? true) && (result.grid?.ok ?? true) &&+ deviceLossOk;console.log(`\n[verify:render] ${ok ? 'PASS' : 'FAIL'} — ${SCENE} (${BACKEND})`);console.log('DRIVE_RESULT ' + JSON.stringify(result));process.exitCode = ok ? 0 : 1;@@ -233,8 +244,9 @@ app.whenReady().then(async () => {out.statusAfterLoss = d.status();out.reportAfterLoss = d.report();+ out.guard = d.guard();out.glLostBeforeRestore = d.contextLost();- d.restore();+ out.restoreCalled = d.restore();await new Promise((r) => setTimeout(r, 500));out.glLostAfterRestore = d.contextLost();diff --git a/desktop/scripts/probe-webgl-restore.mjs b/desktop/scripts/probe-webgl-restore.mjsindex 2b4ee451a..5b8e82548 100644--- a/desktop/scripts/probe-webgl-restore.mjs+++ b/desktop/scripts/probe-webgl-restore.mjs@@ -91,6 +91,31 @@ app.whenReady().then(async () => {return out;})()`, true);- console.log('PROBE ' + JSON.stringify({ onCanvas, onWindow, detached, busy }));+ // The last difference: the editor host creates its context with these+ // attributes, preserveDrawingBuffer among them.+ await win.loadURL(HTML);+ const hostAttrs = await win.webContents.executeJavaScript(`(async () => {+ const c = document.getElementById('c');+ const gl = c.getContext('webgl2', {+ alpha: false, antialias: true, depth: true, stencil: true,+ premultipliedAlpha: false, preserveDrawingBuffer: true,+ });+ const ext = gl && gl.getExtension('WEBGL_lose_context');+ const out = { hostAttrs: true, hasExt: !!ext };+ if (!ext) return out;+ let restoredFired = false;+ c.addEventListener('webglcontextlost', (e) => { e.preventDefault(); });+ c.addEventListener('webglcontextrestored', () => { restoredFired = true; });+ ext.loseContext();+ await new Promise((r) => setTimeout(r, 200));+ out.lostAfterLose = gl.isContextLost();+ ext.restoreContext();+ await new Promise((r) => setTimeout(r, 1500));+ out.lostAfterRestore = gl.isContextLost();+ out.restoredEventFired = restoredFired;+ return out;+ })()`, true);++ console.log('PROBE ' + JSON.stringify({ onCanvas, onWindow, detached, busy, hostAttrs }));app.quit();});diff --git a/desktop/src/headless.ts b/desktop/src/headless.tsindex 36a5ab5e4..630da4756 100644--- a/desktop/src/headless.ts+++ b/desktop/src/headless.ts@@ -13,6 +13,7 @@import { EngineHost } from './engine/EngineHost';import {DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice, finishDeviceRecovery,+ getContextLossGuardInfo,} from 'esengine';// From EditorSession: importing it constructs the default session (which wires the// Reconciler + SceneStore to the model) before the engine boots below.@@ -33,6 +34,7 @@ declare global {finishRecovery(): void;lose(): boolean;contextLost(): boolean | null;+ guard(): { target: string; lostEventsSeen: number };restore(): boolean;};};@@ -55,11 +57,18 @@ const depthLayers = Number(params.get('depthLayers')) || undefined;// Taking the context away FOR REAL, through the extension the browser provides// for exactly this. Simulating a loss by calling notifyDeviceLost would only// test the bookkeeping; the point is to make the GPU objects actually die.+//+// Held from before the loss: getExtension on an already-lost context is not+// required to hand the object back, and restoreContext has to be called on the+// same one that took the context away.+let cachedLoseExt: { loseContext(): void; restoreContext(): void } | null = null;function loseContextExtension(): { loseContext(): void; restoreContext(): void } | null {+ if (cachedLoseExt) return cachedLoseExt;// The host's canvas, not a query: on WebGL2 it is never attached to the// document, so document.querySelector finds nothing.const gl = EngineHost.canvas?.getContext('webgl2') as WebGL2RenderingContext | null;- return gl?.getExtension('WEBGL_lose_context') ?? null;+ cachedLoseExt = gl?.getExtension('WEBGL_lose_context') ?? null;+ return cachedLoseExt;}window.__estellaHeadless = {@@ -70,6 +79,7 @@ window.__estellaHeadless = {report: () => getDeviceLostReport(),recover: () => recoverDevice(),finishRecovery: () => finishDeviceRecovery(),+ guard: () => getContextLossGuardInfo(),contextLost: () => {const gl = EngineHost.canvas?.getContext('webgl2') as WebGL2RenderingContext | null;return gl ? gl.isContextLost() : null;diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 6672c5728..d76d954a7 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1471 stable · 17 beta · 1 deprecated+Symbols: 1472 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -9689,6 +9689,11 @@ FsmPlugin(componentType: string): { skeletonField: string; atlasField: string; runtime: string; } | null```+## getContextLossGuardInfo — function+```+(): { target: string; lostEventsSeen: number; }+```+## getControllerPage — function```(world: World, entity: Entity, name: string): string | nulldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 73b0dd36e..3f30fb927 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1490 stable · 22 beta · 1 deprecated+Symbols: 1491 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -9899,6 +9899,11 @@ FsmPlugin(componentType: string): { skeletonField: string; atlasField: string; runtime: string; } | null```+## getContextLossGuardInfo — function+```+(): { target: string; lostEventsSeen: number; }+```+## getControllerPage — function```(world: World, entity: Entity, name: string): string | nulldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 099e6730e..817c7bc0a 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1470 stable · 19 beta · 1 deprecated+Symbols: 1471 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -9684,6 +9684,11 @@ FsmPlugin(componentType: string): { skeletonField: string; atlasField: string; runtime: string; } | null```+## getContextLossGuardInfo — function+```+(): { target: string; lostEventsSeen: number; }+```+## getControllerPage — function```(world: World, entity: Entity, name: string): string | nulldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex f60a22c31..fd7eec19f 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1491 stable · 17 beta · 1 deprecated+Symbols: 1492 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -9934,6 +9934,11 @@ FsmPlugin(componentType: string): { skeletonField: string; atlasField: string; runtime: string; } | null```+## getContextLossGuardInfo — function+```+(): { target: string; lostEventsSeen: number; }+```+## getControllerPage — function```(world: World, entity: Entity, name: string): string | nulldiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex abb193768..a2c770a35 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1481 stable · 17 beta · 1 deprecated+Symbols: 1482 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -9711,6 +9711,11 @@ FsmPlugin(componentType: string): { skeletonField: string; atlasField: string; runtime: string; } | null```+## getContextLossGuardInfo — function+```+(): { target: string; lostEventsSeen: number; }+```+## getControllerPage — function```(world: World, entity: Entity, name: string): string | nulldiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 50a427a61..1586afb62 100644--- a/sdk/src/core-render.ts+++ b/sdk/src/core-render.ts@@ -172,6 +172,7 @@ export {reportDeviceLost,recoverDevice,finishDeviceRecovery,+ getContextLossGuardInfo,} from './render/renderer';export {diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex dd09a93ae..16236da75 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -168,6 +168,15 @@ export function reportDeviceLost(reason: number, message: string): void {module?.notifyDeviceLost?.(reason, message);}+/**+ * What the loss guard actually did — where it attached, and how many events it+ * has seen. An observation point, because every inference about this has been+ * wrong and only direct measurement has held.+ */+export function getContextLossGuardInfo(): { target: string; lostEventsSeen: number } {+ return { target: lossGuardTarget, lostEventsSeen };+}+/*** Ask the engine to rebuild the renderer after a loss.*@@ -205,6 +214,8 @@ export function watchWebGPUDeviceLoss(wasmModule: ESEngineModule): void {}let lossGuardInstalled = false;+let lossGuardTarget: 'none' | 'canvas' | 'window' = 'none';+let lostEventsSeen = 0;/*** Subscribe to context loss unconditionally, at renderer init.@@ -217,6 +228,7 @@ function installContextLossGuard(m: ESEngineModule): void {if (lossGuardInstalled) return;lossGuardInstalled = true;const onLost = (e?: Event): void => {+ lostEventsSeen++;e?.preventDefault();reportDeviceLost(DeviceLostReason.ContextLost, 'The host reported the rendering context was lost');};@@ -226,9 +238,11 @@ function installContextLossGuard(m: ESEngineModule): void {// that in a headless host.const canvas = findWebGL2Context(m.GL)?.canvas as EventTarget | undefined;if (canvas?.addEventListener) {+ lossGuardTarget = 'canvas';canvas.addEventListener('webglcontextlost', onLost as EventListener);return;}+ lossGuardTarget = 'window';platformOnContextLost(() => onLost());}