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.

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.md
index 473d8b61b..ba4dc25bf 100644
--- a/sdk/etc/index.api.md
+++ b/sdk/etc/index.api.md
@@ -787,6 +787,7 @@ setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
static prototype: AssetsClass
@@ -9649,7 +9650,7 @@ EventBindingPlugin
## finishDeviceRecovery — function @experimental
```
-(): void
+(): number
```
## flattenPrefab — function @experimental
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 23343a08a..735f23940 100644
--- a/sdk/etc/index.native.api.md
+++ b/sdk/etc/index.native.api.md
@@ -787,6 +787,7 @@ setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
static prototype: AssetsClass
@@ -9882,7 +9883,7 @@ EventBindingPlugin
## finishDeviceRecovery — function @experimental
```
-(): void
+(): number
```
## flattenPrefab — function @experimental
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 50f3ae974..2c61c9455 100644
--- a/sdk/etc/index.node.api.md
+++ b/sdk/etc/index.node.api.md
@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
static prototype: AssetsClass
@@ -9644,7 +9645,7 @@ EventBindingPlugin
## finishDeviceRecovery — function @experimental
```
-(): void
+(): number
```
## flattenPrefab — function @experimental
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index f84688f98..6ab70bddd 100644
--- a/sdk/etc/minigame.api.md
+++ b/sdk/etc/minigame.api.md
@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
static prototype: AssetsClass
@@ -9894,7 +9895,7 @@ EventBindingPlugin
## finishDeviceRecovery — function @experimental
```
-(): void
+(): number
```
## flattenPrefab — function @experimental
diff --git a/sdk/etc/wasm.api.md b/sdk/etc/wasm.api.md
index 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, h
setTextureBudget: (bytes: number) => void
setTextureMetadata: (handle: number, left: number, right: number, top: number, bottom: number) => void
supportsCompressedFormat: ((format: number) => boolean) | undefined
+texturesAwaitingReupload: (() => string) | undefined
trimTextureCache: () => number
updateTextureSubregion: (handle: number, x: number, y: number, width: number, height: number, pixels: number, pixelsLen: number) => void
updateTextureSubregionFromBytes: ((handle: number, x: number, y: number, width: number, height: number, pixels: Uint8Array) => void) | undefined
@@ -250,7 +251,7 @@ initRenderer: () => void
initRendererWebGPU: (canvasSelector: string, width: number, height: number, readback: boolean, preferBGRA: boolean) => boolean
initRendererWithCanvas: (canvasSelector: string) => boolean
initRendererWithContext: (contextHandle: number) => boolean
-markDeviceRestored: (() => void) | undefined
+markDeviceRestored: (() => number) | 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
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 653ea48a6..88d8681f0 100644
--- a/sdk/etc/wechat.api.md
+++ b/sdk/etc/wechat.api.md
@@ -782,6 +782,7 @@ setRefCounter: (counter: AssetRefCounter) => void
setRemoteRoot: (url: string | undefined) => void
setSpineController: (controller: SpineModuleController) => void
setTextureImportSettingsResolver: (resolver: TextureImportSettingsResolver | null) => void
+texturesAwaitingReupload: () => { handle: number; path: string; }[]
static create: (options: AssetsOptions) => AssetsClass
static new (options: AssetsOptions): AssetsClass
static prototype: AssetsClass
@@ -9671,7 +9672,7 @@ EventBindingPlugin
## finishDeviceRecovery — function @experimental
```
-(): void
+(): number
```
## flattenPrefab — function @experimental
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 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.ts
index 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.cpp
index 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.hpp
index 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.cpp
index 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.mjs
index 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.mjs
index 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]}]" } },
];