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(sdk): expose the recovery control surface to JS
esengine3e8d47192ef3
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex f3d15d199..6ca27b0da 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -2583,6 +2583,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -2623,6 +2624,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 986189ebc..a8078f25d 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -2591,6 +2591,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -2631,6 +2632,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex a2a7a64b0..314b48aa7 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -2578,6 +2578,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -2618,6 +2619,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 45a058d02..ee04fae1b 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -2578,6 +2578,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -2618,6 +2619,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex 6b4593e75..2bf700bf3 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -245,6 +245,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -285,6 +286,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 1ef1d18da..c0d3573af 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -2578,6 +2578,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean+markDeviceRestored: (() => void) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => void@@ -2618,6 +2619,7 @@ postprocess_setScreenUniformVec4: (passName: string, uniform: string, x: number,postprocess_setUniformFloat: (passName: string, uniform: string, value: number) => voidpostprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => voidpostprocess_shutdown: () => void+recoverDevice: (() => boolean) | undefinedregistry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => voidregistry_getCameraEntities: (registry: CppRegistry) => number[]registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefineddiff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex df942a1bc..624150be7 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -166,6 +166,22 @@ export function reportDeviceLost(reason: number, message: string): void {module?.notifyDeviceLost?.(reason, message);}+/**+ * Ask the engine to rebuild the renderer after a loss.+ *+ * False means "not yet", not "never": a browser hands a WebGL context back when+ * it is ready. On success the device is Recovering — drawing, with placeholder+ * textures — until {@link finishDeviceRecovery}.+ */+export function recoverDevice(): boolean {+ return module?.recoverDevice?.() ?? false;+}++/** Ends recovery: call once the asset layer has re-uploaded the textures. */+export function finishDeviceRecovery(): void {+ module?.markDeviceRestored?.();+}+/*** Subscribe to the host's `GPUDevice.lost`.*diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex 4784c3939..ba680f5bf 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -190,6 +190,14 @@ export interface ESEngineModule {* on its own next poll. Reason codes match GfxDeviceLostReason.*/notifyDeviceLost?(reason: number, message: string): void;+ /**+ * Rebuild the renderer after a loss. False means "not yet" — a browser+ * restores a context when it is ready, so this is expected to be retried.+ * On success the device is Recovering: drawing, with placeholder textures.+ */+ recoverDevice?(): boolean;+ /** End recovery once the textures are back. */+ markDeviceRestored?(): 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 7bedfc86f..2cf547ad6 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -262,6 +262,21 @@ std::string deviceLostReport() {return info ? gfxFormatDeviceLost(*info) : std::string();}+/**+ * @brief Rebuilds the renderer after a loss; see EstellaContext::recoverDevice.+ * @details Leaves the device Recovering — drawable, but its textures are+ * placeholders until the asset layer re-uploads and calls+ * markDeviceRestored.+ */+bool recoverDevice() {+ return g_activeContext ? g_activeContext->recoverDevice() : false;+}++/** @brief Ends recovery: the content is back and the device is fully itself. */+void markDeviceRestored() {+ if (GfxDevice* device = activeGfxDevice()) device->markDeviceRestored();+}+/*** @brief Reports a loss the page observed.* @details The browser tells JS, not wasm: `webglcontextlost` fires on the@@ -388,6 +403,8 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {emscripten::function("deviceStatus", &esengine::deviceStatus);emscripten::function("deviceLostReport", &esengine::deviceLostReport);emscripten::function("notifyDeviceLost", &esengine::notifyDeviceLost);+ emscripten::function("recoverDevice", &esengine::recoverDevice);+ emscripten::function("markDeviceRestored", &esengine::markDeviceRestored);emscripten::class_<esengine::resource::ResourceManager>("ResourceManager").function("createTexture", &esengine::rm_createTexture)