WoW Addon Builder (wct)

这是一个用 Rust 重写的 World of Warcraft 插件构建工具，功能与原 TypeScript 版本的 wow-curse-tools 保持兼容。

✨ 核心特性

🎨 用户体验增强

• ✅ 彩色输出 - 支持带图标的彩色日志输出 (✓ ℹ ⚠ ✗)
• ✅ 进度条 - 实时显示构建进度和文件处理状态
• ✅ 详细模式 - --verbose 查看详细调试信息
• ✅ 静默模式 - --quiet 只显示错误信息

📊 性能与质量

• ✅ 构建统计 - 显示编译、复制、跳过的文件数量和构建速度
• ✅ Lua 验证 - 自动验证 Lua 文件语法，提前发现错误
• ✅ 增量缓存 - SHA-256 文件哈希缓存，避免重复编译
• ✅ 并行准备 - 支持多核并行编译（需配置启用）

⚙️ 配置管理

• ✅ 项目配置 - 支持 .wctrc (JSON) 或 wct.toml 配置文件
• ✅ 全局配置 - 统一管理 API tokens 和 WoW 路径
• ✅ 自动检测 - 智能检测 WoW 安装路径（Battle.net）

🚀 项目模板

• ✅ 快速创建 - wct new 命令快速创建插件项目
• ✅ 4 种模板 - Basic、Advanced、Ace3、LibStub
• ✅ 开箱即用 - 自动生成完整的项目结构和配置

功能命令

核心命令

• ✅ new - 从模板创建新插件项目
• ✅ init - 初始化现有项目配置
• ✅ init-config - 初始化项目配置文件 (.wctrc)
• ✅ build - 构建插件到游戏目录
• ✅ watch - 监视文件变化并自动重新构建
• ✅ package - 打包插件为 ZIP 文件

发布与管理

• ✅ publish - 发布到 CurseForge
• ✅ changelog - 生成 BBCode 格式的变更日志
• ✅ config - 配置工具设置（路径、tokens）
• ✅ locale - 本地化管理（scan/export/import）

开发工具

• ✅ emmyui - 生成 EmmyLua UI 定义
• ✅ update - 更新远程依赖库
• 🚧 nga - 发布到 NGA 论坛（开发中）

安装

从源码编译

git clone <repository-url>
cd wow-addon-builder
cargo build --release

编译后的可执行文件位于 target/release/wct.exe

添加到 PATH

将 target/release 目录添加到系统 PATH 环境变量，即可在任意位置使用 wct 命令。

快速开始

创建新项目

使用模板快速创建插件项目：

# 交互式创建
wct new MyAddon

# 指定模板创建
wct new MyAddon --template advanced

可用模板：

• basic - 最简单的插件结构，适合新手
• advanced - 模块化架构，适合复杂插件
• ace3 - 基于 Ace3 框架的项目结构
• libstub - 用于开发共享库

初始化现有项目

在现有项目目录下运行：

wct init

这将交互式地配置 package.json 中的 WoW 插件信息。

创建项目配置文件

wct init-config

生成 .wctrc 配置文件，可以配置：

• 构建选项（缓存、验证、并行）
• 打包选项（输出目录、压缩级别）
• 发布选项（自动发布、目标平台）
• 开发选项（监视模式、钩子脚本）

使用方法

初始化项目

在插件项目目录下运行：

wct init

这将交互式地配置 package.json 中的 WoW 插件信息。

打包插件

打包所有构建版本：

wct package

打包特定版本：

wct package Mainline
wct package Wrath Vanilla

构建到游戏目录

构建一次：

# 基本用法
wct build Mainline

# 详细输出
wct build Mainline --verbose

# 静默模式
wct build Mainline --quiet

# 禁用缓存
wct build Mainline --no-cache

指定输出目录：

wct build Mainline -O "C:\Games\World of Warcraft\_retail_\Interface\AddOns"

监视模式（自动重新构建）：

wct watch Mainline

构建性能

• 增量构建 - 自动跳过未修改的文件
• 缓存系统 - 使用 SHA-256 哈希验证文件变化
• Lua 验证 - 构建时自动检查 Lua 语法错误
• 实时统计 - 显示编译、复制、跳过的文件数量

示例输出：

ℹ Building addon...
✓ Build completed!

Build Summary
  42 files processed in 0.23s
    ✓ 8 compiled
    ✓ 12 copied
    ○ 22 skipped (unchanged)
  📦 Total size: 1.24 MB
  ⚡ Speed: 183 files/sec

生成变更日志

从 CHANGELOG.md 生成 BBCode 格式：

wct changelog

配置工具

自动扫描并保存 WoW 路径：

# 自动探测所有版本的 WoW 安装路径
wct config scan

交互式配置 WoW 路径和 API Token：

wct config set

这将引导你设置：

• WoW 游戏路径（Mainline, Wrath, Vanilla 等）
• CurseForge API Token
• GitHub Token

发布到 CurseForge

# 使用配置的 token
wct publish

# 使用命令行参数
wct publish -T YOUR_CURSEFORGE_TOKEN

# 发布特定版本
wct publish Mainline Wrath

本地化管理

导出翻译：

wct locale export -T YOUR_TOKEN

导入翻译：

wct locale import -T YOUR_TOKEN

扫描本地化字符串：

wct locale scan

扫描功能会查找代码中的本地化字符串，支持以下模式：

