lorenfa99/hfw-raw-mesh-point-inspector

# hfw-raw-mesh-point-inspector `hfw-raw-mesh-point-inspector` 是一个小型的取证工具包，专门用于处理未知的二进制类网格（mesh）文件， 它是基于《地平线：西之绝境》（Horizon Forbidden West，简称 HFW）/ Decima 引擎的资产研究创建的。 它非常适用于资产逆向工程中尴尬的中间阶段：你可能还不太 了解其格式，但你怀疑某些字节范围包含了位置信息。与其 等待完整的导入工具，不如使用该工具来尝试候选的记录布局，将 记录范围渲染为点云，导出仅包含顶点的 OBJ 文件，并将 OBJ 网格拆分为 连通分量以便手动检查。 该项目有意不提供任何《地平线：西之绝境》文件、Decima 引擎游戏 资产、提取的网格/纹理以及任何专有工具。演示数据均为合成的。 它不隶属于 Guerrilla、Sony、Nixxes 或任何官方的 Decima 引擎工具。 ## 为什么会有这个项目 大多数工具要么是： - 针对已知格式的完整导入器，或者 - 能够显示所有内容但在视觉上无法提供任何解释的十六进制编辑器。 这个项目介于这些极端之间。如果一个二进制数据块可能包含如下记录： ``` record 0: x y z ... other bytes ... record 1: x y z ... other bytes ... ``` 你可以尝试诸如 `f32x3@0:36` 或 `f16x3@0:32` 的布局，预览这些范围，并快速查看 这些记录究竟是构成了躯体、服装外壳、道具、地形块，还是纯粹的无用数据。 第一个现实中的目标是《地平线：西之绝境》网格流调查，但该 工作流程具有普遍适用性：任何涉及 Decima 引擎、游戏模组（modding）或含有未知顶点缓冲区的二进制资产研究 项目，都可以使用相同的点云探测方法。 ## 安装 在仓库根目录下执行： ``` python -m pip install -e ".[plot,test]" ``` `matplotlib` 仅用于生成 PNG 图表。OBJ/CSV/统计报告在没有它的情况下也能正常工作。 ## 快速演示 生成一个合成的二进制文件： ``` meshpoints demo --out-dir examples/generated ``` 扫描它： ``` meshpoints scan examples/generated/synthetic_mesh.bin ``` 在记录窗口中扫描它： ``` meshpoints sweep examples/generated/synthetic_mesh.bin ^ --layout f32x3@0:36 ^ --records-per-range 400 ^ --out-dir outputs/sweep ^ --plot-top 4 ``` 提取特定的记录范围： ``` meshpoints extract examples/generated/synthetic_mesh.bin ^ --layout f32x3@0:36 ^ --range 0..899 ^ --range 900..1499 ^ --out-dir outputs/extract ``` 将一个三角形 OBJ 拆分为连通分量： ``` meshpoints components model.obj --out-dir outputs/components --top 10 ``` 找出两个二进制版本之间发生变化的记录范围： ``` meshpoints diff before.bin after.bin --stride 36 --out-dir outputs/diff ``` 如果发生变化的记录也使用了已知的位置布局，请预览这些已更改的范围： ``` meshpoints diff before.bin after.bin ^ --layout f32x3@0:36 ^ --out-dir outputs/diff ^ --plot-top 8 ``` ## 布局语法 布局使用： ``` TYPE x COMPONENTS @ POSITION_OFFSET : RECORD_STRIDE ``` 示例： - `f32x3@0:36` = 在字节偏移量 `0` 处的三个小端序 float32 值，每 `36` 个字节为一条记录。 - `f16x3@0:32` = 在字节偏移量 `0` 处的三个小端序 float16 值，每 `32` 个字节为一条记录。 - `s16x3@8:48` = 在字节偏移量 `8` 处的三个有符号 int16 值，每 `48` 个字节为一条记录。 支持的类型包括 `f32`、`f16`、`s16` 和 `u16`。 ## 主要命令 - `scan` — 用于查看二进制文件的字节/熵窗口。 - `sweep` — 汇总固定的记录窗口，并可选择绘制最强点云候选对象的图表。 - `extract` — 将选定的记录范围导出为 OBJ/CSV/PNG。 - `diff` — 对比两个二进制版本之间变化的记录进行分组，并可选择预览已更改的范围。 - `components` — 将三角形 OBJ 拆分为连通分量。 - `demo` — 生成合成的类网格数据，作为安全的示例。 ## 符合 GitHub 规范的范围 本仓库用于通用的二进制检查工作流，包括《地平线：西之绝境》 / HFW / Decima 引擎研究。请勿提交专有的游戏资产、提取的网格、 提取的纹理、本地工具二进制文件或已打补丁的游戏文件。 请使用合成的示例、您自己的文件，或您有权共享的文件。

标签：3D网格, Python, 云资产清单, 代码示例, 数据分析, 无后门, 游戏开发, 点云, 逆向工具, 逆向工程