league-tools

WAD、BIN、BNK、WPK 文件处理工具库。

介绍

league-tools 是一个用于处理英雄联盟资源文件的 Python 库，提供对以下格式的底层解析能力：

• WAD（.wad.client）：资源包（模型、贴图、音频等）
• BIN（.bin）：游戏配置与逻辑数据
• BNK（.bnk）：Wwise SoundBank 音频元数据
• WPK（.wpk）：Wwise 打包音频文件

音频事件映射默认推荐使用 NativeHIRC：

• 只关注事件映射所需的 HIRC 音频信息
• 直接从 events.bnk 读取，速度明显快于 wwiser -> XML
• 更适合默认映射链和批量分析

现支持 Layer/Blend 容器（HIRC 9）的子对象映射，已用 Wwise 145 的真实 VALORANT BNK 与官方 wwiser 对照验证。测试代码和本地样本准备说明见 样本目录说明。

如果你需要更完整的 BNK/HIRC 结构、XML 对照能力或调试信息，再使用 WwiserHIRC。

安装

pip install league-tools

如需基于发布分支安装最新代码：

pip install -e "git+https://github.com/Virace/league-tools@package#egg=league_tools"

使用

基础使用示例（四种核心格式）：

from pathlib import Path

from league_tools import BIN, BNK, NativeHIRC, WAD, WPK

# 1) WPK：提取音频文件
wpk = WPK("path/to/audio.wpk")
wem_files = wpk.extract_files()

# 2) BNK：提取内嵌WEM
bnk = BNK("path/to/events.bnk")
bnk_wem_files = bnk.extract_files()

# 3) WAD：按已知路径提取文件
wad = WAD("path/to/archive.wad.client")
wad.extract(
    ["assets/sounds/vo/champions/gwen/skin01/vo_gwen_skin01_events.bnk"],
    out_dir=Path("./wad_output"),
)

# 4) BIN：读取音频事件组数据
bin_file = BIN("path/to/skin.bin")
audio_groups = bin_file.data

# 5) NativeHIRC：默认推荐的 events.bnk 解析入口
hirc = NativeHIRC.from_bnk("path/to/vo_events.bnk")

日志默认关闭；上游项目可按需手动开启：

from league_tools import enable_logging, disable_logging

enable_logging()
# ... 业务逻辑 ...
disable_logging()

WAD 打包与替换（输出固定 v3.4）：

from league_tools import WAD, WADBuilder

# 从零创建
WADBuilder() \
    .add('plugins/demo/config.json', b'{"enabled": true}') \
    .save('demo.wad.client')

# 打开已有 WAD，替换其中的文件后另存（output 省略则覆盖源文件）
wad = WAD('path/to/archive.wad.client')
wad.rebuild(
    {'plugins/demo/config.json': b'{"enabled": false}'},
    output='archive.modified.wad.client',
)

说明：.bnk/.wpk 原样存储，其余 zstd 压缩；头部签名置零（客户端不校验）。 注意游戏客户端更新/修复会按清单还原被修改的 WAD。

详细示例与格式文档：

• 基础 API 与快速上手
• 格式总览
• WAD 解析
• BIN 解析
• BNK 解析
• WPK 解析
• 音频映射
• 音频 Bank 事件解释（开发）

音频映射建议

默认工作流：

from league_tools import AudioEventMapper, BIN, NativeHIRC

bin_file = BIN("path/to/skin.bin")
hirc = NativeHIRC.from_bnk("path/to/events.bnk")
mapping = AudioEventMapper(bin_file, hirc).build_mapping()

何时切到 WwiserHIRC：

• 需要完整 XML / HIRC 结构对照
• 需要调试 wwiser 输出或排查版本差异
• 需要的信息超出 NativeHIRC 当前只关注的音频事件映射范围

参考

• WPK 参考 Morilli/bnk-extract
• WAD 结构与部分逻辑来源于 CommunityDragon/CDTB 与 Pupix/lol-file-parser
• WAD v3.4 写入格式与存储策略对照了 LeagueToolkit/cslol-manager、LeagueToolkit/LeagueToolkit 与 tarngaina/ltMAO 的实现做佐证，未复制其代码
• BNK 结构参考 Xentax Wiki
• NativeHIRC 的 MusicSwitch / 音乐容器读取顺序在调试阶段参考了 Neinndall/AssetsManager 的 BNK 解析实现，用于交叉校验 Wwise 145 样本的偏移处理
• WwiserHIRC 的 XML 对照与调试流程依赖 bnnm/wwiser 提供的导出能力；本项目将其作为外部分析工具使用，运行时需由用户自行提供可执行文件

维护

• 维护者：Virace（孤独的未知数）
• 开发与测试标准：docs/development_testing.md
• 发布与维护流程：docs/release_workflow.md
• Wwise 黑箱转白箱可行性记录：docs/wwise_reverse_engineering_feasibility.md
• 许可证：GPLv3

感谢

• @Morilli（bnk-extract）
• @Pupix（lol-file-parser）
• @CommunityDragon（CDTB）
• @Neinndall（AssetsManager，提供 BNK / 音乐容器解析对照思路）
• @bnnm（wwiser，提供 BNK XML 导出与结构对照能力）
• @vgmstream（vgmstream）