# 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 定义和公式注释**自己写的,不是复制实现。