- gr2: BitKnit2 decompression, 64-bit LE files, compressed curves - net: remaining GamePhase handlers, generated GC packet table - python: event/chat/chr/minimap/guild/quest/messenger/shop-search and other native modules ported against the AVA2 Windows client - render: D3D8 fixed-function lighting in Gr2ModelRenderer, terrain without baked shade; cape/NPC equipment attachment - tests + audits updated; docs/PORT-PLAN.md and WINDOWS-PARITY.md Batch 4 (render pipeline: background.*, app.RenderGame/UpdateGame, camera bindings, main.cpp fake-content removal) is still in progress. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
47 lines
3.5 KiB
Markdown
47 lines
3.5 KiB
Markdown
# libgr2
|
||
|
||
自研 gr2 v6/v7 **只读**读取器。零第三方依赖。施工文档 [`../docs/reference/steps/M0-gr2-reader.md`](../docs/reference/steps/M0-gr2-reader.md)。
|
||
|
||
## 能做什么
|
||
|
||
- 容器:magic / header / section / pointer-fixup(懒解引用,不物化 32 位指针)
|
||
- section 解压:Oodle1(`oodle1.c`)、BitKnit2(`bitknit2.cpp`,Granny 2.11 `Format==4`,含压缩的 fixup 表)
|
||
- 32 / 64 位 little-endian(64 位只是 section 数据里的指针宽 8 字节;header / section 表 / fixup 同 32 位)
|
||
- 动画曲线:老式 `OldCurveType`(Granny 2.4)+ Granny 2.6+ `curve2` 的 19 种 `CurveData*` 变体(AVA2 语料出现的 17 种全覆盖)(常量 / 关键帧 / `K32f` / `K16u` / `K8u` 量化 / `D4n` 压缩四元数),统一解到 `Curve` 走 B 样条求值
|
||
- 自描述类型树遍历(不硬编码 struct 布局)
|
||
- `FileInfo`:skeletons / meshes / materials / textures / models / animations
|
||
- 骨架 + `granny_transform` → 4x4 组合(`BuildCompositeTransform4x4` 语义)
|
||
- 蒙皮网格:顶点(按顶点格式自描述解)/ 索引 / 三角组 / BoneBindings(多 skeleton 取最优匹配)
|
||
- 材质:`granny_material` 链(直接 `.Texture` 或递归 `.Maps[].Map`)→ `granny_texture.FromFileName`;
|
||
`Mesh.material_textures` 与 `MaterialBindings` 平行,`tri_group.material_index` 索引它
|
||
- 动画曲线(`OldCurveType` B 样条,degree 0/1/2)解码 + `gr2::sample_pose`(跨文件按骨骼名 retarget)
|
||
|
||
## 验证
|
||
|
||
- 全量 9166 个 Metin2 `.gr2`:**0 崩溃、0 非退化谓词失败**(`tools/gr2fuzz`)
|
||
- **对拍真 Granny 2.9.12**:骨骼世界矩阵 ≤ 4.6e-5、蒙皮顶点 ≤ 6.5e-5(`tools/oracle_diff`,`tools/granny-oracle/m2-numeric.json`,23 用例含 v7 / 双 root / 刚体 / 多动画帧)
|
||
- 坏输入(空 / 错 magic / 截断 / 越界索引)一律干净报错,不崩
|
||
|
||
## 明确不做(Metin2 语料里 0 出现;要「任意 gr2」才需要)
|
||
|
||
| 缺口 | 现状 | 补的成本 |
|
||
|---|---|---|
|
||
| **writer** | 无(设计上只读)| 大,PoC 不需要 |
|
||
| Oodle0 解压(`Format==1`)| `decompress_status=1`,不崩 | 中,同族算法变体 |
|
||
| BitKnit v1 解压(`Format==3`)| `decompress_status=3`,不崩(AVA2 语料 0 个;`Format==4` 是 BitKnit2,已支持)| 中,与 BitKnit2 同族 |
|
||
| B 样条 degree ≥ 3 | `eval` 退化到 degree 2 | 小,加 `CubicCoefficients` |
|
||
| big-endian gr2 | `load` 直接拒(`big-endian Granny files not supported`;AVA2 语料 0 个)| 中,全部读取加字节序翻转 |
|
||
| 多 skeleton 文件里刚体挂件的 skeleton 归属 | mesh binding 取「悬空最少」的 skeleton;`oracle_diff` 对这种 mesh 会误判(不是 libgr2 的问题)| 需要 FileInfo 暴露 per-model skeleton 索引 |
|
||
|
||
## ⚠ 许可
|
||
|
||
`src/bitknit2.cpp` 依据 MIT 许可的 BG3ModStudio `LibLS/Bitknit2Decompressor.cpp`(© 2025 Thomas A. Rieck,https://github.com/trieck/BG3ModStudio)重写,并对照 powzix/ooz `bitknit.cpp`;不含 RAD 代码,可随 MIT 声明发布。
|
||
|
||
|
||
`src/oodle1.c` 是从泄露的 Granny SDK **直接端口**的解码路径(约 450 行)。
|
||
|
||
- **内部研究 / 不发布 / 非商用**:可用(和「拿泄露 SDK 当字节级规格」同一风险类别,全项目都这么做)。
|
||
- **任何对外发布 / 商用**:必须 clean-room 重写(照公开的「granny2 Oodle1」算法描述从零写,不看这份端口)。
|
||
|
||
其余代码(容器 / 类型树 / 骨架 / 网格 / 曲线 / 姿势)是照泄露 SDK **头文件的 struct 定义和公式注释**自己写的,不是复制实现。
|