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
chore(api): the recovery list and the count it answers with
esengine26a3adf1f673
diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 473d8b61b..ba4dc25bf 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -787,6 +787,7 @@ setRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetSpineController: (controller: SpineModuleController) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+texturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassstatic prototype: AssetsClass@@ -9649,7 +9650,7 @@ EventBindingPlugin## finishDeviceRecovery — function @experimental```-(): void+(): number```## flattenPrefab — function @experimentaldiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex 23343a08a..735f23940 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -787,6 +787,7 @@ setRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetSpineController: (controller: SpineModuleController) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+texturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassstatic prototype: AssetsClass@@ -9882,7 +9883,7 @@ EventBindingPlugin## finishDeviceRecovery — function @experimental```-(): void+(): number```## flattenPrefab — function @experimentaldiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 50f3ae974..2c61c9455 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetSpineController: (controller: SpineModuleController) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+texturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassstatic prototype: AssetsClass@@ -9644,7 +9645,7 @@ EventBindingPlugin## finishDeviceRecovery — function @experimental```-(): void+(): number```## flattenPrefab — function @experimentaldiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex f84688f98..6ab70bddd 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetSpineController: (controller: SpineModuleController) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+texturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassstatic prototype: AssetsClass@@ -9894,7 +9895,7 @@ EventBindingPlugin## finishDeviceRecovery — function @experimental```-(): void+(): number```## flattenPrefab — function @experimentaldiff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.mdindex ae2c2d3df..c0f86641e 100644--- a/sdk/etc/wasm.api.md+++ b/sdk/etc/wasm.api.md@@ -170,6 +170,7 @@ retargetExternalTexture: ((handle: number, glTextureId: number, width: number, hsetTextureBudget: (bytes: number) => voidsetTextureMetadata: (handle: number, left: number, right: number, top: number, bottom: number) => voidsupportsCompressedFormat: ((format: number) => boolean) | undefined+texturesAwaitingReupload: (() => string) | undefinedtrimTextureCache: () => numberupdateTextureSubregion: (handle: number, x: number, y: number, width: number, height: number, pixels: number, pixelsLen: number) => voidupdateTextureSubregionFromBytes: ((handle: number, x: number, y: number, width: number, height: number, pixels: Uint8Array) => void) | undefined@@ -250,7 +251,7 @@ initRenderer: () => voidinitRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean, preferBGRA: boolean) => booleaninitRendererWithCanvas: (canvasSelector: string) => booleaninitRendererWithContext: (contextHandle: number) => boolean-markDeviceRestored: (() => void) | undefined+markDeviceRestored: (() => number) | undefinedmaterial_compileEsshader: (source: string, featuresCsv: string) => numbermaterial_define: (materialId: number, shaderHandle: number, blendMode: number, flags: number) => voidmaterial_setTexture: (materialId: number, name: string, textureHandle: number) => voiddiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 653ea48a6..88d8681f0 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => voidsetRemoteRoot: (url: string | undefined) => voidsetSpineController: (controller: SpineModuleController) => voidsetTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void+texturesAwaitingReupload: () => { handle: number; path: string; }[]static create: (options: AssetsOptions) => AssetsClassstatic new (options: AssetsOptions): AssetsClassstatic prototype: AssetsClass@@ -9671,7 +9672,7 @@ EventBindingPlugin## finishDeviceRecovery — function @experimental```-(): void+(): number```## flattenPrefab — function @experimentaldiff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 52bf280dc..031f24b4c 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -367,15 +367,10 @@ export class Assets {}/**- * The textures the engine says are still the placeholder, with the path each- * was registered under.- *- * This list is the engine's, not a mirror of this cache: a loss sweeps EVERY- * texture onto the placeholder, including the ones another subsystem- * uploaded, and recovering only the ones this layer happens to remember is- * how a device reports itself whole while half the screen is white. An empty- * path is a texture the asset layer never loaded — a render target, a glyph- * atlas — and belongs to whoever created it.+ * The textures still on the placeholder, and the path each was registered+ * under — the engine's list, not a mirror of this cache. A loss sweeps every+ * texture, so restoring only what this layer remembers reports a whole+ * device with half the screen white. A blank path is not the asset layer's.*/texturesAwaitingReupload(): { handle: number; path: string }[] {const raw = requireResourceManager().texturesAwaitingReupload?.() ?? '';diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.tsindex 564493ed9..5bcb88fa6 100644--- a/sdk/src/render/renderer.ts+++ b/sdk/src/render/renderer.ts@@ -212,12 +212,9 @@ export function recoverDevice(): boolean {}/**- * Ends recovery — the engine decides whether it actually ended.- *- * Returns the number of textures still on the placeholder. Anything above zero- * leaves the device Recovering, because a device that reports Live while half- * its content is a white placeholder is the hardest failure to read: the status- * says healthy and the screen disagrees.+ * Ends recovery — the engine decides whether it actually ended, and answers how+ * many textures are still the placeholder. Above zero it stays Recovering: a+ * device reporting Live with white content is the hardest failure to read.*/export function finishDeviceRecovery(): number {return module?.markDeviceRestored?.() ?? 0;diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cppindex 60fa0cd23..6658a6575 100644--- a/src/esengine/bindings/ResourceManagerBindings.cpp+++ b/src/esengine/bindings/ResourceManagerBindings.cpp@@ -132,11 +132,9 @@ bool rm_retargetExternalTexture(resource::ResourceManager& rm, u32 handle,}std::string rm_texturesAwaitingReupload(resource::ResourceManager& rm) {- // One crossing, because a loss parks EVERY texture at once — asking per- // handle would be a call per texture on the frame after a loss. An empty- // path names a texture no asset layer can bring back (a render target, a- // glyph atlas); it belongs to whoever created it, and saying so is what- // lets the caller tell "not mine" from "mine and I failed".+ // One crossing: a loss parks every texture at once, so a call per handle is+ // a call per texture. A blank path is one no asset layer can bring back —+ // it lets the caller tell "not mine" from "mine and I failed".std::string out;for (resource::TextureHandle handle : rm.texturesAwaitingReupload()) {if (!out.empty()) out += '\n';diff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hppindex f09c75f6c..0868039fc 100644--- a/src/esengine/core/EstellaContext.hpp+++ b/src/esengine/core/EstellaContext.hpp@@ -59,12 +59,10 @@ public:/*** @brief Ends recovery — if the content is actually back.- * @details The engine holds this criterion, so declaring the device whole- * is not the caller's to assert: a loss parks every texture on the- * placeholder and lists it until something re-uploads it. A caller- * that restored half of them would otherwise report Live and draw- * the other half white, which is the state hardest to diagnose —- * the report says healthy and the screen disagrees.+ * @details The engine holds the criterion, so declaring the device whole is+ * not the caller's to assert: one that restored half its textures+ * would report Live and draw the rest white, the hardest state to+ * read — the report says healthy and the screen disagrees.* @return Textures still on the placeholder; 0 means the device is Live.*/u32 finishDeviceRecovery();diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex 68310bb92..cf15c1ec5 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -334,12 +334,9 @@ void ResourceManager::setTextureBudget(usize bytes) {TextureHandle ResourceManager::acquireTextureByPath(const std::string& path) {auto handle = textures_.findByPath(path);if (!handle.isValid()) return handle;- // A texture parked on the placeholder no longer holds this path's content,- // so answering a load with it hands back the very thing the load exists to- // replace. The re-upload after a device loss is exactly such a load: it- // would revive the placeholder, retarget the handle onto it, and report the- // content restored — a recovery that confirms itself and draws white.- // Linear because this list is empty except inside a recovery window.+ // A texture on the placeholder no longer holds this path's content, so a+ // residency hit answers the re-upload with the very thing it replaces — a+ // recovery that confirms itself and draws white. Linear: empty at rest.for (TextureHandle awaiting : awaitingReupload_) {if (awaiting == handle) return TextureHandle{};}diff --git a/tools/check-cpp-tests.mjs b/tools/check-cpp-tests.mjsindex b8712ad32..93c760f11 100644--- a/tools/check-cpp-tests.mjs+++ b/tools/check-cpp-tests.mjs@@ -52,12 +52,9 @@ function enginelinked() {const targets = harnessTargets();-// The other direction, and the one that actually bit: CI's list is treated as-// authoritative everywhere, so a harness the test tree declares but the list-// omits is built by nobody and run by nobody — the exact failure the list was-// introduced to end, arriving from the side it does not look at.-// `test_device_loss` sat there. This half needs no compiler, so unlike the-// build below it runs on every machine.+// The other direction: a harness the test tree declares and CI's list omits is+// built by nobody and run by nobody — the failure that list exists to end,+// from the side it never looks at. No compiler needed, so this half always runs.const uncovered = declaredHarnesses().filter((t) => !targets.includes(t));if (uncovered.length) {console.error(`check-cpp-tests: tests/CMakeLists.txt declares ${uncovered.join(', ')},`diff --git a/tools/renderScenes.mjs b/tools/renderScenes.mjsindex eab077939..9818007fb 100644--- a/tools/renderScenes.mjs+++ b/tools/renderScenes.mjs@@ -112,13 +112,9 @@ export const SCENES = [{ id: "material-preview", tier: "pr", webgpu: { ESTELLA_VERIFY_EXPECT: "[{\"x\":0.5,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" }, env: { ESTELLA_VERIFY_SCENE: "/scenes/mat-tint.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/mat-tint.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_PREVIEW: "{\"w\":64,\"h\":64,\"rgb\":[255,0,0],\"tol\":45}" } },{ id: "tilemap-hex", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_SCENE: "/scenes/tilemap-hex.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/tilemap-hex.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "6", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.40,\"y\":0.40,\"rgb\":[255,0,0]},{\"x\":0.60,\"y\":0.40,\"rgb\":[0,255,0]},{\"x\":0.50,\"y\":0.55,\"rgb\":[0,0,255]},{\"x\":0.70,\"y\":0.55,\"rgb\":[255,255,0]}]" } },{ id: "postprocess-lut", tier: "nightly", webgpu: true, env: { ESTELLA_VERIFY_PLAY: "1", ESTELLA_VERIFY_SCENE: "/scenes/lut-grade.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/lut-grade.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "10", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.292,\"y\":0.5,\"rgb\":[0,0,255],\"tol\":40},{\"x\":0.708,\"y\":0.5,\"rgb\":[255,0,0],\"tol\":40}]" } },- // Takes the GPU away for real (WEBGL_lose_context) and drives the whole- // recovery. It reuses tilemap-flip because the capture happens AFTER the- // cycle, and those four points are SAMPLED FROM ITS ATLAS — so they fail- // unless the asset layer put the content back, which is the half of recovery- // no backend can do for itself. A scene whose colours come from vertices- // passes with the re-upload deleted; this one was chosen by breaking it.- // No `webgpu` — a WebGPU device cannot be taken away through a GL extension.+ // Takes the GPU away for real and captures AFTER the cycle: the four points+ // sample the atlas, so they fail unless the content came back. A vertex-colour+ // scene passed with the re-upload deleted. No webgpu — no GL extension there.{ id: "device-loss", tier: "pr", env: { ESTELLA_VERIFY_DEVICE_LOSS: "1", ESTELLA_VERIFY_SCENE: "/scenes/tilemap-flip.esscene", ESTELLA_VERIFY_MANIFEST: "/scenes/tilemap-flip.textures.json", ESTELLA_VERIFY_W: "256", ESTELLA_VERIFY_H: "256", ESTELLA_VERIFY_STEPS: "2", ESTELLA_VERIFY_EXPECT: "[{\"x\":0.40,\"y\":0.36,\"rgb\":[255,0,0]},{\"x\":0.60,\"y\":0.36,\"rgb\":[0,255,0]},{\"x\":0.40,\"y\":0.58,\"rgb\":[0,0,255]},{\"x\":0.60,\"y\":0.58,\"rgb\":[255,255,0]}]" } },];