Repository navigation
Animation Configuration
aurora edited this page Mar 16, 2026
·
5 revisions
根键为 animation:，每个子键为一个动画定义名称，在 indicator/*.yml 中通过 animation 字段引用。
type |
说明 |
|---|---|
keyframe |
关键帧动画（语法糖或原生 NMS 参数） |
equation |
方程式驱动动画（gloomlib-math 表达式） |
preset |
预设引用（复用 presets/ 中的定义） |
指定动画的运动坐标系，适用于 keyframe 和 equation 类型。
| 值 | 说明 |
|---|---|
world |
默认 — 世界坐标系，位移方向固定于世界 X/Y/Z 轴 |
view |
视角坐标系 — 位移方向相对于造成伤害的实体的面朝方向（+X=右方，+Z=前方） |
space: view 别名：local、relative
"攻击者"指触发此次伤害事件的实体（玩家、怪物等），坐标轴以其当前面朝方向为前方（+Z）、右手边为 +X。如果攻击者是玩家，则以该玩家击中目标时的朝向为准。
使用视角坐标后，动画的水平运动会跟随攻击者的面朝方向旋转。例如 move: { right: 0.3 } 在 space: view 下始终偏向攻击者的右手边，而非世界的固定方向。
animation:
directional_hit:
type: keyframe
space: view # 相对攻击者朝向
settings:
billboard: center
timeline:
- time: 0
size: 1.0
- duration: 20
move: { right: 0.3, up: 0.5 } # 向攻击者右方偏移
opacity: 0%提示：
space写在与type同级的位置，不在settings内。
所有动画类型均可配置 settings 块：
| 字段 | 类型 | 默认值 | 说明 |
|---|---|---|---|
billboard |
Enum | CENTER |
面向约束 |
see-through |
boolean | false |
穿透渲染 |
text-shadow |
boolean | false |
文字阴影 |
background |
String | "transparent" |
ARGB 颜色（"#AARRGGBB" 或 "transparent"） |
view-range |
float | 1.0 |
可见距离倍率 |
teleport-duration |
int | 0 |
插值 tick 数 |
brightness |
int | -1 |
亮度覆盖 |
shadow-radius |
float | 0 |
阴影半径 |
shadow-strength |
float | 1.0 |
阴影强度 |
glow-color |
int | 0 |
发光颜色 |
line-width |
int | 200 |
行宽（像素） |
offset |
Object | {x:0, y:0, z:0} |
每实例随机偏移 |
x/y/z 支持两种写法：
-
数字：
x: 0.5— 固定偏移 -
字符串：
x: "r * 0.6 - 0.3"— gloomlib-math 表达式（变量r∈ [0, 1)）
使用 timeline 定义关键帧序列。首帧必须用 time:，后续帧用 duration:。
| 字段 | 格式 | 说明 |
|---|---|---|
move |
{up, down, right, left, forward, backward} |
相对位移 |
size |
数字 或 {width, height}
|
缩放（统一或非均匀） |
tilt |
{left, right} |
Z 轴旋转角度 |
spin |
{left, right} |
Y 轴旋转角度 |
opacity |
"N%" 或 0-127
|
文本透明度 |
所有语法糖字段的数值位置均支持 delta 修饰符——通过引用上一帧同属性的变化量来自动实现加速/减速效果，无需手动计算每段数值。
| 格式 | 含义 | 示例 |
|---|---|---|
0.3 |
绝对值（现有行为不变） | up: 0.3 |
"+N" |
增量 = 上一帧增量 + N | up: "+0.05" |
"-N" |
增量 = 上一帧增量 − N | up: "-0.05" |
"+N%" |
增量 = 上一帧增量 × (1 + N%) |
up: "+50%" — 比上次快 50% |
"-N%" |
增量 = 上一帧增量 × (1 − N%) |
up: "-40%" — 比上次慢 40% |
注意：Delta 修饰符必须用引号包裹（YAML 字符串），不加引号的
+0.1会被解析为数字0.1。
-
move的所有方向键：up/down/left/right/forward/backward -
tilt的left/right -
spin的left/right -
size（统一缩放或width/height分量） -
opacity（有+/-前缀 = delta 修饰符；无前缀 = 绝对值）
timeline:
- time: 0
size: 1.0
opacity: 100%
- duration: 5
move: { up: 0.3 } # 基准速度
- duration: 5
move: { up: "-40%" } # 慢 40% → 0.18
- duration: 5
move: { up: "-40%" } # → 0.108
- duration: 5
move: { up: "-40%" } # → 0.065
- duration: 10
move: { up: "-40%" } # → 0.039
opacity: 0% - duration: 5
move: { up: 0.4, right: 0.1 }
tilt: { right: 5 }
- duration: 5
move: { up: "-30%", right: "+20%" } # 上浮减速, 右移加速
tilt: { right: "-50%" } # 倾斜减速
- duration: 5
move: { up: "-30%", right: "+20%" }
tilt: { right: "-50%" }
opacity: 0%| 字段 | 格式 | 说明 |
|---|---|---|
translation |
[x, y, z] |
绝对位置 |
scale |
[x, y, z] |
缩放向量 |
left_rotation |
[x,y,z,w] 或 [ex,ey,ez]
|
左旋转（四元数或欧拉角） |
right_rotation |
[x,y,z,w] 或 [ex,ey,ez]
|
右旋转（四元数或欧拉角） |
text_opacity |
0-127 |
文本不透明度 |
animation:
critical_hit:
type: keyframe
settings:
billboard: center
background: "transparent"
offset:
x: "r * 0.6 - 0.3"
y: "r * 0.4"
z: "r * 0.6 - 0.3"
timeline:
- time: 0
size: 1.0
opacity: 100%
- duration: 5
size: 1.5
move: { up: 0.15 }
- duration: 15
size: 1.0
move: { up: 0.4 }
- duration: 15
move: { up: 0.3 }
opacity: 0%使用 gloomlib-math 表达式驱动动画，可实现螺旋、波浪等复杂运动轨迹。
详细的表达式语法参考 → 数学表达式
| 字段 | 类型 | 说明 |
|---|---|---|
duration |
int/String | 持续 tick 数（支持表达式） |
sample_interval |
int | 采样间隔（tick） |
math.position |
{x, y, z} |
位置表达式（变量 t=tick, r=random） |
math.scale |
{x, y, z} |
缩放表达式 |
math.rotation |
{x, y, z} |
欧拉角旋转表达式（度） |
math.opacity |
String | 不透明度表达式（0-127） |
animation:
spiral_rise:
type: equation
settings: { billboard: center }
duration: 50
sample_interval: 2
math:
position:
x: "sin(t * 0.3) * 0.6"
y: "t * 0.05"
z: "cos(t * 0.3) * 0.6"
opacity: "127 - t * 2.5"复用 presets/ 中已定义的动画或模板，可选覆盖显示设置和模板参数。
| 字段 | 类型 | 说明 |
|---|---|---|
id |
String | 必填，指向已加载的动画/预设/模板名称 |
settings |
Object | 可选，覆盖引用动画的显示设置 |
params |
Object | 可选，覆盖模板的默认参数（仅在引用模板时使用，详见下方 模板参数化 ） |
animation:
my_anim:
type: preset
id: float_fade根键为 preset:，优先于 animation: 加载。预设格式与普通动画定义一致，可被 type: preset 引用。
preset:
float_fade:
type: keyframe
settings: { billboard: center }
timeline:
- time: 0
size: 1.0
opacity: 100%
- duration: 30
move: { up: 0.7 }
opacity: 0%模板是一种带有可配置参数的预设。通过 $参数名 占位符，可以把一套动画定义做成"模板"，在多个地方以不同参数复用，避免大量复制粘贴。
在预设文件（presets/*.yml）中，给普通预设添加 params 块即可将其声明为模板：
preset:
float_template:
type: keyframe
params: # ← 声明参数及默认值
peak_size: 1.5
float_height: 0.5
fade_ticks: 15
spread: 0.5
settings:
billboard: center
offset:
x: "r * $spread - $spread / 2" # settings 中同样可用 $参数
y: "r * 0.3"
z: "r * $spread - $spread / 2"
timeline:
- time: 0
size: 1.0
opacity: 100%
- duration: 5
size: $peak_size # 完整值 → 保持数字类型
move: { up: $float_height }
- duration: $fade_ticks
move: { up: 0.4 }
opacity: 0%| 写法 | 示例 | 说明 |
|---|---|---|
| 完整值 | size: $peak_size |
整个值被替换，保持参数原始类型（数字、字符串等） |
| 内嵌插值 | x: "sin(t * $speed)" |
$speed 被替换为文本，结果仍为字符串 |
- 参数名格式：以字母或下划线开头，后跟字母、数字、下划线（
$peak_size、$dur） - 每个参数在
params中必须声明默认值 - 未被覆盖的参数自动使用默认值
在动画文件（animations/*.yml）或同一预设文件中，通过 type: preset 引用模板，并用 params 覆盖需要修改的参数：
animation:
strong_hit:
type: preset
id: float_template # 引用上方模板
params: # 覆盖部分参数
peak_size: 2.0
fade_ticks: 18
spread: 0.8
settings: # 还可以额外覆盖显示设置
view-range: 32
light_hit:
type: preset
id: float_template # 同一模板，不同参数
params:
peak_size: 1.0
fade_ticks: 10上方
strong_hit展开后等价于一个手写的keyframe动画——$peak_size变成2.0，$fade_ticks变成18，$spread变成0.8，而$float_height使用默认值0.5。
模板同样适用于 equation 类型：
preset:
spiral_template:
type: equation
params:
radius: 0.5
speed: 0.3
height_rate: 0.05
dur: 50
duration: $dur
sample_interval: 2
math:
position:
x: "sin(t * $speed) * $radius"
y: "t * $height_rate"
z: "cos(t * $speed) * $radius"
opacity: "127 - t * 2.5"animation:
fast_spiral:
type: preset
id: spiral_template
params:
speed: 0.5 # 加快旋转
radius: 0.8 # 加大半径模板可以引用另一个模板，支持一层嵌套：
preset:
base_float:
type: keyframe
params:
height: 0.5
timeline:
- time: 0
size: 1.0
- duration: 15
move: { up: $height }
opacity: 0%
crit_float:
type: preset
id: base_float # 引用另一模板
params:
height: 0.8 # 覆盖参数
settings:
text-shadow: true注意：嵌套深度最多一层，即 A 可以引用模板 B，但 B 不能再引用另一个模板。