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.

refactor: migrate prefab system to new Assets API

esengineb07efc6191dd
diff --git a/sdk/src/prefab.ts b/sdk/src/prefab.ts
index f9a76bc58..ba5b55fd1 100644
--- a/sdk/src/prefab.ts
+++ b/sdk/src/prefab.ts
@@ -1,6 +1,6 @@
import type { World } from './world';
import type { Entity } from './types';
-import type { AssetServer } from './asset/AssetServer';
+import type { Assets } from './asset/Assets';
import { loadSceneWithAssets, type SceneData } from './scene';
import {
flattenPrefab,
@@ -13,7 +13,7 @@ import {
export type { PrefabData, PrefabEntityData, PrefabOverride, NestedPrefabRef } from './prefab/index';
export interface InstantiatePrefabOptions {
- assetServer?: AssetServer;
+ assets?: Assets;
assetBaseUrl?: string;
parent?: Entity;
overrides?: PrefabOverride[];
@@ -31,10 +31,14 @@ export async function instantiatePrefab(
): Promise<InstantiatePrefabResult> {
const prefabCache = new Map<string, PrefabData>();
- if (options?.assetServer) {
+ if (options?.assets) {
+ const assets = options.assets;
await preloadNestedPrefabs(
prefab,
- (path) => options.assetServer!.loadPrefab(path, options.assetBaseUrl),
+ async (path) => {
+ const result = await assets.loadPrefab(path);
+ return result.data as PrefabData;
+ },
prefabCache,
);
}
@@ -67,7 +71,7 @@ export async function instantiatePrefab(
};
const entityMap = await loadSceneWithAssets(world, sceneData, {
- assetServer: options?.assetServer,
+ assets: options?.assets,
assetBaseUrl: options?.assetBaseUrl,
});
diff --git a/sdk/src/prefabServer.ts b/sdk/src/prefabServer.ts
index 6b8937367..8aae8ef61 100644
--- a/sdk/src/prefabServer.ts
+++ b/sdk/src/prefabServer.ts
@@ -6,6 +6,7 @@ import { Assets } from './asset/AssetPlugin';
import { defineResource } from './resource';
import {
instantiatePrefab,
+ type PrefabData,
type PrefabOverride,
type InstantiatePrefabResult,
} from './prefab';
@@ -25,9 +26,9 @@ export class PrefabServer {
overrides?: PrefabOverride[];
}): Promise<InstantiatePrefabResult> {
const prefabResult = await this.assets_.loadPrefab(pathOrAddress);
- const prefab = prefabResult.data as any;
+ const prefab = prefabResult.data as PrefabData;
return instantiatePrefab(this.world_, prefab, {
- assetServer: this.assets_ as any,
+ assets: this.assets_,
assetBaseUrl: options?.baseUrl,
parent: options?.parent,
overrides: options?.overrides,
diff --git a/sdk/src/scene.ts b/sdk/src/scene.ts
index dc4844828..62f511b64 100644
--- a/sdk/src/scene.ts
+++ b/sdk/src/scene.ts
@@ -296,6 +296,13 @@ export async function loadSceneWithAssets(
sceneData: SceneData,
options?: SceneLoadOptions
): Promise<Map<number, Entity>> {
+ if (options?.assets) {
+ const assets = options.assets;
+ const result = await assets.preloadSceneAssets(sceneData);
+ assets.resolveSceneAssetPaths(sceneData, result);
+ return spawnAndLoadEntities(world, sceneData);
+ }
+
const assetServer = options?.assetServer;
const baseUrl = options?.assetBaseUrl ?? assetServer?.baseUrl;
const texturePathToUrl = new Map<string, string>();
diff --git a/sdk/tests/prefab.test.ts b/sdk/tests/prefab.test.ts
index bfa45f1b5..d335666c5 100644
--- a/sdk/tests/prefab.test.ts
+++ b/sdk/tests/prefab.test.ts
@@ -144,18 +144,18 @@ describe('Prefab', () => {
expect(root.children).toHaveLength(1);
});
- it('should pass assetServer and assetBaseUrl to loadSceneWithAssets', async () => {
+ it('should pass assets and assetBaseUrl to loadSceneWithAssets', async () => {
const prefab = simplePrefab();
- const mockAssetServer = { loadPrefab: vi.fn() } as any;
+ const mockAssets = { loadPrefab: vi.fn() } as any;
await instantiatePrefab(world, prefab, {
- assetServer: mockAssetServer,
+ assets: mockAssets,
assetBaseUrl: '/assets',
});
expect(mockLoadScene).toHaveBeenCalledWith(
world,
expect.any(Object),
- { assetServer: mockAssetServer, assetBaseUrl: '/assets' },
+ { assets: mockAssets, assetBaseUrl: '/assets' },
);
});
});
@@ -532,10 +532,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(childPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
expect(capturedSceneData!.entities).toHaveLength(2);
const names = capturedSceneData!.entities.map(e => e.name);
@@ -597,10 +597,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(childPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
const ids = capturedSceneData!.entities.map(e => e.id);
const uniqueIds = new Set(ids);
@@ -651,10 +651,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(childPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
const parentRoot = capturedSceneData!.entities.find(e => e.name === 'ParentRoot')!;
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
@@ -711,10 +711,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(childPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
const sprite = nestedRoot.components.find(c => c.type === 'Sprite')!;
@@ -751,11 +751,11 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(selfRefPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: selfRefPrefab }),
} as any;
await expect(
- instantiatePrefab(world, selfRefPrefab, { assetServer: mockAssetServer }),
+ instantiatePrefab(world, selfRefPrefab, { assets: mockAssetServer }),
).rejects.toThrow('Circular reference detected');
});
@@ -792,7 +792,7 @@ describe('Prefab', () => {
const mockAssetServer = {
loadPrefab: vi.fn().mockImplementation(() => {
callCount++;
- return Promise.resolve({
+ return Promise.resolve({ data: {
...deepPrefab,
name: `Deep_${callCount}`,
entities: deepPrefab.entities.map(e => ({
@@ -801,12 +801,12 @@ describe('Prefab', () => {
? { ...e.nestedPrefab, prefabPath: `deep_${callCount}.prefab` }
: undefined,
})),
- });
+ }});
}),
} as any;
await expect(
- instantiatePrefab(world, deepPrefab, { assetServer: mockAssetServer }),
+ instantiatePrefab(world, deepPrefab, { assets: mockAssetServer }),
).rejects.toThrow('nesting depth exceeded');
});
@@ -912,10 +912,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(childPrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: childPrefab }),
} as any;
- await instantiatePrefab(world, parentPrefab, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, parentPrefab, { assets: mockAssetServer });
const nestedRoot = capturedSceneData!.entities.find(e => e.name === 'NestedRoot')!;
expect(nestedRoot.parent).toBeNull();
@@ -1046,10 +1046,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(basePrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
} as any;
- await instantiatePrefab(world, variant, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, variant, { assets: mockAssetServer });
expect(capturedSceneData!.entities).toHaveLength(1);
const root = capturedSceneData!.entities[0];
@@ -1093,7 +1093,7 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(basePrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
} as any;
const instanceOverrides: PrefabOverride[] = [
@@ -1107,7 +1107,7 @@ describe('Prefab', () => {
];
await instantiatePrefab(world, variant, {
- assetServer: mockAssetServer,
+ assets: mockAssetServer,
overrides: instanceOverrides,
});
@@ -1127,11 +1127,11 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(variant),
+ loadPrefab: vi.fn().mockResolvedValue({ data: variant }),
} as any;
await expect(
- instantiatePrefab(world, variant, { assetServer: mockAssetServer }),
+ instantiatePrefab(world, variant, { assets: mockAssetServer }),
).rejects.toThrow('Circular variant reference');
});
@@ -1168,10 +1168,10 @@ describe('Prefab', () => {
};
const mockAssetServer = {
- loadPrefab: vi.fn().mockResolvedValue(basePrefab),
+ loadPrefab: vi.fn().mockResolvedValue({ data: basePrefab }),
} as any;
- await instantiatePrefab(world, variant, { assetServer: mockAssetServer });
+ await instantiatePrefab(world, variant, { assets: mockAssetServer });
const root = capturedSceneData!.entities[0];
expect(root.name).toBe('RenamedInVariant');