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(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.mjs
new file mode 100644
index 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.ts
index 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 mutates
assets.resolveSceneAssetPaths(resolved, result);
diff --git a/desktop/vite.config.ts b/desktop/vite.config.ts
index 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.md
index 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
```
DragPlugin
diff --git a/sdk/etc/index.native.api.md b/sdk/etc/index.native.api.md
index 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
```
DragPlugin
diff --git a/sdk/etc/index.node.api.md b/sdk/etc/index.node.api.md
index 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
```
DragPlugin
diff --git a/sdk/etc/minigame.api.md b/sdk/etc/minigame.api.md
index 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
```
DragPlugin
diff --git a/sdk/etc/wechat.api.md b/sdk/etc/wechat.api.md
index 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
```
DragPlugin
diff --git a/sdk/src/asset/AssetRefLedger.ts b/sdk/src/asset/AssetRefLedger.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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>();