• L["key"] 或 L['key']
• GetLocale("key")
• locale["key"]

可以导出为 Lua 或 JSON 格式，或与现有 locale 文件对比。

更新远程依赖

从 GitHub 或 CurseForge 下载依赖库（需要 .pkgmeta 文件）：

wct update

.pkgmeta 示例：

externals:
  Libs/LibStub: github@DengSir/LibStub@[releases]
  Libs/CallbackHandler: curse@callbackhandler
  Libs/AceAddon: github@WoWUIDev/Ace3@AceAddon-3.0

发布到 NGA 论坛

# 使用配置的 cookie
wct nga

# 使用命令行参数
wct nga --cookie YOUR_NGA_COOKIE

配置系统

项目配置 (.wctrc 或 wct.toml)

项目级配置文件支持 JSON 或 TOML 格式：

{
  "build": {
    "cache": true,
    "cache_file": ".wct-cache.json",
    "validate_lua": true,
    "parallel": false,
    "exclude": [".git/**", "*.md"]
  },
  "package": {
    "output_dir": "dist",
    "filename_template": "{name}-{version}.zip",
    "compression_level": 6,
    "include_changelog": true
  },
  "publish": {
    "auto_publish": false,
    "targets": ["curseforge"],
    "release_type": "release"
  },
  "dev": {
    "watch": {
      "debounce": 300,
      "ignore": ["*.tmp"]
    }
  }
}

全局配置 (~/.wct.json)

存储全局设置和密钥：

{
  "curse-forge-token": "YOUR_TOKEN",
  "github-token": "YOUR_TOKEN",
  "buildPath": {
    "Mainline": "C:\\Games\\World of Warcraft\\_retail_",
    "Wrath": "C:\\Games\\World of Warcraft\\_classic_"
  }
}

package.json 配置示例

{
  "name": "my-addon",
  "version": "1.0.0",
  "wow": {
    "name": "MyAddon",
    "curse_id": 123456,
    "builds": {
      "Mainline": "110000",
      "Wrath": "30403",
      "Vanilla": "11503"
    },
    "addons": {
      "MyAddonCore": "./Core",
      "MyAddonConfig": "./Config"
    },
    "res-filters": [
      "*.psd",
      "*.blend"
    ],
    "no-compiles": [
      "Libs/**/*.lua"
    ],
    "changelog": "CHANGELOG.md"
  }
}

配置字段说明

• name - 插件名称
• curse_id - CurseForge 项目 ID
• builds - 支持的 WoW 版本及其 Interface 版本号
• addons - 子插件及其目录
• res-filters - 打包时要排除的文件模式
• no-compiles - 不需要编译处理的文件模式
• changelog - 变更日志文件路径
• single - 是否为单一构建模式（所有版本共用同一套代码）
• nga_id - NGA 论坛话题 ID（用于发布）

  "nga_id": {
    "Mainline": 12345678
  }
  

条件编译

工具支持在代码中使用条件注释来控制不同版本的代码：

Lua 文件

--@retail@
print("This only appears in retail")
--@end-retail@

--@debug@
print("This only appears in debug builds")
--@end-debug@

XML 文件

<!--@retail@-->
<Script file="RetailOnly.lua"/>
<!--@end@-->

TOC 文件

## Interface-Mainline@
RetailScript.lua

## Interface-Wrath@
WrathScript.lua

支持的 WoW 版本

• Mainline (retail) - 正式服
• Wrath - 巫妖王之怒怀旧服
• Mists - 熊猫人之谜怀旧服
• Vanilla - 经典旧世怀旧服

与原版兼容性

本工具保持与原 wow-curse-tools 的命令行接口兼容，可以直接替换使用。主要改进：

性能提升

• 10-50x 更快 - Rust 编译速度远超 TypeScript
• 增量构建 - 智能缓存减少不必要的文件操作
• 并行处理 - 支持多核心并行编译

功能增强

• 更好的错误提示 - 彩色输出和详细的错误信息
• 进度反馈 - 实时进度条和构建统计
• 配置系统 - 项目级和全局配置管理
• 项目模板 - 快速创建新项目

兼容性

1. 命令行参数完全兼容
2. package.json 配置格式完全兼容
3. 条件编译语法完全兼容
4. 输出格式完全兼容

技术栈

• Rust 2021 - 高性能、内存安全
• Tokio - 异步运行时
• Clap - 命令行参数解析
• Indicatif - 进度条显示
• Colored - 彩色终端输出
• Full Moon - Lua 语法解析
• SHA-256 - 文件哈希缓存

开发状态

当前版本实现了核心功能：

• ✅ 项目初始化和模板系统
• ✅ 文件扫描与编译
• ✅ 条件编译处理
• ✅ ZIP 打包
• ✅ 构建到游戏目录
• ✅ 文件监视与自动重建
• ✅ 变更日志转换
• ✅ 增量缓存系统
• ✅ Lua 语法验证
• ✅ 构建统计和进度显示
• ✅ 项目配置管理
• ✅ CurseForge 发布
• ✅ 本地化管理
• ✅ EmmyLua UI 生成
• ✅ 远程依赖更新

待完善功能：

• 🚧 NGA 论坛发布
• 🚧 完整的并行编译
• 🚧 更多测试覆盖

许可证

MIT License

致谢

本项目基于 @Dencer 的 wow-curse-tools 重写，感谢原作者的出色工作。