Skip to content

Mascot Packs

Jump to bottom
qingchenyouforcc edited this page Feb 26, 2026 · 5 revisions

NeurolingsCE 看板娘资源包制作指南 / Mascot Pack Guide

本指南介绍了 NeurolingsCE 的看板娘（看板娘/Shimeji）资源包格式，帮助用户创建属于自己的自定义看板娘。

目录

  1. 概述 / Overview
  2. 资源包目录结构 / Directory Structure
  3. 精灵图规格 / Sprite Specifications
  4. 精灵图功能映射表 / Sprite Function Map
  5. actions.xml 详解 / Actions XML Reference
  6. behaviors.xml 详解 / Behaviors XML Reference
  7. 表达式语法 / Expression Syntax
  8. 完整示例 / Complete Examples
  9. NeurolingsCE 特定说明 / NeurolingsCE Specifics
  10. 从零开始制作看板娘 / Step-by-Step Guide
  11. 常见问题 / Troubleshooting FAQ
  12. 参考资源 / References

1. 概述 / Overview

看板娘资源包（Mascot Resource Pack）是 NeurolingsCE 用于展示和模拟桌面宠物的数据集合。NeurolingsCE 完全兼容传统的 Shimeji-ee 格式。一个完整的资源包由两个核心 XML 配置文件（actions.xml 和 behaviors.xml）以及一系列精灵图（Sprite Images）组成。

2. 资源包目录结构 / Directory Structure

NeurolingsCE 的资源包采用以下标准结构。文件夹名必须以 .mascot 结尾，这是程序识别资源包的关键标志。

YourMascotName.mascot/       ← 文件夹名必须以 .mascot 结尾
├── actions.xml              ← 动作定义文件
├── behaviors.xml            ← 行为逻辑文件
├── img/                     ← 精灵图文件夹
│   ├── shime1.png           ← 站立姿势（预览图）
│   ├── shime2.png
│   ├── ...
│   └── shime46.png
└── sound/                   ← (可选) 音效文件夹
    └── *.wav

关键点说明

  • 看板娘的名称取自文件夹名（去除 .mascot 后缀）。
  • 资源包存储路径如下：
    • Windows: %LOCALAPPDATA%\NeurolingsCE\mascots\
    • Linux: ~/.local/share/NeurolingsCE/mascots/
    • macOS: ~/Library/Application Support/NeurolingsCE/mascots/
  • 支持通过拖放 .zip 压缩包到应用程序窗口来直接导入资源包。

3. 精灵图规格 / Sprite Specifications

精灵图需要符合以下技术规格：

  • 格式：带有 alpha 透明通道的 PNG。
  • 尺寸：标准尺寸为 128 x 128 像素。
  • 命名：精灵图必须命名为 shime1.png 到 shime46.png。
  • shime1.png 是必须存在的，它被用作看板娘在菜单中的预览图和默认缩略图。

4. 精灵图功能映射表 / Sprite Function Map

下表详细说明了 46 张精灵图在默认配置中的功能和使用场景。

