Skip to content

Mascot Packs

Jump to bottom
qingchenyouforcc edited this page Apr 24, 2026 · 5 revisions

资源包制作指南

本页面向两类读者：

  • 第一次给 NeurolingsCE / Shimeji 做模板的人，想知道“从哪里开始、先做什么、怎么一步步测”。
  • 已经做过模板的人，想快速查 actions.xml、behaviors.xml、动作类型、字段和调试顺序。

写法上，这一页会先给新手一条能走通的制作路径，再给一组足够实用的参考信息。你不需要一上来就完全理解所有 XML 细节，也能先做出一个可导入、可召唤、会动的模板。

先看最小可用模板

从 0.3.2 开始，推荐发布格式是 .mascot 单文件包。它本质上是 zip 兼容压缩包，根目录长这样：

YourMascot.mascot
├── info.json
├── bubble_context.txt          # 可选
├── actions.xml
├── behaviors.xml
├── img/
│   ├── shime1.png
│   ├── shime2.png
│   ├── shime3.png
│   └── ...
└── sound/                    # 可选

最关键的五点：

  • 文件名建议以 .mascot 结尾。
  • 必须有 info.json，并且 name 非空。
  • 必须有 actions.xml。
  • 必须有 behaviors.xml。
  • 必须有 img/，并且图片路径与 XML 中的引用一致。

如果你是第一次制作模板，建议不要从空目录开始写，而是先复制一个已知能运行的模板内容，再逐步替换内容，最后压缩成 .mascot。

info.json

info.json 提供模板元数据。NeurolingsCE 会使用 name 作为 GUI 列表显示名、CLI/API 召唤名和同名替换依据。

最小示例：

{
    "name": "MyMascot",
    "version": "1.0",
    "description": "A custom mascot.",
    "author": "YourName"
}

字段说明：

字段 必需 说明
name 是 非空；用户可见名称，也是召唤名
version 否 模板版本，可为空
description 否 模板描述，可为空
author 否 作者信息，可为空

bubble_context.txt

bubble_context.txt 是可选文件，放在包根目录。它是一份 UTF-8 文本，一行一句气泡文本。

当它存在时，点击该模板对应桌宠会优先使用包内气泡文本；不存在时继续使用全局或默认气泡文本。

推荐起步方式：从默认模板改

NeurolingsCE 仓库自带一份默认模板，位于主仓库：

  • src/assets/DefaultMascot/actions.xml
  • src/assets/DefaultMascot/behaviors.xml
  • src/assets/DefaultMascot/img/

最推荐的起步流程：

  1. 复制默认模板整套目录结构。
  2. 增加或修改 info.json，把 name 改成你自己的模板名。
  3. 先只替换图片，不急着改 XML。
  4. 把根目录内容压缩成 zip，并把扩展名改为 .mascot。
  5. 确认导入成功、能召唤、能站立、能走动。
  6. 再逐步修改 actions.xml 和 behaviors.xml。

这样做的好处是，你一开始拿到的是一套“已被 NeurolingsCE 当前运行时验证过”的骨架，而不是自己猜一套格式。

从零开始的推荐流程

如果你确实想从零做，建议按这个顺序：

  1. 准备图片资源。
  2. 建好工作目录、img/ 和 info.json。
  3. 先写最小 actions.xml，至少让角色能站和走。
  4. 再写最小 behaviors.xml，让角色能随机进入这些动作。
  5. 压缩为 .mascot 后导入测试。
  6. 跑通后再补坐姿、攀墙、拖拽、分裂、窗口互动等进阶行为。

不要一开始就试图把完整行为树一次性写完。最容易成功的顺序，是先让这四类基础链路稳定：

  • Stand
  • Walk
  • Fall
  • Dragged

图片与文件命名约定

最常见的约定如下：

  • 图片使用带透明通道的 PNG。
  • 图片文件名通常采用 shime1.png、shime2.png、shime3.png 这一套。
  • shime1.png 通常会被当成默认姿势或预览图，所以最好用一张“站姿正常、辨识度高”的图。

命名为什么重要：

  • XML 里的 <Pose Image="/shime1.png" ... /> 这种写法直接依赖文件名。
  • 即使图片本身没问题，只要文件名和 XML 对不上，动作就会失效。

如果你想用别的命名，不是绝对不行，但你必须同步改 XML 引用。对第一次制作模板的人，不建议这么做。

actions.xml 是什么

可以把 actions.xml 理解成“桌宠能做哪些动作，以及动作如何播放”。

它主要负责：

  • 定义动作名
  • 定义动作类型
  • 定义动画帧序列
  • 定义每帧的图片、锚点、速度和持续时间
  • 在需要时通过条件或组合动作表达更复杂的动作流程

在默认模板里，你可以很直观地看到这一层：

  • Stand 是单帧静止动作
  • Walk、Run、Dash 是不同速度的移动动作
  • Falling 是内置的坠落动作
  • Pinched / Resisting 对应拖拽相关表现

一个最小动作示例：站立

下面是最容易理解的动作之一：

