feat: 集成Rust WASM渲染引擎与TypeScript ECS框架 (#228)

* feat: 集成Rust WASM渲染引擎与TypeScript ECS框架 * feat: 增强编辑器UI功能与跨平台支持 * fix: 修复CI测试和类型检查问题 * fix: 修复CI问题并提高测试覆盖率 * fix: 修复CI问题并提高测试覆盖率
2025-11-21 10:03:18 +08:00
parent 8b9616837d
commit a768b890fd
107 changed files with 10221 additions and 477 deletions
--- a/packages/platform-common/README.md
+++ b/packages/platform-common/README.md
@@ -0,0 +1,48 @@
+# @esengine/platform-common
+
+平台通用接口定义包，定义了所有平台子系统的接口规范。
+
+## 安装
+
+```bash
+npm install @esengine/platform-common
+```
+
+## 用途
+
+此包仅包含 TypeScript 接口定义，供各平台适配器包实现：
+
+- `@esengine/platform-wechat` - 微信小游戏
+- `@esengine/platform-web` - Web 浏览器
+- `@esengine/platform-bytedance` - 抖音小游戏
+
+## 接口列表
+
+### Canvas/渲染
+- `IPlatformCanvasSubsystem`
+- `IPlatformCanvas`
+- `IPlatformImage`
+
+### 音频
+- `IPlatformAudioSubsystem`
+- `IPlatformAudioContext`
+
+### 存储
+- `IPlatformStorageSubsystem`
+
+### 网络
+- `IPlatformNetworkSubsystem`
+- `IPlatformWebSocket`
+
+### 输入
+- `IPlatformInputSubsystem`
+
+### 文件系统
+- `IPlatformFileSubsystem`
+
+### WASM
+- `IPlatformWASMSubsystem`
+
+## License
+
+MIT
--- a/packages/platform-common/package.json
+++ b/packages/platform-common/package.json
@@ -0,0 +1,50 @@
+{
+  "name": "@esengine/platform-common",
+  "version": "1.0.0",
+  "description": "平台通用接口定义",
+  "main": "dist/index.js",
+  "module": "dist/index.mjs",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rollup -c",
+    "build:npm": "npm run build",
+    "clean": "rimraf dist",
+    "type-check": "npx tsc --noEmit",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ecs",
+    "platform",
+    "interface",
+    "common"
+  ],
+  "author": "yhh",
+  "license": "MIT",
+  "devDependencies": {
+    "@rollup/plugin-commonjs": "^28.0.3",
+    "@rollup/plugin-node-resolve": "^16.0.1",
+    "@rollup/plugin-typescript": "^11.1.6",
+    "rimraf": "^5.0.0",
+    "rollup": "^4.42.0",
+    "rollup-plugin-dts": "^6.2.1",
+    "typescript": "^5.8.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/esengine/ecs-framework.git",
+    "directory": "packages/platform-common"
+  }
+}
--- a/packages/platform-common/rollup.config.js
+++ b/packages/platform-common/rollup.config.js
@@ -0,0 +1,40 @@
+import resolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import typescript from '@rollup/plugin-typescript';
+import dts from 'rollup-plugin-dts';
+
+export default [
+    // ESM and CJS builds
+    {
+        input: 'src/index.ts',
+        output: [
+            {
+                file: 'dist/index.mjs',
+                format: 'esm',
+                sourcemap: true
+            },
+            {
+                file: 'dist/index.js',
+                format: 'cjs',
+                sourcemap: true
+            }
+        ],
+        plugins: [
+            resolve(),
+            commonjs(),
+            typescript({
+                tsconfig: './tsconfig.json',
+                declaration: false
+            })
+        ]
+    },
+    // Type declarations
+    {
+        input: 'src/index.ts',
+        output: {
+            file: 'dist/index.d.ts',
+            format: 'esm'
+        },
+        plugins: [dts()]
+    }
+];
--- a/packages/platform-common/src/IPlatformSubsystems.ts
+++ b/packages/platform-common/src/IPlatformSubsystems.ts
@@ -0,0 +1,632 @@
+/**
+ * 平台子系统接口定义
+ * 将平台能力分解为独立的子系统，支持按需实现和代码裁剪
+ */
+
+// ============================================================================
+// Canvas/渲染子系统
+// ============================================================================
+
+/**
+ * 平台 Canvas 对象抽象
+ */
+/**
+ * Canvas 上下文属性（兼容 Web 和小游戏平台）
+ */
+export interface CanvasContextAttributes {
+    alpha?: boolean | number;
+    antialias?: boolean;
+    depth?: boolean;
+    stencil?: boolean;
+    premultipliedAlpha?: boolean;
+    preserveDrawingBuffer?: boolean;
+    failIfMajorPerformanceCaveat?: boolean;
+    powerPreference?: 'default' | 'high-performance' | 'low-power';
+    antialiasSamples?: number;
+}
+
+export interface IPlatformCanvas {
+    width: number;
+    height: number;
+    getContext(contextType: '2d' | 'webgl' | 'webgl2', contextAttributes?: CanvasContextAttributes): RenderingContext | null;
+    toDataURL(): string;
+    toTempFilePath?(options: TempFilePathOptions): void;
+}
+
+/**
+ * 平台 Image 对象抽象
+ */
+export interface IPlatformImage {
+    src: string;
+    width: number;
+    height: number;
+    onload: (() => void) | null;
+    onerror: ((error: any) => void) | null;
+}
+
+/**
+ * 临时文件路径选项
+ */
+export interface TempFilePathOptions {
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    destWidth?: number;
+    destHeight?: number;
+    fileType?: 'png' | 'jpg';
+    quality?: number;
+    success?: (res: { tempFilePath: string }) => void;
+    fail?: (error: any) => void;
+    complete?: () => void;
+}
+
+/**
+ * Canvas 子系统接口
+ */
+export interface IPlatformCanvasSubsystem {
+    /**
+     * 创建主 Canvas（首次调用）或离屏 Canvas
+     */
+    createCanvas(width?: number, height?: number): IPlatformCanvas;
+
+    /**
+     * 创建图片对象
+     */
+    createImage(): IPlatformImage;
+
+    /**
+     * 创建 ImageData
+     */
+    createImageData?(width: number, height: number): ImageData;
+
+    /**
+     * 获取屏幕宽度
+     */
+    getScreenWidth(): number;
+
+    /**
+     * 获取屏幕高度
+     */
+    getScreenHeight(): number;
+
+    /**
+     * 获取设备像素比
+     */
+    getDevicePixelRatio(): number;
+}
+
+// ============================================================================
+// 音频子系统
+// ============================================================================
+
+/**
+ * 平台音频上下文抽象
+ */
+export interface IPlatformAudioContext {
+    src: string;
+    autoplay: boolean;
+    loop: boolean;
+    volume: number;
+    duration: number;
+    currentTime: number;
+    paused: boolean;
+    buffered: number;
+
+    play(): void;
+    pause(): void;
+    stop(): void;
+    seek(position: number): void;
+    destroy(): void;
+
+    onPlay(callback: () => void): void;
+    onPause(callback: () => void): void;
+    onStop(callback: () => void): void;
+    onEnded(callback: () => void): void;
+    onError(callback: (error: { errCode: number; errMsg: string }) => void): void;
+    onTimeUpdate(callback: () => void): void;
+    onCanplay(callback: () => void): void;
+    onSeeking(callback: () => void): void;
+    onSeeked(callback: () => void): void;
+
+    offPlay(callback: () => void): void;
+    offPause(callback: () => void): void;
+    offStop(callback: () => void): void;
+    offEnded(callback: () => void): void;
+    offError(callback: (error: { errCode: number; errMsg: string }) => void): void;
+    offTimeUpdate(callback: () => void): void;
+}
+
+/**
+ * 音频子系统接口
+ */
+export interface IPlatformAudioSubsystem {
+    /**
+     * 创建音频上下文
+     */
+    createAudioContext(options?: { useWebAudioImplement?: boolean }): IPlatformAudioContext;
+
+    /**
+     * 获取支持的音频格式
+     */
+    getSupportedFormats(): string[];
+
+    /**
+     * 设置静音模式下是否可以播放音频
+     */
+    setInnerAudioOption?(options: {
+        mixWithOther?: boolean;
+        obeyMuteSwitch?: boolean;
+        speakerOn?: boolean;
+    }): Promise<void>;
+}
+
+// ============================================================================
+// 存储子系统
+// ============================================================================
+
+/**
+ * 存储信息
+ */
+export interface StorageInfo {
+    keys: string[];
+    currentSize: number;
+    limitSize: number;
+}
+
+/**
+ * 存储子系统接口
+ */
+export interface IPlatformStorageSubsystem {
+    /**
+     * 同步获取存储
+     */
+    getStorageSync<T = any>(key: string): T | undefined;
+
+    /**
+     * 同步设置存储
+     */
+    setStorageSync<T = any>(key: string, value: T): void;
+
+    /**
+     * 同步移除存储
+     */
+    removeStorageSync(key: string): void;
+
+    /**
+     * 同步清空存储
+     */
+    clearStorageSync(): void;
+
+    /**
+     * 获取存储信息
+     */
+    getStorageInfoSync(): StorageInfo;
+
+    /**
+     * 异步获取存储
+     */
+    getStorage<T = any>(key: string): Promise<T | undefined>;
+
+    /**
+     * 异步设置存储
+     */
+    setStorage<T = any>(key: string, value: T): Promise<void>;
+
+    /**
+     * 异步移除存储
+     */
+    removeStorage(key: string): Promise<void>;
+
+    /**
+     * 异步清空存储
+     */
+    clearStorage(): Promise<void>;
+}
+
+// ============================================================================
+// 网络子系统
+// ============================================================================
+
+/**
+ * 请求配置
+ */
+export interface RequestConfig {
+    url: string;
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD' | 'OPTIONS' | 'TRACE' | 'CONNECT';
+    data?: any;
+    header?: Record<string, string>;
+    timeout?: number;
+    dataType?: 'json' | 'text' | 'arraybuffer';
+    responseType?: 'text' | 'arraybuffer';
+}
+
+/**
+ * 请求响应
+ */
+export interface RequestResponse<T = any> {
+    data: T;
+    statusCode: number;
+    header: Record<string, string>;
+}
+
+/**
+ * 下载任务
+ */
+export interface IDownloadTask {
+    abort(): void;
+    onProgressUpdate(callback: (res: {
+        progress: number;
+        totalBytesWritten: number;
+        totalBytesExpectedToWrite: number;
+    }) => void): void;
+    offProgressUpdate(callback: Function): void;
+}
+
+/**
+ * 上传任务
+ */
+export interface IUploadTask {
+    abort(): void;
+    onProgressUpdate(callback: (res: {
+        progress: number;
+        totalBytesSent: number;
+        totalBytesExpectedToSend: number;
+    }) => void): void;
+    offProgressUpdate(callback: Function): void;
+}
+
+/**
+ * WebSocket 接口
+ */
+export interface IPlatformWebSocket {
+    send(data: string | ArrayBuffer): void;
+    close(code?: number, reason?: string): void;
+    onOpen(callback: (res: { header: Record<string, string> }) => void): void;
+    onClose(callback: (res: { code: number; reason: string }) => void): void;
+    onError(callback: (error: any) => void): void;
+    onMessage(callback: (res: { data: string | ArrayBuffer }) => void): void;
+}
+
+/**
+ * 网络子系统接口
+ */
+export interface IPlatformNetworkSubsystem {
+    /**
+     * 发起请求
+     */
+    request<T = any>(config: RequestConfig): Promise<RequestResponse<T>>;
+
+    /**
+     * 下载文件
+     */
+    downloadFile(options: {
+        url: string;
+        filePath?: string;
+        header?: Record<string, string>;
+        timeout?: number;
+    }): Promise<{ tempFilePath: string; filePath?: string; statusCode: number }> & IDownloadTask;
+
+    /**
+     * 上传文件
+     */
+    uploadFile(options: {
+        url: string;
+        filePath: string;
+        name: string;
+        header?: Record<string, string>;
+        formData?: Record<string, any>;
+        timeout?: number;
+    }): Promise<{ data: string; statusCode: number }> & IUploadTask;
+
+    /**
+     * 创建 WebSocket 连接
+     */
+    connectSocket(options: {
+        url: string;
+        header?: Record<string, string>;
+        protocols?: string[];
+        timeout?: number;
+    }): IPlatformWebSocket;
+
+    /**
+     * 获取网络类型
+     */
+    getNetworkType(): Promise<'wifi' | '2g' | '3g' | '4g' | '5g' | 'unknown' | 'none'>;
+
+    /**
+     * 监听网络状态变化
+     */
+    onNetworkStatusChange(callback: (res: {
+        isConnected: boolean;
+        networkType: string;
+    }) => void): void;
+
+    /**
+     * 取消监听网络状态变化
+     */
+    offNetworkStatusChange(callback: Function): void;
+}
+
+// ============================================================================
+// 输入子系统
+// ============================================================================
+
+/**
+ * 触摸点信息
+ */
+export interface TouchInfo {
+    identifier: number;
+    x: number;
+    y: number;
+    force?: number;
+}
+
+/**
+ * 触摸事件
+ */
+export interface TouchEvent {
+    touches: TouchInfo[];
+    changedTouches: TouchInfo[];
+    timeStamp: number;
+}
+
+/**
+ * 触摸事件处理函数
+ */
+export type TouchHandler = (event: TouchEvent) => void;
+
+/**
+ * 输入子系统接口
+ */
+export interface IPlatformInputSubsystem {
+    /**
+     * 监听触摸开始
+     */
+    onTouchStart(handler: TouchHandler): void;
+
+    /**
+     * 监听触摸移动
+     */
+    onTouchMove(handler: TouchHandler): void;
+
+    /**
+     * 监听触摸结束
+     */
+    onTouchEnd(handler: TouchHandler): void;
+
+    /**
+     * 监听触摸取消
+     */
+    onTouchCancel(handler: TouchHandler): void;
+
+    /**
+     * 取消监听触摸开始
+     */
+    offTouchStart(handler: TouchHandler): void;
+
+    /**
+     * 取消监听触摸移动
+     */
+    offTouchMove(handler: TouchHandler): void;
+
+    /**
+     * 取消监听触摸结束
+     */
+    offTouchEnd(handler: TouchHandler): void;
+
+    /**
+     * 取消监听触摸取消
+     */
+    offTouchCancel(handler: TouchHandler): void;
+
+    /**
+     * 获取触摸点是否支持压感
+     */
+    supportsPressure?(): boolean;
+}
+
+// ============================================================================
+// 文件系统子系统
+// ============================================================================
+
+/**
+ * 文件信息
+ */
+export interface FileInfo {
+    size: number;
+    createTime: number;
+    modifyTime?: number;
+    isDirectory: boolean;
+    isFile: boolean;
+}
+
+/**
+ * 文件系统子系统接口
+ */
+export interface IPlatformFileSubsystem {
+    /**
+     * 读取文件
+     */
+    readFile(options: {
+        filePath: string;
+        encoding?: 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf-8' | 'utf8';
+        position?: number;
+        length?: number;
+    }): Promise<string | ArrayBuffer>;
+
+    /**
+     * 同步读取文件
+     */
+    readFileSync(
+        filePath: string,
+        encoding?: 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf-8' | 'utf8',
+        position?: number,
+        length?: number
+    ): string | ArrayBuffer;
+
+    /**
+     * 写入文件
+     */
+    writeFile(options: {
+        filePath: string;
+        data: string | ArrayBuffer;
+        encoding?: 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf-8' | 'utf8';
+    }): Promise<void>;
+
+    /**
+     * 同步写入文件
+     */
+    writeFileSync(
+        filePath: string,
+        data: string | ArrayBuffer,
+        encoding?: 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf-8' | 'utf8'
+    ): void;
+
+    /**
+     * 追加文件内容
+     */
+    appendFile(options: {
+        filePath: string;
+        data: string | ArrayBuffer;
+        encoding?: 'ascii' | 'base64' | 'binary' | 'hex' | 'ucs2' | 'utf-8' | 'utf8';
+    }): Promise<void>;
+
+    /**
+     * 删除文件
+     */
+    unlink(filePath: string): Promise<void>;
+
+    /**
+     * 创建目录
+     */
+    mkdir(options: {
+        dirPath: string;
+        recursive?: boolean;
+    }): Promise<void>;
+
+    /**
+     * 删除目录
+     */
+    rmdir(options: {
+        dirPath: string;
+        recursive?: boolean;
+    }): Promise<void>;
+
+    /**
+     * 读取目录
+     */
+    readdir(dirPath: string): Promise<string[]>;
+
+    /**
+     * 获取文件信息
+     */
+    stat(path: string): Promise<FileInfo>;
+
+    /**
+     * 检查文件/目录是否存在
+     */
+    access(path: string): Promise<void>;
+
+    /**
+     * 重命名文件
+     */
+    rename(oldPath: string, newPath: string): Promise<void>;
+
+    /**
+     * 复制文件
+     */
+    copyFile(srcPath: string, destPath: string): Promise<void>;
+
+    /**
+     * 获取用户数据目录路径
+     */
+    getUserDataPath(): string;
+
+    /**
+     * 解压文件
+     */
+    unzip?(options: {
+        zipFilePath: string;
+        targetPath: string;
+    }): Promise<void>;
+}
+
+// ============================================================================
+// WASM 子系统
+// ============================================================================
+
+/**
+ * WASM 模块导出
+ */
+export type WASMExports = Record<string, WebAssembly.ExportValue>;
+
+/**
+ * WASM 导入值类型（兼容 Web 和小游戏平台）
+ */
+export type WASMImportValue = WebAssembly.ExportValue | number;
+
+/**
+ * WASM 模块导入
+ */
+export type WASMImports = Record<string, Record<string, WASMImportValue>>;
+
+/**
+ * WASM 实例
+ */
+export interface IWASMInstance {
+    exports: WASMExports;
+}
+
+/**
+ * WASM 子系统接口
+ */
+export interface IPlatformWASMSubsystem {
+    /**
+     * 实例化 WASM 模块
+     * @param path WASM 文件路径
+     * @param imports 导入对象
+     */
+    instantiate(path: string, imports?: WASMImports): Promise<IWASMInstance>;
+
+    /**
+     * 检查是否支持 WASM
+     */
+    isSupported(): boolean;
+}
+
+// ============================================================================
+// 系统信息
+// ============================================================================
+
+/**
+ * 系统信息
+ */
+export interface SystemInfo {
+    /** 设备品牌 */
+    brand: string;
+    /** 设备型号 */
+    model: string;
+    /** 设备像素比 */
+    pixelRatio: number;
+    /** 屏幕宽度 */
+    screenWidth: number;
+    /** 屏幕高度 */
+    screenHeight: number;
+    /** 可使用窗口宽度 */
+    windowWidth: number;
+    /** 可使用窗口高度 */
+    windowHeight: number;
+    /** 状态栏高度 */
+    statusBarHeight: number;
+    /** 操作系统及版本 */
+    system: string;
+    /** 客户端平台 */
+    platform: 'ios' | 'android' | 'windows' | 'mac' | 'devtools';
+    /** 客户端基础库版本 */
+    SDKVersion: string;
+    /** 设备性能等级 */
+    benchmarkLevel: number;
+    /** 设备内存大小 (MB) */
+    memorySize?: number;
+}
--- a/packages/platform-common/src/index.ts
+++ b/packages/platform-common/src/index.ts
@@ -0,0 +1,42 @@
+/**
+ * 平台通用接口定义包
+ * @packageDocumentation
+ */
+
+// 导出所有平台子系统接口
+export type {
+    // Canvas/渲染
+    IPlatformCanvas,
+    IPlatformImage,
+    IPlatformCanvasSubsystem,
+    TempFilePathOptions,
+    CanvasContextAttributes,
+    // 音频
+    IPlatformAudioContext,
+    IPlatformAudioSubsystem,
+    // 存储
+    IPlatformStorageSubsystem,
+    StorageInfo,
+    // 网络
+    IPlatformNetworkSubsystem,
+    RequestConfig,
+    RequestResponse,
+    IDownloadTask,
+    IUploadTask,
+    IPlatformWebSocket,
+    // 输入
+    IPlatformInputSubsystem,
+    TouchInfo,
+    TouchEvent,
+    TouchHandler,
+    // 文件系统
+    IPlatformFileSubsystem,
+    FileInfo,
+    // WASM
+    IPlatformWASMSubsystem,
+    IWASMInstance,
+    WASMExports,
+    WASMImports,
+    // 系统信息
+    SystemInfo
+} from './IPlatformSubsystems';
--- a/packages/platform-common/tsconfig.json
+++ b/packages/platform-common/tsconfig.json
@@ -0,0 +1,24 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "lib": ["ES2020", "DOM"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "strict": true,
+    "strictNullChecks": true,
+    "noImplicitAny": true,
+    "moduleResolution": "node",
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "resolveJsonModule": true,
+    "isolatedModules": true,
+    "noEmit": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}