CocosPlugin/esengine
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

规范为cococs wasm

Browse Source
This commit is contained in:
YHH
2025-06-09 18:00:50 +08:00
parent 757eff2937
commit f6250b6d5b
9 changed files with 459 additions and 1017 deletions
Download Patch File Download Diff File Expand all files Collapse all files

243
scripts/build-cocos.bat Normal file
View File

@@ -0,0 +1,243 @@
@echo off
setlocal enabledelayedexpansion
echo.
echo 🎮 构建 ECS Framework WASM for Cocos Creator
echo ============================================
echo.
:: 设置变量
set "RUST_DIR=src\wasm\rust-ecs-core"
set "OUTPUT_DIR=cocos-pkg"
set "WASM_NAME=ecs_wasm_core"
:: 检查必要工具
echo 🔍 检查构建环境...
where wasm-pack >nul 2>&1
if %errorlevel% neq 0 (
echo ❌ 错误: 未找到 wasm-pack
echo 请运行: cargo install wasm-pack
goto :error
)
where rustc >nul 2>&1
if %errorlevel% neq 0 (
echo ❌ 错误: 未找到 Rust 编译器
echo 请安装 Rust: https://rustup.rs/
goto :error
)
echo ✅ 构建环境检查通过
:: 进入 Rust 项目目录
cd /d "%RUST_DIR%"
if %errorlevel% neq 0 (
echo ❌ 错误: 无法进入目录 %RUST_DIR%
goto :error
)
echo.
echo 📦 开始编译 WASM 模块...
echo 目标环境: Cocos Creator (Web + Native)
echo.
:: 清理之前的构建
if exist "pkg" (
echo 🧹 清理旧的构建文件...
rmdir /s /q "pkg"
)
:: 使用 wasm-pack 构建（针对 web 环境）
echo 🔨 编译 WASM 模块...
wasm-pack build --target web --release --no-typescript --out-dir pkg --out-name %WASM_NAME%
if %errorlevel% neq 0 (
echo ❌ WASM 编译失败
goto :error
)
echo ✅ WASM 编译完成
:: 回到项目根目录
cd ..\..\..
:: 创建输出目录
if not exist "%OUTPUT_DIR%" (
mkdir "%OUTPUT_DIR%"
) else (
echo 🧹 清理输出目录...
del /q "%OUTPUT_DIR%\*.*" 2>nul
)
echo.
echo 📁 处理输出文件...
:: 复制和处理 JavaScript 胶水代码
set "JS_SOURCE=%RUST_DIR%\pkg\%WASM_NAME%.js"
set "TS_TARGET=%OUTPUT_DIR%\%WASM_NAME%.ts"
if exist "%JS_SOURCE%" (
echo ✓ 复制并转换 JS 文件为 TS: %WASM_NAME%.ts
copy "%JS_SOURCE%" "%TS_TARGET%" >nul
) else (
echo ❌ 错误: 未找到生成的 JS 文件
goto :error
)
:: 复制 WASM 文件（原生端用 .bin，微信小游戏用 .wasm）
set "WASM_SOURCE=%RUST_DIR%\pkg\%WASM_NAME%_bg.wasm"
set "BIN_TARGET=%OUTPUT_DIR%\%WASM_NAME%_bg.bin"
set "WASM_TARGET=%OUTPUT_DIR%\%WASM_NAME%_bg.wasm"
if exist "%WASM_SOURCE%" (
echo ✓ 复制 WASM 文件（原生端）: %WASM_NAME%_bg.bin
copy "%WASM_SOURCE%" "%BIN_TARGET%" >nul
echo ✓ 复制 WASM 文件（微信小游戏）: %WASM_NAME%_bg.wasm
copy "%WASM_SOURCE%" "%WASM_TARGET%" >nul
) else (
echo ❌ 错误: 未找到生成的 WASM 文件
goto :error
)
:: 复制 TypeScript 类型定义（如果存在）
set "DTS_SOURCE=%RUST_DIR%\pkg\%WASM_NAME%.d.ts"
set "DTS_TARGET=%OUTPUT_DIR%\%WASM_NAME%.d.ts"
set "BG_DTS_SOURCE=%RUST_DIR%\pkg\%WASM_NAME%_bg.wasm.d.ts"
set "BG_DTS_TARGET=%OUTPUT_DIR%\%WASM_NAME%_bg.wasm.d.ts"
if exist "%DTS_SOURCE%" (
echo ✓ 复制类型定义: %WASM_NAME%.d.ts
copy "%DTS_SOURCE%" "%DTS_TARGET%" >nul
)
if exist "%BG_DTS_SOURCE%" (
echo ✓ 复制 WASM 类型定义: %WASM_NAME%_bg.wasm.d.ts
copy "%BG_DTS_SOURCE%" "%BG_DTS_TARGET%" >nul
)
:: 生成 Cocos Creator 使用指南
echo.
echo 📋 生成使用指南...
(
echo # ECS Framework WASM for Cocos Creator
echo.
echo ## 文件说明
echo.
echo - `%WASM_NAME%.ts` - WASM 胶水代码（原 JS 文件重命名）
echo - `%WASM_NAME%_bg.bin` - WASM 二进制文件（原生端使用）
echo - `%WASM_NAME%_bg.wasm` - WASM 二进制文件（微信小游戏使用）
echo - `%WASM_NAME%.d.ts` - TypeScript 类型定义
echo.
echo ## 在 Cocos Creator 中使用
echo.
echo ### 1. 导入文件到项目
echo.
echo 1. 将 `%WASM_NAME%.ts` 放到 assets/scripts/ 目录
echo 2. 将 `%WASM_NAME%_bg.bin` 导入为 BufferAsset（原生端）
echo 3. 将 `%WASM_NAME%_bg.wasm` 放到微信小游戏构建目录
echo.
echo ### 2. 组件代码示例
echo.
echo ```typescript
echo import { _decorator, Component, BufferAsset } from 'cc';
echo import { initSync } from './%WASM_NAME%';
echo.
echo const { ccclass, property } = _decorator;
echo.
echo @ccclass('WasmLoader'^)
echo export class WasmLoader extends Component {
echo @property(BufferAsset^)
echo wasmAsset!: BufferAsset;
echo.
echo start(^) {
echo this.initWasm(^);
echo }
echo.
echo private async initWasm(^) {
echo try {
echo // 检查平台
echo if (typeof wx !== 'undefined'^) {
echo // 微信小游戏环境
echo initSync("/%WASM_NAME%_bg.wasm"^);
echo } else {
echo // 原生端/浏览器环境
echo const wasmBuffer = this.wasmAsset?.buffer(^);
echo if (wasmBuffer^) {
echo initSync(wasmBuffer^);
echo } else {
echo console.error('WASM 资源未正确加载'^);
echo return;
echo }
echo }
echo
echo console.log('✅ ECS WASM 模块初始化成功'^);
echo
echo // 这里可以开始使用 WASM 导出的函数
echo // 例如: wasmFunction(^);
echo
echo } catch (error^) {
echo console.error('❌ WASM 初始化失败:', error^);
echo console.log('↪️ 将使用 JavaScript 实现'^);
echo }
echo }
echo }
echo ```
echo.
echo ### 3. 微信小游戏配置
echo.
echo 使用 build-templates 自动复制 WASM 文件：
echo.
echo 1. 在项目 build-templates/wechatgame/ 目录下创建构建脚本
echo 2. 构建时会自动复制 %WASM_NAME%_bg.wasm 到发布目录
echo.
echo ## 注意事项
echo.
echo 1. 确保在使用 ECS 系统前初始化 WASM 模块
echo 2. 原生端使用 .bin 文件，微信小游戏使用 .wasm 文件
echo 3. 如果 WASM 初始化失败，框架会自动回退到 JavaScript 实现
echo 4. WASM 主要优化查询性能，对大多数应用场景提升有限
echo.
echo ## 重新构建
echo.
echo 运行 `build-cocos.bat` 重新编译最新的 WASM 模块
) > "%OUTPUT_DIR%\README.md"
:: 显示构建结果
echo.
echo 📊 构建结果：
for %%f in ("%OUTPUT_DIR%\*.*") do (
call :filesize "%%f"
echo %%~nxf: !size! KB
)
echo.
echo ✅ 构建完成！
echo 📦 输出目录: %OUTPUT_DIR%
echo 📋 使用说明: %OUTPUT_DIR%\README.md
echo.
echo 💡 下一步：
echo 1. 将文件导入到 Cocos Creator 项目
echo 2. 参考 README.md 集成到游戏中
echo 3. 对于微信小游戏，使用 build-templates 自动复制 WASM 文件
echo.
goto :end
:filesize
set "file=%~1"
for %%A in ("%file%") do set "bytes=%%~zA"
set /a size=bytes/1024
if %size% lss 1 set size=1
goto :eof
:error
echo.
echo ❌ 构建失败！
echo 请检查错误信息并重试。
echo.
pause
exit /b 1
:end
pause