<Action Name="Stand" Type="Stay" BorderType="Floor">
    <Animation>
        <Pose Image="/shime1.png" ImageAnchor="64,128" Velocity="0,0" Duration="250" />
    </Animation>
</Action>

这段可以读成：

  • 动作名叫 Stand
  • 动作类型是 Stay，也就是原地停留
  • 它适用于地面 Floor
  • 这个动作只播放一帧：shime1.png
  • 锚点是 64,128
  • 不移动，速度是 0,0
  • 持续 250 tick

一个最小动作示例：走路

默认模板里的 Walk 本质上是多帧循环播放，并且每帧都带水平移动：

<Action Name="Walk" Type="Move" BorderType="Floor">
    <Animation>
        <Pose Image="/shime1.png" ImageAnchor="64,128" Velocity="-2,0" Duration="6" />
        <Pose Image="/shime2.png" ImageAnchor="64,128" Velocity="-2,0" Duration="6" />
        <Pose Image="/shime1.png" ImageAnchor="64,128" Velocity="-2,0" Duration="6" />
        <Pose Image="/shime3.png" ImageAnchor="64,128" Velocity="-2,0" Duration="6" />
    </Animation>
</Action>

这段说明了三件事：

  • Move 类型动作可以边播动画边移动。
  • Velocity="-2,0" 表示沿水平方向移动。
  • 图片切换和位移是同时发生的，所以“走路像不像走路”，取决于图片序列、锚点和速度是否匹配。

behaviors.xml 是什么

如果说 actions.xml 定义的是“能做什么动作”，那么 behaviors.xml 定义的就是“什么时候做这些动作、做完后接什么”。

它更像 AI 或调度层，主要负责：

  • 哪些行为可以被随机选中
  • 在什么环境下允许选中
  • 行为之间如何接力
  • 哪些行为只作为内部链路使用，不直接暴露

默认模板里，Behavior Name 必须和动作侧对应的可执行行为名匹配。名字如果对不上，行为链就会断。

一个最小行为示例

下面是一个简化版的行为链例子：

<Behavior Name="SitDown" Frequency="200">
    <NextBehavior Add="true">
        <BehaviorReference Name="SitWhileDanglingLegs" Frequency="100" />
        <BehaviorReference Name="LieDown" Frequency="100" />
    </NextBehavior>
</Behavior>

这段的意思是：

  • SitDown 本身是一个可被随机选中的行为
  • 它的出现权重是 200
  • 它执行完后，还会继续接后续行为
  • 后续行为会在 SitWhileDanglingLegs 和 LieDown 之间按权重选择

也就是说，角色不是“执行完一个动作就停住”，而是可以沿着行为链继续往后走。

动作和行为的关系

这两个文件最容易混淆，所以这里单独强调一次：

  • actions.xml：定义动作内容，回答“怎么动”。
  • behaviors.xml：定义触发与调度，回答“什么时候动、接着做什么”。

如果你的模板：

  • 图片都正常
  • 动作 XML 看起来也对
  • 但角色一直不动

那么大概率不是动作层的问题，而是行为层没有把它们调度起来。

默认模板里哪些基础行为不要乱删

默认模板里有一些行为是“基础交互链路”的一部分，不应该被新手随意删掉。最重要的是：

  • ChaseMouse
  • Fall
  • Dragged
  • Thrown

在默认模板里，这些行为被标注为 always required。你可以把它们理解为运行时对“基本互动与物理行为”的最低骨架：

  • Fall：桌宠离开支撑面时的坠落逻辑
  • Dragged：被拖拽时的响应链路
  • Thrown：被抛出后的行为链
  • ChaseMouse：与鼠标相关的一条常见互动链

第一次做模板时，不建议主动删这些基础行为。更稳妥的做法是先保留，再逐步调整它们引用的动作或出现频率。

常见动作类型说明表

类型 含义 典型用途 默认模板例子
Stay 原地停留 站立、坐下、抓墙、抓天花板 Stand、Sit、GrabWall
Move 带位移的动作 走、跑、爬、爬天花板 Walk、Run、ClimbWall
Animate 只播动画，不强调独立移动路径 小范围表现动画 SitAndSpinHeadAction、Bouncing
Sequence 串联多个动作 从一个动作接到另一个动作 StandUp、SitDown、Thrown
Select 从多个分支中选一个 条件分支、随机分支 Fall 内部的分支逻辑
Embedded 引擎内置动作 坠落、跳跃、拖拽、繁殖等底层行为 Falling、Jumping、Pinched

对第一次做模板的人，最实用的经验是：

  • 先掌握 Stay、Move、Sequence
  • Embedded 动作先照着默认模板用，不要急着重构

常见字段速查表

字段 常出现在哪 作用
Name Action、Behavior 名字，必须前后对应
Type Action 动作类型，如 Stay、Move、Sequence
BorderType Action 适用表面，如 Floor、Wall、Ceiling
Image Pose 当前帧图片路径
ImageAnchor Pose 当前帧锚点
Velocity Pose 当前帧位移速度
Duration Pose 或动作引用 持续 tick 数
Frequency Behavior、BehaviorReference 随机权重
Condition Animation、Behavior、Action 条件判断
Hidden Behavior 是否隐藏为内部行为
NextBehavior Behavior 当前行为结束后接什么

