janing/shooter-demo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
e8a07c695e941fa288fdfa0b1c40285e4b7501e3
shooter-demo/tools/emscripten/README.md
janing 8c7f70ae9b 项目进展
2025-11-28 18:11:30 +08:00

3.4 KiB
Raw Blame History

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

# 运行安装脚本
tools\emscripten\install.bat

前置要求:

  • Git (用于下载 emsdk)
  • Python 3.x (Emscripten 运行需要)

安装过程会:

  • 下载 Emscripten SDK
  • 安装指定版本 (3.1.41)
  • 验证安装
  • 创建环境设置脚本

2. 设置环境变量

每次使用前需要设置环境变量：

# 方法1: 使用自动生成的脚本
tools\emscripten\setup-env.bat

# 方法2: 手动运行
tools\emscripten\emsdk\emsdk_env.bat

3. 转换 WASM 为 asm.js

# 语法
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

工作流程示例

# 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 文件可以在浏览器中使用：

<!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 控制台的错误信息
  • 验证导出函数名称是否正确

相关链接