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(sdk): expose the recovery control surface to JS

esengine3e8d47192ef3
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.md
index f3d15d199..6ca27b0da 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -2583,6 +2583,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 986189ebc..a8078f25d 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -2591,6 +2591,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index a2a7a64b0..314b48aa7 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -2578,6 +2578,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 45a058d02..ee04fae1b 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -2578,6 +2578,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 6b4593e75..2bf700bf3 100644
--- a/sdk/etc/wasm.api.md
+++ b/sdk/etc/wasm.api.md
@@ -245,6 +245,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 1ef1d18da..c0d3573af 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -2578,6 +2578,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
+markDeviceRestored: (() => void) | undefined
material_compileEsshader: (source: string, featuresCsv: string) => number
material_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => void
material_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) => void
postprocess_setUniformVec4: (passName: string, uniform: string, x: number, y: number, z: number, w: number) => void
postprocess_shutdown: () => void
+recoverDevice: (() => boolean) | undefined
registry_batchSyncPhysicsTransforms: (registry: CppRegistry, bufferPtr: number, count: number, ppu: number) => void
registry_getCameraEntities: (registry: CppRegistry) => number[]
registry_getCanvasEntities: ((registry: CppRegistry) => number[]) | undefined
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index 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.ts
index 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 the
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 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)