项目进展

2025-11-28 18:11:30 +08:00
parent 4db1caed6d
commit 8c7f70ae9b
12 changed files with 1605 additions and 0 deletions
--- a/tools/emscripten/README.md
+++ b/tools/emscripten/README.md
@@ -0,0 +1,125 @@
+# Emscripten 工具使用指南
+
+本目录包含用于安装和使用 Emscripten 的工具脚本，用于将 Rust 编译的 WebAssembly 转换为 asm.js。
+
+## 文件说明
+
+- `install.bat` - Emscripten 3.1.41 安装脚本
+- `gen-asm.bat` - WASM 转 asm.js 转换脚本
+- `setup-env.bat` - 环境变量设置脚本（安装后自动生成）
+- `.gitignore` - Git 忽略文件配置
+
+## 使用步骤
+
+### 1. 安装 Emscripten
+
+```batch
+# 运行安装脚本
+tools\emscripten\install.bat
+```
+
+**前置要求:**
+- Git (用于下载 emsdk)
+- Python 3.x (Emscripten 运行需要)
+
+安装过程会:
+- 下载 Emscripten SDK
+- 安装指定版本 (3.1.41)
+- 验证安装
+- 创建环境设置脚本
+
+### 2. 设置环境变量
+
+每次使用前需要设置环境变量：
+
+```batch
+# 方法1: 使用自动生成的脚本
+tools\emscripten\setup-env.bat
+
+# 方法2: 手动运行
+tools\emscripten\emsdk\emsdk_env.bat
+```
+
+### 3. 转换 WASM 为 asm.js
+
+```batch
+# 语法
+tools\emscripten\gen-asm.bat <wasm文件路径> <输出路径>
+
+# 示例1: 转换 pinball-physics
+tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
+
+# 示例2: 转换 server-rust
+tools\emscripten\gen-asm.bat server-rust\target\wasm32-unknown-unknown\release\server_rust.wasm client-cocos\assets\wasm\server-asm.js
+```
+
+## 工作流程示例
+
+```batch
+# 1. 首次安装
+tools\emscripten\install.bat
+
+# 2. 编译 Rust 项目为 WASM
+cd pinball-physics
+cargo build --target wasm32-unknown-unknown --release
+cd ..
+
+# 3. 设置 Emscripten 环境
+tools\emscripten\setup-env.bat
+
+# 4. 转换为 asm.js
+tools\emscripten\gen-asm.bat pinball-physics\target\wasm32-unknown-unknown\release\pinball_physics.wasm client-cocos\assets\wasm\pinball-asm.js
+```
+
+## 输出文件使用
+
+生成的 asm.js 文件可以在浏览器中使用：
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+    <script src="pinball-asm.js"></script>
+</head>
+<body>
+    <script>
+        PinballModule().then(function(Module) {
+            // 使用 Module.ccall 调用 Rust 导出的函数
+            var result = Module.ccall('exported_function', 'number', ['number'], [42]);
+            console.log('Result:', result);
+        });
+    </script>
+</body>
+</html>
+```
+
+## 注意事项
+
+1. **版本固定**: 当前使用 Emscripten 3.1.41 版本，确保兼容性
+2. **环境变量**: 每次新开命令行窗口都需要重新设置环境变量
+3. **文件大小**: asm.js 文件通常比 WebAssembly 大 3-5 倍
+4. **性能差异**: asm.js 性能不如原生 WebAssembly
+5. **浏览器兼容**: asm.js 主要用于兼容不支持 WebAssembly 的老旧浏览器
+
+## 故障排除
+
+### 安装问题
+- 确保网络连接正常，能够访问 GitHub
+- 检查 Git 和 Python 是否正确安装
+- 如果下载失败，可以删除 `emsdk` 目录重新运行
+
+### 转换问题
+- 确保 WASM 文件存在且格式正确
+- 检查 Emscripten 环境变量是否设置
+- 验证输出目录权限
+
+### 运行时问题
+- 确保在支持 asm.js 的浏览器中测试
+- 检查 JavaScript 控制台的错误信息
+- 验证导出函数名称是否正确
+
+## 相关链接
+
+- [Emscripten 官方文档](https://emscripten.org/docs/)
+- [asm.js 规范](http://asmjs.org/)
+- [Rust WebAssembly 指南](https://rustwasm.github.io/docs/book/)