浏览器适配器

概述

浏览器平台适配器为标准Web浏览器环境提供支持，包括 Chrome、Firefox、Safari、Edge 等现代浏览器。

特性支持

✅ Worker: 支持 Web Worker 和 Module Worker
✅ SharedArrayBuffer: 支持（需要COOP/COEP头部）
✅ Transferable Objects: 完全支持
✅ 高精度时间: 使用 performance.now()
✅ 基础信息: 浏览器版本和基本配置

完整实现

typescript

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

/**
 * 浏览器平台适配器
 * 支持标准Web浏览器环境
 */
export class BrowserAdapter implements IPlatformAdapter {
    public readonly name = 'browser';
    public readonly version: string;

    constructor() {
        this.version = this.getBrowserInfo();
    }

    /**
     * 检查是否支持Worker
     */
    public isWorkerSupported(): boolean {
        return typeof Worker !== 'undefined';
    }

    /**
     * 检查是否支持SharedArrayBuffer
     */
    public isSharedArrayBufferSupported(): boolean {
        return typeof SharedArrayBuffer !== 'undefined' && this.checkSharedArrayBufferEnabled();
    }

    /**
     * 获取硬件并发数（CPU核心数）
     */
    public getHardwareConcurrency(): number {
        return navigator.hardwareConcurrency || 4;
    }

    /**
     * 创建Worker
     */
    public createWorker(script: string, options: WorkerCreationOptions = {}): PlatformWorker {
        if (!this.isWorkerSupported()) {
            throw new Error('浏览器不支持Worker');
        }

        try {
            return new BrowserWorker(script, options);
        } catch (error) {
            throw new Error(`创建浏览器Worker失败: ${(error as Error).message}`);
        }
    }

    /**
     * 创建SharedArrayBuffer
     */
    public createSharedArrayBuffer(length: number): SharedArrayBuffer | null {
        if (!this.isSharedArrayBufferSupported()) {
            return null;
        }

        try {
            return new SharedArrayBuffer(length);
        } catch (error) {
            console.warn('SharedArrayBuffer创建失败:', error);
            return null;
        }
    }

    /**
     * 获取高精度时间戳
     */
    public getHighResTimestamp(): number {
        return performance.now();
    }

    /**
     * 获取平台配置
     */
    public getPlatformConfig(): PlatformConfig {
        return {
            maxWorkerCount: this.getHardwareConcurrency(),
            supportsModuleWorker: false,
            supportsTransferableObjects: true,
            maxSharedArrayBufferSize: 1024 * 1024 * 1024, // 1GB
            workerScriptPrefix: '',
            limitations: {
                noEval: false,
                requiresWorkerInit: false
            }
        };
    }

    /**
     * 获取浏览器信息
     */
    private getBrowserInfo(): string {
        const userAgent = navigator.userAgent;
        if (userAgent.includes('Chrome')) {
            const match = userAgent.match(/Chrome\/([0-9.]+)/);
            return match ? `Chrome ${match[1]}` : 'Chrome';
        } else if (userAgent.includes('Firefox')) {
            const match = userAgent.match(/Firefox\/([0-9.]+)/);
            if (match) return `Firefox ${match[1]}`;
        } else if (userAgent.includes('Safari')) {
            const match = userAgent.match(/Version\/([0-9.]+)/);
            if (match) return `Safari ${match[1]}`;
        }
        return 'Unknown Browser';
    }

    /**
     * 检查SharedArrayBuffer是否真正可用
     */
    private checkSharedArrayBufferEnabled(): boolean {
        try {
            new SharedArrayBuffer(8);
            return true;
        } catch {
            return false;
        }
    }
}

/**
 * 浏览器Worker封装
 */
class BrowserWorker implements PlatformWorker {
    private _state: 'running' | 'terminated' = 'running';
    private worker: Worker;

    constructor(script: string, options: WorkerCreationOptions = {}) {
        this.worker = this.createBrowserWorker(script, options);
    }

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

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

        try {
            if (transfer && transfer.length > 0) {
                this.worker.postMessage(message, transfer);
            } else {
                this.worker.postMessage(message);
            }
        } catch (error) {
            throw new Error(`发送消息到Worker失败: ${(error as Error).message}`);
        }
    }

    public onMessage(handler: (event: { data: any }) => void): void {
        this.worker.onmessage = (event: MessageEvent) => {
            handler({ data: event.data });
        };
    }

    public onError(handler: (error: ErrorEvent) => void): void {
        this.worker.onerror = handler;
    }

    public terminate(): void {
        if (this._state === 'running') {
            try {
                this.worker.terminate();
                this._state = 'terminated';
            } catch (error) {
                console.error('终止Worker失败:', error);
            }
        }
    }

    /**
     * 创建浏览器Worker
     */
    private createBrowserWorker(script: string, options: WorkerCreationOptions): Worker {
        try {
            // 创建Blob URL
            const blob = new Blob([script], { type: 'application/javascript' });
            const url = URL.createObjectURL(blob);

            // 创建Worker
            const worker = new Worker(url, {
                type: options.type || 'classic',
                credentials: options.credentials,
                name: options.name
            });

            // 清理Blob URL（延迟清理，确保Worker已加载）
            setTimeout(() => {
                URL.revokeObjectURL(url);
            }, 1000);

            return worker;
        } catch (error) {
            throw new Error(`无法创建浏览器Worker: ${(error as Error).message}`);
        }
    }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205

