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 - 更适合默认映射链和批量分析
如果你需要更完整的 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。
详细示例与格式文档：
音频映射建议
默认工作流：
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）
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
league_tools-1.2.0.tar.gz
(134.4 kB
view details)
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
league_tools-1.2.0-py3-none-any.whl
(101.8 kB
view details)
File details
Details for the file league_tools-1.2.0.tar.gz.
File metadata
- Download URL: league_tools-1.2.0.tar.gz
- Upload date:
- Size: 134.4 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
ab05563b1de98b699038d63c30f2a30de445e4f1e333aa55e4420563e01b5774
|
|
| MD5 |
d0052a8030c09777ecf7e4e71e9c8588
|
|
| BLAKE2b-256 |
13ac56a91db03cae124c8eb2465d192c7aea215d2e612e022b718c46fa2e766f
|
Provenance
The following attestation bundles were made for league_tools-1.2.0.tar.gz:
Publisher:
python-publish.yml on Virace/league-tools
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
league_tools-1.2.0.tar.gz -
Subject digest:
ab05563b1de98b699038d63c30f2a30de445e4f1e333aa55e4420563e01b5774 - Sigstore transparency entry: 2211552183
- Sigstore integration time:
-
Permalink:
Virace/league-tools@672bd117d05f2826ae879f4252cbee0f060a056a -
Branch / Tag:
refs/tags/v1.2.0 - Owner: https://github.com/Virace
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@672bd117d05f2826ae879f4252cbee0f060a056a -
Trigger Event:
release
-
Statement type:
File details
Details for the file league_tools-1.2.0-py3-none-any.whl.
File metadata
- Download URL: league_tools-1.2.0-py3-none-any.whl
- Upload date:
- Size: 101.8 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/6.1.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
950c71038d900ef0b6ead84587051e39cf6d00ad8b00c16a690375607b001e12
|
|
| MD5 |
1406db6f83214865855d738cf8e576c1
|
|
| BLAKE2b-256 |
99ad8d063b5d38c6c3790931285abb35f8a441e150f41120d348f301433add10
|
Provenance
The following attestation bundles were made for league_tools-1.2.0-py3-none-any.whl:
Publisher:
python-publish.yml on Virace/league-tools
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
league_tools-1.2.0-py3-none-any.whl -
Subject digest:
950c71038d900ef0b6ead84587051e39cf6d00ad8b00c16a690375607b001e12 - Sigstore transparency entry: 2211552204
- Sigstore integration time:
-
Permalink:
Virace/league-tools@672bd117d05f2826ae879f4252cbee0f060a056a -
Branch / Tag:
refs/tags/v1.2.0 - Owner: https://github.com/Virace
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
python-publish.yml@672bd117d05f2826ae879f4252cbee0f060a056a -
Trigger Event:
release
-
Statement type:
