Importing Mascots

导入桌宠模板

本页告诉你如何把资源包导入 NeurolingsCE、导入后文件会放到哪里，以及遇到失败时先检查什么。

从 0.3.2 开始，推荐安装格式是 .mascot 单文件包。这个格式本质上是 zip 兼容压缩包，根目录必须包含 info.json。

最推荐的导入方式

把 .mascot、兼容的 .zip 或模板文件夹直接拖到管理器窗口。

从 0.5.1 起，拖放也接受模板文件夹。这是最稳妥的方式，因为运行时会同时处理：

• .mascot 包验证
• 传统 ZIP 结构识别
• 模板文件夹导入
• 必要时转换为 .mascot
• 模板安装与同名替换
• 导入后列表刷新

如果管理器提供导入按钮或菜单入口，也可以使用，但优先级仍是“拖进去试一次”。

如果你手上是旧 Shimeji .zip，也可以先用管理器的“制作”页做内容检查和转换。制作页会把结果写到你选择的输出目录，不会自动导入模板库；转换完成后再把生成的 .mascot 导入即可。

.mascot 包结构

一个标准 .mascot 包长这样：

Name.mascot
├── info.json              必需
├── bubble_context.txt     可选
├── actions.xml
├── behaviors.xml
├── img/
└── sound/                 可选

info.json 负责提供用户可见的模板信息。运行时使用 info.json.name 作为模板列表中的显示名和召唤名，而不是使用文件名。

默认 info.json 示例：

{
    "name": "Default",
    "version": "1.0",
    "description": "Default mascot for the application.",
    "author": "pixelomer[https://github.com/pixelomer]"
}

bubble_context.txt 是可选 UTF-8 文本文件，放在包根目录，一行一句气泡文本。存在时，点击该模板对应桌宠会优先使用包内文本；不存在时继续使用全局或默认气泡文本 fallback。

传统 ZIP 仍然可以导入

导入器仍会尝试自动识别几类常见 Shimeji-ee 结构。传统 ZIP 导入成功后会被转换并安装成 .mascot 文件。

1. 标准 Shimeji-ee 结构

legacy.zip/
├── shimeji-ee.jar
├── conf/
│   ├── actions.xml
│   └── behaviors.xml
└── img/
    └── <MascotName>/

2. 根目录直接带 XML 和 img/

legacy.zip/
├── actions.xml
├── behaviors.xml
└── img/

或 actions.xml / behaviors.xml 位于 conf/ 下。

3. 外层再包一层子目录

legacy.zip/
└── MyMascot/
    ├── conf/
    └── img/

4. 纯图片包

legacy.zip/
├── shime1.png
├── shime2.png
└── ...

如果资源只提供标准命名的图片序列，程序可以为它补最基础的 XML，让你先导入预览。但这类模板能力通常很有限，更适合快速试图而不是正式发布。

用“制作”页转换旧包

如果你不想让旧 zip 直接进模板库，也可以先用主界面的“制作”页：

1. 选择旧 Shimeji zip，程序先检查内容。
2. 压缩包包含多只桌宠时，勾选要转换的条目。
3. 可以编辑 info.json 元数据。
4. 转换结果写入你选择的输出目录，不会自动导入模板库。

转换完成后，可以把生成的 .mascot 拖进管理器或通过 CLI 导入。

导入后的模板放在哪里

平台	位置
Windows	%LOCALAPPDATA%\NeurolingsCE\mascots\
Linux	~/.local/share/NeurolingsCE/mascots/
macOS	~/Library/Application Support/NeurolingsCE/mascots/

每个已安装模板通常是一个独立的 Name.mascot 文件。程序会把它解压到应用缓存目录读取 XML、图片、音效和 bubble_context.txt，但模板管理和删除针对的是安装目录中的 .mascot 文件。

旧版本留下的 xxx.mascot/ 目录会在启动时尽量迁移为单文件包。

模板至少需要什么

最常见的完整模板至少包含：

• info.json
• actions.xml
• behaviors.xml
• img/
• 至少一张可用的 shime*.png

包校验会比较严格：缺少必要 XML、预览图或图片检查不通过时，导入或加载会失败。如果你在制作模板，请直接阅读 资源包制作指南。

导入成功后你应该看到什么

导入成功后，一般会出现这些现象：

• 进度或结果提示结束
• 模板列表刷新
• 新模板出现在管理器中
• 右侧详情面板显示名称、版本、作者和描述
• 你可以立即召唤它

如果压缩包转换成功，但模板没有出现在列表中，通常不是“复制失败”，而是“模板格式或 XML 通过不了运行时加载”。

最常见的失败原因

.mascot 包缺少 info.json

.mascot 包必须在根目录包含 info.json，并且 name 必须是非空字符串。version、description、author 可以为空或缺省。

资源包结构不符合识别规则

优先检查：

• 有没有 actions.xml / behaviors.xml
• 有没有 img/
• 目录层级是不是多包了一层甚至多层

XML 语法错误

常见情况：

• 编码不正确
• 特殊字符未转义
• 行为名和动作名对不上

图片检查不通过

0.4.0 起包验证会检查图片有效性；图片缺失、路径对不上或文件不可用都会导致失败。

纯图片包不完整

如果你依赖自动补全的基础模板，图片序列不完整时很容易失败。

排查顺序建议

1. 先确认 .mascot 根目录是否有有效的 info.json。
2. 再确认包里是否真的有 XML 和图片目录。
3. 再确认导入后本机模板目录里是否生成了 Name.mascot 文件。
4. 如果文件已经存在但列表里没有，优先怀疑 XML、图片路径或 info.json.name 问题。
5. 如果你是开发者，继续看运行时日志与 ManagerImportWorkflow、MascotPackage 相关代码。

和 CLI 的关系

当前 CLI 主要负责模板管理与运行时控制。

• NeurolingsCE-cli --mascot list
• NeurolingsCE-cli --mascot add PACKAGE_OR_ZIP
• NeurolingsCE-cli --mascot remove MASCOT

CLI 的 --mascot add 接受 .mascot 或兼容 ZIP 文件；模板文件夹导入目前只支持 GUI 拖放。具体命令格式见 HTTP API 与 CLI。

下一步阅读

• 快速开始
• 资源包制作指南
• HTTP API 与 CLI