ss26367098/rofllens
GitHub: ss26367098/rofllens
RoflLens 是一个只读的 Python 库和命令行工具包，用于在不启动游戏客户端的情况下解析《英雄联盟》ROFL v2 回放文件的容器结构和网络传输层，并提供版本绑定的语义事件解码能力。
Stars: 0 | Forks: 0
# RoflLens
[简体中文](README.zh-CN.md)
RoflLens 是一个用于《英雄联盟》`.rofl` 回放文件的只读 Python 库和命令行工具包。它解析 ROFL v2 容器和网络传输层，而无需启动或修改英雄联盟客户端。与特定版本绑定的语义解码器，均通过精确的客户端版本、协议摘要以及可执行文件的 SHA-256 校验进行隔离。
RoflLens 绝不会将未经证实的猜测转化为已确认的游戏事件。未知的 opcode 和字段会保留其传输原始值，并可导出供后续研究使用。
## 安装说明
RoflLens 支持 Python 3.11 至 3.13。
```
python -m pip install .
```
仅在需要特定版本的解码功能时，才安装可选的语义分析和逆向工程依赖项：
```
python -m pip install ".[semantic]"
```
## 五分钟入门
```
rofllens inspect replay.rofl --verify
rofllens histogram replay.rofl
rofllens export-blocks replay.rofl --output blocks.jsonl
rofllens export-blocks replay.rofl --output blocks-with-payload.jsonl --include-payload
rofllens capabilities
rofllens capabilities --json
```
在复制 payload 字节之前过滤大型导出数据：
```
rofllens export-blocks replay.rofl --output movement.jsonl \
--streams gameChunk --opcodes 0x022c --limit 100
```
所有 JSON 和 JSONL 输出均使用 `schemaVersion: 1`。文件导出会先写入临时的 `.part` 文件中，在刷新并完成写入后，才会进行原子重命名。
## Python API
```
from rofllens import ReplayReader
with ReplayReader.open("replay.rofl") as replay:
print(replay.summary(verify=True).as_dict())
for block in replay.iter_blocks(
streams={"gameChunk"},
opcodes={0x022C},
include_payload=False,
):
print(block.timestamp, block.packet_id, block.param)
```
默认迭代器在不复制 payload 字节的情况下暴露元数据。需显式使用 `include_payload=True` 来请求原始 payload。
## 功能支持
`verified` 表示该结构或语义字段具备可重复验证的证据。
`candidate` 表示该结构是稳定的，但至少有一项业务含义尚未明确。
`unknown` 表示未声称任何语义标签。
| 状态 | 支持 | Opcode | 功能 |
| --- | --- | --- | --- |
| verified | rofl-v2 | - | ROFL v2 容器：Header、签名和元数据边界、原始/Zstandard 数据块以及数据流。 |
| verified | rofl-v2 | - | 网络数据块分帧：绝对/相对时间戳、重用的 opcode、参数增量以及 u8/u32 payload 长度。 |
| verified | rofl-v2 | - | 参与者元数据：Riot ID、PUUID、召唤师 ID、英雄、队伍、位置以及赛后统计数据。 |
| verified | 16.14.794.5912 | `0x0023`, `0x0193`, `0x03a0` | 动画状态：实体、动画名称、状态代码以及保留的原始速率。 |
| verified | 16.14.794.5912 | `0x015c` | 命名通道状态：回城、传送以及命名通道的起始/结束标记。 |
| verified | 16.14.794.5912 | `0x022c` | 移动路径：实体 ID、速度、所有路径点以及玩家实体分类。 |
| verified | 16.14.794.5912 | `0x0226` | 物体与守卫生成：物体/所有者 ID、名称、坐标以及已证实的守卫分类。 |
| verified | 16.14.794.5912 | `0x00c5` | 技能施放：施法者与连锁所有者、技能哈希/槽位/等级、目标、时机、冷却时间和消耗；未明确的向量仍标记为 candidate。 |
| verified | 16.14.794.5912 | `0x036f` | 英雄死亡：击杀者、受害者、受害者英雄名称以及相关上下文实体。 |
| verified | 16.14.794.5912 | `0x02ef` | 弹道轨迹：弹道/来源/所有者 ID、哈希、速度、时间以及 3D 几何形状。 |
| verified | 16.14.794.5912 | `0x03c3`, `0x019b` | 物体生命周期：临时网络对象的起始/结束边界。 |
| verified | 16.14.794.5912 | `0x035d` | 强制创建弹道：已证实的强制创建弹道传输字段。 |
| verified | 16.14.794.5912 | `0x0048` | 玩家金币增量：玩家对象 ID 的带符号金币变动。 |
| verified | 16.14.794.5912 | `0x018e` | Buff 移除：作用对象、槽位以及已证实的 Buff 移除字段。 |
| verified | 16.14.794.5912 | `0x006d` | 属性公式输出：受配置绑定的对象属性/公式输出记录。 |
| candidate | 16.14.794.5912 | `0x0214` | 雕纹、物品栏和符文状态批处理：已证实的子记录与未解析的特定类型语义并存。 |
| candidate | 16.14.794.5912 | `0x0278` | UnitApplyDamage：恢复了核心伤害量/来源/目标字段；所有者归属和枚举值尚未明确。 |
| candidate | 16.14.794.5912 | `0x0357` | 物体位置向量：物体 ID 和 3D 向量，缺少未证实的命中/目标标签。 |
| candidate | 16.14.794.5912 | `0x0318`, `0x0035` | 队伍、可见性与路由候选：玩家映射已通过验证，但非玩家路由语义尚未明确。 |
| candidate | 16.14.794.5912 | `0x0399`, `0x015f`, `0x0103` | Buff 添加/更新候选：保留了核心的槽位/计数/哈希/时间字段，未夸大分支语义。 |
| candidate | 16.14.794.5912 | `0x00f6`, `0x01eb`, `0x0314`, `0x02ab` | 周期性网格、物品组、标志/数值以及生命周期标记：结构稳定，但其游戏层面的作用尚未证实。 |
| unknown | rofl-v2 | - | 未解析的游戏玩法语义：治疗、护盾、完整的伤害归属、购买、经验、完整的 Buff 分支以及地图目标。 |
具有权威性的机器可读列表为 `rofllens capabilities --json`。详细的字段证据和未明确的边界记录在
[语义解码器](docs/semantic-decoders.md)以及
[完整的中文研究笔记](docs/research-notes.zh-CN.md)中。
## 语义配置文件
内置的 `16.14.794.5912` 配置文件仅包含派生配置、RVA 和哈希值。它不包含 Riot 的可执行代码或提取的 PE 区段。
要运行其语义解码器，请提供您自己的精确匹配的
`League of Legends.exe`：
```
rofllens export-spells replay.rofl `
--output spells.jsonl --players-only --qwer-only `
--semantic-profile "path\to\profile.json" `
--client-exe "path\to\League of Legends.exe"
```
在运行时，RoflLens 会验证可执行文件的 SHA-256，在内存中提取所需的 PE 区段，并验证每个区段的哈希值和 RVA。如果版本、协议或哈希值不匹配，将仅输出传输层数据或返回固定的不匹配错误；旧的解码器绝不会被静默应用。
`profile-skeleton` 可以为其他客户端创建本地研究配置文件。其提取的区段会保留在用户的本地配置文件目录中，并被 Git 忽略：
```
rofllens profile-skeleton "path\to\League of Legends.exe" `
--client-version 16.14.794.5912 `
--protocol-digest 509c49fd988fca11
```
## 回放样本
[`v0.1.0` 版本](https://github.com/ss26367098/rofllens/releases/tag/v0.1.0)中附带了五个未修改的 `16.14.794.5912` KR 回放文件，
以及 `samples-manifest.json`。它们并未存储在 Git 中。
这些文件包含了 50 名真实玩家的 Riot ID、PUUID、召唤师 ID 和比赛数据。在下载或重新分发它们之前，请阅读 [SAMPLE_DATA_NOTICE.md](SAMPLE_DATA_NOTICE.md)。
## 开发
```
python -m unittest discover -s tests -v
python tools/render_capabilities.py --check
python -m build
```
研究实用工具位于 `tools/` 目录下。贡献内容必须将 verified、candidate 和 unknown 数据严格区分开；详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。
## 法律声明
RoflLens 是一个独立的、非官方的项目，未受到 Riot Games 的认可或背书。《英雄联盟》和 Riot Games 是 Riot Games, Inc. 的商标。MIT 许可证仅适用于 RoflLens 的代码和文档，不适用于 Riot 的软件、回放内容、商标、Data Dragon 资产或提取的客户端区段。详情请参阅 [NOTICE.md](NOTICE.md)。
标签：Python, 协议分析, 数据提取, 文件解析, 文档结构分析, 无后门, 时序数据库, 权限提升, 游戏, 英雄联盟, 逆向工具