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(asset): transfer standalone spawn resources to entity owners

yhh912da9d0fc29
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 360a5a372..ec5e2ba66 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -22,6 +22,8 @@ published separately; it ships inside the editor.
### Fixed
+- **Standalone scene and prefab spawns release their resources.** Loads without a scene collector transfer acquired resources to the entities that reference them, then release the preload receipts. Destroying or rolling back a spawned hierarchy retires those acquisitions. Prefab document reads also use scoped receipts, including nested sources, so repeated spawns no longer accumulate unowned references.
+
- **Prefab spawns roll back when their parent disappears.** Runtime instantiation checks that its requested parent accepts the root after asynchronous loading. A rejected attachment despawns the newly created hierarchy and rejects the spawn instead of leaving an unparented instance behind; live parents and the explicit no-parent sentinel remain supported.
- **Scene completion errors settle the transition promise.** A throwing fade-completion callback rejects the caller's promise with its original error after clearing the old overlay, so callers can recover and later scene switches remain available. A callback that starts another fade keeps that new transition intact.
diff --git a/sdk/src/prefab.ts b/sdk/src/prefab.ts
index a3ddc2468..bbb7c0089 100644
--- a/sdk/src/prefab.ts
+++ b/sdk/src/prefab.ts
@@ -71,10 +71,10 @@ export async function instantiatePrefab(
await preloadNestedPrefabs(
normalized,
async (path) => {
- const result = await assets.loadPrefab(path);
- // Safety net: asset loader already migrates, but if a caller
- // side-loaded a PrefabData manually, re-migration is idempotent.
- return migratePrefabData(result.data as PrefabData).data;
+ const lease = await assets.acquireTyped<{ data: PrefabData }>('prefab', path);
+ try {
+ return migratePrefabData(lease.value.data).data;
+ } finally { lease.release(); }
},
prefabCache,
);
diff --git a/sdk/src/prefab/prefabServer.ts b/sdk/src/prefab/prefabServer.ts
index 2c5ef3754..ea54d545d 100644
--- a/sdk/src/prefab/prefabServer.ts
+++ b/sdk/src/prefab/prefabServer.ts
@@ -62,16 +62,18 @@ export class PrefabServer {
scene?: boolean;
}): Promise<InstantiatePrefabResult> {
const assets = this.getAssets_();
- const prefabResult = await assets.loadPrefab(pathOrAddress);
- const prefab = prefabResult.data as PrefabData;
- const result = await instantiatePrefab(this.world_, prefab, {
- assets,
- assetBaseUrl: options?.baseUrl,
- parent: options?.parent,
- overrides: resolveSpawnOverrides(prefab, pathOrAddress, options?.overrides),
- });
- if (options?.scene !== false) this.adoptIntoActiveScene_(result);
- return result;
+ const lease = await assets.acquireTyped<{ data: PrefabData }>('prefab', pathOrAddress);
+ try {
+ const prefab = lease.value.data;
+ const result = await instantiatePrefab(this.world_, prefab, {
+ assets,
+ assetBaseUrl: options?.baseUrl,
+ parent: options?.parent,
+ overrides: resolveSpawnOverrides(prefab, pathOrAddress, options?.overrides),
+ });
+ if (options?.scene !== false) this.adoptIntoActiveScene_(result);
+ return result;
+ } finally { lease.release(); }
}
/**
diff --git a/sdk/src/scene/scene.ts b/sdk/src/scene/scene.ts
index 3c4e50c2b..085906952 100644
--- a/sdk/src/scene/scene.ts
+++ b/sdk/src/scene/scene.ts
@@ -16,6 +16,7 @@ import { discoverSceneAssets } from '../asset/discoverAssets';
import { requireResourceManager } from '../wasm/resourceManager';
import { validateComponentData, formatValidationErrors } from '../util/validation';
import { log } from '../util/logger';
+import { prepareSpawnOwnership, type PreparedSpawnOwnership } from '../prefab/preparedAssetOwnership';
import { ESTELLA_SCENE_GENERATOR } from '../util/provenance';
import {
expandEntry,
@@ -654,30 +655,42 @@ async function loadSceneAssetsAndSpawn(
world: World, data: SceneData, options: SceneLoadOptions | undefined,
timed: <T>(phase: string, run: () => Promise<T> | T) => Promise<T>,
): Promise<Map<number, Entity>> {
- if (options?.assets) {
- const assets = options.assets;
- const result = await timed('assets', () => assets.preloadSceneAssets(data, options.onProgress));
- if (options.onMissingAssets) {
- options.onMissingAssets(result.missing);
- }
- if (options.abortOnMissingAssets && result.missing.length > 0) {
- throw new MissingAssetsError(result.missing);
- }
- assets.resolveSceneAssetPaths(data, result);
- applyTextureMetadata(data, result.textureHandles);
- if (options.collectAssets) {
- // The receipts MOVE to the owner (absorb, not add): two scopes each
- // holding every receipt leaves "which one releases it" unanswered.
- // Materials keep their handle set too, but the RELEASE rides the scope.
- options.collectAssets.scope?.absorb(result.scope);
- for (const handle of result.materialHandles.values()) {
- if (handle) options.collectAssets.materialHandles.add(handle);
+ let ownership: PreparedSpawnOwnership | undefined;
+ let releasePreload: (() => void) | undefined;
+ try {
+ if (options?.assets) {
+ const assets = options.assets;
+ const result = await timed('assets', () => assets.preloadSceneAssets(data, options.onProgress));
+ if (!options.collectAssets && assets.entityScopes) {
+ releasePreload = () => result.scope.releaseAll();
+ ownership = prepareSpawnOwnership(data, result, assets.entityScopes, assets.resolveRef.bind(assets))?.();
+ }
+ if (options.onMissingAssets) {
+ options.onMissingAssets(result.missing);
+ }
+ if (options.abortOnMissingAssets && result.missing.length > 0) {
+ throw new MissingAssetsError(result.missing);
+ }
+ assets.resolveSceneAssetPaths(data, result);
+ applyTextureMetadata(data, result.textureHandles);
+ if (options.collectAssets) {
+ // The receipts MOVE to the owner (absorb, not add): two scopes each
+ // holding every receipt leaves "which one releases it" unanswered.
+ // Materials keep their handle set too, but the RELEASE rides the scope.
+ options.collectAssets.scope?.absorb(result.scope);
+ for (const handle of result.materialHandles.values()) {
+ if (handle) options.collectAssets.materialHandles.add(handle);
+ }
}
}
+ const entities = await timed('spawn', () => spawnAndLoadEntities(world, data, options?.externalEntities, options?.onPhase));
+ ownership?.attach(world, entities);
+ options?.assets?.trackSceneAssetReferences(data, entities);
+ return entities;
+ } finally {
+ ownership?.release();
+ releasePreload?.();
}
- const entities = await timed('spawn', () => spawnAndLoadEntities(world, data, options?.externalEntities, options?.onPhase));
- options?.assets?.trackSceneAssetReferences(data, entities);
- return entities;
}
function applyTextureMetadata(sceneData: SceneData, textureHandles: Map<string, number>): void {
diff --git a/sdk/tests/prefab-spawn-overrides.test.ts b/sdk/tests/prefab-spawn-overrides.test.ts
index 5e1afe341..324f5bafc 100644
--- a/sdk/tests/prefab-spawn-overrides.test.ts
+++ b/sdk/tests/prefab-spawn-overrides.test.ts
@@ -13,6 +13,7 @@ import { describe, it, expect, vi } from 'vitest';
import type { PrefabData } from '../src/prefab';
const instantiateSpy = vi.fn(async () => ({ root: 1 as never, entities: new Map() }));
+const releaseSpy = vi.fn();
vi.mock('../src/prefab', async (importOriginal) => ({
...(await importOriginal<typeof import('../src/prefab')>()),
instantiatePrefab: (...args: unknown[]) => instantiateSpy(...(args as [])),
@@ -39,7 +40,8 @@ const positionAt = (x: number, prefabEntityId?: string) => ({
});
function server(): InstanceType<typeof PrefabServer> {
- const assets = { loadPrefab: async () => ({ data: PREFAB }) };
+ releaseSpy.mockClear();
+ const assets = { acquireTyped: async () => ({ value: { data: PREFAB }, release: releaseSpy }) };
return new PrefabServer({} as never, () => assets as never);
}
@@ -53,12 +55,14 @@ describe('PrefabServer.instantiate overrides', () => {
instantiateSpy.mockClear();
await server().instantiate('assets/prefabs/Bullet.esprefab', { overrides: [positionAt(7)] });
expect(overridesPassed()).toEqual([{ ...positionAt(7), prefabEntityId: 'aaaa-bbbb' }]);
+ expect(releaseSpy).toHaveBeenCalledOnce();
});
it('passes an id the prefab has through untouched', async () => {
instantiateSpy.mockClear();
await server().instantiate('assets/prefabs/Bullet.esprefab', { overrides: [positionAt(7, 'cccc-dddd')] });
expect(overridesPassed()).toEqual([positionAt(7, 'cccc-dddd')]);
+ expect(releaseSpy).toHaveBeenCalledOnce();
});
it('refuses an id nobody answers to, naming the root and the alternatives', async () => {
@@ -67,5 +71,6 @@ describe('PrefabServer.instantiate overrides', () => {
.rejects.toThrow(/no entity "0"/);
await expect(server().instantiate('assets/prefabs/Bullet.esprefab', { overrides: [positionAt(7, '0')] }))
.rejects.toThrow(/aaaa-bbbb/);
+ expect(releaseSpy).toHaveBeenCalledOnce();
});
});
diff --git a/sdk/tests/prefab-spawn-ownership.test.ts b/sdk/tests/prefab-spawn-ownership.test.ts
index 8cd861ee4..9b0e7154d 100644
--- a/sdk/tests/prefab-spawn-ownership.test.ts
+++ b/sdk/tests/prefab-spawn-ownership.test.ts
@@ -43,7 +43,7 @@ function scenes(active: string | null): { manager: unknown; adopted: Entity[] }
const spawn = async (active: string | null, opts?: { scene?: boolean }): Promise<Entity[]> => {
const { manager, adopted } = scenes(active);
- const assets = { loadPrefab: async () => ({ data: PREFAB }) };
+ const assets = { acquireTyped: async () => ({ value: { data: PREFAB }, release: () => {} }) };
const server = new PrefabServer({} as never, () => assets as never, () => manager as never);
await server.instantiate('assets/prefabs/Wisp.esprefab', opts);
return adopted;
diff --git a/sdk/tests/prefab.test.ts b/sdk/tests/prefab.test.ts
index b804eac2f..37f201ccd 100644
--- a/sdk/tests/prefab.test.ts
+++ b/sdk/tests/prefab.test.ts
@@ -20,6 +20,13 @@ import { defineComponent } from '../src/ecs/component';
const mockLoadScene = vi.mocked(loadOwnedSceneWithAssets);
+function withAssetLeases<T extends { loadPrefab: (path: string) => Promise<{ data: PrefabData }> }>(assets: T): T {
+ Object.assign(assets, { acquireTyped: async (_type: string, path: string) => ({
+ value: await assets.loadPrefab(path), release: vi.fn(),
+ }) });
+ return assets;
+}
+
function createMockWorld(): World {
const parentMap = new Map<Entity, Entity>();
const setParent = vi.fn((child: Entity, parent: Entity) => {
@@ -154,14 +161,14 @@ describe('Prefab', () => {
const prefab = simplePrefab();
const mockAssets = { loadPrefab: vi.fn() } as any;
await instantiatePrefab(world, prefab, {
- assets: mockAssets,
+ assets: withAssetLeases(mockAssets),
assetBaseUrl: '/assets',
});
expect(mockLoadScene).toHaveBeenCalledWith(
world,
expect.any(Object),
- { assets: mockAssets, assetBaseUrl: '/assets' },
+ { assets: withAssetLeases(mockAssets), assetBaseUrl: '/assets' },
);
});
});
@@ -744,7 +751,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });
expect(capturedSceneData!.entities).toHaveLength(2);
const names = capturedSceneData!.entities.map(e => e.name);
@@ -809,7 +816,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });
const ids = capturedSceneData!.entities.map(e => e.id);
const uniqueIds = new Set(ids);
@@ -863,7 +870,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });
const parentRoot = capturedSceneData!.entities.find(e => e.name === 'ParentRoot')!;
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
@@ -923,7 +930,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
const sprite = nestedRoot.components.find(c => c.type === 'Sprite')!;
@@ -964,7 +971,7 @@ describe('Prefab', () => {
} as any;
await expect(
- instantiatePrefab(world, selfRefPrefab, { assets: mockAssetServer }),
+ instantiatePrefab(world, selfRefPrefab, { assets: withAssetLeases(mockAssetServer) }),
).rejects.toThrow('Circular reference detected');
});
@@ -1015,7 +1022,7 @@ describe('Prefab', () => {
} as any;
await expect(
- instantiatePrefab(world, deepPrefab, { assets: mockAssetServer }),
+ instantiatePrefab(world, deepPrefab, { assets: withAssetLeases(mockAssetServer) }),
).rejects.toThrow('nesting depth exceeded');
});
@@ -1124,7 +1131,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: withAssetLeases(mockAssetServer) });
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
expect(nestedRoot.parent).toBeNull();
@@ -1258,7 +1265,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
} as any;
- await instantiatePrefab(world, variant, { assets: mockAssetServer });
+ await instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) });
expect(capturedSceneData!.entities).toHaveLength(1);
const root = capturedSceneData!.entities[0];
@@ -1316,7 +1323,7 @@ describe('Prefab', () => {
];
await instantiatePrefab(world, variant, {
- assets: mockAssetServer,
+ assets: withAssetLeases(mockAssetServer),
overrides: instanceOverrides,
});
@@ -1340,7 +1347,7 @@ describe('Prefab', () => {
} as any;
await expect(
- instantiatePrefab(world, variant, { assets: mockAssetServer }),
+ instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) }),
).rejects.toThrow('Circular variant reference');
});
@@ -1380,7 +1387,7 @@ describe('Prefab', () => {
loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
} as any;
- await instantiatePrefab(world, variant, { assets: mockAssetServer });
+ await instantiatePrefab(world, variant, { assets: withAssetLeases(mockAssetServer) });
const root = capturedSceneData!.entities[0];
expect(root.name).toBe('RenamedInVariant');
diff --git a/sdk/tests/prepared-prefab.test.ts b/sdk/tests/prepared-prefab.test.ts
index 056216bdb..13b12f6d6 100644
--- a/sdk/tests/prepared-prefab.test.ts
+++ b/sdk/tests/prepared-prefab.test.ts
@@ -15,8 +15,10 @@ const leaf = (name: string): PrefabData => ({ version: '2', name, rootEntityId:
] });
function assetsFor(prefabs: Record<string, PrefabData>) {
const release = vi.fn();
+ const loadPrefab = vi.fn(async (ref: string) => ({ data: prefabs[ref] }));
const assets = {
- loadPrefab: vi.fn(async (ref: string) => ({ data: prefabs[ref] })),
+ loadPrefab,
+ acquireTyped: async (_type: string, ref: string) => ({ value: await loadPrefab(ref), release: vi.fn() }),
preloadSceneAssets: vi.fn(async () => ({ missing: [], scope: { releaseAll: release } })),
resolveSceneAssetPaths: vi.fn(),
trackSceneAssetReferences: vi.fn(),
diff --git a/sdk/tests/scene-asset-receipts.test.ts b/sdk/tests/scene-asset-receipts.test.ts
index 96d54cf0f..e10a9cb01 100644
--- a/sdk/tests/scene-asset-receipts.test.ts
+++ b/sdk/tests/scene-asset-receipts.test.ts
@@ -24,6 +24,31 @@ vi.mock('../src/wasm/resourceManager', () => ({
}));
describe('a scene owns the receipts its preload produced', () => {
+ it('standalone spawns release acquisitions when their entities are destroyed', async () => {
+ const unloaded: number[] = [];
+ let next = 0;
+ const assets = Assets.create({ backend: {
+ fetchBinary: async () => new ArrayBuffer(8), fetchText: async () => '{}',
+ resolveUrl: (path: string) => `http://test/${path}`,
+ } as Backend, module: { _malloc: () => 0, _free: () => {}, HEAPU8: new Uint8Array(16) } as never });
+ assets.register<{ handle: number }>({ type: 'mesh',
+ load: async () => ({ handle: ++next }),
+ unload: (value: { handle: number }) => { unloaded.push(value.handle); },
+ } as never);
+ const world = new World();
+ const scene = { version: '1.0', name: 'owned', entities: [{ id: 1, name: 'mesh', parent: null,
+ children: [], components: [{ type: 'MeshRenderer', data: { mesh: 'mesh.esmesh' } }],
+ }] } as SceneData;
+ try {
+ for (let i = 0; i < 20; i++) {
+ const entities = await loadSceneWithAssets(world, scene, { assets });
+ expect(assets.sizes().refRows).toBe(1);
+ for (const entity of entities.values()) world.despawn(entity);
+ expect(assets.sizes()).toMatchObject({ refRows: 0, genericCached: 0, trackedRefRows: 0 });
+ }
+ expect(unloaded).toHaveLength(20);
+ } finally { assets.releaseAll(); }
+ });
it('carries them to collectAssets, and they release the real asset', async () => {
const unloaded: string[] = [];
let n = 0;
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index f39642dc8..d1ebe768c 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -28,6 +28,8 @@ export const NOTES_FLOOR = 'v0.65.0';
* the reader recognises anyway.
*/
export const NOTED = {
+ 'fix(asset): transfer standalone spawn resources to entity owners':
+ { note: 'Standalone scene and prefab spawns release their resources.' },
'fix(prefab): roll back spawns when parent attachment fails':
{ note: 'Prefab spawns roll back when their parent disappears.' },
'fix(scene): reject transitions when completion callbacks fail':