自定义模型指南
ArkPets 允许用户在《明日方舟》官方模型库之外，自行添加自定义 Spine 模型作为桌面宠物。本文档说明 v3.x 版本中自定义模型的数据集文件（models_data.json）格式、资源文件组织方式、启动器重载机制，以及模型资产在源码中的加载链路。
目的与范围
本页覆盖以下内容：
- 为 ArkPets v3.x 手动添加自定义 Spine 模型的完整操作流程
- 数据集文件
models_data.json的顶层结构（storageDirectory、sortTags、data等字段） data字段中单模型条目的字段定义（type、style、name、assetList等）- 资源文件（
.atlas/.png/.skel）的目录组织约定 - 启动器侧模型加载与校验所涉及的核心源码类（
ModelsDataset、ModelItem、ModelItemGroup、ModelsModule及各 GUI 任务类） - 常见故障排查与边界情况
本页不覆盖以下相关主题（属于兄弟页面范畴）：
- 模型在线下载、更新检查与解压校验任务的逐步实现细节（由
desktop/src/cn/harryh/arkpets/guitasks/下的任务类承担） - 桌面宠物的动画行为控制与状态机（动画命名规范仅在本页"前提条件"中引用）
- 命令行参数与启动器其他功能
概述
ArkPets 的桌面宠物基于 Spine 骨骼动画渲染，其官方模型资源来自 ArkModels 仓库。所谓"自定义模型"，本质上就是向 ArkPets 提供两样东西：
- 一个数据集文件
models_data.json：声明所有可用模型的元信息（名称、类型、标签、资源文件清单等），以及各模型类型对应的总模型文件夹名称。 - 一个总模型文件夹（如
models）：其下每个单模型子文件夹存放一组完整的 Spine 资源文件（.atlas图集描述、.png贴图、.skel骨骼数据）。
完成上述两步后，在启动器中执行模型"重载"即可让自定义模型出现在模型列表中。官方文档特别强调：该流程适用于 ArkPets v3.x，不同版本的模型管理逻辑可能有较大差异。
架构
自定义模型从磁盘文件到桌面宠物实例的整体数据流如下：
要点说明：
ModelsDataset（core/src/cn/harryh/arkpets/assets/ModelsDataset.java）是数据集文件的解析入口，负责把models_data.json反序列化为内存中的模型集合。ModelItem对应data字段中的一个模型对象（键名即单模型文件夹名称），ModelItemGroup负责对模型条目进行分组（例如按角色类型或标签聚合），供启动器模型列表展示。ModelsModule（desktop/src/cn/harryh/arkpets/controllers/ModelsModule.java）是启动器中模型列表页的控制器，用户执行"重载"时由此触发数据集重新读取。- GUI 任务类（
desktop/src/cn/harryh/arkpets/guitasks/下的DownloadModelsTask、UnzipModelsTask、VerifyModelsTask、PostUnzipModelTask等）提供了与手动放置文件等效的替代路径：通过启动器"选项"页直接下载或导入 ArkModels 数据集。 - 最终
ModelItem携带的assetList信息被用于在渲染时按相对路径定位并加载单模型文件夹内的 Spine 资源。
注：本节中各源码类的职责划分依据仓库实际文件结构与官方文档描述归纳；各类的具体字段与方法实现请直接参阅对应源文件。
前提条件
添加自定义模型前必须满足以下三项要求（摘自官方文档 docs/CustomModel.md）：
- 熟悉 JSON 数据格式——数据集文件是纯 JSON，需要手工编辑。
- Spine 版本必须是 3.8。这也是截至文档撰写时《明日方舟》所使用的 Spine 版本。不同版本的 Spine 之间兼容性较差；可以用文本编辑器强制查看
.skel骨骼文件的头部信息，以确定其 Spine 版本。 - 模型必须是《明日方舟》角色模型；如果不是，则模型包含的动画名称必须与《明日方舟》动画命名方式一致。命名规范定义在 Java 源码
cn.harryh.arkpets.animations.AnimClip中的AnimType枚举里。
设计意图：这三条约束都是为了保证自定义模型能被 ArkPets 既有的 Spine 渲染管线与动画状态机直接消费，避免在渲染层为非标准模型做特判。
完整操作步骤
以添加名称为 MyModel 的干员类型模型为例，分为四步：
- 在程序工作目录（下称"根目录"）创建数据集文件
models_data.json与总模型文件夹models。 - 将模型的资源文件（
.atlas/.png/.skel）放入同一个单模型文件夹，再把该文件夹放入总模型文件夹。 - 在数据集文件
data字段中，仿照其他模型对象的格式加入新模型信息。 - 打开 ArkPets 启动器，执行模型"重载"后即可载入自定义模型；若列表中未出现，请检查操作与拼写。
数据集文件格式详解
顶层结构 models_data.json
1{
2 "storageDirectory": {
3 "Operator": "models"
4 },
5 "sortTags": {
6 "Operator": "干员",
7 "Skinned": "时装"
8 },
9 "gameDataVersionDescription": "xxxxx",
10 "gameDataServerRegion": "zh_CN",
11 "data": {
12 },
13 "arkPetsCompatibility": [2, 2, 0]
14}Source: CustomModel.md
各字段含义（标注 * 者为必需条目）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
storageDirectory | object | * | 每种模型类型所对应的总模型文件夹名称，如 "Operator": "models" |
sortTags | object | 否 | 每个模型标签所对应的本地化描述，如 "Operator": "干员"、"Skinned": "时装" |
gameDataVersionDescription | string | 否 | 游戏数据版本描述 |
gameDataServerRegion | string | 否 | 游戏数据服务器地区描述，如 zh_CN |
data | object | * | 每个模型的信息，键名为单模型文件夹名称，值为模型对象 |
arkPetsCompatibility | array | 否 | ArkPets 兼容性版本标识，如 [2, 2, 0] |
注意事项（来自官方文档的提示）：
- 也可以通过启动器"选项"页的模型下载或导入功能来导入 ArkModels 仓库的数据集文件和总模型文件夹，从而省去手工放置。
- 总模型文件夹名称可以是其他名称，但需要在
storageDirectory字段中补充一对"角色类型" : "总资源文件夹名"的键值对。 - 示例中的
//注释仅作说明使用，标准 JSON 不支持注释，实际文件中不要写入注释。
data 字段中的单模型条目
1{
2 "my_model": {
3 "assetId": "build_my_model",
4 "type": "Operator",
5 "style": "BuildingDefault",
6 "name": "My Model",
7 "sortTags": [
8 "Operator"
9 ],
10 "appellation": "My Model",
11 "skinGroupId": "ILLUST",
12 "skinGroupName": "默认服装",
13 "assetList": {
14 ".atlas": "mymodel.atlas",
15 ".png": [
16 "mymodel1.png",
17 "mymodel2.png"
18 ],
19 ".skel": "mymodel.skel"
20 }
21 },
22 "my_next_model": {
23 }
24}Source: CustomModel.md
各字段含义（标注 * 者为必需条目）：
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| （对象键名） | string | * | 单模型文件夹的名称，必须与磁盘上的实际文件夹名一致 |
assetId | string | 否 | 已弃用，可忽略（历史遗留字段） |
type | string | * | 模型类型，如 Operator；须与 storageDirectory 中的键对应 |
style | string | 否 | 模型子类型，如 BuildingDefault |
name | string | * | 角色名称（启动器模型列表中显示） |
sortTags | string[] | 否 | 模型标签数组，如 ["Operator"] |
appellation | string | 否 | 角色代号 |
skinGroupId | string | 否 | 时装系列编号，如 ILLUST |
skinGroupName | string | 否 | 时装系列名称，如 默认服装 |
assetList | object | * | 资源文件列表，键为扩展名，值为文件名（字符串或字符串列表） |
关于 assetList 的设计意图：它以扩展名为键映射到该扩展名的全部文件。当同一扩展名对应多个文件（例如多张 .png 贴图）时，值使用字符串列表；只有一个文件时可直接使用字符串。渲染器据此在单模型文件夹内定位 .atlas、.png、.skel 三类文件，无需扫描目录。
核心流程：从文件到桌面宠物
流程说明：
- 用户手工编辑数据集并放置资源后，通过启动器"重载"触发数据集重新读取（对应上文的第 4 步）。
ModelsDataset解析 JSON，生成ModelItem并按ModelItemGroup分组，供ModelsModule展示。- 用户选中模型并启动后，
ModelItem中的assetList被传递给桌面宠物进程，按相对路径加载单模型文件夹内的三类 Spine 资源并渲染。
上述交互关系依据官方文档描述的"重载"机制与仓库源码文件结构归纳；
ModelsModule与ModelsDataset的具体方法签名请参阅源文件。
源码入口点参考
自定义模型能力在源码中由以下文件承担（按模块划分）：
| 模块 | 文件 | 职责 |
|---|---|---|
| core | ModelsDataset.java | 数据集文件解析入口，反序列化 models_data.json |
| core | ModelItem.java | 单个模型条目的数据载体 |
| core | ModelItemGroup.java | 模型条目分组聚合 |
| desktop | ModelsModule.java | 启动器模型列表页控制器，承载"重载"交互 |
| desktop | UnzipModelsTask.java | 解压模型资源任务（导入数据集的替代路径） |
| desktop | PostUnzipModelTask.java | 解压后处理任务 |
| desktop | DownloadModelsTask.java | 在线下载模型资源任务 |
| desktop | DownloadModelDatasetTask.java | 在线下载数据集任务 |
| desktop | VerifyModelsTask.java | 模型完整性校验任务 |
| desktop | McCheckModelsUpdateTask.java | 模型更新检查任务 |
本页不展开各任务类的逐步实现细节；其内部控制流请参阅上述源文件。由于源码探索预算所限，本页未能逐行读取上述 Java 类的实现，字段级结论均以
docs/CustomModel.md官方文档为准。
故障排查、边界情况与并发
基于官方文档与资源加载机制，可归纳以下注意事项：
重载后模型未出现
官方文档给出的排查建议是"检查相关操作和拼写"。结合数据集结构，应依次核对：
- 对象键名与文件夹名一致性：
data字段中模型对象的键名必须与总模型文件夹下单模型文件夹的实际名称完全一致。 type与storageDirectory对应：模型的type（如Operator）必须在顶层storageDirectory中有对应的总文件夹映射，否则资源定位会失败。assetList文件名拼写：.atlas/.png/.skel的文件名需与单模型文件夹中的实际文件名一致；注意多文件场景应使用列表。- JSON 语法：标准 JSON 不支持注释，若把示例中的
//注释一并写入会导致解析失败。 - Spine 版本兼容性：模型必须为 Spine 3.8；版本不符时骨骼文件无法正确解析，用文本编辑器查看
.skel头部可确认版本。
版本边界情况
arkPetsCompatibility兼容性标识：数据集顶层携带形如[2, 2, 0]的版本数组，用于标识数据集与 ArkPets 的兼容性；使用与当前程序不匹配的旧/新数据集时可能出现解析差异。- 跨版本差异：官方文档明确声明本文档仅适用于 v3.x，不同版本的 ArkPets 模型管理逻辑可能有较大差异，不可直接套用。
与启动器导入任务的并存关系（并发/一致性视角）
手动放置文件与启动器的下载/导入（DownloadModelsTask、UnzipModelsTask、PostUnzipModelTask）是两条并行的资源写入路径，最终都收敛到同一 models_data.json 与总模型文件夹。因此：
- 手动修改数据集后，必须执行"重载"使启动器内存中的
ModelsDataset快照失效并重新读取；否则列表显示的是旧快照。 - 若在启动器执行下载/导入任务期间同时手工编辑数据集文件，可能产生写入冲突，建议错开操作。
相关链接
- 官方自定义模型文档：CustomModel.md
- 动画命名规范所在源码：
cn.harryh.arkpets.animations.AnimClip中的AnimType枚举 - 命令行说明：CmdLine.md
- 常见问题：FAQ.md