Randombirdnoise/Spine_Magic_Builder

# Spine Magic Builder Spine Magic Builder 是一个优先适配 Windows 的重构工具包，专为处理分散或命名不当的 Spine 资源而设计。它在字节级别扫描目录树，识别骨骼和图集，匹配纹理页面，生成规范化的 Spine 资源集，并为有歧义的匹配提供可视化的候选工作流。 该项目专为文件名和扩展名不可信的解包资源树而设计。它支持 JSON 和二进制骨骼文件的发现、内嵌或独立的图集数据、PNG/JPEG/WebP 纹理尺寸检测、多页图集以及可选的同尺寸候选暂存功能。 ## 快速开始 ### 环境要求 - Windows 10 或 11 - Python 3.10 或更高版本，且在 `PATH` 中可通过 `py` 或 `python` 调用 - 可选：[SpineViewer](https://github.com/ww-rm/SpineViewer)（用于视觉验证） - 可选的 GUI 增强功能：Pillow 和 tkinterdnd2 克隆或下载本仓库，然后可选择安装 GUI 扩展依赖： ``` py -3 -m pip install -r requirements-optional.txt ``` 核心构建器仅使用 Python 标准库。Pillow 提供了更广泛的图像尺寸和缩略图支持；tkinterdnd2 为 GUI 增加了拖放功能。 ### 推荐工作流 1. 将源文件夹拖放到 `Run_SpineMagic_Builder_Candidate_Stage_v3.bat` 上。 2. 等待构建器创建一个相邻的 `Spine_Built-*` 目录。 3. 打开 `Run_SpineCandidatePicker_GUI.bat`。 4. 浏览到包含 `_candidates` 文件夹的构建目录。 5. 选择一个页面和候选项，然后按 **Activate** 或数字键。 6. 出现提示时，在 GUI 中指定 `SpineViewer.exe` 的路径并进行可视化验证。 7. 将所选内容标记为正确、将其加入黑名单或跳过该页面。 GUI 会将其查看器路径和决定记录在以下文件中： ``` %LOCALAPPDATA%\SpineMagicBuilder\spine_candidate_picker_state.json ``` 设置 `SPINE_MAGIC_BUILDER_STATE` 可使用不同的状态文件位置。设置 `SPINE_VIEWER_EXE` 可定义初始的查看器路径。 ## 包含的程序 | 文件 | 用途 | | --- | --- | | `spine_magic_builder.py` | 核心递归扫描器和规范化资源集构建器。 | | `spine_magic_builder_candidate_materializer_v3.py` | 带有候选暂存和单候选项实体化功能的扩展构建器。 | | `spine_candidate_picker_gui.py` | 用于审查、激活和记录候选选择的 Tk GUI。 | | `Run_SpineMagic_Builder.bat` | 保守的复制模式构建器预设。 | | `Run_SpineMagic_Builder_Candidate_Stage_v3.bat` | 针对大型解包资源树优化的候选暂存预设。 | | `Run_SpineCandidatePicker_GUI.bat` | GUI 启动器；接受可选的起始文件夹。 | ## 输出内容的组织方式 除非在命令行中明确提供了 `--move`，否则源文件将保留在原处。包含的启动脚本从不使用 `--move`。 对于选定的源文件夹，输出内容将被写入到其旁边生成的容器中，类似于： ``` ParentFolder\ ├── SourceFolder\ └── Spine_Built-Context_Name\ └── SourceFolder\ └── normalized_spine_set\ ├── normalized_spine_set.skel (or .json) ├── normalized_spine_set.atlas ├── texture pages └── _candidates\ ``` 在放置新候选项之前，候选激活操作会将先前处于活动状态的页面保留在 `_materialized_history` 中。 ## 启动脚本详情 ### 标准构建器 `Run_SpineMagic_Builder.bat` 使用复制模式和适中的图集匹配阈值。将文件夹拖放到其上或调用： ``` Run_SpineMagic_Builder.bat "D:\ExtractedGame\assets" ``` ### 候选暂存构建器 `Run_SpineMagic_Builder_Candidate_Stage_v3.bat` 将直接子文件夹隔离为独立实体，对模糊的同尺寸纹理进行排名，并暂存所有候选项。它请求使用符号链接以避免重复庞大的纹理集合；在不可用符号链接的系统上，脚本会尝试硬链接，最后退回到复制方式。 当无限暂存产生过多候选项时，可直接从 Python 中使用 `--stage-dim-candidates-limit N`。 ### 候选项选择器 GUI 不带参数运行并浏览到某个文件夹，或提供一个起始路径： ``` Run_SpineCandidatePicker_GUI.bat "D:\ExtractedGame\Spine_Built-Example" ``` 常用快捷键： | 键 | 操作 | | --- | --- | | `1`-`9` | 激活排名第 1-9 的候选项 | | `Enter` | 激活所选候选项 | | `Left` / `Right` | 上一个 / 下一个候选项 | | `Ctrl+Left` / `Ctrl+Right` | 上一个 / 下一个图集页面 | | `C` | 将所选候选项标记为正确 | | `B` | 将所选候选项加入黑名单 | | `S` | 跳过当前页面 | | `F5` | 启动 SpineViewer | 如果未自动找到 SpineViewer，请使用 **Viewer exe** 按钮。自动搜索会检查仓库文件夹、`SpineViewer` 子文件夹以及仓库的父文件夹。SpineViewer 需要单独下载。 ## 命令行用法 核心构建器： ``` py -3 spine_magic_builder.py --root "D:\ExtractedGame\assets" --dims-fallback --prefer-nearby-textures ``` 暂存有歧义的尺寸匹配项： ``` py -3 spine_magic_builder_candidate_materializer_v3.py ` --root "D:\ExtractedGame\assets" ` --dims-fallback ` --stage-dim-candidates ` --stage-dim-candidates-limit 250 ``` 无需 GUI 即可激活一个暂存的候选项： ``` py -3 spine_magic_builder_candidate_materializer_v3.py ` --materialize-built-set "D:\Path\To\OneBuiltSet" ` --materialize-page 1 ` --materialize-candidate 3 ` --link-mode copy ``` 对任一构建器运行 `--help` 可获取完整的选项列表。有用的高级开关包括 `--explain-match`、`--top-n`、`--entity-mode`、`--rewrite-pages-to-match-source` 和 `--dedupe-textures`。 ## 安全提示 - 默认的 CLI 行为是复制源纹理；标准启动脚本明确使用复制模式。 - 包含的启动脚本从不传递 `--move`。 - 符号链接和硬链接模式可节省磁盘空间，但会将生成的输出链接到原始纹理数据。如果需要编辑构建好的资源集，请使用复制模式。 - `--aggressive-atlas` 和 `--dims-fallback` 可提高命名受损时的恢复率，但也可能导致错误匹配。请以可视化方式验证有歧义的结果。 - 如果无法使用链接，候选暂存可能会消耗大量磁盘空间。如有需要，请设置有限的候选数量限制。 - 生成的状态、游戏资源、候选文件夹和构建输出均被 `.gitignore` 排除。 ## 故障排除 **未找到 Python** 安装 Python 3.10+ 并在安装程序中启用将 Python 添加到 `PATH` 的选项，然后打开一个新的终端。 **GUI 打开了，但缩略图受限** 安装 `requirements-optional.txt`。当未安装 Pillow 时，GUI 会退回到 Tk 内置的 PNG 加载器。 **拖放操作无效** 安装 `tkinterdnd2`，或使用 GUI 的“浏览”按钮。 **在 Windows 上创建符号链接失败** 启用 Windows 开发者模式，使用适当的权限运行，或使用 `--link-mode copy`。候选构建器已经会自动退回到硬链接，然后退回到复制方式。 **缺少 SpineViewer** 从上游的 [SpineViewer 仓库](https://github.com/ww-rm/SpineViewer) 下载一个发布版本，然后使用 GUI 的 **Viewer exe** 按钮选择 `SpineViewer.exe`。 ## 致谢 特别感谢 [ww-rm/SpineViewer](https://github.com/ww-rm/SpineViewer) 及其贡献者。SpineViewer 是 GUI 工作流中使用的外部可视化验证组件，正是它使得快速检查候选项成为可能。 SpineViewer 并未与本项目打包在一起，也未重新授权。有关详细信息，请参阅 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)。 ## 许可证 Spine Magic Builder 的原始代码和文档在 [MIT 许可证](LICENSE) 下发布。第三方程序和资源受其各自条款的约束。

标签：Python, Spine动画, 无后门, 桌面GUI, 资产重构, 逆向工具, 逆向提取