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): take the GPU away for real, and see what happens
esengine28733f12376f
diff --git a/desktop/scripts/headless-verify.mjs b/desktop/scripts/headless-verify.mjsindex 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.tsindex 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.mdindex 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 @@ PrefabsPluginReplicationPlugin```+## reportDeviceLost — function+```+(reason: number, message: string): void+```+## requireResourceManager — function```(): CppResourceManagerdiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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 @@ PrefabsPluginReplicationPlugin```+## reportDeviceLost — function+```+(reason: number, message: string): void+```+## requireResourceManager — function```(): CppResourceManagerdiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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 @@ PrefabsPluginReplicationPlugin```+## reportDeviceLost — function+```+(reason: number, message: string): void+```+## requireResourceManager — function```(): CppResourceManagerdiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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 @@ PrefabsPluginReplicationPlugin```+## reportDeviceLost — function+```+(reason: number, message: string): void+```+## requireResourceManager — function```(): CppResourceManagerdiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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 @@ PrefabsPluginReplicationPlugin```+## reportDeviceLost — function+```+(reason: number, message: string): void+```+## requireResourceManager — function```(): CppResourceManagerdiff --git a/sdk/src/core-render.ts b/sdk/src/core-render.tsindex 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,