米哈游 DesignData 二进制结构的声明式解析器——声明类似 better-proto,
类型尽量用 Python 自带的;从 il2cpp 提取结构的代码独立成子包;解析走
construct 式运行时代码编译。纯静态:GameAssembly.dll + global-metadata.dat 进,声明模块出,不运行游戏。
2026-11 重构(v0.2)。旧
hoyobin_struct/、参考用旧代码/为 1.x 遗迹保留作参照。
from typing import Annotated
from hoyobinstruct import Row, Struct, TextID, Zigzag, Double
class TextID(Struct): # Struct = 无位图内联复合值(TextID/FixPoint 这类)
hash: Annotated[int, Zigzag] # 有符号 → zigzag varint
hash64: int # 裸 int = raw varint
class MazePlaneRow(Row): # Row = presence 位图驱动的表行
plane_id: int
plane_type: int # enum → int
plane_name: TextID # struct 引用
floor_id_list: list[int] # zigzag 计数 + 逐元素类型映射:int=raw varint、Annotated[int, Zigzag]=zigzag、bool、
float=fixed32、Annotated[float, Double]=fixed64、str=varint-len UTF-8、
bytes=varint-len、Annotated[bytes, Fixed(n)]=定长、list[T]、
Struct 子类(内联)、Row 子类(内嵌位图行)。
compile_message(cls) 把声明编译成专属解析函数并 exec:位图 → 局部位标志、
逐字段直接分支、list/嵌套生成专属辅助函数、位图尾巴非零严格报错。无通用分发器、
无 schema 字典查找。实测吞吐:35MB 中文 TextMap 397,428 行 / 3.3s(10.8 MB/s)。
python -m hoyobinstruct.il2cpp \
--ga <GameAssembly.dll> --meta <解密metadata> \
--tables <tables_result.json> --layout <layout.json> \
--fields <fields.json> --ptr-rva 0x4b6a160 \
--version 4.6.51-beta --out gen/sr_4651.py产出可 import 的声明模块(本仓已带 gen/sr_4651.py:1756 类 / 10 失败)。
方法定位链带名字自证:typeDef B份名字列 → 格位(+8) → 方法表 → FromBinary RVA;
字段名 = 写入偏移 ↔ 确定性布局;编码 = fields.json 静态类型。
MazePlaneRow 产出顺序与 pearl-sr 已知明文 8/8 精确一致。
python -m hoyobinstruct textmap <DesignData目录|文件...> --out textmap.json
python -m hoyobinstruct manifest <M_DesignV.bytes>
python -m hoyobinstruct designv <DesignV_*.bytes>
python -m hoyobinstruct table <表数据> --module gen.sr_4651 --class ActionGroupRowimport gen.sr_4651 as sr
from hoyobinstruct import parse_table, TextMapIndex
rows, used = parse_table(data, sr.ActionGroupRow) # → list[ActionGroupRow]
idx = TextMapIndex.from_files([cn_textmap])
idx.lookup(rows[0].action_group_textmap_id) # '选择菜单'| 项 | 状态 |
|---|---|
| 声明生成 | ✅ 1756 类(FromBinary 反汇编 + 名字自证) |
| MazePlaneRow vs pearl-sr | ✅ 8/8 精确一致 |
| TextMap 全行 | ✅ 6 语言文件 + cn 397,428 行 |
| 真实 pack | ✅ ActionGroup 280 行,TextID→'移动' 联查命中 |
| SRMI / DesignV | ✅ pack0 精确闭合(pack1+ 3B 异常待解) |
| 表名→hash | |
| FixPoint 编码 |
hoyobinstruct/ 核心运行时(零第三方依赖)
base.py compiler.py builtin.py textmap.py container.py mhyhash.py io.py cli.py
hoyobinstruct/il2cpp/ ★ 提取层独立子包(capstone 隔离):toolchain/resolve/codegen
gen/sr_4651.py 生成的声明模块(1756 类)
tests/ 回归(7 用例,含合成字节样本)
docs/METHOD.md ★ 通用方法全文:证据链 + 已知缺口
Python 3.10+(3.14 惰性注解已兼容)。核心运行时零依赖;
hoyobinstruct.il2cpp 另需 capstone。