自定义骨架屏加载器

《杀戮尖塔2》自定义骨骼加载器

概述

CustomSkeletonLoader 是《杀戮尖塔2》的一款强大的运行时骨骼替换工具，允许模组制作者在不修改游戏文件的情况下，使用自定义资源替换游戏内的 Spine 骨骼动画。

它支持超过 136 种可替换的骨骼，包括可玩角色、怪物、商人、背景、UI 元素和视觉效果。

该模组内置了一个导出工具包，用于从 PCK 包中提取所有官方骨骼资源，一个能处理多种命名变体的智能名称匹配算法，以及无缝的 ModConfig 面板集成，方便进行调试和一键导出。

如果此模组对您有帮助，请点击“ endorse”按钮以示支持。:)

功能特性

1. 自定义骨骼替换

此模组会自动扫描模组目录下的 ReplaceResources 文件夹，查找自定义骨骼文件（.atlas, .skel, .png），并在运行时使用 Harmony 补丁替换游戏默认骨骼，对原始代码零侵入。

支持替换的资源类型：

• .atlas
• .skel
• .png

替换范围包括：

• 可玩角色： 铁甲战士、静默猎手、故障机器人、死灵法师、摄政王（包含战斗和武器变体）。
• 商人变体： 所有 5 个角色，具有独特的商店待机动画。
• 休息点： 角色专属的休息动画（包括死灵法师的 Osty 同伴）。
• 角色选择： 所有 5 个职业的完整选择界面骨骼。
• 怪物： 超过 90 种跨越所有幕的敌人类型（首领、精英、普通）。
• 背景： 仪式野兽、宝藏室（第1/2/3幕）、商人房间、主菜单、特斯卡特拉。
• UI 元素： 战斗充能球（暗黑、冰霜、玻璃、闪电、等离子）、MegaCrit 标志动画。
• 视觉效果： 首领爆炸、激光束、护盾效果、划痕、刀光、藤蔓触手。

2. 骨骼导出工具

该模组包含一个全面的内置导出功能，可通过 ModConfig 面板访问，该功能会将游戏 PCK 包中所有可替换的 Spine 骨骼资源提取为标准文件格式，方便编辑。

导出能力：

• 从 .spatlas（Godot 压缩格式）中提取完整的 .atlas 文件。
• 将 .spskel 二进制文件转换为与 Spine 编辑器兼容的标准 .skel 格式。
• 导出所有关联的 .png 纹理页，并具有正确的文件名。
• 处理多页纹理集（例如，necrobinder.png + necrobinder_2.png）。
• 自动创建带有重命名文件集的 /unified 子目录，便于查看。
• 合并重复的骨骼（通过 MD5 哈希比较）以减少冗余。

导出输出结构：

Spine_resource/
├── ironclad/
│   ├── ironclad.atlas
│   ├── ironclad.skel
│   ├── ironclad.png
│   └── unified/
│       ├── ironclad.atlas
│       ├── ironclad.skel
│       └── ironclad.png
├── necrobinder/
│   ├── necrobinder.atlas
│   ├── necrobinder.skel
│   ├── necrobinder.png
│   ├── necrobinder_2.png
│   └── unified/
│       └── ...
└── ... (130+ 个骨骼目录)

导出总量： 超过136套包含完整纹理数据的骨骼。非常适合创建自定义骨骼模组或研究官方动画结构。

3. 运行时稳定性

稳定性特性：

• 并发安全缓存： 使用 ConcurrentDictionary 进行线程安全的骨骼数据缓存，并具有空值保护（失败的加载永远不会被缓存）。
• 资源生命周期管理： 在 try-catch-finally 块中进行适当的 GodotObject 释放，防止加载失败时内存泄漏。
• Harmony 非侵入式补丁： 所有替换都使用 Harmony 前缀/后缀，保留原始方法行为作为回退。
• 优雅降级： 缺失或无效的自定义文件会被静默跳过；游戏继续使用默认资源。
• 调试日志系统： 可配置的详细日志记录，用于故障排除（通过 ModConfig 开关控制）。
• 导出安全： 具有重复检测的原子导出操作可防止损坏；并发导出请求将排队处理。
• 路径自动解析： 自动定位相对于 DLL 位置的模组目录——无需手动配置。

4. 安装

1. 从模组页面下载最新版本。
2. 将内容解压到您的《杀戮尖塔2》模组文件夹中： .../Slay the Spire 2/mods/
3. 安装必需的依赖项：
   • ModConfig – 游戏内设置面板和导出功能所需（如果不安装，则仅提供基本替换功能）。

模组目录结构：

