角色模组
动画帧与动作
角色和迷你宠物共用的基础：播放速度、循环与定位。
从图片到动作
一个动作对应一组按序编号的 PNG 帧。act_conf.json 中的 images 填写图片前缀，不包含编号和扩展名。
{
"walk_left": {
"images": "leftwalk",
"act_num": 5,
"need_move": true,
"direction": "left",
"frame_move": 0.5,
"frame_refresh": 0.2
}
}这是动作配置示例：leftwalk_0.png 开始的一组帧循环播放 5 次，同时向左移动。它仍需在角色或迷你宠物的行为配置中被引用，才会在相应情况下播放。
常用参数速查
| 字段 | 含义 | 填写提示 |
|---|---|---|
images |
图片前缀 | 帧从 0 开始连续编号 |
act_num |
整组帧的播放次数 | 循环素材只需保存一轮图片 |
frame_refresh |
每帧的显示时间，单位秒 | 数值越小，播放越快 |
need_move |
是否同时移动 | true 或 false |
direction |
移动方向 | left、right、up、down |
frame_move |
每次移动的距离 | 配合播放速度观察实际效果 |
anchor |
水平与垂直偏移 | [x, y]，向右、向下为正 |
让动作切换时不跳动
为角色设定统一的底部中心，例如两脚之间的点。各组素材尽量让这个点落在画布底边的中点。
如果某个动作需要额外移动，可用 anchor 修正。例如 [0, 36] 表示向下平移 36 像素。请在待机、行走、睡眠等不同动作之间来回切换检查。
定位正确不仅取决于配置。角色的实际大小、画布尺寸和脚底位置也需要保持一致。
与行为配置连接
动作文件负责“如何播放”，行为文件负责“何时播放”。将动作名写入 default、drag、fall 或动作组的 act_list 等对应位置。
角色与迷你宠物共用这些动画基础；迷你宠物的专属联动和字段差异见迷你宠物教程。
同一角色的不同动作尽量使用一致的 frame_refresh，便于在动画管理中组合已有素材。动画默认值为：act_num: 1、need_move: false、direction: null、frame_move: 10、frame_refresh: 0.5、anchor: [0, 0]；images 必须填写。建议显式填写播放速度，先检查实际效果再批量添加动作。
Turn images into an animation
Each animation uses a numbered sequence of PNG frames. Set images in act_conf.json to their prefix, without the number or extension.
{
"walk_left": {
"images": "leftwalk",
"act_num": 5,
"need_move": true,
"direction": "left",
"frame_move": 0.5,
"frame_refresh": 0.2
}
}This animation example loops the sequence starting with leftwalk_0.png five times while moving left. Reference it in the character or mini-pet behavior configuration to play it in the appropriate situation.
Common fields
| Field | Meaning | Notes |
|---|---|---|
images |
Image prefix | Number frames consecutively from 0 |
act_num |
Number of sequence repeats | Store only one cycle of a looping animation |
frame_refresh |
Seconds per frame | Smaller values play faster |
need_move |
Whether to move while playing | true or false |
direction |
Movement direction | left, right, up, down |
frame_move |
Distance per movement step | Test together with playback timing |
anchor |
Horizontal and vertical offset | [x, y]; right and down are positive |
Avoid jumps between animations
Choose a consistent bottom-center reference, such as the point between the feet. Try to place it at the center of the canvas’s bottom edge in each animation.
Use anchor when an animation needs an offset. For example, [0, 36] moves it down 36 pixels. Test transitions between idle, walking, sleeping and other poses.
Good positioning also depends on consistent character size, canvas dimensions and ground references in the artwork.
Connect animations to behavior
The animation file defines how an action plays; the behavior file decides when. Reference animation names in default, drag, fall, an action group’s act_list, or the appropriate field.
These animation fundamentals apply to characters and mini-pets. See the mini-pet tutorial for differences and character interactions.
Use a consistent frame_refresh across a character’s animations where possible, making assets easier to combine in animation management. Defaults are act_num: 1, need_move: false, direction: null, frame_move: 10, frame_refresh: 0.5 and anchor: [0, 0]; images is required. Set playback speed explicitly and check the result before adding many animations.
文档持续完善中。 查看原始开发文档 ↗