RiotManifest

Riot 提供的 manifest 解析、并发下载、WAD 按需提取与差异分析工具。

• 安装
• 30 秒上手
• 常见任务
• 实践建议
• 文档导航
• 维护者
• 感谢
• 许可证

安装

pip3 install riotmanifest

30 秒上手

最常见的下载入口是 PatcherManifest：

import asyncio
from riotmanifest import PatcherManifest


async def main() -> None:
    manifest = PatcherManifest(
        "https://lol.secure.dyn.riotcdn.net/channels/public/releases/CB3A1B2A17ED9AAB.manifest",
        path="./out",
        bundle_urls=[
            "https://lol.dyn.riotcdn.net/channels/public/bundles/",
            "https://lol.secure.dyn.riotcdn.net/channels/public/bundles/",
        ],
    )

    files = list(manifest.filter_files(flag="zh_CN", pattern="wad.client"))
    await manifest.download_files_concurrently(files)


if __name__ == "__main__":
    asyncio.run(main())

默认并发为 16。bundle_urls 可选：给定多个等价镜像时，下载作业会分摊到各域名，重试自动切换域名；只需单一地址时可继续用 bundle_url。下载策略参数（gap 合并、整包阈值、并发等）均可在构造时改写，见 docs/manifest.md。

常见任务

1. 下载 manifest 中的一批文件

• 入口：PatcherManifest
• 适合：批量下载 wad.client、语言资源、配置文件
• 这是无状态的单独下载：不读取或写入 .rman/installed.json，也不清理其他文件

2. 受管理安装 / 增量更新 / 修复本地文件

from riotmanifest import ManifestUpdater

updater = ManifestUpdater(manifest)  # 受管理安装：旧清单和文件覆盖从本地状态解析
result = await updater.sync(files)
print(result.downloaded_bytes, result.reused_bytes)

• 本地已有数据逐 chunk 验证复用，只下载变化部分
• installed.json schema 2 记录实际确认落盘的文件；多次部分同步会累积可信覆盖
• 只有状态已记录、且磁盘上仍是声明大小的普通文件，未变化文件才会快速跳过
• 首次运行和 schema 1 旧状态都会先验证；成功后写入 schema 2
• archive=False 完全无状态，不读取、不写入安装状态，也不执行受管理清理
• 多清单（如 LCU + GAME）联合同步用 sync_many：单 worker 池、跨清单合计的单一进度流
• 详见 docs/update.md

3. 从 WAD 中按需提取少量文件

from riotmanifest import PatcherManifest, WADExtractor

manifest = PatcherManifest(manifest_url, path="")
extractor = WADExtractor(manifest)

data = extractor.extract_files(
    {
        "DATA/FINAL/Champions/Ahri.wad.client": [
            "data/characters/ahri/skins/skin0.bin",
        ]
    }
)

4. 比较两个版本的 manifest / WAD 差异

from riotmanifest import diff_manifests, diff_wad_headers

manifest_report = diff_manifests(old_manifest, new_manifest, flags="zh_CN", pattern="wad.client")
wad_report = diff_wad_headers(manifest_report=manifest_report)

5. 获取当前 live 且版本规则明确的一对 LCU / GAME manifest

from riotmanifest import LeagueManifestResolver

resolver = LeagueManifestResolver()
pair = resolver.resolve_manifest_pair("EUW")

print(str(pair.version))  # 例如 16.5
print(pair.lcu.url)
print(pair.game.url)

重要： LeagueManifestResolver 的默认 match_mode 现在就是 VersionMatchMode.IGNORE_REVISION。 Riot 的 live 发布经常出现“GAME 先更新、LCU 稍后更新”的窗口期； 同时 patchsieve 只暴露当前滚动窗口中的少量 GAME 候选，不是完整历史库。 因此 STRICT 要求 normalized_build 完全一致，在 live 场景里大概率直接失败。 如果你只处理 wad.client、语言包、贴图、音频等资源文件，通常可以忽略修订号， 只按补丁版本匹配。只有在你明确要求 EXE / DLL / build 级完全一致时， 才建议使用 STRICT 并自行处理失败。 旧类名 RiotGameData 仍保留为兼容别名，实例化时会发出 FutureWarning。

6. 判断单个或两个英雄联盟 manifest 的类型与版本

from riotmanifest import LeagueManifestInspector

