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
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.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 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) => voidanim_setSequenceNext: (registry: CppRegistry, tweenEntity: number, nextEntity: number) => voidanim_setTweenBezier: (registry: CppRegistry, tweenEntity: number, p1x: number, p1y: number, p2x: number, p2y: number) => voidanim_updateTweens: (registry: CppRegistry, deltaTime: number) => void+deviceLostReport: (() => string) | undefined+deviceStatus: (() => number) | undefineddraw_begin: (matrixPtr: number) => voiddraw_circle: (centerX: number, centerY: number, radius: number, r: number, g: number, b: number, a: number, filled: boolean, segments: number) => voiddraw_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) => voidmaterial_undefine: (materialId: number) => voidmesh2d_setGeometry: ((registry: CppRegistry, entity: number, posUvPtr: number, vertexCount: number, colorsPtr: number, indicesPtr: number, indexCount: number) => void) | undefined+notifyDeviceLost: ((reason: number, message: string) => void) | undefinedparticle_getAliveCount: ((entity: number) => number) | undefinedparticle_play: ((registry: CppRegistry, entity: number) => void) | undefinedparticle_reset: ((registry: CppRegistry, entity: number) => void) | undefineddiff --git a/sdk/src/app/app.ts b/sdk/src/app/app.tsindex 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 '../cameraimport { 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.tsindex 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.tsindex 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.tsindex 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 thediff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex 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)