编号 文件名 功能 / Function 使用场景
1 shime1.png 站立 / Standing (默认姿势) Stand, Walk, Run, Dash 等地面动画的基础帧
2 shime2.png 行走帧 1 / Walk frame 1 Walk, Run, Dash 动画序列
3 shime3.png 行走帧 2 / Walk frame 2 Walk, Run, Dash 动画序列
4 shime4.png 下落 / Falling Falling 动作
5 shime5.png 被拖拽（左倾斜）/ Dragged left-lean Pinched, Resisting 动作
6 shime6.png 被拖拽（右倾斜）/ Dragged right-lean Pinched, Resisting 动作
7 shime7.png 被拖拽（左倾斜较大）/ Dragged left-lean more Pinched 动作 (偏移 30)
8 shime8.png 被拖拽（右倾斜较大）/ Dragged right-lean more Pinched 动作 (偏移 50)
9 shime9.png 被拖拽（大幅左倾）/ Dragged extreme left Pinched 动作 (偏移 > 50), PullUpShimeji2
10 shime10.png 被拖拽（大幅右倾）/ Dragged extreme right Pinched 动作 (偏移 >= 30)
11 shime11.png 坐下 / Sitting Sit, SitAndLookAtMouse, SitAndSpinHead 终帧
12 shime12.png 攀墙帧 1 / Wall climbing frame 1 ClimbWall 动画
13 shime13.png 抓墙 / Grab wall GrabWall, ClimbWall 动画
14 shime14.png 攀墙帧 2 / Wall climbing frame 2 ClimbWall 动画
15 shime15.png 转头帧 1 / Head spin frame 1 SitAndSpinHeadAction
16 shime16.png 转头帧 2 / Head spin frame 2 SitAndSpinHeadAction
17 shime17.png 转头帧 3 / Head spin frame 3 SitAndSpinHeadAction
18 shime18.png 弹跳帧 1 / Bounce frame 1 Bouncing, Tripping
19 shime19.png 弹跳帧 2 / Bounce frame 2 Bouncing, Tripping
20 shime20.png 爬行准备 / Creep start Creep, Tripping
21 shime21.png 趴下 / Sprawl / Laying Sprawl, Creep
22 shime22.png 跳跃 / Jumping Jumping 动作
23 shime23.png 抓天花板 / Grab ceiling GrabCeiling, ClimbCeiling
24 shime24.png 天花板攀爬帧 1 / Ceiling climb frame 1 ClimbCeiling 动画
25 shime25.png 天花板攀爬帧 2 / Ceiling climb frame 2 ClimbCeiling 动画
26 shime26.png 坐下仰望 / Sitting look up SitAndLookUp, SitAndLookAtMouse, SitAndSpinHead
27 shime27.png 转头帧 4 / Head spin frame 4 SitAndSpinHeadAction
28 shime28.png 转头帧 5 / Head spin frame 5 SitAndSpinHeadAction
29 shime29.png 转头帧 6 / Head spin frame 6 SitAndSpinHeadAction
30 shime30.png 坐下抬腿 / Sitting legs up SitWithLegsUp
31 shime31.png 坐下放腿 / Sitting legs down SitWithLegsDown, SitAndDangleLegs
32 shime32.png 荡腿帧 1 / Dangle legs frame 1 SitAndDangleLegs
33 shime33.png 荡腿帧 2 / Dangle legs frame 2 SitAndDangleLegs
34 shime34.png 搬窗口行走帧 1 / Walk with IE frame 1 WalkWithIe, RunWithIe
35 shime35.png 搬窗口行走帧 2 / Walk with IE frame 2 WalkWithIe
36 shime36.png 搬窗口站立 / Standing with IE FallWithIe, WalkWithIe, RunWithIe
37 shime37.png 扔窗口 / Throw IE ThrowIe 动作
38 shime38.png 拉起同伴帧 1 / Pull up shimeji frame 1 PullUpShimeji1 (Breed)
39 shime39.png 拉起同伴帧 2 / Pull up shimeji frame 2 PullUpShimeji1
40 shime40.png 拉起同伴帧 3 / Pull up shimeji frame 3 PullUpShimeji1
41 shime41.png 拉起同伴帧 4 / Pull up shimeji frame 4 PullUpShimeji1
42 shime42.png 分裂帧 1 / Split frame 1 Divide1 (Breed)
43 shime43.png 分裂帧 2 / Split frame 2 Divide1
44 shime44.png 分裂帧 3 / Split frame 3 Divide1
45 shime45.png 分裂帧 4 / Split frame 4 Divide1
46 shime46.png 分裂帧 5 / Split frame 5 Divide1

5. actions.xml 详解 / Actions XML Reference

actions.xml 是动作定义文件，它决定了看板娘可以执行哪些具体动作。

5.1 文件结构

基本的 XML 骨架结构如下：

<?xml version="1.0" encoding="UTF-8" ?>
<Mascot xmlns="http://www.group-finity.com/Mascot" ...>
    <ActionList>
        <!-- 基础原子动作定义 (Atomic Actions) -->
    </ActionList>
    <ActionList>
        <!-- 复合行为动作序列 (Composite Behavior Actions) -->
    </ActionList>
</Mascot>

注意：该文件包含两个 <ActionList> 模块。第一个用于定义基础原子动作，第二个用于定义复杂的行为序列。

5.2 必需的内置动作 / Required Embedded Actions

以下动作是引擎运行所必需的内置实现：

