ContinualDissapointment/Ultra-Despair-Extractor

# Ultra-Despair-Extractor 用于从《**弹丸论破外传：绝对绝望少女**》（Danganronpa Another Episode: Ultra Despair Girls）中提取 3D 模型（及其相关的归档文件/纹理）的工具——支持 PC (Steam) 版本和原始 PS Vita 版本。 这些仅仅是**工具**。它们不包含任何游戏数据。您必须提供自己合法拥有的游戏副本。 ## 目录说明 | 文件 | 功能 | |---|---| | `cpk_extract.py` | 解包 CRIWARE **`.cpk`** 归档文件（包含 CRILAYLA 压缩的条目）。适用于 PC 端的 `a1..a5.cpk` 和 Vita 端的 `dso_en.cpk`。 | | `bnc_to_obj.py` | 将模型 **`.bnc`** 文件转换为 Wavefront **`.obj`** 网格。 | | `btx_dec.py` | 解压 **`.btx`** 纹理容器（PC → DDS，Vita → GXT）。 | | `btx_to_png.py` | 将 **`.btx`** 纹理转换为 **PNG**（PC DDS 路径；需要 Pillow）。 | | `docs/FORMAT.md` | 逆向工程的文件格式说明。 | 模型/归档工具是纯 Python 3 标准库。`btx_to_png.py` 的 DDS→PNG 步骤需要 Pillow (`pip install pillow`)；解压本身使用的是标准库。 ## 快速开始（简易版） 你需要：游戏文件的副本，以及已安装的 Python 3。 ### 1. 找到游戏的归档文件 在 **PC 版本** 中，在游戏文件夹内你会看到 `en/a1.cpk`、`a2.cpk`……直到 `a5.cpk`。这些是包含所有内容的大型归档文件。 ### 2. 解包归档文件 ``` python cpk_extract.py "path/to/a1.cpk" ``` 这会在脚本旁边创建一个 `cpk_out/` 文件夹，其中包含游戏文件，包括以 **`.bnc`** 结尾的 3D 模型（你会在 `_chr` 文件夹中找到它们——角色、道具、物品）。 ### 3. 将模型转换为 `.obj` ``` python bnc_to_obj.py "cpk_out/en00_helmet.bnc" helmet.obj ``` 它会输出类似以下的内容： ``` en00_helmet.bnc: 68 verts, 132 faces, 1 submesh-chunks -> helmet.obj ``` ### 4. 打开它 在 **Blender** 中打开 `helmet.obj`（文件 → 导入 → Wavefront (.obj) — 在 Blender 4 中不需要插件），或使用任何 3D 应用程序。 ## 格式工作原理（简述） `.bnc` 是一个 `PSCa` 容器。在内部，每个网格是： - 一个**顶点缓冲区** — 每个顶点 16 字节：一个 4 字节的 tag（蒙皮：骨骼索引 + 权重），后跟一个作为三个 32 位浮点数的 XYZ 位置；以及 - 一个**面列表** — 每个三角形一条记录，其前三个 32 位整数是三个角点索引。 坐标被转换为 OBJ 空间，形式为 `(x, z, -y)`。完整的细节，包括我们排除的绝路，都在 [`docs/FORMAT.md`](docs/FORMAT.md) 中。 该格式是通过将原始文件与少数已知正确的社区提取文件进行交叉引用而逆向工程的（仅用作验证解码的“答案参考”——此处不包含任何该数据）。 ## 当前覆盖范围 `bnc_to_obj.py` 处理两种几何编码（参见 [`docs/FORMAT.md`](docs/FORMAT.md)）并自动检测使用哪一种： - **简单格式**（道具、物品、武器） — 面记录紧跟在顶点之后。对比参考提取文件（头盔），UV 已验证 **132/132**，并在多样化集合中进行了视觉确认。 - **复杂/蒙皮格式**（角色） — 顶点位于一个块中，面记录位于另一个单独的块中（自动定位），顶点存储在**骨骼局部空间**中。提取器找到骨骼绑定位置数组（脊柱签名）并应用**平移蒙皮**将模型展开为其绑定姿势。已在人类角色 (`ev*`) 和黑白熊小子 (`kks*`) 上进行了视觉确认 — 姿势已处理、UV 已映射、已加纹理。道具保持原样（无骨架）；角色姿势会自动处理。一次完整的 `a1` 扫描导出约 400 个静态模型，大部分带有 UV。 ## 使用说明 - **使用静态 `.bnc` 文件，而不是 `_anm` / `_evt_anm` 变体。** 动画文件会重新映射 UV，看起来会出现纹理错误。（也请跳过 `_shadow`。） - 完整角色 = 其**身体 + 头发 + 面部**静态网格，每个都有自己的纹理（位于 `_tex_pc` 归档中的 `.btx`；使用 `btx_to_png.py` 转换）。 - 正确性是在大量样本上通过视觉确认的，而非详尽验证 — 请对你关心的模型进行抽查。 ## 局限性 - **Vita 版本：** `cpk_extract.py` 可以解包 Vita 归档，但 `bnc_to_obj.py` 针对的是 PC 的 `.bnc` 结构（Vita 是一个更旧、更紧凑的变体）。 - **多纹理角色：** 每个网格分配一个 `.mtl`/纹理；少数跨越多个纹理图集的网格可能需要手动拆分材质。 ## 路线图 1. ~~`.btx` 纹理解码~~ — **已完成**（`btx_dec.py` / `btx_to_png.py`）。 2. ~~**UV 坐标**~~ — **已完成。** 每个面记录的 `strip[1]`（位于 +22 的 uint16）是其在 40 字节步长 UV 记录数组中的索引 `X`；`recoff = base + X*40`，每个角点包含三个 `(u,v)`，V 轴翻转。对比参考提取文件验证了 132/132。 3. ~~材质分配~~ — **已完成**；输出每个角点的 `vt` + 一个 `.mtl`。 4. ~~蒙皮角色~~ — **已完成。** 自动定位骨骼绑定位置数组并应用平移蒙皮；自动定位复杂格式的面块。 5. **优化：** 为批量导出提供更智能的纹理名称匹配；多材质网格；Vita 的 `.bnc` 变体。 ## 先前技术与鸣谢 我们站在许多巨人的肩膀上。如果没有以下各方的支持，这个项目就不会存在： - **akderebur** — **UniViewer** 及其弹丸论破 UDG 模型查看器插件的作者。这是最早尝试*原生*解析该游戏模型的努力。尽管我们无法让它在 PC 版本上运行，但反编译其解析逻辑**独立验证了我们的格式模型**（16 字节顶点布局、uint64 节指针、uint16 索引数据，以及每个顶点 tag 携带蒙皮/骨骼数据的事实）。非常感谢他们率先涉足这一格式。 - **XeNTaX 和 VG-Resource 论坛** — 社区讨论 `.bnc` / `.btx` 格式并分享样本文件的帖子。那里提出的问题（和指出的死胡同）为我们节省了实际时间。 - **互联网档案馆** — 感谢其保存了那些现已失效的论坛帖子。XeNTaX 论坛已经关闭；如果没有 Wayback Machine，那些知识将永远丢失。 - **The Models Resource**（以及贡献 UDG 模型的提取者） — 他们已知正确的提取文件是我们的**答案参考**：我们将解码的顶点和面数与其进行匹配，以*证明*格式已被正确解码。此处未重新分发任何数据 — 仅用于验证。 - **BlackDragonHunt / yukinogatari** 和 **@FireyFly** — 他们在 [Danganronpa-Tools](https://github.com/yukinogatari/Danganronpa-Tools) (`dr12ae/dr_dec.py`，WTFPL) 中逆向工程了 `.btx` 纹理压缩（`fc aa 55 a7` 容器）。此处的 `btx_dec.py` 是其算法的 Python 3 移植版。我们**并没有**自己破解这个 — 他们早在几年前就做到了。 - **xdanieldzd** — [GXTConvert](https://github.com/xdanieldzd/GXTConvert) 和 [Scarlet](https://github.com/xdanieldzd/Scarlet) 解码了 Vita `.btx` 解压后生成的 PS Vita **GXT** 纹理。 - **The Textures Resource** — 社区提取的 UDG 纹理，可用作检查参考。 如果你贡献了上述任何内容并希望更改措辞或归属信息，请提交 issue。 ## 法律/道德声明 本项目**不包含任何受版权保护的游戏内容** — 没有模型、纹理、归档或参考提取数据。它仅用于个人使用、保存以及与你合法获取的游戏副本进行互操作。Danganronpa Another Episode: Ultra Despair Girls 的版权归 © Spike Chunsoft 所有。本项目与其无关。 ## 许可证 MIT — 参见 [`LICENSE`](LICENSE)。

标签：3D模型提取, CRIWARE, Python, 云资产清单, 文件格式转换, 无后门, 游戏工具, 逆向工程