inspector = LeagueManifestInspector()

manifest = inspector.inspect_manifest(
    "https://lol.secure.dyn.riotcdn.net/channels/public/releases/79CFFE595C2B0C01.manifest"
)
print(manifest.artifact_group)           # game
print(manifest.version.display_version)  # 16.5.7511533

pair = inspector.inspect_pair(
    "https://lol.secure.dyn.riotcdn.net/channels/public/releases/8E78E3C2EFDB30F0.manifest",
    "https://lol.secure.dyn.riotcdn.net/channels/public/releases/79CFFE595C2B0C01.manifest",
)
print(str(pair.version))  # 16.5

LeagueManifestInspector 是开发者工具：它只根据 manifest 内容提取类型与版本， 不对上游清单真实性背书。当前 riotmanifest.game 包中的 LeagueManifestResolver 与 LeagueManifestInspector 都只面向英雄联盟（LoL）清单；其他 Riot 游戏当前没有接入计划。 手动验证时可直接使用 Morilli/riot-manifests 中的文本样本；例如 LoL/EUW1/windows/league-client/16.5.751.8496.txt 与 LoL/EUW1/windows/lol-game-client/16.5.7511533.txt 当前分别指向一对可配对的 LCU / GAME manifest URL。这里的 EUW1 是样本仓库目录名，不是 LeagueManifestResolver 推荐的公开输入；新代码仍建议传 EUW 这类主区域名。

实践建议

下载

• 默认并发 16 是当前推荐值（真实基准：批量下载可打满百 MB/s 级带宽）。
• 网络或磁盘较弱时可降到 8~12。
• 稀疏下载（如只取单个 WAD）受请求延迟主导，速度低于全量下载属预期行为， 官方客户端部分更新同样如此。
• 传入 bundle_urls 双域名镜像可获得 CDN 供应商多样性与重试跨域名切换。
• 需要进一步避开劣质节点 / DNS 异常时段时，可启用可选的边缘 IP 优选层 （pip install riotmanifest[edge]，见 docs/edge.md）； 定位是稳定兜底而非提速。

日志

• 库内日志默认整体关闭，不会干扰下游输出。
• 排查网络问题时可开启：from loguru import logger; logger.enable("riotmanifest")， 级别语义与量级见 docs/manifest.md。
• 失败原因的结构化获取不依赖日志：DownloadBatchError.failures / UpdateResult.failures。

WAD 提取

• WADExtractor 适合“少量小文件按需提取”。
• 若单个 WAD 目标文件很多，通常更建议先下载完整 WAD 再本地处理。

差异分析

• 大多数情况下，先 diff_manifests，再按需进入 diff_wad_headers。
• resolve_wad_diff_paths() 默认推荐 extractor 模式。
• 仅在“需要完整落盘、后续离线复用、磁盘空间充足”时考虑 download_root_wad。

LeagueManifestResolver

• 默认 match_mode 现在就是 IGNORE_REVISION。
• Riot live 常见顺序是 GAME 先更新、LCU 稍后更新，因此 STRICT 在 live 场景里大概率失败。
• 如果你只处理资源文件（如 wad.client、语言包、贴图、音频），通常可以忽略修订号。
• IGNORE_REVISION 当前会优先选择“同补丁内不高于 LCU build 的最大 GAME 候选”，避免误选比 LCU 更新的 GAME build。
• 如果你明确要“同补丁内无条件取最新 GAME 修订”，可改用 VersionMatchMode.PATCH_LATEST。
• 只有在你要求 EXE / DLL / build 级完全一致时，才建议使用 STRICT。
• str(pair.version) 默认输出补丁号，例如 16.5；如需精确显示，可读取 pair.version.lcu.display_version 或 pair.version.game.display_version。

文档导航

详细文档已按功能拆分：

• docs/API.md：文档导航页
• docs/manifest.md：Manifest 下载参考
• docs/update.md：增量更新参考
• docs/extractor.md：WADExtractor 参考
• docs/diff.md：差异分析参考
• docs/game.md：LeagueManifestResolver / LeagueManifestInspector / 版本对象参考
• docs/TESTING.md：测试与基准说明

维护者

Virace

• github: Virace
• blog: 孤独的未知数

感谢

• @CommunityDragon, CDTB
• @moonshadow565, rman：增量更新的验证与同步语义参考了该项目的实现

许可证

GPLv3