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): take the GPU away for real, and see what happens

esengine28733f12376f
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjs
index 02656bced..f74d4ff51 100644
--- a/desktop/scripts/headless-verify.mjs
+++ b/desktop/scripts/headless-verify.mjs
@@ -130,6 +130,7 @@ app.whenReady().then(async () => {
await win.loadURL(url);
const exec = (code) => win.webContents.executeJavaScript(code, true);
+ let deviceLoss = null;
await exec('window.__estellaHeadless.ready');
const entityCount = await exec(
`window.__estellaHeadless.api.loadScene(${JSON.stringify(SCENE)}, ${JSON.stringify(MANIFEST)})`,
@@ -213,6 +214,39 @@ app.whenReady().then(async () => {
await exec(`window.__estellaHeadless.api.step(${STEPS}, 1 / 60)`);
}
+ // ESTELLA_VERIFY_DEVICE_LOSS=1 takes the GPU away for real (WEBGL_lose_context)
+ // and drives the whole cycle, because everything downstream of a loss is
+ // reachable only by actually losing one.
+ if (process.env.ESTELLA_VERIFY_DEVICE_LOSS === '1') {
+ deviceLoss = await exec(`(async () => {
+ const d = window.__estellaHeadless.device;
+ const api = window.__estellaHeadless.api;
+ const out = { supported: d.lose() };
+ if (!out.supported) return out;
+
+ // The browser reports the loss to JS asynchronously; step so the engine's
+ // own poll sees it too, then confirm it refuses to submit.
+ await new Promise((r) => setTimeout(r, 100));
+ api.step(3, 1 / 60);
+ out.statusAfterLoss = d.status();
+ out.reportAfterLoss = d.report();
+
+ d.restore();
+ await new Promise((r) => setTimeout(r, 300));
+
+ // A context comes back when the browser is ready, not when asked.
+ out.recovered = false;
+ for (let i = 0; i < 20 && !out.recovered; i++) {
+ out.recovered = d.recover();
+ if (!out.recovered) await new Promise((r) => setTimeout(r, 100));
+ }
+ out.statusAfterRecover = d.status();
+ api.step(${STEPS}, 1 / 60);
+ out.drawCallsAfterRecover = api.getStats ? api.getStats().drawCalls : -1;
+ return out;
+ })()`);
+ }
+
// WebGPU: the engine has no synchronous readback (buffer maps are async)
// and a hidden window never presents, so drawImage-style page readback is
// blank — capture the PAGE instead (capturePage forces a composite; the
@@ -416,7 +450,7 @@ app.whenReady().then(async () => {
})()`);
}
}
- finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, grid }, server);
+ finish({ ok: true, entityCount, drawCalls, capture, expect, resize, preview, grid, deviceLoss }, server);
} catch (e) {
finish({ ok: false, error: String((e && e.stack) || e) }, server);
}
diff --git a/desktop/src/headless.ts b/desktop/src/headless.ts
index 2a0ad8166..51c983547 100644
--- a/desktop/src/headless.ts
+++ b/desktop/src/headless.ts
@@ -11,6 +11,9 @@
* back for reproducible verification.
*/
import { EngineHost } from './engine/EngineHost';
+import {
+ DeviceStatus, getDeviceStatus, getDeviceLostReport, recoverDevice, finishDeviceRecovery,
+} from 'esengine';
// From EditorSession: importing it constructs the default session (which wires the
// Reconciler + SceneStore to the model) before the engine boots below.
import { EditorControlSurface, type EditorControlSurfaceT } from './engine/EditorSession';
@@ -22,6 +25,15 @@ declare global {
/** Resolves once the engine is booted and ready to load a scene. */
ready: Promise<void>;
api: EditorControlSurfaceT;
+ /** Device-loss driving surface: lets a verifier take the GPU away for real. */
+ device: {
+ status(): number;
+ report(): string;
+ recover(): boolean;
+ finishRecovery(): void;
+ lose(): boolean;
+ restore(): boolean;
+ };
};
}
}
@@ -39,7 +51,39 @@ const colorSpace = params.get('colorSpace') === 'linear' ? 'linear' : undefined;
// project setting would — the engine takes a mask, not a checkbox list.
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.
+function loseContextExtension(): { loseContext(): void; restoreContext(): void } | null {
+ // 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;
+}
+
window.__estellaHeadless = {
ready: EngineHost.bootHeadless({ width, height, backend, colorSpace, depthLayers }),
api: EditorControlSurface,
+ device: {
+ status: () => getDeviceStatus(),
+ report: () => getDeviceLostReport(),
+ recover: () => recoverDevice(),
+ finishRecovery: () => finishDeviceRecovery(),
+ lose: () => {
+ const ext = loseContextExtension();
+ if (!ext) return false;
+ ext.loseContext();
+ return true;
+ },
+ restore: () => {
+ const ext = loseContextExtension();
+ if (!ext) return false;
+ ext.restoreContext();
+ return true;
+ },
+ },
};
+
+// Referenced so the unused-import check sees it; DeviceStatus is the vocabulary
+// a driver compares status() against.
+export const DEVICE_STATUS_VOCAB = DeviceStatus;
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index 6ca27b0da..6672c5728 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: 1464 stable · 17 beta · 1 deprecated
+Symbols: 1471 stable · 17 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -2175,6 +2175,16 @@ pixels: Uint8Array<ArrayBufferLike>
width: number
```
+## DeviceLostReason — const
+```
+{ readonly Unknown: 0; readonly ContextLost: 1; readonly OutOfMemory: 2; readonly Reset: 3; readonly Removed: 4; readonly Destroyed: 5; readonly Validation: 6; readonly Internal: 7; }
+```
+
+## DeviceStatus — const
+```
+{ readonly Live: 0; readonly Lost: 1; readonly Recovering: 2; readonly Dead: 3; }
+```
+
## DiagnosticEvent — interface
```
context: Record<string, unknown> | undefined
@@ -9514,6 +9524,11 @@ EventBindingPlugin
(report: DiagnosticReport): string
```
+## finishDeviceRecovery — function
+```
+(): void
+```
+
## flattenPrefab — function
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -9689,6 +9704,16 @@ FsmPlugin
(): AppContext
```
+## getDeviceLostReport — function
+```
+(): string
+```
+
+## getDeviceStatus — function
+```
+(): number
+```
+
## getEditorType — function
```
(path: string): EditorAssetType
@@ -10414,6 +10439,11 @@ PrefabsPlugin
(entities: ProcessedEntity[]): void
```
+## recoverDevice — function
+```
+(): boolean
+```
+
## reflectEsshader — function
```
(source: string): ShaderReflection
@@ -10564,6 +10594,11 @@ PrefabsPlugin
ReplicationPlugin
```
+## reportDeviceLost — function
+```
+(reason: number, message: string): void
+```
+
## requireResourceManager — function
```
(): CppResourceManager
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index a8078f25d..73b0dd36e 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: 1483 stable · 22 beta · 1 deprecated
+Symbols: 1490 stable · 22 beta · 1 deprecated
## ABI_LAYOUT_HASH — const
```
@@ -2183,6 +2183,16 @@ pixels: Uint8Array<ArrayBufferLike>
width: number
```
+## DeviceLostReason — const
+```
+{ readonly Unknown: 0; readonly ContextLost: 1; readonly OutOfMemory: 2; readonly Reset: 3; readonly Removed: 4; readonly Destroyed: 5; readonly Validation: 6; readonly Internal: 7; }
+```
+
+## DeviceStatus — const
+```
+{ readonly Live: 0; readonly Lost: 1; readonly Recovering: 2; readonly Dead: 3; }
+```
+
## DiagnosticEvent — interface
```
context: Record<string, unknown> | undefined
@@ -9724,6 +9734,11 @@ EventBindingPlugin
(report: DiagnosticReport): string
```
+## finishDeviceRecovery — function
+```
+(): void
+```
+
## flattenPrefab — function
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -9899,6 +9914,16 @@ FsmPlugin
(): AppContext
```
+## getDeviceLostReport — function
+```
+(): string
+```
+
+## getDeviceStatus — function
+```
+(): number
+```
+
## getEditorType — function
```
(path: string): EditorAssetType
@@ -10634,6 +10659,11 @@ PrefabsPlugin
(entities: ProcessedEntity[]): void
```
+## recoverDevice — function
+```
+(): boolean
+```
+
## reflectEsshader — function
```
(source: string): ShaderReflection
@@ -10784,6 +10814,11 @@ PrefabsPlugin
ReplicationPlugin
```
+## reportDeviceLost — function
+```
+(reason: number, message: string): void
+```
+
## requireResourceManager — function
```
(): CppResourceManager
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 314b48aa7..099e6730e 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: 1463 stable · 19 beta · 1 deprecated
+Symbols: 1470 stable · 19 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2170,6 +2170,16 @@ pixels: Uint8Array<ArrayBufferLike>
width: number
```
+## DeviceLostReason — const
+```
+{ readonly Unknown: 0; readonly ContextLost: 1; readonly OutOfMemory: 2; readonly Reset: 3; readonly Removed: 4; readonly Destroyed: 5; readonly Validation: 6; readonly Internal: 7; }
+```
+
+## DeviceStatus — const
+```
+{ readonly Live: 0; readonly Lost: 1; readonly Recovering: 2; readonly Dead: 3; }
+```
+
## DiagnosticEvent — interface
```
context: Record<string, unknown> | undefined
@@ -9509,6 +9519,11 @@ EventBindingPlugin
(report: DiagnosticReport): string
```
+## finishDeviceRecovery — function
+```
+(): void
+```
+
## flattenPrefab — function
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -9684,6 +9699,16 @@ FsmPlugin
(): AppContext
```
+## getDeviceLostReport — function
+```
+(): string
+```
+
+## getDeviceStatus — function
+```
+(): number
+```
+
## getEditorType — function
```
(path: string): EditorAssetType
@@ -10419,6 +10444,11 @@ PrefabsPlugin
(entities: ProcessedEntity[]): void
```
+## recoverDevice — function
+```
+(): boolean
+```
+
## reflectEsshader — function
```
(source: string): ShaderReflection
@@ -10569,6 +10599,11 @@ PrefabsPlugin
ReplicationPlugin
```
+## reportDeviceLost — function
+```
+(reason: number, message: string): void
+```
+
## requireResourceManager — function
```
(): CppResourceManager
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index ee04fae1b..f60a22c31 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: 1484 stable · 17 beta · 1 deprecated
+Symbols: 1491 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2170,6 +2170,16 @@ pixels: Uint8Array<ArrayBufferLike>
width: number
```
+## DeviceLostReason — const
+```
+{ readonly Unknown: 0; readonly ContextLost: 1; readonly OutOfMemory: 2; readonly Reset: 3; readonly Removed: 4; readonly Destroyed: 5; readonly Validation: 6; readonly Internal: 7; }
+```
+
+## DeviceStatus — const
+```
+{ readonly Live: 0; readonly Lost: 1; readonly Recovering: 2; readonly Dead: 3; }
+```
+
## DiagnosticEvent — interface
```
context: Record<string, unknown> | undefined
@@ -9759,6 +9769,11 @@ EventBindingPlugin
(report: DiagnosticReport): string
```
+## finishDeviceRecovery — function
+```
+(): void
+```
+
## flattenPrefab — function
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -9934,6 +9949,16 @@ FsmPlugin
(): AppContext
```
+## getDeviceLostReport — function
+```
+(): string
+```
+
+## getDeviceStatus — function
+```
+(): number
+```
+
## getEditorType — function
```
(path: string): EditorAssetType
@@ -10669,6 +10694,11 @@ PrefabsPlugin
(entities: ProcessedEntity[]): void
```
+## recoverDevice — function
+```
+(): boolean
+```
+
## reflectEsshader — function
```
(source: string): ShaderReflection
@@ -10819,6 +10849,11 @@ PrefabsPlugin
ReplicationPlugin
```
+## reportDeviceLost — function
+```
+(reason: number, message: string): void
+```
+
## requireResourceManager — function
```
(): CppResourceManager
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index c0d3573af..abb193768 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: 1474 stable · 17 beta · 1 deprecated
+Symbols: 1481 stable · 17 beta · 1 deprecated
## ANCHOR_AXES — const
```
@@ -2170,6 +2170,16 @@ pixels: Uint8Array<ArrayBufferLike>
width: number
```
+## DeviceLostReason — const
+```
+{ readonly Unknown: 0; readonly ContextLost: 1; readonly OutOfMemory: 2; readonly Reset: 3; readonly Removed: 4; readonly Destroyed: 5; readonly Validation: 6; readonly Internal: 7; }
+```
+
+## DeviceStatus — const
+```
+{ readonly Live: 0; readonly Lost: 1; readonly Recovering: 2; readonly Dead: 3; }
+```
+
## DiagnosticEvent — interface
```
context: Record<string, unknown> | undefined
@@ -9536,6 +9546,11 @@ EventBindingPlugin
(report: DiagnosticReport): string
```
+## finishDeviceRecovery — function
+```
+(): void
+```
+
## flattenPrefab — function
```
(prefab: PrefabData, overrides: PrefabOverride[], ctx: FlattenContext): FlattenResult
@@ -9711,6 +9726,16 @@ FsmPlugin
(): AppContext
```
+## getDeviceLostReport — function
+```
+(): string
+```
+
+## getDeviceStatus — function
+```
+(): number
+```
+
## getEditorType — function
```
(path: string): EditorAssetType
@@ -10441,6 +10466,11 @@ PrefabsPlugin
(entities: ProcessedEntity[]): void
```
+## recoverDevice — function
+```
+(): boolean
+```
+
## reflectEsshader — function
```
(source: string): ShaderReflection
@@ -10591,6 +10621,11 @@ PrefabsPlugin
ReplicationPlugin
```
+## reportDeviceLost — function
+```
+(reason: number, message: string): void
+```
+
## requireResourceManager — function
```
(): CppResourceManager
diff --git a/sdk/src/core-render.ts b/sdk/src/core-render.ts
index 5989dd175..50a427a61 100644
--- a/sdk/src/core-render.ts
+++ b/sdk/src/core-render.ts
@@ -160,6 +160,20 @@ export {
type RenderStats,
} from './render/renderer';
+// =============================================================================
+// Device Loss
+// =============================================================================
+
+export {
+ DeviceStatus,
+ DeviceLostReason,
+ getDeviceStatus,
+ getDeviceLostReport,
+ reportDeviceLost,
+ recoverDevice,
+ finishDeviceRecovery,
+} from './render/renderer';
+
export {
LayerOrder,
layerOrderOf,