BotWConverter（C# 双向版）

Nitr4m12/UltimateBotWConverter 的 C# 重写版， 并新增了原版不支持的 Switch → Wii U 反向转换。

原版 Python 工具只支持 Wii U → Switch（converter.py 中明确写着 NotImplementedError("...does not support Switch to Wii U conversion")）。 本项目在移植全部原有格式支持的同时，把整条管线做成了双向的。

功能

• 双向转换：--to switch（Wii U → Switch）或 --to wiiu（Switch → Wii U）
• 输入：.bnp 文件或 mod 文件夹；输出：.bnp（7z/LZMA2）或文件夹
• 自动递归处理 SARC pack（.sbactorpack / .sbeventpack / .pack 等）， 并按目标平台切换 pack 的字节序（Wii U 大端 ↔ Switch 小端）
• 更新 info.json 中的 platform 字段

支持的格式

格式	说明	实现
.sbfres/.bfres、.sbitemico/.bitemico、.bcamanim	BFRES 模型/动画（含 Tex1+Tex2 mipmap 合并）	BfresLibrary ChangePlatform，双向参数分别取自原版工具与 BfresPlatformConverter
.hkcl、.hkrg、.shknm2	Havok 物理	调用 HKXConvert（json2hkx --nx = Switch，不带 --nx = Wii U）
.bars、.bfstm、.bfstp、.bfwav	音频	逐字节移植 AboodXD 的 BCFConverter + NanobotZ 的 bfstp 修复；只做字节序转换，不重编码，比特级无损
*pack*（除 .sbquestpack）	SARC 归档	SarcLibrary 3.3.4，递归转换内部文件
.sblarc/.blarc	布局归档（UI 贴图容器）	双向：Wii U→Switch 把 bflim 注入库存 bntx；Switch→Wii U 把 bntx 解码为 bflim
.bflim/.bntx	贴图	BFLIM 读取/写出（BfresLibrary GX2）；BNTX 读取/注入/解码（bntx.py 移植 + BfresLibrary TegraX1Swizzle）
.byml/.sbyml/.mubin/.smubin/.baniminfo/.baischedule	BYML（二进制 YAML，含 pack 内部文件）	自包含 BYML v2 读写器，双向字节序转换（Wii U 大端 BY ↔ Switch 小端 YB），保留 Yaz0 外壳；对未知扩展名按内容魔数兜底识别
.aamp 家族（.bxml/.baiprog/.bgparamlist/.bmodellist/.bfevfl 等）	参数/事件流	实测两平台字节级一致（平台无关格式），无需转换，原样透传
.bnp	BCML mod 包	SharpCompress 解包 + ManagedLzma 打包（纯托管，无需 7-Zip）

尚未实现（路线图中）

• 原版依赖 BCML 哈希表跳过未修改文件的优化未移植——本工具无条件转换所有受支持文件 （对未修改文件，转换结果与原版"替换为原版文件"等效）。

构建

要求：.NET SDK 10（Windows；Linux/macOS 理论可行，HKXConvert 需对应版本）

cd BotWConverter
dotnet build BotWConverter.slnx -c Release
dotnet test tests/BotWConverter.Tests        # 33 个单元/端到端测试

产物：

• CLI：src/BotWConverter.Cli/bin/Release/net10.0/BotWConverter.Cli.exe
• GUI：src/BotWConverter.Gui/bin/Release/net10.0-windows/BotWConverter.Gui.exe

（HKXConvert.exe 会自动部署到输出目录的 tools/ 下）

使用

# Wii U mod → Switch
BotWConverter.Cli.exe MyMod.bnp --to switch

# Switch mod → Wii U
BotWConverter.Cli.exe MySwitchMod.bnp --to wiiu

# 指定目标平台的游戏 dump（用于 .bfstp 等原版文件回退）
BotWConverter.Cli.exe MyMod.bnp --to switch --dump "D:\BotW Switch Dump" --dlc "D:\BotW DLC"

