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
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.tsindex 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.tsindex 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.tsindex 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 thediff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cppindex 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.hppindex 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.cppindex 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.cppindex 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 backenddiff --git a/src/esengine/core/EstellaContext.hpp b/src/esengine/core/EstellaContext.hppindex 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.cppindex 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;}