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
feat(assets): compressed textures bill their real VRAM size; editor VRAM readout
yhhc03623c484da
diff --git a/desktop/src/engine/StatsStore.ts b/desktop/src/engine/StatsStore.tsindex ddb21d923..3ac23c6a5 100644--- a/desktop/src/engine/StatsStore.ts+++ b/desktop/src/engine/StatsStore.ts@@ -1,6 +1,7 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { createStore } from 'zustand/vanilla';+import { getResourceStats } from 'esengine';import { EngineHost } from './EngineHost';import { SceneModel } from './SceneModel';import { useSelection } from '@/store/selectionStore';@@ -12,11 +13,20 @@ export interface SelTransform {rot: number;}+/** Texture residency for the status bar (bytes; evictable = warm cache). */+export interface VramReadout {+ bytes: number;+ budget: number;+ evictable: number;+}+export interface StatsSnapshot {fps: number;entities: number;/** The transform of the single selected entity, or null (0 or >1 selected). */selection: SelTransform | null;+ /** Resident texture memory vs budget, or null before the engine is up. */+ vram: VramReadout | null;}const round1 = (n: number) => Math.round(n * 10) / 10;@@ -38,11 +48,25 @@ function sampleSelection(): SelTransform | null {const selEq = (a: SelTransform | null, b: SelTransform | null): boolean =>a === b || (!!a && !!b && a.x === b.x && a.y === b.y && a.rot === b.rot);+/** Sample texture residency from the engine's resource stats, or null. */+function sampleVram(): VramReadout | null {+ const stats = getResourceStats();+ if (!stats) return null;+ return {+ bytes: stats.textureBytes,+ budget: stats.textureBudget,+ evictable: stats.textureEvictableCount,+ };+}++const vramEq = (a: VramReadout | null, b: VramReadout | null): boolean =>+ a === b || (!!a && !!b && a.bytes === b.bytes && a.budget === b.budget && a.evictable === b.evictable);+// Live editor telemetry for the status bar: real FPS (measured here), live// entity count, and the viewport cursor's world position. Updated a few times// a second (not per frame) to avoid churning the status bar.class StatsStoreImpl {- private readonly store = createStore<StatsSnapshot>(() => ({ fps: 0, entities: 0, selection: null }));+ private readonly store = createStore<StatsSnapshot>(() => ({ fps: 0, entities: 0, selection: null, vram: null }));// Pointer-rate churn stays out of the slow-stats subscribers.private readonly cursorStore = createStore<{ x: number; y: number } | null>(() => null);@@ -67,8 +91,10 @@ class StatsStoreImpl {this.windowStart = t;const cur = this.store.getState();const selection = sampleSelection();- if (fps !== cur.fps || entities !== cur.entities || !selEq(selection, cur.selection)) {- this.store.setState({ fps, entities, selection });+ const vram = sampleVram();+ if (fps !== cur.fps || entities !== cur.entities+ || !selEq(selection, cur.selection) || !vramEq(vram, cur.vram)) {+ this.store.setState({ fps, entities, selection, vram });}}};diff --git a/desktop/src/layout/StatusBar.tsx b/desktop/src/layout/StatusBar.tsxindex 3768ed811..42fdbd7f3 100644--- a/desktop/src/layout/StatusBar.tsx+++ b/desktop/src/layout/StatusBar.tsx@@ -1,13 +1,15 @@// SPDX-License-Identifier: Apache-2.0// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Teamimport { useSyncExternalStore } from 'react';-import { Gauge, MousePointer2, Boxes, FolderOpen } from 'lucide-react';+import { Gauge, MousePointer2, Boxes, FolderOpen, MemoryStick } from 'lucide-react';import { useEditorStore } from '@/store/editorStore';import { useSelection } from '@/store/selectionStore';import { StatsStore } from '@/engine/StatsStore';import { SubsystemIndicator } from './SubsystemIndicator';import { Perf } from '@/components/Perf';+const formatMb = (bytes: number) => (bytes / (1024 * 1024)).toFixed(1);+// Only this text node re-renders on mouse move, never the footer.function CursorReadout() {const cursor = useSyncExternalStore(StatsStore.subscribeCursor, StatsStore.getCursor);@@ -63,6 +65,16 @@ export function StatusBar() {<span className="sitem mono"><Boxes size={11} strokeWidth={1.85} /> {stats.entities} entities</span>+ {stats.vram && (+ <span+ className="sitem mono"+ title={`Resident texture memory / budget · ${stats.vram.evictable} cached (evictable) texture(s)`}+ >+ <MemoryStick size={11} strokeWidth={1.85} />+ {formatMb(stats.vram.bytes)}+ <span className="smute">/{formatMb(stats.vram.budget)} MB</span>+ </span>+ )}<span className="sitem smute">esengine 0.10.0</span></footer>);diff --git a/sdk/src/asset/compressed.ts b/sdk/src/asset/compressed.tsindex ea4e1c6bc..ff610be04 100644--- a/sdk/src/asset/compressed.ts+++ b/sdk/src/asset/compressed.ts@@ -150,11 +150,26 @@ function applyParams(gl: WebGL2RenderingContext, opts?: CompressedUploadOptions)gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_WRAP_T, wrap);}-function registerGlTexture(module: ESEngineModule, texture: WebGLTexture, width: number, height: number): number {+/**+ * Register an uploaded GL texture with the C++ pool. `gpuBytes` is the actual+ * VRAM size for the eviction budget — compressed formats are 4–8× smaller than+ * the pool's RGBA8 estimate, so billing them at the estimate would squat on+ * most of the budget. 0 keeps the estimate (RGBA8 uploads, where it's exact).+ */+function registerGlTexture(+ module: ESEngineModule, texture: WebGLTexture,+ width: number, height: number, gpuBytes = 0,+): number {const glObj = module.GL;const id = glObj.getNewId(glObj.textures);glObj.textures[id] = texture;- return requireResourceManager().registerExternalTexture(id, width, height);+ const rm = requireResourceManager();+ // Older wasm builds / minimal mocks lack the sized variant — fall back to+ // the estimate rather than fail the upload.+ if (gpuBytes > 0 && typeof rm.registerExternalTextureSized === 'function') {+ return rm.registerExternalTextureSized(id, width, height, gpuBytes);+ }+ return rm.registerExternalTexture(id, width, height);}/** Upload pre-transcoded compressed blocks via `gl.compressedTexImage2D`. */@@ -176,7 +191,10 @@ export function uploadCompressedTexture(gl.deleteTexture(texture);throw err;}- return { handle: registerGlTexture(module, texture, t.width, t.height), width: t.width, height: t.height };+ return {+ handle: registerGlTexture(module, texture, t.width, t.height, t.data.byteLength),+ width: t.width, height: t.height,+ };}/** Fallback: upload decoded RGBA8 via `gl.texImage2D`. */diff --git a/sdk/src/wasm.ts b/sdk/src/wasm.tsindex d905ad66f..94fb3d803 100644--- a/sdk/src/wasm.ts+++ b/sdk/src/wasm.ts@@ -44,6 +44,10 @@ export interface CppResourceManager {createTextureEx(width: number, height: number, pixels: number, pixelsLen: number, format: number, flipY: boolean, filterMode: number, wrapMode: number): number;createShader(vertSrc: string, fragSrc: string): number;registerExternalTexture(glTextureId: number, width: number, height: number): number;+ /** Like registerExternalTexture, but with the actual GPU byte size for the+ * eviction budget (compressed textures are 4–8× smaller than the RGBA8+ * estimate the plain variant books). */+ registerExternalTextureSized(glTextureId: number, width: number, height: number, bytes: number): number;getTextureGLId(handle: number): number;getTextureDimensions(handle: number): { width: number; height: number } | null;releaseTexture(handle: number): void;diff --git a/sdk/tests/compressed-texture.test.ts b/sdk/tests/compressed-texture.test.tsindex 06e86f49d..1f45d7983 100644--- a/sdk/tests/compressed-texture.test.ts+++ b/sdk/tests/compressed-texture.test.ts@@ -142,3 +142,28 @@ describe('uploadCompressedTexture', () => {).toThrow(/internalformat/i);});});++describe('GPU byte accounting', () => {+ let registerExternalTextureSized: ReturnType<typeof vi.fn>;+ beforeEach(() => {+ registerExternalTextureSized = vi.fn(() => 42);+ initResourceManager({ registerExternalTexture, registerExternalTextureSized } as never);+ });++ it('books compressed uploads at their real block size, not the RGBA8 estimate', () => {+ const gl = makeGl({ astc: true });+ // 4×4 ASTC block data is 8 bytes here vs a 64-byte RGBA8 estimate.+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER);++ expect(registerExternalTextureSized).toHaveBeenCalledWith(7, 4, 4, 8);+ expect(registerExternalTexture).not.toHaveBeenCalled();+ });++ it('books the RGBA8 fallback at the estimate (which is exact for RGBA8)', () => {+ const gl = makeGl(); // no compressed support → RGBA path+ loadCompressedTexture(gl as never, makeModule() as never, makeTranscoder(), KTX2_HEADER);++ expect(registerExternalTexture).toHaveBeenCalledWith(7, 4, 4);+ expect(registerExternalTextureSized).not.toHaveBeenCalled();+ });+});diff --git a/src/esengine/bindings/ResourceManagerBindings.cpp b/src/esengine/bindings/ResourceManagerBindings.cppindex 802d1bd07..71fa7d71b 100644--- a/src/esengine/bindings/ResourceManagerBindings.cpp+++ b/src/esengine/bindings/ResourceManagerBindings.cpp@@ -74,6 +74,13 @@ u32 rm_registerExternalTexture(resource::ResourceManager& rm, u32 glTextureId,return handle.id();}+u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,+ u32 width, u32 height, u32 bytes) {+ auto handle = rm.registerExternalTexture(glTextureId, width, height,+ static_cast<usize>(bytes));+ return handle.id();+}+void rm_releaseTexture(resource::ResourceManager& rm, u32 handleId) {rm.releaseTexture(resource::TextureHandle(handleId));}diff --git a/src/esengine/bindings/ResourceManagerBindings.hpp b/src/esengine/bindings/ResourceManagerBindings.hppindex f17ebc16b..87e20e125 100644--- a/src/esengine/bindings/ResourceManagerBindings.hpp+++ b/src/esengine/bindings/ResourceManagerBindings.hpp@@ -22,6 +22,8 @@ u32 rm_createShader(resource::ResourceManager& rm,const std::string& vertSrc, const std::string& fragSrc);u32 rm_registerExternalTexture(resource::ResourceManager& rm, u32 glTextureId,u32 width, u32 height);+u32 rm_registerExternalTextureSized(resource::ResourceManager& rm, u32 glTextureId,+ u32 width, u32 height, u32 bytes);void rm_releaseTexture(resource::ResourceManager& rm, u32 handleId);u32 rm_getTextureRefCount(resource::ResourceManager& rm, u32 handleId);void rm_registerTextureWithPath(resource::ResourceManager& rm, u32 handleId, const std::string& path);diff --git a/src/esengine/bindings/WebSDKEntry.cpp b/src/esengine/bindings/WebSDKEntry.cppindex a52f91f95..f321341a5 100644--- a/src/esengine/bindings/WebSDKEntry.cpp+++ b/src/esengine/bindings/WebSDKEntry.cpp@@ -396,6 +396,7 @@ EMSCRIPTEN_BINDINGS(esengine_renderer) {.function("createTextureEx", &esengine::rm_createTextureEx).function("createShader", &esengine::rm_createShader).function("registerExternalTexture", &esengine::rm_registerExternalTexture)+ .function("registerExternalTextureSized", &esengine::rm_registerExternalTextureSized).function("releaseTexture", &esengine::rm_releaseTexture).function("getTextureRefCount", &esengine::rm_getTextureRefCount).function("releaseShader", &esengine::rm_releaseShader)diff --git a/src/esengine/resource/ResourceManager.cpp b/src/esengine/resource/ResourceManager.cppindex a3f314b8e..0baabd1f0 100644--- a/src/esengine/resource/ResourceManager.cpp+++ b/src/esengine/resource/ResourceManager.cpp@@ -198,14 +198,16 @@ u32 ResourceManager::getTextureRefCount(TextureHandle handle) const {return textures_.getRefCount(handle);}-TextureHandle ResourceManager::registerExternalTexture(u32 glTextureId, u32 width, u32 height) {+TextureHandle ResourceManager::registerExternalTexture(u32 glTextureId, u32 width, u32 height, usize bytes) {if (!device_) return {};auto texture = Texture::createFromExternalId(*device_, glTextureId, width, height, TextureFormat::RGBA8);if (!texture) {ES_LOG_ERROR("Failed to register external texture (GL ID: {})", glTextureId);return TextureHandle();}- const usize bytes = static_cast<usize>(width) * height * 4;+ if (bytes == 0) {+ bytes = static_cast<usize>(width) * height * 4;+ }return textures_.add(std::move(texture), "", bytes);}diff --git a/src/esengine/resource/ResourceManager.hpp b/src/esengine/resource/ResourceManager.hppindex df675fd60..602b57849 100644--- a/src/esengine/resource/ResourceManager.hpp+++ b/src/esengine/resource/ResourceManager.hpp@@ -233,9 +233,13 @@ public:* @param glTextureId The OpenGL texture ID* @param width Texture width in pixels* @param height Texture height in pixels+ * @param bytes Actual GPU size for the eviction budget; 0 = estimate as+ * RGBA8 (width × height × 4). Compressed uploads (KTX2 →+ * ASTC/ETC2/S3TC) pass their real block size, 4–8× smaller —+ * billing them as RGBA8 would waste most of the budget.* @return Handle to the registered texture*/- TextureHandle registerExternalTexture(u32 glTextureId, u32 width, u32 height);+ TextureHandle registerExternalTexture(u32 glTextureId, u32 width, u32 height, usize bytes = 0);/*** @brief Registers a texture with a path for cache lookup