# Wii U dump 可额外指定 update 目录
BotWConverter.Cli.exe MyMod.bnp --to wiiu --dump "D:\BotW WiiU\content" --update "D:\BotW WiiU\update"

# 输出到指定路径（.bnp 或目录）
BotWConverter.Cli.exe MyMod.bnp --to switch -o Converted.bnp

完整选项见 --help。

图形界面

运行 BotWConverter.Gui.exe：

1. 把 .bnp 文件或 mod 文件夹拖进列表（也可点「添加」）；
2. 选择目标平台（→ Switch 或 → Wii U）；
3. 可选：输出目录（留空 = 在输入旁边生成 xxx_switch.bnp / xxx_wiiu.bnp）；
4. 可选：目标平台的游戏 dump 目录（bflim 注入与 bfstp 回退需要它； Wii U dump 可另选 update 目录，DLC 目录可选）；
5. 点「开始转换」，日志区实时显示进度与警告/错误，结束后可一键打开输出位置。

项目结构

BotWConverter/
├── src/
│   ├── BotWConverter.Core/        # 核心库
│   │   ├── Compression/Yaz0.cs    # Yaz0 压缩/解压（哈希链快速压缩器）
│   │   ├── Audio/                 # BARS/BFSTM/BFSTP/BFWAV（bars_py + bcf_converter.py 移植）
│   │   ├── Bfres/BfresConvert.cs  # BFRES 双向（BfresLibrary 包装）
│   │   ├── Byml/BymlConvert.cs    # BYML v2 双向字节序转换（自包含读写器）
│   │   ├── Havok/HavokConvert.cs  # Havok 双向（HKXConvert 包装）
│   │   ├── Textures/              # BFLIM/BNTX 读写、NVN/GX2 互转、sblarc/blarc 双向
│   │   ├── Packaging/Bnp.cs       # bnp 解包(SharpCompress)/打包(ManagedLzma)
│   │   └── Mod/                   # ModConverter 编排器、GameDump 解析
│   ├── BotWConverter.Cli/         # 命令行入口
│   └── BotWConverter.Gui/         # WinForms 图形界面
└── tests/BotWConverter.Tests/     # Yaz0/SARC/音频/贴图/bnp/BYML 回环 + 端到端管线测试

外部依赖：

组件	来源	用途
BfresLibrary	源码编译（netstandard2.0，内置在 external/BfresLibrary，含本项目的一处上游修复）	BFRES 平台转换
SarcLibrary 3.3.4	NuGet（NCF-Library）	SARC 读写/对齐
SharpCompress	NuGet	7z/bnp 解包
ManagedLzma	NuGet（预发布）	7z/bnp 打包
HKXConvert	内置二进制（external/HKXConvert）	Havok 转换

与原版 Python 工具的差异

