esengine/docs/guide/platform-adapter/wechat-minigame.md

# 微信小游戏适配器

## 概述

微信小游戏平台适配器专为微信小游戏环境设计，处理微信小游戏的特殊限制和API。

## 特性支持

- ✅ **Worker**: 支持（通过 `wx.createWorker` 创建，需要配置 game.json）
- ❌ **SharedArrayBuffer**: 不支持
- ❌ **Transferable Objects**: 不支持（只支持可序列化对象）
- ✅ **高精度时间**: 使用 `Date.now()` 或 `wx.getPerformance()`
- ✅ **设备信息**: 完整的微信小游戏设备信息

## 完整实现

```typescript
import type {
    IPlatformAdapter,
    PlatformWorker,
    WorkerCreationOptions,
    PlatformConfig,
    WeChatDeviceInfo
} from '@esengine/ecs-framework';

/**
 * 微信小游戏平台适配器
 * 支持微信小游戏环境
 */
export class WeChatMiniGameAdapter implements IPlatformAdapter {
    public readonly name = 'wechat-minigame';
    public readonly version: string;
    private systemInfo: any;

    constructor() {
        // 获取微信小游戏版本信息
        this.systemInfo = this.getSystemInfo();
        this.version = this.systemInfo.version || 'unknown';
    }

    /**
     * 检查是否支持Worker
     */
    public isWorkerSupported(): boolean {
        // 微信小游戏支持Worker，通过wx.createWorker创建
        return typeof wx !== 'undefined' && typeof wx.createWorker === 'function';
    }

    /**
     * 检查是否支持SharedArrayBuffer（不支持）
     */
    public isSharedArrayBufferSupported(): boolean {
        return false; // 微信小游戏不支持SharedArrayBuffer
    }

    /**
     * 获取硬件并发数
     */
    public getHardwareConcurrency(): number {
        // 微信小游戏官方限制：最多只能创建 1 个 Worker
        return 1;
    }

    /**
     * 创建Worker
     * @param script 脚本内容或文件路径
     * @param options Worker创建选项
     */
    public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker {
        if (!this.isWorkerSupported()) {
            throw new Error('微信小游戏不支持Worker');
        }

        try {
            return new WeChatWorker(script, options);
        } catch (error) {
            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
        }
    }

    /**
     * 创建SharedArrayBuffer（不支持）
     */
    public createSharedArrayBuffer(length: number): SharedArrayBuffer | null {
        return null; // 微信小游戏不支持SharedArrayBuffer
    }

    /**
     * 获取高精度时间戳
     */
    public getHighResTimestamp(): number {
        // 尝试使用微信的性能API，否则使用Date.now()
        if (typeof wx !== 'undefined' && wx.getPerformance) {
            const performance = wx.getPerformance();
            return performance.now();
        }
        return Date.now();
    }

    /**
     * 获取平台配置
     */
    public getPlatformConfig(): PlatformConfig {
        return {
            maxWorkerCount: 1, // 微信小游戏最多支持 1 个 Worker
            supportsModuleWorker: false, // 不支持模块Worker
            supportsTransferableObjects: this.checkTransferableObjectsSupport(),
            maxSharedArrayBufferSize: 0,
            workerScriptPrefix: '',
            limitations: {
                noEval: true, // 微信小游戏限制eval使用
                requiresWorkerInit: false,
                memoryLimit: this.getMemoryLimit(),
                workerNotSupported: false,
                workerLimitations: [
                    '最多只能创建 1 个 Worker',
                    '创建新Worker前必须先调用 Worker.terminate()',
                    'Worker脚本必须为项目内相对路径',
                    '需要在 game.json 中配置 workers 路径',
                    '使用 worker.onMessage() 而不是 self.onmessage',
                    '需要基础库 1.9.90 及以上版本'
                ]
            },
            extensions: {
                platform: 'wechat-minigame',
                systemInfo: this.systemInfo,
                appId: this.systemInfo.host?.appId || 'unknown'
            }
        };
    }

    /**
     * 获取微信小游戏设备信息
     */
    public getDeviceInfo(): WeChatDeviceInfo {
        return {
            // 设备基础信息
            brand: this.systemInfo.brand,
            model: this.systemInfo.model,
            platform: this.systemInfo.platform,
            system: this.systemInfo.system,
            benchmarkLevel: this.systemInfo.benchmarkLevel,
            cpuType: this.systemInfo.cpuType,
            memorySize: this.systemInfo.memorySize,
            deviceAbi: this.systemInfo.deviceAbi,
            abi: this.systemInfo.abi,

            // 窗口信息
            screenWidth: this.systemInfo.screenWidth,
            screenHeight: this.systemInfo.screenHeight,
            screenTop: this.systemInfo.screenTop,
            windowWidth: this.systemInfo.windowWidth,
            windowHeight: this.systemInfo.windowHeight,
            pixelRatio: this.systemInfo.pixelRatio,
            statusBarHeight: this.systemInfo.statusBarHeight,
            safeArea: this.systemInfo.safeArea,

            // 应用信息
            version: this.systemInfo.version,
            language: this.systemInfo.language,
            theme: this.systemInfo.theme,
            SDKVersion: this.systemInfo.SDKVersion,
            enableDebug: this.systemInfo.enableDebug,
            fontSizeSetting: this.systemInfo.fontSizeSetting,
            host: this.systemInfo.host
        };
    }

    /**
     * 异步获取完整的平台配置
     */
    public async getPlatformConfigAsync(): Promise<PlatformConfig> {
        // 可以在这里添加异步获取设备性能信息的逻辑
        const baseConfig = this.getPlatformConfig();

        // 尝试获取设备性能信息
        try {
            const benchmarkLevel = await this.getBenchmarkLevel();
            baseConfig.extensions = {
                ...baseConfig.extensions,
                benchmarkLevel
            };
        } catch (error) {
            console.warn('获取性能基准失败:', error);
        }

        return baseConfig;
    }

    /**
     * 检查是否支持Transferable Objects
     */
    private checkTransferableObjectsSupport(): boolean {
        // 微信小游戏不支持 Transferable Objects
        // 基础库 2.20.2 之前只支持可序列化的 key-value 对象
        // 2.20.2 之后支持任意类型数据，但仍然不支持 Transferable Objects
        return false;
    }

    /**
     * 获取系统信息
     */
    private getSystemInfo(): any {
        if (typeof wx !== 'undefined' && wx.getSystemInfoSync) {
            try {
                return wx.getSystemInfoSync();
            } catch (error) {
                console.warn('获取微信系统信息失败:', error);
                return {};
            }
        }
        return {};
    }

    /**
     * 获取内存限制
     */
    private getMemoryLimit(): number {
        // 微信小游戏通常有内存限制
        const memorySize = this.systemInfo.memorySize;
        if (memorySize) {
            // 解析内存大小字符串（如 "4GB"）
            const match = memorySize.match(/(\d+)([GM]B)?/i);
            if (match) {
                const value = parseInt(match[1], 10);
                const unit = match[2]?.toUpperCase();

                if (unit === 'GB') {
                    return value * 1024 * 1024 * 1024;
                } else if (unit === 'MB') {
                    return value * 1024 * 1024;
                }
            }
        }

        // 默认限制为512MB
        return 512 * 1024 * 1024;
    }

    /**
     * 异步获取设备性能基准
     */
    private async getBenchmarkLevel(): Promise<number> {
        return new Promise((resolve) => {
            if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
                wx.getDeviceInfo({
                    success: (res: any) => {
                        resolve(res.benchmarkLevel || 0);
                    },
                    fail: () => {
                        resolve(0);
                    }
                });
            } else {
                resolve(this.systemInfo.benchmarkLevel || 0);
            }
        });
    }
}

/**
 * 微信Worker封装
 */
class WeChatWorker implements PlatformWorker {
    private _state: 'running' | 'terminated' = 'running';
    private worker: any;
    private scriptPath: string;
    private isTemporaryFile: boolean = false;

    constructor(script: string, options: WorkerCreationOptions = {}) {
        if (typeof wx === 'undefined' || typeof wx.createWorker !== 'function') {
            throw new Error('微信小游戏不支持Worker');
        }

        try {
            // 判断 script 是文件路径还是脚本内容
            if (this.isFilePath(script)) {
                // 直接使用文件路径
                this.scriptPath = script;
                this.isTemporaryFile = false;
                this.worker = wx.createWorker(this.scriptPath);
            } else {
                // 将脚本内容写入文件系统
                this.scriptPath = this.writeScriptToFile(script, options.name);
                this.isTemporaryFile = true;
                this.worker = wx.createWorker(this.scriptPath);
            }
        } catch (error) {
            throw new Error(`创建微信Worker失败: ${(error as Error).message}`);
        }
    }

    /**
     * 判断是否为文件路径
     */
    private isFilePath(script: string): boolean {
        // 简单判断：如果包含 .js 后缀且不包含换行符或分号，认为是文件路径
        return script.endsWith('.js') &&
               !script.includes('\n') &&
               !script.includes(';') &&
               script.length < 200; // 文件路径通常不会太长
    }

    /**
     * 将脚本内容写入文件系统
     */
    private writeScriptToFile(script: string, name?: string): string {
        const fs = wx.getFileSystemManager();
        const fileName = name ? `worker-${name}.js` : `worker-${Date.now()}.js`;
        const filePath = `${wx.env.USER_DATA_PATH}/${fileName}`;

        try {
            fs.writeFileSync(filePath, script, 'utf8');
            return filePath;
        } catch (error) {
            throw new Error(`写入Worker脚本文件失败: ${(error as Error).message}`);
        }
    }

    public get state(): 'running' | 'terminated' {
        return this._state;
    }

    public postMessage(message: any, transfer?: Transferable[]): void {
        if (this._state === 'terminated') {
            throw new Error('Worker已被终止');
        }

        try {
            // 微信小游戏 Worker 只支持可序列化对象，忽略 transfer 参数
            this.worker.postMessage(message);
        } catch (error) {
            throw new Error(`发送消息到微信Worker失败: ${(error as Error).message}`);
        }
    }

    public onMessage(handler: (event: { data: any }) => void): void {
        // 微信小游戏使用 onMessage 方法，不是 onmessage 属性
        this.worker.onMessage((res: any) => {
            handler({ data: res });
        });
    }

    public onError(handler: (error: ErrorEvent) => void): void {
        // 注意：微信小游戏 Worker 的错误处理可能与标准不同
        if (this.worker.onError) {
            this.worker.onError(handler);
        }
    }

    public terminate(): void {
        if (this._state === 'running') {
            try {
                this.worker.terminate();
                this._state = 'terminated';

                // 清理临时脚本文件
                this.cleanupScriptFile();
            } catch (error) {
                console.error('终止微信Worker失败:', error);
            }
        }
    }

    /**
     * 清理临时脚本文件
     */
    private cleanupScriptFile(): void {
        // 只清理临时创建的文件，不清理用户提供的文件路径
        if (this.scriptPath && this.isTemporaryFile) {
            try {
                const fs = wx.getFileSystemManager();
                fs.unlinkSync(this.scriptPath);
            } catch (error) {
                console.warn('清理Worker脚本文件失败:', error);
            }
        }
    }
}
```