<Action Name="Look" Type="Embedded" Class="com.group_finity.mascot.action.Look" />
<Action Name="Offset" Type="Embedded" Class="com.group_finity.mascot.action.Offset" />

5.3 必需的行为动作 / Required Behavior Actions

为了保证看板娘能正常工作，必须定义以下 4 个核心动作：

  • ChaseMouse：追逐鼠标。
  • Fall：自由落体。
  • Dragged：被鼠标拖拽。
  • Thrown：被鼠标抛出。

5.4 Action 类型 / Action Types

Type 中文 说明
Stay 静止 看板娘保持在原位，播放原地动画（如站立、坐下）。
Move 移动 看板娘以一定速度向目标点移动。
Animate 动画 仅播放动画，不涉及物理位移或逻辑。
Sequence 序列 按顺序串联多个动作。
Select 选择 根据条件从多个子动作中选择一个执行。
Embedded 内置 由引擎底层实现的特定功能动作。

5.5 Embedded Class 一览 / Embedded Classes

Class 功能
com.group_finity.mascot.action.Look 改变看板娘的朝向。
com.group_finity.mascot.action.Offset 改变看板娘的坐标偏移。
com.group_finity.mascot.action.Fall 物理模拟下落（包含重力、空气阻力）。
com.group_finity.mascot.action.Jump 跳跃至指定的目标点。
com.group_finity.mascot.action.Dragged 响应鼠标拖拽行为。
com.group_finity.mascot.action.Regist 模拟被拖拽时的挣扎表现。
com.group_finity.mascot.action.Breed 产生新的看板娘实例（分裂或繁殖）。
com.group_finity.mascot.action.FallWithIE 与窗口（IE）共同执行下落动作。
com.group_finity.mascot.action.WalkWithIE 搬运着窗口进行移动。
com.group_finity.mascot.action.ThrowIE 执行扔出窗口的操作。

5.6 Action 属性 / Action Attributes

  • Name：动作名称，供行为逻辑引用。
  • Type：动作类型。
  • BorderType：允许执行动作的表面类型。包括 Floor（地面）、Wall（墙壁）、Ceiling（天花板）。
  • Loop：是否循环执行（true 或 false）。
  • Class：针对 Embedded 类型的具体实现类。
  • Condition：触发该动作的条件表达式。
  • 物理属性（用于物理动作）：InitialVX（初始水平速度）、InitialVY（初始垂直速度）、Gravity（重力系数）、RegistanceX（水平阻力）、RegistanceY（垂直阻力）、VelocityParam（速度参数）。
  • 窗口属性（用于窗口交互）：IeOffsetX、IeOffsetY。
  • 繁殖属性（用于 Breed 动作）：BornX、BornY、BornBehavior。

5.7 Pose 元素 / Pose Element

用于定义动画的每一帧：

<Pose Image="/shime1.png" ImageAnchor="64,128" Velocity="0,0" Duration="250" />
属性 说明
Image 精灵图文件名，路径必须以 / 开头。
ImageAnchor 锚点坐标 "X,Y"。这是精灵图在屏幕上的定位基准点。
Velocity 速度 "VX,VY"。定义每帧移动的像素数。
Duration 持续帧数。引擎固定为 25 FPS，即 25 帧约为 1 秒。

关于 ImageAnchor 的详细说明：

  • "64,128"：水平居中、底部对齐。常用于地面动作。
  • "64,48"：水平居中、顶部偏下。常用于天花板动作。
  • "64,112"：水平居中、位置稍偏上。常用于坐下荡腿等姿势。
  • "96,128"：偏向右侧、底部对齐。常用于拉起同伴等宽幅动画。

5.8 Animation 元素与条件 / Animation with Conditions

一个 Action 可以包含多个 <Animation> 块，通过 Condition 属性来控制。引擎会执行第一个匹配条件的块：

<Action Name="SitAndLookAtMouse" Type="Stay" BorderType="Floor">
    <Animation Condition="#{mascot.environment.cursor.y &lt; mascot.environment.screen.height/2}">
        <Pose Image="/shime26.png" ... />  <!-- 鼠标在屏幕上半部时抬头 -->
    </Animation>
    <Animation>
        <Pose Image="/shime11.png" ... />  <!-- 默认情况下低头 -->
    </Animation>