1. 新增 Switch → Wii U 方向（BFRES 参数：ChangePlatform(false, 256|4096, 4,5,0,3, BOTW)； Havok 不带 --nx；音频转大端；pack 转大端 SARC）。
2. 不再依赖 Python 3.7/3.8 + pythonnet + BCML；单个 .NET 可执行文件即可运行。
3. Yaz0 压缩使用哈希链实现（原版依赖 oead；NCF 的 Yaz0Library 压缩器是暴力搜索， 对 BotW 的大文件太慢，故自实现快速版本，格式完全兼容并有回环测试）。
4. 修复了原版的一个潜在 bug：BARS 中 FSTP 音轨转换后长度变化 ±0x20 会使后续音轨 偏移失效——本工具按偏移从后往前回填音轨，任意顺序都正确。
5. bnp 打包不需要系统安装 7-Zip（纯托管 ManagedLzma）。
6. 贴图转换增强：
   • BotW 两个平台的布局归档都是 Layout/*.sblarc 散文件（Switch 版内部用合并的 timg/__Combined.bntx 代替散 bflim）。本工具按 Layout/<同名> 在目标 dump 中 直接查找库存归档（找不到再回退到 pack 内查找），并修正了原版对 BootUp.sblarc 的错误跳过（Switch 版 BootUp.sblarc 实际存在且含 bntx）；
   • 注入前先把 BFLIM 的 GX2 swizzle 解成线性数据再做 NVN swizzle（原版直接把 GX2 数据喂给 NVN 路径，仅对线性源贴图正确）；
   • 新增 S→W 方向：bntx 解码（NVN deswizzle）→ 线性 BFLIM；ASTC 等 Wii U 无对应 的格式会警告并跳过，部分转换时保留原 bntx 以免丢数据；
   • 新增 WinForms GUI（原版只有命令行）。
7. 修复原版 W→S 的 BFRES 版本号 bug：原版参数把 Switch 版本号写成 0x00000003 （Switch 头部版本编码不含 major2），导致模型文件被按旧版布局解析而损坏； 本工具写入库存 Switch BotW 的 0x00050003，模型/骨骼/动画文件转换后可正常读取。
8. 新增 aamp/byml 家族支持（原版与 BCML convert_mod 均只做 W→S 方向的一部分）：
   • byml 系列（.byml/.sbyml/.mubin/.smubin/.baniminfo/.baischedule，含 pack 内部文件） 用自包含 BYML v2 读写器做双向字节序转换。未直接引用 NCF 的 BymlLibrary， 因其依赖 Syroot.BinaryData 5.x，与 BfresLibrary 绑定的 2.x 在同一输出目录冲突； 本实现按同一格式规范编写，字符串/键表排序、节点去重均与任天堂写入器一致—— 实测 Wii U 版 .baniminfo 转换后与库存 Switch 文件字节级相同；
   • aamp 系列（.aamp/.bxml/.baiprog/.bgparamlist/.bmodellist/.bfevfl 等）经原版 dump 逐字节比对确认为平台无关格式，无需转换（原版工具对其中部分文件做了多余的"转换"）。

已知限制

• byml 转换后的节点布局与本工具的规范顺序一致；个别原版文件（如 ActorInfo.product.sbyml）出自不同版本的任天堂写入器，节点摆放顺序不同， 转换结果与其字节不同但语义等价（游戏按偏移解析，不受影响）。 Yaz0 重压缩率也可能与原版略有差异（内容不变）。
• W→S 的 bflim 注入需要目标平台（Switch）的游戏 dump 提供库存 bntx 容器； 未提供 dump 时 sblarc 会原样保留并警告。
• S→W 的 bntx→bflim 不需要 dump（线性 tiling 输出，Cemu 可正常读取）；提供 Wii U dump 时会自动沿用库存 bflim 的 tiling 参数。
• Switch 独占内容（1.6.0 新增特效/参数等）转 Wii U 时无对应目标，属平台差异，无法自动处理。
• 转换质量最终请以 Cemu（Wii U）或实机/模拟器（Switch）实测为准。

许可证

本项目采用 GPL-3.0 开源许可证发布。选择该许可证的原因：本项目是 Nitr4m12/UltimateBotWConverter（GPL-3.0） 的 C# 重写版，且依赖 NCF-Library 的 SarcLibrary（GPL-3.0），衍生作品必须沿用相同许可证；BfresLibrary 为 MIT，不构成额外限制。

基于本项目修改后再分发的版本同样需要以 GPL-3.0 开源。

致谢

• Nitr4m12 — 原版 UltimateBotWConverter
• AboodXD — BCFConverter、bflim 工具
• KillzXGaming — BfresLibrary、BfresPlatformConverter
• krenyy — HKXConvert
• ArchLeaders — NCF-Library（SarcLibrary 等）
• NiceneNerd — BCML（本项目不再依赖它，但格式兼容性以它为准）