项目进展

2025-11-28 18:11:30 +08:00
parent 4db1caed6d
commit 8c7f70ae9b
12 changed files with 1605 additions and 0 deletions
--- a/tools/emscripten/.gitignore
+++ b/tools/emscripten/.gitignore
@@ -0,0 +1,20 @@
+# Emscripten SDK 目录 - 不提交源码
+emsdk/
+
+# 环境设置脚本（自动生成）
+setup-env.bat
+
+# 临时文件和缓存
+*.tmp
+*.cache
+*.log
+
+# 编译输出临时文件
+*.o
+*.obj
+*.wasm.tmp
+*.js.tmp
+
+# Emscripten 缓存目录
+.emscripten_cache/
+.emscripten_ports/
--- 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/)
--- a/tools/emscripten/gen-asm.bat
+++ b/tools/emscripten/gen-asm.bat
@@ -0,0 +1,140 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo ========================================
+echo WASM to asm.js 转换器
+echo ========================================
+echo.
+
+:: 检查参数
+if "%~1"=="" (
+    echo 错误: 缺少 WASM 文件路径参数
+    echo.
+    echo 用法: gen-asm.bat ^<wasm文件路径^> ^<输出路径^>
+    echo.
+    echo 示例:
+    echo   gen-asm.bat pinball.wasm output/pinball-asm.js
+    echo   gen-asm.bat ../target/wasm32-unknown-unknown/release/pinball_physics.wasm ../client-cocos/assets/wasm/pinball-asm.js
+    echo.
+    goto :error
+)
+
+if "%~2"=="" (
+    echo 错误: 缺少输出路径参数
+    echo.
+    echo 用法: gen-asm.bat ^<wasm文件路径^> ^<输出路径^>
+    echo.
+    goto :error
+)
+
+set WASM_FILE=%~1
+set OUTPUT_FILE=%~2
+set SCRIPT_DIR=%~dp0
+
+:: 转换为绝对路径
+for %%i in ("%WASM_FILE%") do set WASM_FILE_ABS=%%~fi
+for %%i in ("%OUTPUT_FILE%") do set OUTPUT_FILE_ABS=%%~fi
+for %%i in ("%OUTPUT_FILE_ABS%") do set OUTPUT_DIR=%%~dpi
+
+:: 检查输入文件是否存在
+if not exist "%WASM_FILE_ABS%" (
+    echo 错误: WASM 文件不存在: %WASM_FILE_ABS%
+    goto :error
+)
+
+:: 创建输出目录（如果不存在）
+if not exist "%OUTPUT_DIR%" (
+    echo 创建输出目录: %OUTPUT_DIR%
+    mkdir "%OUTPUT_DIR%"
+)
+
+echo 输入文件: %WASM_FILE_ABS%
+echo 输出文件: %OUTPUT_FILE_ABS%
+echo.
+
+:: 检查 Emscripten 环境
+call emcc --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo Emscripten 环境未设置，尝试自动设置...
+    if exist "%SCRIPT_DIR%emsdk\emsdk_env.bat" (
+        echo 运行 Emscripten 环境设置...
+        call "%SCRIPT_DIR%emsdk\emsdk_env.bat"
+        call emcc --version >nul 2>&1
+        if %errorlevel% neq 0 (
+            echo 错误: 无法设置 Emscripten 环境
+            echo 请先运行 install.bat 安装 Emscripten，或手动运行 setup-env.bat
+            goto :error
+        )
+    ) else (
+        echo 错误: 未找到 Emscripten 安装
+        echo 请先运行 install.bat 安装 Emscripten
+        goto :error
+    )
+)
+
+echo Emscripten 版本信息:
+call emcc --version | findstr "emcc"
+echo.
+
+echo 开始转换 WASM 到 asm.js...
+
+:: 使用 emcc 将 WASM 转换为 asm.js
+:: 关键参数说明:
+:: -s WASM=0           : 禁用 WebAssembly，生成 asm.js
+:: -s LEGACY_VM_SUPPORT=1 : 支持较老的 JavaScript 引擎
+:: -s ALLOW_MEMORY_GROWTH=1 : 允许内存增长
+:: -s NO_EXIT_RUNTIME=1 : 不退出运行时
+:: -s EXPORTED_FUNCTIONS=["_main"] : 导出函数（根据需要调整）
+:: -s MODULARIZE=1     : 生成模块化代码
+:: -s EXPORT_NAME="Module" : 导出模块名
+:: -O3                 : 最高优化级别
+
+call emcc "%WASM_FILE_ABS%" ^
+    -s WASM=0 ^
+    -s LEGACY_VM_SUPPORT=1 ^
+    -s ALLOW_MEMORY_GROWTH=1 ^
+    -s NO_EXIT_RUNTIME=1 ^
+    -s MODULARIZE=1 ^
+    -s EXPORT_NAME="PinballModule" ^
+    -s EXPORTED_RUNTIME_METHODS="['ccall','cwrap']" ^
+    -O3 ^
+    --closure 0 ^
+    -o "%OUTPUT_FILE_ABS%"
+
+if %errorlevel% neq 0 (
+    echo 错误: 转换失败
+    goto :error
+)
+
+echo.
+echo ========================================
+echo 转换成功！
+echo ========================================
+echo.
+echo 输出文件: %OUTPUT_FILE_ABS%
+
+:: 显示文件大小
+for %%A in ("%OUTPUT_FILE_ABS%") do (
+    set file_size=%%~zA
+    set /a size_kb=!file_size!/1024
+    echo 文件大小: !size_kb! KB
+)
+
+echo.
+echo 使用方法:
+echo 在 HTML 中引入生成的 JS 文件，然后使用:
+echo   PinballModule().then(function(Module) {
+echo     // 使用 Module.ccall 调用导出的函数
+echo     var result = Module.ccall('function_name', 'number', ['number'], [42]);
+echo   });
+echo.
+
+goto :end
+
+:error
+echo.
+echo 转换失败！
+exit /b 1
+
+:end
+pause
--- a/tools/emscripten/install.bat
+++ b/tools/emscripten/install.bat
@@ -0,0 +1,106 @@
+@echo off
+setlocal enabledelayedexpansion
+
+echo ========================================
+echo Emscripten 安装脚本 (版本: 3.1.41)
+echo ========================================
+echo.
+
+:: 设置变量
+set EMSCRIPTEN_VERSION=3.1.41
+set SCRIPT_DIR=%~dp0
+set EMSDK_DIR=%SCRIPT_DIR%emsdk
+
+:: 检查是否已存在 emsdk 目录
+if exist "%EMSDK_DIR%" (
+    echo 检测到已存在的 emsdk 目录...
+    set /p "choice=是否重新安装? (y/n): "
+    if /i "!choice!" neq "y" (
+        echo 安装已取消
+        goto :end
+    )
+    echo 删除现有安装...
+    rmdir /s /q "%EMSDK_DIR%"
+)
+
+:: 检查 Git 是否可用
+git --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo 错误: 未找到 Git，请先安装 Git
+    goto :error
+)
+
+:: 检查 Python 是否可用
+python --version >nul 2>&1
+if %errorlevel% neq 0 (
+    echo 错误: 未找到 Python，请先安装 Python 3.x
+    goto :error
+)
+
+echo 开始下载 Emscripten SDK...
+cd /d "%SCRIPT_DIR%"
+git clone https://github.com/emscripten-core/emsdk.git
+if %errorlevel% neq 0 (
+    echo 错误: 下载 Emscripten SDK 失败
+    goto :error
+)
+
+echo.
+echo 进入 emsdk 目录...
+cd "%EMSDK_DIR%"
+
+echo 安装和激活 Emscripten %EMSCRIPTEN_VERSION%...
+call emsdk.bat install %EMSCRIPTEN_VERSION%
+if %errorlevel% neq 0 (
+    echo 错误: 安装 Emscripten %EMSCRIPTEN_VERSION% 失败
+    goto :error
+)
+
+echo.
+echo 激活 Emscripten %EMSCRIPTEN_VERSION%...
+call emsdk.bat activate %EMSCRIPTEN_VERSION%
+if %errorlevel% neq 0 (
+    echo 错误: 激活 Emscripten %EMSCRIPTEN_VERSION% 失败
+    goto :error
+)
+
+echo.
+echo 设置环境变量...
+call emsdk_env.bat
+
+echo.
+echo 验证安装...
+call emcc --version
+if %errorlevel% neq 0 (
+    echo 错误: Emscripten 安装验证失败
+    goto :error
+)
+
+echo.
+echo ========================================
+echo Emscripten %EMSCRIPTEN_VERSION% 安装成功！
+echo ========================================
+echo.
+echo 注意事项:
+echo 1. 每次使用前需要运行 setup-env.bat 来设置环境变量
+echo 2. 或者手动运行: tools\emscripten\emsdk\emsdk_env.bat
+echo.
+echo 创建快速设置脚本...
+echo @echo off > "%SCRIPT_DIR%setup-env.bat"
+echo echo 设置 Emscripten 环境变量... >> "%SCRIPT_DIR%setup-env.bat"
+echo call "%EMSDK_DIR%\emsdk_env.bat" >> "%SCRIPT_DIR%setup-env.bat"
+echo echo Emscripten 环境已设置完成 >> "%SCRIPT_DIR%setup-env.bat"
+
+echo setup-env.bat 已创建
+goto :end
+
+:error
+echo.
+echo ========================================
+echo 安装失败！请检查错误信息
+echo ========================================
+exit /b 1
+
+:end
+echo.
+pause