数值直觉：Duration、Velocity、锚点怎么理解

Duration

当前运行时按 25 FPS 节奏推进，所以可以粗略地这样理解：

  • Duration=1：约 1/25 秒
  • Duration=5：约 0.2 秒
  • Duration=25：约 1 秒
  • Duration=250：约 10 秒

这也是为什么默认模板中：

  • 静止姿势常用较大 Duration
  • 走路或小动作切换常用较小 Duration

Velocity

Velocity 写的是每帧的位移速度，通常是 x,y。

在默认模板里你会经常看到：

  • -2,0：水平移动
  • 0,-1：向上移动
  • 0,2：向下移动
  • 0,0：只换帧，不位移

对作者最重要的不是死记正负方向，而是“图片姿态、角色朝向、位移方向”三者要匹配。默认模板里的 Walk、Run、Dash 很适合拿来做速度感参考。

ImageAnchor

锚点决定图片贴在角色逻辑位置上的方式。默认模板里的几个典型值很值得记：

锚点 常见用途
64,128 地面站姿、走路、拖拽、坠落
64,112 坐姿、荡腿等位置稍高的动作
64,48 天花板相关动作

如果同一组动作里的锚点乱跳，你通常会看到：

  • 角色位置抖动
  • 不同帧之间上下左右突然错位
  • 明明图片画得没问题，跑起来却“像在抽搐”

一个新手最容易照着做的制作步骤

如果你想要一条尽量不出错的路径，可以直接按下面做：

  1. 复制默认模板。
  2. 保留 actions.xml 和 behaviors.xml 不动。
  3. 先把 img/shime1.png 到常用帧替换成你自己的图片。
  4. 导入测试。
  5. 如果能导入、能站、能走、能拖拽，再开始改动作。
  6. 如果动作改完后角色不再会动，再去检查行为文件。

第一次扩展建议优先改这些内容：

  • Stand
  • Walk
  • Sit
  • Falling

不建议第一次就改这些复杂部分：

  • 分裂 / 繁殖
  • 攀墙与天花板全链路
  • 窗口互动（IE / activeIE）
  • 大量复杂 Condition

常见失败与排错顺序

1. 导入失败时先检查什么

先按这个顺序排查：

  1. .mascot 根目录是否包含有效 info.json。
  2. info.json.name 是否非空。
  3. ZIP 解开后最外层层级是否正确。
  4. actions.xml 和 behaviors.xml 是否存在。
  5. img/ 是否存在，图片命名是否与 XML 匹配。

很多“导入失败”其实不是引擎逻辑问题，而是资源包结构本身不符合导入器的预期。

2. 导入成功但模板不显示

这通常说明文件已经落盘，但运行时加载失败。

优先检查：

  • XML 是否有语法错误
  • 行为名和动作名是否对得上
  • XML 里引用的图片是否真实存在
  • .mascot 包结构是否正确

3. 桌宠只会站着或完全不动

优先看行为层，而不是图片层。

重点检查：

  • Frequency 是否全是 0
  • Condition 是否总是不成立
  • NextBehavior 是否断链
  • 某些行为是不是只是被引用行为，本来就不会独立随机触发

4. 动作存在，但行为从不触发

重点检查：

  • 这个行为是否被 Hidden="true" 且 Frequency="0"
  • 它是不是设计上只作为内部行为被其他行为引用
  • 当前环境条件是否根本满足不了它的 Condition

5. 动画错位、抖动或“跳帧感很怪”

重点检查：

  • 各帧 ImageAnchor 是否一致
  • 图片尺寸是否差异过大
  • 同组动作的角色落脚点是否画在同一逻辑位置
  • Velocity 是否和画面动作方向匹配

给初学者的推荐调试顺序

不要同时调所有系统。最稳妥的顺序是：

  1. 跑通 Stand
  2. 跑通 Walk
  3. 跑通 Fall
  4. 跑通 Dragged
  5. 再补 Sit
  6. 再补攀墙、天花板
  7. 最后再做窗口互动、分裂繁殖等高级行为

这样做的原因很简单：

  • 前四类问题最好定位
  • 失败时能明确判断是图片、动作还是行为的问题
  • 你会更快得到一份“已经能玩”的模板，而不是一直卡在 XML 大工程里

何时需要回头看默认模板

遇到下面这些情况，最省时间的做法通常不是硬猜，而是回头对照默认模板：

  • 不确定某个动作应该用什么 Type
  • 不确定 Duration 合理范围
  • 不确定某个行为应该写成独立行为还是 NextBehavior
  • 想参考拖拽、跳跃、分裂、攀墙等复杂动作

默认模板不是唯一标准，但它是当前项目里最可靠、最贴近运行时真实行为的参考实现。

和导入文档的关系

这一页讲的是“怎么做模板”，重点是结构、动作、行为和调试。

如果你要看“怎么装模板”和“导入失败时导入器怎么识别 ZIP”，请看：

进一步参考

NeurolingsCE Wiki

用户入口

资源包与模板

开发者入口

Clone this wiki locally