</Action>

5.9 ActionReference 元素 / Action References

用于在 Sequence 或 Select 类型的动作中引用其他动作：

<ActionReference Name="Walk" TargetX="${expression}" />
<ActionReference Name="Stand" Duration="${500+Math.random()*1000}" />
<ActionReference Name="Falling" InitialVX="${mascot.environment.cursor.dx}" />

关键属性包括：Name、TargetX、TargetY、Duration、InitialVX、InitialVY、Condition、LookRight。

6. behaviors.xml 详解 / Behaviors XML Reference

behaviors.xml 是行为逻辑文件，它定义了动作在何时发生，类似于看板娘的 AI 决策树。

6.1 文件结构

<?xml version="1.0" encoding="UTF-8" ?>
<Mascot xmlns="http://www.group-finity.com/Mascot" ...>
    <BehaviorList>
        <!-- 各种行为 Behavior 的定义 -->
    </BehaviorList>
</Mascot>

6.2 必需的行为 / Required Behaviors

以下 4 个行为必须定义，且通常设置 Frequency="0" 并在菜单中隐藏：

  • ChaseMouse
  • Fall
  • Dragged
  • Thrown

6.3 Behavior 属性

属性 说明
Name 行为名称。必须与 actions.xml 中的 Action Name 严格对应。
Frequency 相对概率权重。数值越大，被随机选中的几率越高。0 表示不主动随机触发。
Hidden true 表示该行为不会出现在右键菜单中。
Condition 该行为触发的额外条件表达式。

6.4 Condition 元素 / Conditions

行为可以被包装在 <Condition> 块中，根据环境状态进行分组：

<Condition Condition="#{mascot.environment.floor.isOn(mascot.anchor)}">
    <Behavior Name="StandUp" Frequency="200" Hidden="true" />
    <Behavior Name="SitDown" Frequency="200" />
</Condition>

内置的行为环境上下文包括：

  • 在地面上（On the Floor）。
  • 在墙壁上（On the Wall）。
  • 在天花板上（On the Ceiling）。
  • 在工作区地面上（On Work Area Floor）。
  • 面向工作区墙壁（On Work Area Facing Wall）。
  • 在窗口顶部（On Top of IE）。
  • 在窗口侧面（On IE's Side）。
  • 在窗口底部（On the Bottom of IE）。
  • 窗口可见时（IE Is Visible）。

6.5 NextBehavior / 后续行为

定义当前动作结束后可能衔接的下一个行为：

<Behavior Name="SitDown" Frequency="200">
    <NextBehavior Add="true">
        <BehaviorReference Name="SitWhileDanglingLegs" Frequency="100" />
        <BehaviorReference Name="LieDown" Frequency="100" />
    </NextBehavior>
</Behavior>
  • Add="false"：替换当前的行为队列。
  • Add="true"：将新行为追加到当前队列末尾。
  • BehaviorReference 会基于 Frequency 的权重进行随机选择。

6.6 行为选择机制 / Behavior Selection

引擎每隔一段时间会进行一次行为选择，逻辑如下：

  1. 评估所有的 <Condition> 块，筛选出当前符合环境条件的块。
  2. 在符合条件的块中，找出所有 Frequency > 0 的行为作为候选。
  3. 根据相对权重随机选取一个行为。
  4. 执行与该行为同名的 Action。
  5. 动作执行完毕后，根据 NextBehavior 链条决定后续走向。

7. 表达式语法 / Expression Syntax

表达式有两种前缀类型：

  • #{ ... }：条件表达式，返回布尔值（true/false）。
  • ${ ... }：值表达式，返回数值或字符串。

7.1 mascot 对象模型 / Mascot Object Model

  • mascot.anchor.x / anchor.y：看板娘当前的坐标位置。
  • mascot.lookRight：看板娘当前是否面向右侧。
  • mascot.totalCount：当前桌面上的看板娘总数。
  • mascot.environment：环境对象。
    • cursor.x / cursor.y：鼠标光标位置。
    • cursor.dx / cursor.dy：鼠标移动速度。
    • screen.width / height：屏幕物理尺寸。
    • floor.isOn(point)：判断点是否在地面边界上。
    • ceiling.isOn(point)：判断点是否在天花板边界上。
    • workArea：工作区对象（包含 left, right, top, bottom 等属性）。
    • activeIE：当前活动的交互窗口（包含 visible, left, top 等属性，以及各类 isOn 方法）。

