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.

feat(diagnostics): a lost device now names the GPU and driver

esengine0454723bac2a
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index b39146f6f..f3d15d199 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2530,6 +2530,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2587,6 +2589,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index fe7c800e1..986189ebc 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2538,6 +2538,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2595,6 +2597,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index d14a61a76..a2a7a64b0 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2525,6 +2525,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2582,6 +2584,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 3a5072e29..45a058d02 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2525,6 +2525,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2582,6 +2584,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 87c960580..6b4593e75 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -192,6 +192,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -249,6 +251,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 30a9cc069..1ef1d18da 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2525,6 +2525,8 @@ anim_resumeTween: (registry: CppRegistry, tweenEntity: number) => void
anim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => void
anim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => void
anim_updateTweens: (registry: CppRegistry, deltaTime: number) => void
+deviceLostReport: (() => string) | undefined
+deviceStatus: (() => number) | undefined
draw_begin: (matrixPtr: number) => void
draw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => void
draw_circleOutline: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, thickness: number, segments: number) => void
@@ -2582,6 +2584,7 @@ material_setTexture: (materialId: number, name: string, textureHandle: number) =
material_setUniform: (materialId: number, name: string, arity: number, v0: number, v1: number, v2: number, v3: number) => void
material_undefine: (materialId: number) => void
mesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined
+notifyDeviceLost: ((reason: number, message: string) => void) | undefined
particle_getAliveCount: ((entity: number) => number) | undefined
particle_play: ((registry: CppRegistry, entity: number) => void) | undefined
particle_reset: ((registry: CppRegistry, entity: number) => void) | undefined
diff --git a/sdk/src/app/app.ts b/sdk/src/app/app.ts
index f84f99f97..f410804f8 100644
--- a/sdk/src/app/app.ts
+++ b/sdk/src/app/app.ts
@@ -30,6 +30,7 @@ import { ScreenScaling, SCREEN_FIT_OFF, type ScreenScalingData } from '../camera
import { PhysicsRuntime } from '../physics/PhysicsRuntime';
import { SubsystemRegistry } from './subsystems';
import type { SideModuleHost } from '../sideModules/host';
+import { watchWebGPUDeviceLoss } from '../render/renderer';
import { log } from '../util/logger';
// =============================================================================
@@ -1253,6 +1254,7 @@ export function createWebApp(module: ESEngineModule, options?: WebAppOptions): A
'WebGPU renderer initialization failed — the module needs a ' +
'preinitializedWebGPUDevice and a WebGPU-enabled engine build.');
}
+ watchWebGPUDeviceLoss(module);
break;
}
case 'gl-context':
diff --git a/sdk/src/diagnostics/DiagnosticsPlugin.ts b/sdk/src/diagnostics/DiagnosticsPlugin.ts
index b4ead4297..1804cdd43 100644
--- a/sdk/src/diagnostics/DiagnosticsPlugin.ts
+++ b/sdk/src/diagnostics/DiagnosticsPlugin.ts
@@ -36,6 +36,9 @@ import { log, LogLevel, type LogEntry, type LogHandler } from '../util/logger';
import {
platformOnContextLost, platformOnMemoryWarning, platformOnUnhandledError,
} from '../platform';
+import {
+ DeviceLostReason, DeviceStatus, getDeviceLostReport, getDeviceStatus, reportDeviceLost,
+} from '../render/renderer';
import { Diagnostics, DiagnosticsAPI, type DiagnosticsOptions } from './Diagnostics';
export interface DiagnosticsPluginOptions extends DiagnosticsOptions {
@@ -81,14 +84,24 @@ export class DiagnosticsPlugin implements Plugin {
this.handler_ = new DiagnosticsLogHandler(api, this.options_.captureLevel ?? LogLevel.Error);
log.addHandler(this.handler_);
+ // Shared by both loss paths below so a single loss is reported once,
+ // whichever of them saw it first.
+ let lastDeviceStatus: number = DeviceStatus.Live;
+ const reportLoss = (fallback: string): void => {
+ lastDeviceStatus = getDeviceStatus();
+ api.report({ kind: 'context-lost', message: getDeviceLostReport() || fallback });
+ };
+
this.unsubscribes_.push(
platformOnUnhandledError((error) => api.reportError('unhandled', error)),
- // No error object and nothing to name: what matters is that it
- // happened, and when. The frames after it draw nothing.
- platformOnContextLost(() => api.report({
- kind: 'context-lost',
- message: 'The rendering context was lost',
- })),
+ // The event itself names nothing. Handed to the engine first, it
+ // stops submission on this frame and comes back naming the backend,
+ // GPU and driver recorded while they could still be asked.
+ platformOnContextLost(() => {
+ reportDeviceLost(DeviceLostReason.ContextLost,
+ 'The host reported the rendering context was lost');
+ reportLoss('The rendering context was lost');
+ }),
// Reported rather than acted on — the residency caches already
// subscribe to this and trim themselves. What this adds is the
// record, because the process being killed a moment later is the
@@ -102,6 +115,16 @@ export class DiagnosticsPlugin implements Plugin {
app.addSystemToSchedule(Schedule.Last, defineSystem(
[],
() => {
+ // The engine notices losses the page never hears about (a GL
+ // error check, a WebGPU callback inside wasm). One integer read
+ // per frame is what gets those into a report.
+ const status = getDeviceStatus();
+ if (status !== lastDeviceStatus) {
+ lastDeviceStatus = status;
+ if (status !== DeviceStatus.Live) {
+ reportLoss('The GPU device was lost');
+ }
+ }
const time = app.getResource(Time);
app.getResource(Diagnostics)?.tick(time?.delta ?? 0);
},
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index e40a7dcc6..df942a1bc 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -131,6 +131,61 @@ function wasmBackend(m: ESEngineModule): RendererBackend {
};
}
+/** GPU device status, mirroring the engine's `GfxDeviceStatus`. */
+export const DeviceStatus = { Live: 0, Lost: 1, Recovering: 2, Dead: 3 } as const;
+
+/** Why a device was lost, mirroring the engine's `GfxDeviceLostReason`. */
+export const DeviceLostReason = {
+ Unknown: 0, ContextLost: 1, OutOfMemory: 2, Reset: 3,
+ Removed: 4, Destroyed: 5, Validation: 6, Internal: 7,
+} as const;
+
+/**
+ * Whether the GPU device can still be drawn to.
+ *
+ * Reports `Live` when the core cannot answer — an older wasm build, or a native
+ * backend with no heap to marshal. Treating "cannot tell" as a loss would black
+ * out every host predating this call.
+ */
+export function getDeviceStatus(): number {
+ return module?.deviceStatus?.() ?? DeviceStatus.Live;
+}
+
+/** The engine's one-line loss report (backend, GPU, driver, reason); empty while live. */
+export function getDeviceLostReport(): string {
+ return module?.deviceLostReport?.() ?? '';
+}
+
+/**
+ * Tell the engine about a loss the host observed.
+ *
+ * The browser reports context loss to JS, not to wasm, so without this the core
+ * keeps submitting until its own next poll notices.
+ */
+export function reportDeviceLost(reason: number, message: string): void {
+ module?.notifyDeviceLost?.(reason, message);
+}
+
+/**
+ * Subscribe to the host's `GPUDevice.lost`.
+ *
+ * WebGPU reports loss to whoever holds the JS device object, never to the
+ * engine — the page acquires it before the module exists. Reading it back off
+ * the module lets ONE subscription cover every host, instead of each wiring its own.
+ */
+export function watchWebGPUDeviceLoss(wasmModule: ESEngineModule): void {
+ const device = (wasmModule as unknown as {
+ preinitializedWebGPUDevice?: { lost?: Promise<{ reason?: string; message?: string }> };
+ }).preinitializedWebGPUDevice;
+ void device?.lost?.then((info) => {
+ // `destroyed` is us tearing the device down, not a failure.
+ const reason = info?.reason === 'destroyed'
+ ? DeviceLostReason.Destroyed
+ : DeviceLostReason.Unknown;
+ reportDeviceLost(reason, info?.message ?? 'The GPUDevice reported itself lost');
+ });
+}
+
/** @internal Wired by the engine plugins — not part of the public API. */
export function initRendererAPI(wasmModule: ESEngineModule): void {
bridge.connect(wasmModule);
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 6850c123f..4784c3939 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -176,6 +176,20 @@ export interface ESEngineModule {
* pointers to width*height byte buffers; the SDF is written into `outPtr`.
*/
sdfFromAlpha?(alphaPtr: number, outPtr: number, width: number, height: number, spread: number): void;
+ /**
+ * Whether the GPU device can still be drawn to: 0 live, 1 lost, 2 recovering,
+ * 3 dead. Reports live before a renderer exists — there is nothing to lose yet.
+ * Optional: an older wasm build does not carry it.
+ */
+ deviceStatus?(): number;
+ /** One-line loss report naming backend, GPU, driver and reason; empty while live. */
+ deviceLostReport?(): string;
+ /**
+ * Report a loss the page observed (`webglcontextlost`, a rejected GPUDevice
+ * `lost` promise) so the engine stops submitting on this frame rather than
+ * on its own next poll. Reason codes match GfxDeviceLostReason.
+ */
+ notifyDeviceLost?(reason: number, message: string): void;
/**
* UI draw order of an entity (its UIVisual.uiOrder, assigned by the UI
* render-order pass), so SDF text quads interleave with UI quads. -1 if the
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 5d68792f8..7bedfc86f 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -238,6 +238,43 @@ resource::ResourceManager* getResourceManager() {
return g_resourceManager;
}
+// =============================================================================
+// Device Loss
+// =============================================================================
+
+namespace {
+GfxDevice* activeGfxDevice() {
+ return g_activeContext ? g_activeContext->tryGet<GfxDevice>() : nullptr;
+}
+} // namespace
+
+/** @brief The device's status (see GfxDeviceStatus). Live when no device exists yet. */
+u32 deviceStatus() {
+ GfxDevice* device = activeGfxDevice();
+ return static_cast<u32>(device ? device->deviceStatus() : GfxDeviceStatus::Live);
+}
+
+/** @brief The formatted loss report; empty while the device is live. */
+std::string deviceLostReport() {
+ GfxDevice* device = activeGfxDevice();
+ if (!device) return {};
+ const GfxDeviceLostInfo* info = device->deviceLostInfo();
+ return info ? gfxFormatDeviceLost(*info) : std::string();
+}
+
+/**
+ * @brief Reports a loss the page observed.
+ * @details The browser tells JS, not wasm: `webglcontextlost` fires on the
+ * canvas element and a GPUDevice resolves its `lost` promise. Both
+ * arrive here so the C++ device stops submitting on the same frame
+ * rather than after its own next poll.
+ */
+void notifyDeviceLost(u32 reason, const std::string& message) {
+ if (GfxDevice* device = activeGfxDevice()) {
+ device->notifyDeviceLost(static_cast<GfxDeviceLostReason>(reason), message, "host");
+ }
+}
+
// Runtime glyph atlas: convert a Canvas2D-rasterized alpha
// bitmap to a signed distance field. Both buffers are caller-allocated in WASM
// linear memory (TS passes HEAPU8 pointers); `alpha` and `out` are width*height.
@@ -348,6 +385,9 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
emscripten::function("renderFrameWithMatrix", &esengine::renderFrameWithMatrix);
emscripten::function("getResourceManager", &esengine::getResourceManager, emscripten::allow_raw_pointers());
emscripten::function("sdfFromAlpha", &esengine::web_sdfFromAlpha);
+ emscripten::function("deviceStatus", &esengine::deviceStatus);
+ emscripten::function("deviceLostReport", &esengine::deviceLostReport);
+ emscripten::function("notifyDeviceLost", &esengine::notifyDeviceLost);
emscripten::class_<esengine::resource::ResourceManager>("ResourceManager")
.function("createTexture", &esengine::rm_createTexture)