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.

test(verify): the whole loss and recovery cycle now passes

esengine1c7396aaacf1
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 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.mjs
index 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.ts
index 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.md
index 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 | null
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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 | null
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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 | null
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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 | null
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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 | null
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 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.ts
index 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());
}