7.2 可用函数 / Available Functions

  • Math.random()：生成 0 到 1 之间的随机数。
  • Math.abs(x)：计算绝对值。
  • Math.min(a,b) / Math.max(a,b)：取最小值或最大值。
  • 标准算术运算：+, -, *, /。
  • 比较运算：<, >, <=, >=, ==。
  • 逻辑运算：&&, ||, !。
  • 三元运算：condition ? valueA : valueB。

7.3 XML 转义 / XML Escaping

在 XML 属性中使用特殊符号时必须进行转义：

  • < 替换为 &lt;
  • > 替换为 &gt;
  • & 替换为 &amp;
  • " 替换为 &quot;

8. 完整示例 / Complete Examples

8.1 最简单的自定义动作 / Simplest Custom Action

如果你想增加一个简单的挥手动作，可以定义一个 Stay 类型的动作并引用一张新图：

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

8.2 动画速度与 Duration / Animation Speed

Duration 的单位是 Tick（节拍）。由于引擎固定运行在 25 FPS：

  • Duration="1"：耗时 1/25 秒（40 毫秒），速度极快。
  • Duration="25"：耗时 1 秒。
  • Duration="250"：耗时 10 秒。常用于站立或坐下等静态姿势。

8.3 速度与方向 / Velocity and Direction

  • 负值的 VX 表示向左移动。
  • 看板娘默认面向左侧。如果看板娘面向右侧，引擎会自动水平镜像图片。
  • 移动速度参考：行走 VX="-2"，奔跑 VX="-4"，冲刺 VX="-8"。

9. NeurolingsCE 特定说明 / NeurolingsCE Specifics

  • 资源文件夹后缀：必须以 .mascot 结尾。
  • 导入方式：支持直接将 .zip 拖入窗口，或手动拷贝到资源目录。
  • 运行引擎：使用 libshijima 引擎。这是 Shimeji-ee 的 C++ 高性能重构版本。
  • 帧率限制：固定为 25 FPS，不支持动态修改。
  • 音效支持：音效功能依赖于编译时的 SHIJIMA_USE_QTMULTIMEDIA 标志。
  • 兼容性：导入工具支持标准 Shimeji-ee 布局、无 XML 的纯图片布局以及带子目录的布局。
  • 验证机制：程序会在加载时校验 XML 格式。如果 XML 语法错误，会在日志中报错。

10. 从零开始制作看板娘 / Step-by-Step Guide

  1. 准备精灵图：绘制 46 张 128x128 像素、背景透明的 PNG 图片。
  2. 复制模板：将默认资源包中的 actions.xml 和 behaviors.xml 拷贝作为起点。
  3. 创建文件夹：建立以 .mascot 结尾的文件夹，并将 img/ 文件夹放入其中。
  4. 修改 XML：如果你的精灵图文件名不标准，需要更新 XML 中的引用路径。
  5. 调整行为概率：修改 behaviors.xml 中的 Frequency 值来调整看板娘的各种行为出现频率。
  6. 测试导入：将整个文件夹压缩为 .zip 并拖入 NeurolingsCE 窗口。
  7. 调试优化：根据实际运行效果调整 ImageAnchor 锚点和动画 Duration。

11. 常见问题 / Troubleshooting FAQ

  • 看板娘不显示：请确认 shime1.png 存在，XML 语法正确，且文件夹以 .mascot 结尾。
  • 动作不触发：确认行为的 Frequency 大于 0，且 behaviors.xml 中的行为名称与 actions.xml 中的动作名称一致。
  • 图片位置偏移或错位：检查 ImageAnchor 的数值是否统一。对于地面动作，锚点通常在图片的底部中心。
  • 导入失败：确认压缩包内部结构。XML 文件和 img 目录应该位于压缩包根目录或标准的子目录结构中。
  • 表达式失效或报错：检查是否遗漏了转义字符，例如在属性中使用 < 而不是 &lt;。

12. 参考资源 / References

相关页面 / Related Pages

NeurolingsCE Wiki

用户入口

资源包与模板

开发者入口

Clone this wiki locally