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(asset): transfer standalone spawn resources to entity owners
yhh912da9d0fc29
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.tsindex 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.mjsindex 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':