## 使用方法

### 1. 复制代码

将上述代码复制到你的项目中，例如 `src/platform/WeChatMiniGameAdapter.ts`。

### 2. 注册适配器

```typescript
import { PlatformManager } from '@esengine/ecs-framework';
import { WeChatMiniGameAdapter } from './platform/WeChatMiniGameAdapter';

// 检查是否在微信小游戏环境
if (typeof wx !== 'undefined') {
    const wechatAdapter = new WeChatMiniGameAdapter();
    PlatformManager.getInstance().registerAdapter(wechatAdapter);
}
```

### 3. Worker 使用方式

微信小游戏适配器支持两种 Worker 使用方式：

#### 方式一：使用脚本文件路径（推荐）

```typescript
// 1. 在 game.json 中配置 Worker 路径
/*
{
  "workers": "workers"
}
*/

// 2. 创建 Worker 脚本文件 workers/physics.js
// workers/physics.js 内容：
/*
// 微信小游戏 Worker 中使用 worker 对象，不是 self
worker.onMessage(function(data) {
    const { entities, deltaTime, systemConfig } = data;

    // 处理物理计算
    const results = entities.map(entity => {
        entity.vy += systemConfig.gravity * deltaTime;
        entity.x += entity.vx * deltaTime;
        entity.y += entity.vy * deltaTime;
        return entity;
    });

    worker.postMessage({ result: results });
});
*/

// 2. 在 WorkerEntitySystem 中使用
class PhysicsSystem extends WorkerEntitySystem {
    constructor() {
        super(Matcher.all(Transform, Velocity), {
            enableWorker: true,
            workerCount: 1, // 微信小游戏限制
            systemConfig: { gravity: 100 }
        });
    }

    // 重写创建 Worker 脚本的方法，返回文件路径
    private createWorkerScript(): string {
        return 'workers/physics.js'; // 微信小游戏使用相对路径
    }
}
```

