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(editor): every scene opened added texture references and dropped none
esengine78bfd0d19ad5
diff --git a/desktop/scripts/editor-checks/scene-churn.mjs b/desktop/scripts/editor-checks/scene-churn.mjsnew file mode 100644index 000000000..e83b5f8b5--- /dev/null+++ b/desktop/scripts/editor-checks/scene-churn.mjs@@ -0,0 +1,73 @@+// SPDX-License-Identifier: Apache-2.0+// SPDX-FileCopyrightText: Copyright (c) 2024-present ESEngine Team+/**+ * @file scene-churn — open one scene, then another, then back, and count.+ *+ * The Play/Stop soak keeps one scene open for its whole run, so the question it+ * cannot ask is what a session of AUTHORING costs: an editor that pins every+ * asset it ever loaded accumulates one scene's worth of GPU memory per scene+ * opened, and the texture pool's budget can never evict any of it because+ * everything still holds a reference.+ *+ * This alternates two scenes and reads the census between. `render.gl.textures`+ * climbing across a cycle is the whole finding; the counters that do NOT move+ * say where it is not.+ *+ * SOAK_CYCLES=8 SOAK_REPORT=1 node scripts/editor-checks/run.mjs scene-churn+ */+import path from 'node:path';+import { cp, writeFile, mkdir, readFile } from 'node:fs/promises';+import { makeProject, checker, DESKTOP } from '../lib/editorDriver.mjs';+import { analyzeCensusSeries, formatCensusReport } from '../lib/censusJudge.mjs';++const EXAMPLE = path.resolve(DESKTOP, '..', 'examples', 'sprite-rendering');+const CYCLES = Number(process.env.SOAK_CYCLES ?? 6);++export const name = 'scene-churn';+export const describes = 'opening scenes back and forth does not accumulate GPU resources';++async function census(ed) {+ const raw = await ed.json('resource_census', {}, 60000);+ return {+ atMs: 0,+ entries: new Map((raw?.entries ?? []).map((e) => [e.key, e])),+ failedProbes: raw?.failedProbes ?? [],+ };+}++export async function run(ed) {+ const root = await makeProject({});+ await cp(EXAMPLE, root, { recursive: true });++ // A second scene that references the SAME texture as the first, so switching+ // between them is the ordinary authoring loop rather than two disjoint sets.+ const scenesDir = path.join(root, 'assets', 'scenes');+ await mkdir(scenesDir, { recursive: true });+ const first = JSON.parse(await readFile(path.join(scenesDir, 'main.esscene'), 'utf8'));+ await writeFile(path.join(scenesDir, 'second.esscene'), JSON.stringify({ ...first, name: 'second' }, null, 2));++ const check = checker();+ await ed.open(root, 'assets/scenes/main.esscene');++ const first_ = await census(ed);+ if (!check(first_.entries.size > 0, 'resource_census came back empty')) return check.failures;+ const glKeys = [...first_.entries.keys()].filter((k) => k.startsWith('render.gl.'));+ if (!check(glKeys.length > 0, 'no render.gl.* counters — GL was not measured')) return check.failures;++ const samples = [];+ for (let cycle = 0; cycle < CYCLES; cycle++) {+ for (const scene of ['assets/scenes/second.esscene', 'assets/scenes/main.esscene']) {+ await ed.call('open_scene', { path: scene, discardChanges: true }, 120000);+ await ed.call('step', { frames: 4, dt: 1 / 60 }, 60000);+ }+ samples.push(await census(ed));+ }++ const report = analyzeCensusSeries(samples, { projectCycles: 10_000 });+ if (process.env.SOAK_REPORT) console.log(formatCensusReport(report));+ check(report.failedProbes.length === 0, `probes stopped answering: ${report.failedProbes.join('; ')}`);+ for (const leak of report.leaks) check(false, `${leak.key} — ${leak.reason}`);+ if (report.leaks.length > 0) console.error(formatCensusReport(report));++ return check.failures;+}diff --git a/desktop/src/project/ProjectStore.ts b/desktop/src/project/ProjectStore.tsindex 7f2f410be..cf56ea668 100644--- a/desktop/src/project/ProjectStore.ts+++ b/desktop/src/project/ProjectStore.ts@@ -20,6 +20,7 @@ import { ViewportController } from '@/engine/ViewportController';import { blankInputMap } from './inputMapDoc';import { EditorHistory } from '@/engine/EditorHistory';import { expandScenePrefabs, collapseScenePrefabs } from '@/engine/PrefabInstance';+import { discoverSceneAssets } from 'esengine';import { SceneCommands } from '@/engine/SceneCommands';import { Boxes } from 'lucide-react';import { spritePrefab, sourceById, type EntitySource } from '@/engine/entitySources';@@ -178,6 +179,13 @@ class ProjectStoreImpl {/** The latest scene preload result; the Reconciler resolver reads handles from* it for entities recreated incrementally (duplicate / undo / play-stop). */private lastAssetResult: PreloadResult | null = null;+ /**+ * What the open scene acquired, so the NEXT open can give it back.+ *+ * Without it a session only ever adds references, so the texture pool can+ * never evict anything and its budget stops meaning anything.+ */+ private sceneAssetRefs: ReadonlyMap<string, ReadonlySet<string>> | null = null;/** The open document as it last was on disk — a scene, or the `.esprefab` in* Prefab Mode. Answers "was that change ours" for the disk-change reconcile. */private diskText: string | null = null;@@ -524,6 +532,10 @@ class ProjectStoreImpl {const assets = EngineHost.getResource(Assets);let resolved: SceneData = expandedRaw;if (assets) {+ // The outgoing document lets go BEFORE the incoming one acquires, so an+ // asset both scenes use is revived from the warm pool rather than refetched.+ if (this.sceneAssetRefs) assets.releaseAssets(this.sceneAssetRefs);+ this.sceneAssetRefs = discoverSceneAssets(expandedRaw).byType;const result = await bootProfiler.phase('preloadSceneAssets', () => assets.preloadSceneAssets(expandedRaw));resolved = JSON.parse(JSON.stringify(expandedRaw)) as SceneData; // resolveSceneAssetPaths mutatesassets.resolveSceneAssetPaths(resolved, result);diff --git a/desktop/vite.config.ts b/desktop/vite.config.tsindex d6643a002..29cf91b1a 100644--- a/desktop/vite.config.ts+++ b/desktop/vite.config.ts@@ -99,12 +99,15 @@ export default defineConfig({// electron-updater is external for a different reason: it resolves its own// package.json and requires its providers by path, and it must stay the// CommonJS package Node's interop knows how to load (see autoUpdate.ts).+ // The cast keeps `rolldownOptions` — vite-plugin-electron types its+ // `vite` option against a vite whose BuildOptions predates the rename,+ // and `rollupOptions` is the wrong option for the bundler that runs.vite: {build: {rolldownOptions: {external: ['esbuild', 'typescript', 'ffmpeg-static', 'electron-updater', /[\\/]build-tools[\\/]basis[\\/]/],},- },+ } as never,},},preload: {diff --git a/sdk/etc/index.api.md b/sdk/etc/index.api.mdindex 99827d007..bd0862580 100644--- a/sdk/etc/index.api.md+++ b/sdk/etc/index.api.md@@ -1,7 +1,7 @@# API surface — esengine/index<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1462 stable · 17 beta · 1 deprecated+Symbols: 1464 stable · 17 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -6163,6 +6163,16 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAssetRefs — interface+```+byType: Map<string, Set<string>>+dragonBones: SpineAssetRef[]+rawByType: Map<string, Set<string>>+rawFor: Map<string, string>+spines: SpineAssetRef[]+unresolved: string[]+```+## SceneComponentCodec — interface```exportData: ((entity: number, data: Record<string, unknown>) => void) | undefined@@ -9348,6 +9358,11 @@ DiagnosticsPlugin(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph```+## discoverSceneAssets — function+```+(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs+```+## dragPlugin — const```DragPlugindiff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.mdindex bd37d6dd9..03e03064e 100644--- a/sdk/etc/index.native.api.md+++ b/sdk/etc/index.native.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.native<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1481 stable · 22 beta · 1 deprecated+Symbols: 1483 stable · 22 beta · 1 deprecated## ABI_LAYOUT_HASH — const```@@ -6333,6 +6333,16 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAssetRefs — interface+```+byType: Map<string, Set<string>>+dragonBones: SpineAssetRef[]+rawByType: Map<string, Set<string>>+rawFor: Map<string, string>+spines: SpineAssetRef[]+unresolved: string[]+```+## SceneComponentCodec — interface```exportData: ((entity: number, data: Record<string, unknown>) => void) | undefined@@ -9558,6 +9568,11 @@ DiagnosticsPlugin(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph```+## discoverSceneAssets — function+```+(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs+```+## dragPlugin — const```DragPlugindiff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.mdindex 230f877b3..c78068d0c 100644--- a/sdk/etc/index.node.api.md+++ b/sdk/etc/index.node.api.md@@ -1,7 +1,7 @@# API surface — esengine/index.node<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1461 stable · 19 beta · 1 deprecated+Symbols: 1463 stable · 19 beta · 1 deprecated## ANCHOR_AXES — const```@@ -6158,6 +6158,16 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAssetRefs — interface+```+byType: Map<string, Set<string>>+dragonBones: SpineAssetRef[]+rawByType: Map<string, Set<string>>+rawFor: Map<string, string>+spines: SpineAssetRef[]+unresolved: string[]+```+## SceneComponentCodec — interface```exportData: ((entity: number, data: Record<string, unknown>) => void) | undefined@@ -9343,6 +9353,11 @@ DiagnosticsPlugin(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph```+## discoverSceneAssets — function+```+(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs+```+## dragPlugin — const```DragPlugindiff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.mdindex 144259ce1..4c9fc727c 100644--- a/sdk/etc/minigame.api.md+++ b/sdk/etc/minigame.api.md@@ -1,7 +1,7 @@# API surface — esengine/minigame<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1482 stable · 17 beta · 1 deprecated+Symbols: 1484 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -6403,6 +6403,16 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAssetRefs — interface+```+byType: Map<string, Set<string>>+dragonBones: SpineAssetRef[]+rawByType: Map<string, Set<string>>+rawFor: Map<string, string>+spines: SpineAssetRef[]+unresolved: string[]+```+## SceneComponentCodec — interface```exportData: ((entity: number, data: Record<string, unknown>) => void) | undefined@@ -9593,6 +9603,11 @@ DiagnosticsPlugin(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph```+## discoverSceneAssets — function+```+(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs+```+## dragPlugin — const```DragPlugindiff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.mdindex 095eb2dd2..4812aad0d 100644--- a/sdk/etc/wechat.api.md+++ b/sdk/etc/wechat.api.md@@ -1,7 +1,7 @@# API surface — esengine/wechat<!-- Generated by tools/api-surface.mjs — do not edit. Run --update to accept changes. -->-Symbols: 1472 stable · 17 beta · 1 deprecated+Symbols: 1474 stable · 17 beta · 1 deprecated## ANCHOR_AXES — const```@@ -6165,6 +6165,16 @@ setJSON: <T>(key: string, value: T) => void(typeof ScaleMode)[keyof typeof ScaleMode]```+## SceneAssetRefs — interface+```+byType: Map<string, Set<string>>+dragonBones: SpineAssetRef[]+rawByType: Map<string, Set<string>>+rawFor: Map<string, string>+spines: SpineAssetRef[]+unresolved: string[]+```+## SceneComponentCodec — interface```exportData: ((entity: number, data: Record<string, unknown>) => void) | undefined@@ -9370,6 +9380,11 @@ DiagnosticsPlugin(g: MaterialGraph, toId: string, toSlot: string): MaterialGraph```+## discoverSceneAssets — function+```+(sceneData: SceneData, refResolver?: RefResolver): SceneAssetRefs+```+## dragPlugin — const```DragPlugindiff --git a/sdk/src/asset/AssetRefLedger.ts b/sdk/src/asset/AssetRefLedger.tsindex db9f2401c..0fdbe3a9f 100644--- a/sdk/src/asset/AssetRefLedger.ts+++ b/sdk/src/asset/AssetRefLedger.ts@@ -88,6 +88,21 @@ export class AssetRefLedger<T> {return this.byKey_.size;}+ /**+ * Live references across every key and generation.+ *+ * The distinction from {@link size} is the whole point: a key whose count+ * climbs from one to a hundred is one key either way, so a census that+ * reported only `size` would show a runaway acquire as a flat line.+ */+ get rows(): number {+ let n = 0;+ for (const generations of this.byKey_.values()) {+ for (const generation of generations) n += generation.count;+ }+ return n;+ }+/** @internal Live generations of one key, oldest first — diagnostics and tests. */generations(key: string): readonly AssetRefGeneration<T>[] {return this.byKey_.get(key) ?? [];diff --git a/sdk/src/asset/Assets.ts b/sdk/src/asset/Assets.tsindex 2dfb95a21..cb2444404 100644--- a/sdk/src/asset/Assets.ts+++ b/sdk/src/asset/Assets.ts@@ -1278,6 +1278,23 @@ export class Assets {if (path !== null) this.releaseTyped('material', path);}+ /**+ * Give back one reference to every asset in `byType` — what a scene, a+ * document or a group acquired, in one call.+ *+ * Materials (handle-keyed) and skeletons (SpineManager's) are skipped.+ * @beta Pre-1.0: the type vocabulary follows the loader registry.+ */+ releaseAssets(byType: ReadonlyMap<string, ReadonlySet<string>>): void {+ for (const [type, paths] of byType) {+ if (type === 'material' || type === 'spine') continue;+ for (const path of paths) {+ if (type === 'texture') this.releaseTexture(path);+ else this.releaseTyped(type, path);+ }+ }+ }+/*** @internal Release one reference to a typed asset by path — the door the* group channel table uses. Game code calls the named release* methods.@@ -1400,6 +1417,7 @@ export class Assets {textureCached: number;pendingLoads: number;refCounts: number;+ refRows: number;genericCaches: number;genericCached: number;handlePaths: number;@@ -1419,6 +1437,7 @@ export class Assets {textureCached: tex.cached,pendingLoads: pending,refCounts: this.textureRefs_.size + this.genericRefs_.size,+ refRows: this.textureRefs_.rows + this.genericRefs_.rows,genericCaches: this.genericCache_.size,genericCached,handlePaths: this.handleToPath_.size,diff --git a/sdk/src/core-content.ts b/sdk/src/core-content.tsindex 390d895cf..3247a1fb2 100644--- a/sdk/src/core-content.ts+++ b/sdk/src/core-content.ts@@ -133,6 +133,14 @@ export {type SliceBorder,} from './scene/scene';+/**+ * Every asset a scene references, bucketed by declared type — the input to+ * releasing what a document acquired.+ *+ * @beta Pre-1.0: the type vocabulary follows the loader registry.+ */+export { discoverSceneAssets, type SceneAssetRefs } from './asset/discoverAssets';+// =============================================================================// Scene Manager// =============================================================================diff --git a/sdk/src/diagnostics/censusProbes.ts b/sdk/src/diagnostics/censusProbes.tsindex 39d397679..fc0c1c1aa 100644--- a/sdk/src/diagnostics/censusProbes.ts+++ b/sdk/src/diagnostics/censusProbes.ts@@ -148,6 +148,9 @@ export function installBuiltinCensusProbes(): void {const s = assets.sizes();return [counter('asset.refCounts', s.refCounts, 'conserved'),+ // Keys, above; REFERENCES, here. A key whose count runs away is+ // still one key, so the first counter alone cannot see it.+ counter('asset.refRows', s.refRows, 'conserved'),counter('asset.handlePaths', s.handlePaths, 'conserved'),counter('asset.trackedRefRows', s.trackedRefRows, 'conserved'),counter('asset.invalidateListeners', s.invalidateListeners, 'conserved'),diff --git a/sdk/src/scene/sceneManager.ts b/sdk/src/scene/sceneManager.tsindex dde6ae34d..12877be49 100644--- a/sdk/src/scene/sceneManager.ts+++ b/sdk/src/scene/sceneManager.ts@@ -570,17 +570,9 @@ export class SceneManagerState {? this.app_.getResource(Assets): null;- if (assetsRes) {- // Driven by what the scene acquired and the loader registry, not by a- // list: a type with a registered loader has a release channel, and a- // type without one no-ops. Adding an asset kind touches neither.- for (const [type, paths] of instance.loadedByType) {- for (const path of paths) {- if (type === 'texture') assetsRes.releaseTexture(path);- else assetsRes.releaseTyped(type, path);- }- }- }+ // Whatever the scene acquired, through the one batch door. A type with a+ // registered loader has a release channel; one without no-ops.+ assetsRes?.releaseAssets(instance.loadedByType);if (instance.loadedMaterials) {for (const handle of instance.loadedMaterials) {diff --git a/sdk/tests/scene-asset-release.test.ts b/sdk/tests/scene-asset-release.test.tsindex 4fc5c6a24..b9b0c9717 100644--- a/sdk/tests/scene-asset-release.test.ts+++ b/sdk/tests/scene-asset-release.test.ts@@ -36,7 +36,28 @@ import { SceneManagerState } from '../src/scene/sceneManager';import { Assets } from '../src/asset';import { Material } from '../src/render/material';+/**+ * The batch door, implemented as Assets implements it, so a stub stays+ * observable through releaseTexture / releaseTyped — which is what the+ * assertions read.+ */+function withBatchRelease(stub: Record<string, unknown>): Record<string, unknown> {+ return {+ ...stub,+ releaseAssets(byType: ReadonlyMap<string, ReadonlySet<string>>) {+ for (const [type, paths] of byType) {+ if (type === 'material' || type === 'spine') continue;+ for (const path of paths) {+ if (type === 'texture') (stub.releaseTexture as (r: string) => void)?.(path);+ else (stub.releaseTyped as (t: string, r: string) => void)?.(type, path);+ }+ }+ },+ };+}+function createMockApp(assets?: unknown) {+ if (assets) assets = withBatchRelease(assets as Record<string, unknown>);const entities = new Map<number, Map<symbol, unknown>>();let nextEntity = 1;const resources = new Map<unknown, unknown>();