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

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

把 .mascot 或兼容的 .zip 资源包直接拖到管理器窗口。

这是最稳妥的方式,因为运行时会同时处理:

• .mascot 包验证
• 传统 ZIP 结构识别
• 必要时转换为 .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。

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

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

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

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

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

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

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

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

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

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

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

如果你在制作模板,请直接阅读 资源包制作指南。

导入成功后,一般会出现这些现象:

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

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

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

优先检查:

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

常见情况:

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

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

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

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

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

也就是说,导入模板不一定非要通过 GUI 完成。如果你在写自动化,CLI 往往更合适。具体命令格式见 HTTP API 与 CLI。

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