#### 方式二：动态脚本内容（自动处理）

```typescript
// WorkerEntitySystem 会自动将用户的 workerProcess 函数序列化
class PhysicsSystem extends WorkerEntitySystem {
    protected workerProcess(entities, deltaTime, config) {
        return entities.map(entity => {
            entity.vy += config.gravity * deltaTime;
            entity.x += entity.vx * deltaTime;
            entity.y += entity.vy * deltaTime;
            return entity;
        });
    }
}
// 框架会自动将此函数内容写入临时文件并创建 Worker
```

### 4. 获取设备信息

```typescript
const manager = PlatformManager.getInstance();
if (manager.hasAdapter()) {
    const adapter = manager.getAdapter();
    console.log('微信设备信息:', adapter.getDeviceInfo());
}
```

## 官方文档参考

在使用微信小游戏 Worker 之前，建议先阅读官方文档：

- [wx.createWorker API](https://developers.weixin.qq.com/minigame/dev/api/worker/wx.createWorker.html)
- [Worker.postMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.postMessage.html)
- [Worker.onMessage API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.onMessage.html)
- [Worker.terminate API](https://developers.weixin.qq.com/minigame/dev/api/worker/Worker.terminate.html)

## 重要注意事项

### Worker 限制和配置

微信小游戏的 Worker 有以下限制：

- **数量限制**: 最多只能创建 1 个 Worker
- **版本要求**: 需要基础库 1.9.90 及以上版本
- **配置要求**: 必须在 `game.json` 中配置 workers 路径
- **文件路径**: Worker 脚本必须为项目内的相对路径
- **生命周期**: 创建新 Worker 前必须先调用 `Worker.terminate()` 终止当前 Worker
- **API 差异**: 使用 `worker.onMessage()` 而不是 `self.onmessage`

#### 必要配置

在 `game.json` 中添加 workers 配置：

```json
{
  "deviceOrientation": "portrait",
  "showStatusBar": false,
  "workers": "workers",
  "subpackages": []
}
```

### 内存限制

微信小游戏有严格的内存限制：

- 通常限制在 256MB - 512MB
- 需要及时释放不用的资源
- 避免内存泄漏

### API 限制

- 不支持 `eval()` 函数
- 不支持 `Function` 构造器
- DOM API 受限
- 文件系统 API 受限

## 性能优化建议

### 1. 分帧处理

```typescript
class FramedProcessor {
    private tasks: (() => void)[] = [];
    private isProcessing = false;

    public addTask(task: () => void): void {
        this.tasks.push(task);
        if (!this.isProcessing) {
            this.processNextFrame();
        }
    }

    private processNextFrame(): void {
        this.isProcessing = true;
        const startTime = Date.now();
        const frameTime = 16; // 16ms per frame

        while (this.tasks.length > 0 && Date.now() - startTime < frameTime) {
            const task = this.tasks.shift();
            if (task) task();
        }

        if (this.tasks.length > 0) {
            setTimeout(() => this.processNextFrame(), 0);
        } else {
            this.isProcessing = false;
        }
    }
}
```

### 2. 内存管理

```typescript
class MemoryManager {
    private static readonly MAX_MEMORY = 256 * 1024 * 1024; // 256MB

    public static checkMemoryUsage(): void {
        if (typeof wx !== 'undefined' && wx.getPerformance) {
            const performance = wx.getPerformance();
            const memoryInfo = performance.getEntries().find(
                (entry: any) => entry.entryType === 'memory'
            );

            if (memoryInfo && memoryInfo.usedJSHeapSize > this.MAX_MEMORY * 0.8) {
                console.warn('内存使用率过高，建议清理资源');
                // 触发垃圾回收或资源清理
            }
        }
    }
}
```

## 调试技巧

```typescript
// 检查微信小游戏环境
if (typeof wx !== 'undefined') {
    const adapter = new WeChatMiniGameAdapter();

    console.log('微信版本:', adapter.version);
    console.log('设备信息:', adapter.getDeviceInfo());
    console.log('平台配置:', adapter.getPlatformConfig());

    // 检查功能支持
    console.log('Worker支持:', adapter.isWorkerSupported());
    console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
}
```

## 微信小游戏特殊API

```typescript
// 获取设备性能等级
if (typeof wx !== 'undefined' && wx.getDeviceInfo) {
    wx.getDeviceInfo({
        success: (res) => {
            console.log('设备性能等级:', res.benchmarkLevel);
        }
    });
}

// 监听内存警告
if (typeof wx !== 'undefined' && wx.onMemoryWarning) {
    wx.onMemoryWarning(() => {
        console.warn('收到内存警告，开始清理资源');
        // 清理不必要的资源
    });
}
```