321 lines
10 KiB
TypeScript
321 lines
10 KiB
TypeScript
|
/**
|
|||
|
|
* WASM加载器
|
|||
|
|
* 基于Cocos Creator官方文档的WASM/ASM加载最佳实践
|
|||
|
|
* https://docs.cocos.com/creator/3.8/manual/zh/advanced-topics/wasm-asm-load.html
|
|||
|
|
*/
|
|||
|
|
|
|||
|
|
import { Asset, assetManager, sys } from 'cc';
|
|||
|
|
import { EDITOR } from 'cc/env';
|
|||
|
|
|
|||
|
|
// ASM模块内存配置常量
|
|||
|
|
const PAGESIZE = 65536; // 64KiB
|
|||
|
|
const PAGECOUNT = 32 * 16; // 可根据需要调整
|
|||
|
|
const MEMORYSIZE = PAGESIZE * PAGECOUNT; // 32 MiB
|
|||
|
|
|
|||
|
|
|
|||
|
|
export interface WasmLoadOptions {
|
|||
|
|
bundleName?: string;
|
|||
|
|
fileName: string;
|
|||
|
|
editorUuid?: string; // 编辑器内的资源UUID
|
|||
|
|
supportAsm?: boolean; // 是否支持ASM回退
|
|||
|
|
asmFileName?: string; // ASM文件名
|
|||
|
|
asmEditorUuid?: string; // ASM文件的编辑器UUID
|
|||
|
|
wasmFactory?: any; // WASM工厂函数
|
|||
|
|
asmFactory?: any; // ASM工厂函数
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export interface WasmLoadResult {
|
|||
|
|
instance: any;
|
|||
|
|
isWasm: boolean; // true为WASM，false为ASM
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
export class WasmLoader {
|
|||
|
|
private static instance: WasmLoader;
|
|||
|
|
private initialized = false;
|
|||
|
|
|
|||
|
|
private constructor() { }
|
|||
|
|
|
|||
|
|
public static getInstance(): WasmLoader {
|
|||
|
|
if (!WasmLoader.instance) {
|
|||
|
|
WasmLoader.instance = new WasmLoader();
|
|||
|
|
}
|
|||
|
|
return WasmLoader.instance;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 初始化WASM加载器
|
|||
|
|
* 注册WASM/ASM文件的下载器和解析器
|
|||
|
|
*/
|
|||
|
|
public initialize(): void {
|
|||
|
|
if (this.initialized) {
|
|||
|
|
return;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 判断当前平台是否支持加载WASM文件
|
|||
|
|
// Cocos引擎目前暂不支持在iOS平台加载WASM文件
|
|||
|
|
if (sys.hasFeature(sys.Feature.WASM) || (sys.isNative && sys.os !== sys.OS.IOS)) {
|
|||
|
|
if (sys.isNative) {
|
|||
|
|
// 原生平台
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.downloader.register('.wasm', assetManager.downloader._downloaders[".bin"]);
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.parser.register('.wasm', assetManager.parser._parsers[".bin"]);
|
|||
|
|
} else if (sys.isBrowser || sys.platform === sys.Platform.WECHAT_GAME) {
|
|||
|
|
// 浏览器或微信小游戏平台
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.downloader.register('.wasm', assetManager.downloader._downloadArrayBuffer);
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.downloader.register('.mem', assetManager.downloader._downloadArrayBuffer);
|
|||
|
|
}
|
|||
|
|
} else {
|
|||
|
|
// 不支持WASM的平台，注册ASM相关文件
|
|||
|
|
if (sys.isNative) {
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.downloader.register('.mem', assetManager.downloader._downloaders[".bin"]);
|
|||
|
|
//@ts-ignore
|
|||
|
|
assetManager.parser.register('.mem', assetManager.parser._parsers[".bin"]);
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
this.initialized = true;
|
|||
|
|
console.log('[WasmLoader] 初始化完成');
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 加载WASM模块
|
|||
|
|
* @param options 加载配置选项（必须包含工厂函数）
|
|||
|
|
* @returns Promise<WasmLoadResult>
|
|||
|
|
*/
|
|||
|
|
public async loadWasmModule(options: WasmLoadOptions): Promise<WasmLoadResult> {
|
|||
|
|
if (!this.initialized) {
|
|||
|
|
this.initialize();
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 判断是否支持WASM
|
|||
|
|
if (sys.hasFeature(sys.Feature.WASM) || (sys.isNative && sys.os !== sys.OS.IOS)) {
|
|||
|
|
// 加载WASM
|
|||
|
|
return this.loadWasm(options);
|
|||
|
|
} else if (options.supportAsm && options.asmFileName && options.asmFactory) {
|
|||
|
|
// 回退到ASM
|
|||
|
|
return this.loadAsm(options);
|
|||
|
|
} else {
|
|||
|
|
throw new Error('当前平台不支持WASM，且未配置ASM回退选项');
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 加载WASM
|
|||
|
|
*/
|
|||
|
|
private async loadWasm(options: WasmLoadOptions): Promise<WasmLoadResult> {
|
|||
|
|
if (!options.wasmFactory) {
|
|||
|
|
throw new Error('WASM工厂函数未提供');
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
const wasmFactory = options.wasmFactory;
|
|||
|
|
|
|||
|
|
// 加载WASM二进制文件
|
|||
|
|
const wasmFile = await this.loadWasmFile(
|
|||
|
|
options.bundleName || '',
|
|||
|
|
options.fileName,
|
|||
|
|
options.editorUuid
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
// 初始化WASM
|
|||
|
|
const instance = await this.initWasm(wasmFactory, wasmFile);
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
instance,
|
|||
|
|
isWasm: true
|
|||
|
|
};
|
|||
|
|
} catch (error) {
|
|||
|
|
console.error('[WasmLoader] WASM加载失败:', error);
|
|||
|
|
throw error;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 加载ASM
|
|||
|
|
*/
|
|||
|
|
private async loadAsm(options: WasmLoadOptions): Promise<WasmLoadResult> {
|
|||
|
|
if (!options.asmFactory) {
|
|||
|
|
throw new Error('ASM工厂函数未提供');
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
try {
|
|||
|
|
const asmFactory = options.asmFactory;
|
|||
|
|
|
|||
|
|
// 加载ASM内存文件
|
|||
|
|
const asmFile = await this.loadWasmFile(
|
|||
|
|
options.bundleName || '',
|
|||
|
|
options.asmFileName || options.fileName,
|
|||
|
|
options.asmEditorUuid
|
|||
|
|
);
|
|||
|
|
|
|||
|
|
// 初始化ASM
|
|||
|
|
const instance = await this.initAsm(asmFactory, asmFile);
|
|||
|
|
|
|||
|
|
return {
|
|||
|
|
instance,
|
|||
|
|
isWasm: false
|
|||
|
|
};
|
|||
|
|
} catch (error) {
|
|||
|
|
console.error('[WasmLoader] ASM加载失败:', error);
|
|||
|
|
throw error;
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 加载WASM/ASM二进制文件
|
|||
|
|
*/
|
|||
|
|
private loadWasmFile(bundleName: string, fileName: string, editorUuid?: string): Promise<Asset> {
|
|||
|
|
return new Promise<Asset>((resolve, reject) => {
|
|||
|
|
if (EDITOR) {
|
|||
|
|
// 编辑器内通过UUID加载资源
|
|||
|
|
if (editorUuid) {
|
|||
|
|
assetManager.loadAny(editorUuid, (err, file: Asset) => {
|
|||
|
|
if (!err) {
|
|||
|
|
resolve(file);
|
|||
|
|
} else {
|
|||
|
|
reject(err);
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
} else {
|
|||
|
|
reject(new Error('编辑器环境下需要提供editorUuid'));
|
|||
|
|
}
|
|||
|
|
} else {
|
|||
|
|
// 运行时通过Bundle加载
|
|||
|
|
if (bundleName && fileName) {
|
|||
|
|
assetManager.loadBundle(bundleName, (err, bundle) => {
|
|||
|
|
if (!err) {
|
|||
|
|
bundle.load(fileName, Asset, (err2: any, file: Asset) => {
|
|||
|
|
if (!err2) {
|
|||
|
|
resolve(file);
|
|||
|
|
} else {
|
|||
|
|
reject(err2);
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
} else {
|
|||
|
|
reject(err);
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
} else {
|
|||
|
|
reject(new Error('运行时环境下需要提供bundleName和fileName'));
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 初始化WASM模块
|
|||
|
|
*/
|
|||
|
|
private initWasm(wasmFactory: any, wasmFile: Asset): Promise<any> {
|
|||
|
|
const self = this;
|
|||
|
|
return new Promise<any>((resolve, reject) => {
|
|||
|
|
wasmFactory({
|
|||
|
|
instantiateWasm(importObject: WebAssembly.Imports, receiveInstance: any) {
|
|||
|
|
self.instantiateWasm(wasmFile, importObject).then((result) => {
|
|||
|
|
receiveInstance(result.instance, result.module);
|
|||
|
|
}).catch((err) => reject(err));
|
|||
|
|
}
|
|||
|
|
}).then((instance: any) => {
|
|||
|
|
resolve(instance);
|
|||
|
|
}).catch((err: any) => reject(err));
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 实例化WASM
|
|||
|
|
*/
|
|||
|
|
private instantiateWasm(wasmFile: Asset, importObject: WebAssembly.Imports): Promise<any> {
|
|||
|
|
if (sys.isBrowser || sys.isNative) {
|
|||
|
|
//@ts-ignore
|
|||
|
|
return WebAssembly.instantiate(wasmFile._file, importObject);
|
|||
|
|
} else if (sys.platform === sys.Platform.WECHAT_GAME) {
|
|||
|
|
//@ts-ignore
|
|||
|
|
return CCWebAssembly.instantiate(wasmFile.nativeUrl, importObject);
|
|||
|
|
} else {
|
|||
|
|
return Promise.reject(new Error('不支持的平台'));
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 初始化ASM模块
|
|||
|
|
*/
|
|||
|
|
private initAsm(asmFactory: any, asmFile: Asset): Promise<any> {
|
|||
|
|
const asmMemory: any = {};
|
|||
|
|
asmMemory.buffer = new ArrayBuffer(MEMORYSIZE);
|
|||
|
|
|
|||
|
|
const module = {
|
|||
|
|
asmMemory,
|
|||
|
|
memoryInitializerRequest: {
|
|||
|
|
//@ts-ignore
|
|||
|
|
response: asmFile._file,
|
|||
|
|
status: 200,
|
|||
|
|
} as Partial<XMLHttpRequest>,
|
|||
|
|
};
|
|||
|
|
|
|||
|
|
return asmFactory(module);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 便捷方法：加载简单的WASM模块（仅WASM，不支持ASM回退）
|
|||
|
|
*/
|
|||
|
|
public async loadSimpleWasm(wasmFactory: any, fileName: string, editorUuid?: string, bundleName?: string): Promise<any> {
|
|||
|
|
const result = await this.loadWasmModule({
|
|||
|
|
fileName,
|
|||
|
|
editorUuid,
|
|||
|
|
bundleName,
|
|||
|
|
supportAsm: false,
|
|||
|
|
wasmFactory
|
|||
|
|
});
|
|||
|
|
return result.instance;
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 便捷方法：加载支持ASM回退的WASM模块
|
|||
|
|
*/
|
|||
|
|
public async loadWasmWithAsmFallback(
|
|||
|
|
wasmFactory: any,
|
|||
|
|
asmFactory: any,
|
|||
|
|
fileName: string,
|
|||
|
|
asmFileName: string,
|
|||
|
|
editorUuid?: string,
|
|||
|
|
asmEditorUuid?: string,
|
|||
|
|
bundleName?: string
|
|||
|
|
): Promise<WasmLoadResult> {
|
|||
|
|
return this.loadWasmModule({
|
|||
|
|
fileName,
|
|||
|
|
editorUuid,
|
|||
|
|
bundleName,
|
|||
|
|
supportAsm: true,
|
|||
|
|
asmFileName,
|
|||
|
|
asmEditorUuid,
|
|||
|
|
wasmFactory,
|
|||
|
|
asmFactory
|
|||
|
|
});
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 检查当前平台是否支持WASM
|
|||
|
|
*/
|
|||
|
|
public isWasmSupported(): boolean {
|
|||
|
|
return sys.hasFeature(sys.Feature.WASM) || (sys.isNative && sys.os !== sys.OS.IOS);
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
/**
|
|||
|
|
* 获取推荐的加载策略
|
|||
|
|
*/
|
|||
|
|
public getRecommendedStrategy(): 'wasm' | 'asm' | 'unsupported' {
|
|||
|
|
if (this.isWasmSupported()) {
|
|||
|
|
return 'wasm';
|
|||
|
|
} else if (sys.isNative || sys.isBrowser) {
|
|||
|
|
return 'asm';
|
|||
|
|
} else {
|
|||
|
|
return 'unsupported';
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
}
|
|||
|
|
|
|||
|
|
// 导出单例实例
|
|||
|
|
export const wasmLoader = WasmLoader.getInstance();
|