CustomSkeletonLoader/
├── CustomSkeletonLoader.dll
├── CustomSkeletonLoader.pck
├── CustomSkeletonLoader.json
└── ReplaceResources/
    │   (将自定义骨骼文件放置在此处)
    │   ├── ironclad/
    │   │   ├── ironclad.atlas
    │   │   ├── ironclad.skel
    │   │   └── ironclad.png
    │   ├── silent/
    │   │   └── ...
    │   └── ... (其他骨骼目录)

---

配置

所有设置均可通过游戏内的 ModConfig 面板中的“CustomSkeletonLoader”部分进行访问：

• 启用调试日志 (开关，默认开启)
• 导出所有骨骼 (按钮) – 一键提取所有 136+ 个游戏骨骼到 /Spine_resource 文件夹。将 Godot 格式（.spatlas/.spskel）转换为标准 Spine 格式（.atlas/.skel），并导出所有 PNG 纹理。
• /unified 文件夹中的 Spine 文件仅为方便导入编辑工具而重命名，不 用于实际的资源替换。

使用方法

创建自定义骨骼

1. 使用 ModConfig 面板中的 Export 按钮导出基础游戏骨骼。

2. 导航到导出目录：.../mods/CustomSkeletonLoader/Spine_resource/{skeleton_name}/unified/

3. 使用兼容 Spine 的工具（例如，Spine Essential、其他编辑器）编辑骨骼文件。

4. 将修改后的文件放置在：.../mods/CustomSkeletonLoader/ReplaceResources/{skeleton_name}/

5. 检查替换文件的文件名是否与原文件名匹配。

6. 重新启动游戏 – 骨骼在首次访问时于运行时加载（懒加载）。

文件命名约定

自定义骨骼文件必须遵循 ReplaceResources/ 目录内的以下结构：

• 目录名称： 使用目标骨骼标识符
• Atlas 文件： {name}.atlas
• 骨骼数据： {name}.skel
• 纹理页： {name}.png， {name}_2.png 等（如 atlas 所引用）

支持的命名示例：

ReplaceResources/
├── ironclad/              # 替换战斗中的铁甲战士
│   ├── ironclad.atlas
│   ├── ironclad.skel
│   └── ironclad.png
├── ironclad_merchant/     # 替换商店中的铁甲战士（自动匹配）
│   ├── ironclad_merchant.atlas
│   ├── ironclad_merchant.skel
│   └── ironclad_merchant.png
├── necrobinder/           # 替换战斗中的死灵法师
│   └── ...
├── ceremonial_beast/      # 替换首领怪物
│   └── ...
└── dark_orb/              # 替换 UI 充能球动画
    └── ...

（支持读取子文件夹中的文件。即使命名有变体，智能匹配也能找到您的文件。）

---

故障排除

自定义骨骼未加载

1. 验证所有三种文件类型（.atlas, .skel, .png）是否存在于同一目录中。
2. 检查 PNG 文件名是否与 .atlas 文件内的引用完全匹配（区分大小写）。
3. 在 ModConfig 中启用调试日志，并在游戏日志中查找 [CustomSkeletonLoader] 消息。
4. 确认 ReplaceResources/ 位于模组文件夹内（而不是在 Spine_resource/ 中）。
5. 确保骨骼目录名称与目标匹配。

导出失败或不完整

1. 检查模组目录的写入权限。
2. 确保有足够的磁盘空间（导出将生成 136+ 个包含纹理的目录）。
3. 验证 ModConfig 依赖项已安装并正常工作。
4. 检查游戏日志中的导出进度消息和错误详细信息。

替换后出现纹理/图集错误

1. 使用文本编辑器验证 .atlas 文件语法（检查 spatlas 转换中是否有损坏的 JSON）。
2. 确保 .skel 文件版本与您的 Spine 运行时版本兼容。
3. 首先使用原始导出的文件进行测试，以确认替换流程工作正常。
4. 检查图集中引用的所有 PNG 纹理页是否存在于同一目录中。

游戏崩溃或性能问题

1. 在生产环境中禁用调试日志（详细日志记录会影响性能）。
2. 减少同时替换的骨骼数量，以隔离有问题的资源。
3. 验证自定义骨骼文件未损坏（先在 Spine 编辑器中测试）。
4. 检查 .png 文件是否过大（建议每页保持在 2048×2048 以下）。

点击导出按钮后游戏冻结

• 资源正在后台导出，请耐心等待 10–30 秒，导出速度取决于您的设备性能。

相关工具：

• Godot RE Tools – 从其他 STS2 模组或游戏版本中提取资源以供参考。
• Custom Card Texture Loader SG - 加载自定义卡牌纹理，支持 GIF 动画、交互式播放模式和纹理导出功能。

本模组旨在为动画师和模组制作者提供无缝的骨骼定制能力，无需复杂的重新打包，同时提供专业级的资源提取和替换工具。

来自 STS2 模组创作者的爱。 :)