278
scripts/build-wasm-release.js
View File

@@ -2,46 +2,23 @@ const fs = require('fs');
const path = require('path');
const { execSync } = require('child_process');
console.log('🚀 构建WASM发布包...');
console.log('🚀 构建 WASM 发布包（支持 Cocos Creator）...');
async function main() {
try {
// 确保WASM已构建
if (!fs.existsSync('./bin/wasm')) {
console.log('📦 构建WASM...');
execSync('npm run build:wasm', { stdio: 'inherit' });
}
// 构建 Cocos Creator 版本
console.log('🎮 构建 Cocos Creator 版本...');
await buildCocosVersion();
// 创建发布目录
const releaseDir = './wasm-release';
if (fs.existsSync(releaseDir)) {
execSync(`rimraf ${releaseDir}`, { stdio: 'inherit' });
}
fs.mkdirSync(releaseDir);
// 构建通用版本（保持兼容性）
console.log('🌐 构建通用版本...');
await buildUniversalVersion();
// 复制WASM文件
console.log('📁 复制WASM文件...');
const wasmDir = './bin/wasm';
fs.readdirSync(wasmDir).forEach(file => {
if (file !== '.gitignore') {
fs.copyFileSync(
path.join(wasmDir, file),
path.join(releaseDir, file)
);
console.log(` ✓ ${file}`);
}
});
// 创建使用说明
console.log('📋 生成使用说明...');
generateUsageInstructions(releaseDir);
// 显示结果
showReleaseResults(releaseDir);
console.log('\n✅ WASM发布包构建完成！');
console.log(`📦 发布目录: ${releaseDir}`);
console.log('💡 可以将整个目录打包为zip文件上传到GitHub Release');
console.log('\n✅ WASM 发布包构建完成！');
console.log('📦 输出目录:');
console.log(' - cocos-release/ (Cocos Creator 专用包)');
console.log(' - wasm-release/ (通用包)');
console.log('💡 可以将整个目录打包为 zip 文件上传到 GitHub Release');
} catch (error) {
console.error('❌ 构建失败:', error.message);
@@ -49,6 +26,155 @@ async function main() {
}
}
async function buildCocosVersion() {
// 确保 Cocos 版本已构建
if (!fs.existsSync('./cocos-pkg')) {
console.log('📦 构建 Cocos Creator WASM...');
execSync('scripts\\build-cocos.bat', { stdio: 'inherit' });
}
// 创建 Cocos 发布目录
const releaseDir = './cocos-release';
if (fs.existsSync(releaseDir)) {
execSync(`rimraf ${releaseDir}`, { stdio: 'inherit' });
}
fs.mkdirSync(releaseDir);
// 复制 Cocos 包文件
console.log('📁 复制 Cocos Creator 文件...');
const cocosDir = './cocos-pkg';
fs.readdirSync(cocosDir).forEach(file => {
fs.copyFileSync(
path.join(cocosDir, file),
path.join(releaseDir, file)
);
console.log(` ✓ ${file}`);
});
// 生成 Cocos 包信息
console.log('📋 生成 Cocos Creator 包信息...');
generateCocosPackageInfo(releaseDir);
// 复制 build-templates 示例
generateBuildTemplate(releaseDir);
// 显示结果
showReleaseResults(releaseDir, 'Cocos Creator');
}
async function buildUniversalVersion() {
// 确保通用 WASM 已构建
if (!fs.existsSync('./bin/wasm')) {
console.log('📦 构建通用 WASM...');
execSync('npm run build:wasm', { stdio: 'inherit' });
}
// 创建通用发布目录
const releaseDir = './wasm-release';
if (fs.existsSync(releaseDir)) {
execSync(`rimraf ${releaseDir}`, { stdio: 'inherit' });
}
fs.mkdirSync(releaseDir);
// 复制通用 WASM 文件
console.log('📁 复制通用 WASM 文件...');
const wasmDir = './bin/wasm';
fs.readdirSync(wasmDir).forEach(file => {
if (file !== '.gitignore') {
fs.copyFileSync(
path.join(wasmDir, file),
path.join(releaseDir, file)
);
console.log(` ✓ ${file}`);
}
});
// 创建使用说明
console.log('📋 生成通用使用说明...');
generateUsageInstructions(releaseDir);
// 显示结果
showReleaseResults(releaseDir, '通用');
}
function generateCocosPackageInfo(releaseDir) {
const packageInfo = {
name: "@esengine/ecs-framework-wasm-cocos",
version: "1.0.0",
description: "ECS Framework WASM 加速模块 - Cocos Creator 专用版",
main: "ecs_wasm_core.ts",
files: [
"ecs_wasm_core.ts",
"ecs_wasm_core_bg.bin",
"ecs_wasm_core_bg.wasm",
"*.d.ts",
"README.md",
"build-templates/"
],
keywords: ["ecs", "wasm", "cocos-creator", "game-engine"],
author: "ESEngine Team",
license: "MIT",
peerDependencies: {
"@esengine/ecs-framework": "^1.0.0"
},
engines: {
"cocos-creator": ">=3.8.0"
}
};
fs.writeFileSync(
path.join(releaseDir, 'package.json'),
JSON.stringify(packageInfo, null, 2)
);
}
function generateBuildTemplate(releaseDir) {
const templateDir = path.join(releaseDir, 'build-templates', 'wechatgame');
fs.mkdirSync(templateDir, { recursive: true });
const buildScript = `/**
* 微信小游戏 build-templates 脚本
* 自动将 WASM 文件复制到发布目录
*
* 使用方法：
* 1. 将此文件复制到项目的 build-templates/wechatgame/ 目录
* 2. 重命名为 build-finish.js
* 3. 构建微信小游戏时会自动执行
*/
const fs = require('fs');
const path = require('path');
function copyWasmFiles(options, callback) {
const { buildPath } = options;
console.log('🎮 复制 ECS WASM 文件到微信小游戏目录...');
// WASM 源文件路径（需要根据实际项目结构调整）
const wasmSourcePath = path.join(__dirname, '../../assets/scripts/ecs_wasm_core_bg.wasm');
const wasmTargetPath = path.join(buildPath, 'ecs_wasm_core_bg.wasm');
try {
if (fs.existsSync(wasmSourcePath)) {
fs.copyFileSync(wasmSourcePath, wasmTargetPath);
console.log('✅ WASM 文件复制成功');
} else {
console.warn('⚠️ WASM 文件不存在，跳过复制');
}
} catch (error) {
console.error('❌ 复制 WASM 文件失败:', error.message);
}
if (callback) callback();
}
module.exports = {
onBuildFinished: copyWasmFiles
};`;
fs.writeFileSync(path.join(templateDir, 'build-finish.js'), buildScript);
}
function generateUsageInstructions(releaseDir) {
const instructions = `# ECS Framework WASM 支持包
@@ -64,29 +190,7 @@ function generateUsageInstructions(releaseDir) {
## 使用方法
### 1. Cocos Creator 3.8+
\`\`\`typescript
import { ecsCore } from '@esengine/ecs-framework';
// 1. 将WASM文件导入到项目资源中
// 2. 导入胶水代码
import('./ecs_wasm_core.js').then(({ default: wasmFactory }) => {
// 3. 使用Cocos API加载WASM文件
this.loadWasmOrAsm("wasmFiles", "ecs_wasm_core", "your-wasm-uuid").then((wasmFile) => {
// 4. 初始化WASM支持
ecsCore.initializeWasm(wasmFactory, wasmFile).then((success) => {
if (success) {
console.log("ECS WASM加速已启用");
} else {
console.log("回退到JavaScript实现");
}
});
});
});
\`\`\`
### 2. 其他环境（浏览器/Node.js）
### 1. 其他环境（浏览器/Node.js）
\`\`\`typescript
import { ecsCore } from '@esengine/ecs-framework';
@@ -107,12 +211,41 @@ import('./ecs_wasm_core.js').then(({ default: wasmFactory }) => {
});
\`\`\`
### 2. Webpack/Vite 等构建工具
\`\`\`typescript
import { ecsCore } from '@esengine/ecs-framework';
import wasmFactory from './ecs_wasm_core.js';
import wasmUrl from './ecs_wasm_core_bg.wasm?url';
async function initWasm() {
try {
const wasmFile = await fetch(wasmUrl).then(r => r.arrayBuffer());
const success = await ecsCore.initializeWasm(wasmFactory, wasmFile);
if (success) {
console.log("ECS WASM加速已启用");
} else {
console.log("回退到JavaScript实现");
}
} catch (error) {
console.error("WASM初始化失败:", error);
}
}
initWasm();
\`\`\`
## 注意事项
1. 如果不使用此WASM包，框架会自动使用JavaScript实现，功能完全正常
2. WASM主要提供查询性能优化，对于大多数应用场景JavaScript实现已足够
3. 确保在ECS系统初始化之前调用\`initializeWasm\`方法
## Cocos Creator 用户
Cocos Creator 用户请使用专门的 Cocos Creator 包：\`cocos-release/\`
## 技术支持
如遇问题，请访问：
@@ -123,12 +256,33 @@ import('./ecs_wasm_core.js').then(({ default: wasmFactory }) => {
fs.writeFileSync(path.join(releaseDir, 'README.md'), instructions);
}
function showReleaseResults(releaseDir) {
console.log('\n📊 WASM发布包内容:');
function showReleaseResults(releaseDir, packageType = '') {
console.log(`\n📊 ${packageType} WASM 发布包内容:`);
fs.readdirSync(releaseDir).forEach(file => {
const filePath = path.join(releaseDir, file);
const size = fs.statSync(filePath).size;
console.log(` ${file}: ${(size / 1024).toFixed(1)}KB`);
const stats = fs.statSync(filePath);
if (stats.isDirectory()) {
console.log(` 📁 ${file}/`);
// 显示子目录内容
try {
fs.readdirSync(filePath).forEach(subFile => {
const subFilePath = path.join(filePath, subFile);
const subStats = fs.statSync(subFilePath);
if (subStats.isFile()) {
const size = (subStats.size / 1024).toFixed(1);
console.log(` ${subFile}: ${size}KB`);
} else {
console.log(` 📁 ${subFile}/`);
}
});
} catch (e) {
// 忽略读取错误
}
} else {
const size = (stats.size / 1024).toFixed(1);
console.log(` ${file}: ${size}KB`);
}
});
}