Skip to content

About

用于解析某米的二进制数据结构(DesignData)

Resources

Stars

4 stars

Watchers

1 watching

Forks

Latest commit

 

History

6 Commits

Folders and files

Repository files navigation

HoyoBinStruct (hoyobinstruct)

米哈游 DesignData 二进制结构的声明式解析器——声明类似 better-proto, 类型尽量用 Python 自带的;从 il2cpp 提取结构的代码独立成子包;解析走 construct 式运行时代码编译。纯静态:GameAssembly.dll + global-metadata.dat 进,声明模块出,不运行游戏。

2026-11 重构(v0.2)。旧 hoyobin_struct/、参考用旧代码/ 为 1.x 遗迹保留作参照。

声明方式(better-proto 风格)

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 子类(内嵌位图行)。

运行时编译(construct 式)

compile_message(cls) 把声明编译成专属解析函数并 exec:位图 → 局部位标志、 逐字段直接分支、list/嵌套生成专属辅助函数、位图尾巴非零严格报错。无通用分发器、 无 schema 字典查找。实测吞吐:35MB 中文 TextMap 397,428 行 / 3.3s(10.8 MB/s)。

从 il2cpp 提取(独立子包,capstone 隔离在内)

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 ActionGroupRow
import 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)          # '选择菜单'

实测状态(4.6.51 beta)

项 状态
声明生成 ✅ 1756 类(FromBinary 反汇编 + 名字自证)
MazePlaneRow vs pearl-sr ✅ 8/8 精确一致
TextMap 全行 ✅ 6 语言文件 + cn 397,428 行
真实 pack ✅ ActionGroup 280 行,TextID→'移动' 联查命中
SRMI / DesignV ✅ pack0 精确闭合(pack1+ 3B 异常待解)
表名→hash ⚠️ 魔改 XXH64 已转录,缺验证对
FixPoint 编码 ⚠️ 反汇编见 raw 与 zigzag 两种形态,默认 raw(见 docs/METHOD.md §5)

仓库结构

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。

About

用于解析某米的二进制数据结构(DesignData)

Resources

Stars

4 stars

Watchers

1 watching

Forks

Releases

Packages

Contributors

Languages