使用方法

1. 复制代码

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

2. 注册适配器

typescript

import { PlatformManager } from '@esengine/ecs-framework';
import { BrowserAdapter } from './platform/BrowserAdapter';

// 创建并注册浏览器适配器
const browserAdapter = new BrowserAdapter();
PlatformManager.registerAdapter(browserAdapter);

// 框架会自动检测和使用合适的适配器

3. 使用 WorkerEntitySystem

浏览器适配器与 WorkerEntitySystem 配合使用，框架会自动处理 Worker 脚本的创建：

typescript

import { WorkerEntitySystem, Matcher } from '@esengine/ecs-framework';

class PhysicsSystem extends WorkerEntitySystem {
    constructor() {
        super(Matcher.all(Transform, Velocity), {
            enableWorker: true,
            workerCount: navigator.hardwareConcurrency || 4,
            useSharedArrayBuffer: true,
            systemConfig: { gravity: 9.8 }
        });
    }

    protected getDefaultEntityDataSize(): number {
        return 6; // x, y, vx, vy, mass, radius
    }

    protected extractEntityData(entity: Entity): PhysicsData {
        const transform = entity.getComponent(Transform);
        const velocity = entity.getComponent(Velocity);
        return {
            x: transform.x,
            y: transform.y,
            vx: velocity.x,
            vy: velocity.y,
            mass: 1,
            radius: 10
        };
    }

    // 这个函数会被自动序列化并在Worker中执行
    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;
        });
    }

    protected applyResult(entity: Entity, result: PhysicsData): void {
        const transform = entity.getComponent(Transform);
        const velocity = entity.getComponent(Velocity);

        transform.x = result.x;
        transform.y = result.y;
        velocity.x = result.vx;
        velocity.y = result.vy;
    }
}

interface PhysicsData {
    x: number;
    y: number;
    vx: number;
    vy: number;
    mass: number;
    radius: number;
}

4. 验证适配器工作状态

typescript

// 验证适配器是否正常工作
const adapter = new BrowserAdapter();
console.log('适配器名称:', adapter.name);
console.log('浏览器版本:', adapter.version);
console.log('Worker支持:', adapter.isWorkerSupported());
console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
console.log('CPU核心数:', adapter.getHardwareConcurrency());

重要注意事项

SharedArrayBuffer 支持

SharedArrayBuffer 需要特殊的安全配置：

HTTPS: 必须在安全上下文中使用
COOP/COEP 头部: 需要设置正确的跨域隔离头部

html

<!-- 在 HTML 中设置 -->
<meta http-equiv="Cross-Origin-Opener-Policy" content="same-origin">
<meta http-equiv="Cross-Origin-Embedder-Policy" content="require-corp">

或在服务器配置中设置：

Cross-Origin-Opener-Policy: same-origin
Cross-Origin-Embedder-Policy: require-corp

浏览器兼容性

Worker: 所有现代浏览器支持
Module Worker: Chrome 80+, Firefox 114+
SharedArrayBuffer: Chrome 68+, Firefox 79+（需要COOP/COEP）
Transferable Objects: 所有现代浏览器支持

性能优化建议

Worker 池: 复用 Worker 实例，避免频繁创建和销毁
数据传输: 使用 Transferable Objects 减少数据拷贝
SharedArrayBuffer: 对于大量数据共享，使用 SharedArrayBuffer
模块 Worker: 在支持的浏览器中使用模块 Worker 来更好地组织代码

调试技巧

typescript

// 检查浏览器支持情况
const adapter = new BrowserAdapter();
console.log('Worker支持:', adapter.isWorkerSupported());
console.log('SharedArrayBuffer支持:', adapter.isSharedArrayBufferSupported());
console.log('硬件并发数:', adapter.getHardwareConcurrency());
console.log('平台配置:', adapter.getPlatformConfig());

浏览器适配器 ​

概述 ​

特性支持 ​

完整实现 ​

使用方法 ​

1. 复制代码 ​

2. 注册适配器 ​

3. 使用 WorkerEntitySystem ​

4. 验证适配器工作状态 ​

重要注意事项 ​

SharedArrayBuffer 支持 ​

浏览器兼容性 ​

性能优化建议 ​

调试技巧 ​

浏览器适配器

概述

特性支持

完整实现

使用方法

1. 复制代码

2. 注册适配器

3. 使用 WorkerEntitySystem

4. 验证适配器工作状态

重要注意事项

SharedArrayBuffer 支持

浏览器兼容性

性能优化建议

调试技巧