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.

fix(render): a device that came back draws its content, not the placeholder

esenginec8ddc8c3d5de
diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.ts
index 6258d814d..52bf280dc 100644
--- a/sdk/src/asset/Assets.ts
+++ b/sdk/src/asset/Assets.ts
@@ -366,6 +366,29 @@ export class Assets {
return this.loadTextureVariant_(ref, false);
}
+ /**
+ * 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.
+ */
+ texturesAwaitingReupload(): { handle: number; path: string }[] {
+ const raw = requireResourceManager().texturesAwaitingReupload?.() ?? '';
+ if (!raw) return [];
+ return raw.split('\n').map((line) => {
+ const cut = line.indexOf('|');
+ return {
+ handle: Number(cut < 0 ? line : line.slice(0, cut)),
+ path: cut < 0 ? '' : line.slice(cut + 1),
+ };
+ });
+ }
+
/**
* Re-uploads every cached texture behind the handle it already has.
*
@@ -415,7 +438,12 @@ export class Assets {
async recoverFromDeviceLoss(): Promise<boolean> {
if (!recoverDevice()) return false;
await this.reuploadTexturesAfterDeviceLoss();
- finishDeviceRecovery();
+ const pending = finishDeviceRecovery();
+ if (pending > 0) {
+ log.warn('assets',
+ `Device recovery: ${pending} texture(s) are still the placeholder`);
+ return false;
+ }
return true;
}
diff --git a/sdk/src/render/renderer.ts b/sdk/src/render/renderer.ts
index 0c72abff1..564493ed9 100644
--- a/sdk/src/render/renderer.ts
+++ b/sdk/src/render/renderer.ts
@@ -211,9 +211,16 @@ 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?.();
+/**
+ * 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.
+ */
+export function finishDeviceRecovery(): number {
+ return module?.markDeviceRestored?.() ?? 0;
}
/**
diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.ts
index 75f9656d5..dcc42b46a 100644
--- a/sdk/src/wasm.ts
+++ b/sdk/src/wasm.ts
@@ -75,6 +75,13 @@ export interface CppResourceManager {
* Optional: absent on an older wasm build.
*/
retargetExternalTexture?(handle: number, glTextureId: number, width: number, height: number): boolean;
+ /**
+ * The textures still parked on the placeholder after a loss, one
+ * `handle|path` per line. A blank path is a texture the asset layer never
+ * loaded — a render target, a glyph atlas — so it is not one to fetch.
+ * Optional: absent on an older wasm build.
+ */
+ texturesAwaitingReupload?(): string;
getTextureGLId(handle: number): number;
getTextureDimensions(handle: number): { width: number; height: number } | null;
releaseTexture(handle: number): void;
@@ -212,8 +219,11 @@ export interface ESEngineModule {
* On success the device is Recovering: drawing, with placeholder textures.
*/
recoverDevice?(): boolean;
- /** End recovery once the textures are back. */
- markDeviceRestored?(): void;
+ /**
+ * End recovery — the engine decides whether it actually ended. Returns how
+ * many textures are still on the placeholder; 0 means the device is Live.
+ */
+ markDeviceRestored?(): number;
/**
* 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/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cpp
index c3d605863..60fa0cd23 100644
--- a/src/esengine/bindings/ResourceManagerBindings.cpp
+++ b/src/esengine/bindings/ResourceManagerBindings.cpp
@@ -131,6 +131,22 @@ bool rm_retargetExternalTexture(resource::ResourceManager& rm, u32 handle,
return rm.retargetExternalTexture(resource::TextureHandle(handle), glTextureId, width, height);
}
+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".
+ std::string out;
+ for (resource::TextureHandle handle : rm.texturesAwaitingReupload()) {
+ if (!out.empty()) out += '\n';
+ out += std::to_string(handle.id());
+ out += '|';
+ out += rm.getTexturePath(handle);
+ }
+ return out;
+}
+
u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,
u32 width, u32 height, u32 bytes) {
auto handle = rm.registerExternalTexture(glTextureId, width, height,
diff --git a/src/esengine/bindings/ResourceManagerBindings.hpp b/src/esengine/bindings/ResourceManagerBindings.hpp
index 299521be5..2e90b1774 100644
--- a/src/esengine/bindings/ResourceManagerBindings.hpp
+++ b/src/esengine/bindings/ResourceManagerBindings.hpp
@@ -38,6 +38,9 @@ u32 rm_registerExternalTexture(resource::ResourceManager& rm, u32 glTextureId,
bool rm_retargetExternalTexture(resource::ResourceManager& rm, u32 handle,
u32 glTextureId, u32 width, u32 height);
+/** @brief The textures still parked on the placeholder, as `handle|path` lines. */
+std::string rm_texturesAwaitingReupload(resource::ResourceManager& rm);
+
u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,
u32 width, u32 height, u32 bytes);
void rm_releaseTexture(resource::ResourceManager& rm, u32 handleId);
diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cpp
index 0e92b2b76..84981a80a 100644
--- a/src/esengine/bindings/WebSDKEntry.cpp
+++ b/src/esengine/bindings/WebSDKEntry.cpp
@@ -306,9 +306,16 @@ 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 Ends recovery, and answers whether it actually ended.
+ * @details Routed through the context rather than straight to the device: the
+ * device cannot see the textures still parked on the placeholder, and
+ * the context is the one layer that knows both. Reaching for the
+ * device here is the shorter path that skips the only criterion.
+ * @return Textures still awaiting re-upload; 0 means the device is Live.
+ */
+u32 markDeviceRestored() {
+ return g_activeContext ? g_activeContext->finishDeviceRecovery() : 0;
}
/**
@@ -450,6 +457,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {
.function("registerExternalTexture", &esengine::rm_registerExternalTexture)
.function("registerExternalTextureSized", &esengine::rm_registerExternalTextureSized)
.function("retargetExternalTexture", &esengine::rm_retargetExternalTexture)
+ .function("texturesAwaitingReupload", &esengine::rm_texturesAwaitingReupload)
.function("releaseTexture", &esengine::rm_releaseTexture)
.function("getTextureRefCount", &esengine::rm_getTextureRefCount)
.function("releaseShader", &esengine::rm_releaseShader)
diff --git a/src/esengine/core/EstellaContext.cpp b/src/esengine/core/EstellaContext.cpp
index c5ceff9db..4e8df043a 100644
--- a/src/esengine/core/EstellaContext.cpp
+++ b/src/esengine/core/EstellaContext.cpp
@@ -142,6 +142,16 @@ bool EstellaContext::recoverDevice() {
return true;
}
+u32 EstellaContext::finishDeviceRecovery() {
+ auto* resources = services_.getService<resource::ResourceManager>();
+ const u32 pending = resources
+ ? static_cast<u32>(resources->texturesAwaitingReupload().size())
+ : 0;
+ if (pending > 0) return pending;
+ if (auto* device = services_.getService<GfxDevice>()) device->markDeviceRestored();
+ return 0;
+}
+
void EstellaContext::initSubsystems(Unique<GfxDevice> gfxDevice) {
// The device arrives first: ResourceManager (the GPU-resource factory) and
// every other renderer subsystem borrow this single device. Which backend
diff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hpp
index 3a67d2957..f09c75f6c 100644
--- a/src/esengine/core/EstellaContext.hpp
+++ b/src/esengine/core/EstellaContext.hpp
@@ -57,6 +57,18 @@ public:
*/
bool recoverDevice();
+ /**
+ * @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.
+ * @return Textures still on the placeholder; 0 means the device is Live.
+ */
+ u32 finishDeviceRecovery();
+
/**
* @brief Shut down all subsystems and release resources
*/
diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cpp
index ab4958a7a..68310bb92 100644
--- a/src/esengine/resource/ResourceManager.cpp
+++ b/src/esengine/resource/ResourceManager.cpp
@@ -333,7 +333,17 @@ void ResourceManager::setTextureBudget(usize bytes) {
TextureHandle ResourceManager::acquireTextureByPath(const std::string& path) {
auto handle = textures_.findByPath(path);
- if (handle.isValid()) textures_.addRef(handle);
+ 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.
+ for (TextureHandle awaiting : awaitingReupload_) {
+ if (awaiting == handle) return TextureHandle{};
+ }
+ textures_.addRef(handle);
return handle;
}