图片进度
自动裁切、分段、缓动和拖尾的完整字段参考
先在图片组中登记 PNG，再在 Layout 元素的 progress 中引用。完整制作步骤见血条和圆周进度。下面使用自带 xerr_ui/player_status 图片组。
需要完整操作流程时，先阅读血条和圆周进度。本页代码未标为完整文件时，均为对应节点中的片段。
文件关系
config.yml
health_full.png
health_empty.png
health_trail.png
tutorial_health.yml
自动裁切示例
progress:
namespace: xerr_ui
basename: player_status
image:
full: health_full
empty: health_empty
fill:
direction: left-to-right
steps: auto
variables:
total: "player max health"
current: "player health"
refresh: 5
transition:
duration: 6
delay: 0
easing: ease-out
trail:
image: health_trail
delay: 8
duration: 12
easing: ease-out顶层字段
| 字段 | 类型 / 省略值 | 说明 | 生效 |
|---|---|---|---|
namespace | 字符串 / 继承 | 图片命名空间 | 打包 |
basename | 字符串 / 继承 | 图片组 | 打包 |
variables | 对象 / 必填 | 当前值和最大值 | 重载 |
list | 图片 ID 列表 / 无 | 旧式整图分段进度 | 打包 |
image | 对象 / 无 | 空图和满图 | 打包 |
fill | 对象 / 无 | 自动裁切设置 | 打包 |
transition | 对象 / 无 | 主进度缓动 | 重载 |
trail | 对象 / 无 | 延迟追赶层，仅自动裁切支持 | 打包 |
refresh | 整数 1～72000 / 继承 | 数值采样间隔，tick | 重载 |
list 和 image 不能同时使用。
variables
| 字段 | 类型 / 省略值 | 说明 |
|---|---|---|
total | Kether / 必填 | 最大值，必须得到大于 0 的有限数字 |
current | Kether / 必填 | 当前值 |
units | 整数 1～1000 / 1 | 旧式重复分段数量；自动裁切必须为 1 |
先计算 total，再计算 current。求值失败时保留上一份有效结果，不当作 0%。
image
| 字段 | 类型 / 省略值 | 说明 |
|---|---|---|
full | 图片 ID / 视模式必填 | 完整进度图片 |
empty | 图片 ID / 可选 | 始终显示的空背景；旧式重复分段时必填 |
full、empty 和拖尾图片应使用相同 PNG 画布及配置高度。
fill
| 字段 | 类型 / 省略值 | 范围 | 说明 |
|---|---|---|---|
direction | 字符串 / left-to-right | 见下表 | 裁切方向 |
steps | 字符串 / auto | auto 或 1～1000 | 进度帧数 |
start-angle | 小数 / 0 | 有限数字 | 圆周起始角度，0° 向上 |
center.x | 小数 / 50 | 0～100 | 图片内部圆心横向百分比 |
center.y | 小数 / 50 | 0～100 | 图片内部圆心纵向百分比，向下增加 |
方向：
left-to-rightright-to-leftbottom-to-toptop-to-bottomclockwisecounter-clockwise
0% 不绘制满图，100% 使用完整原图。
transition
| 字段 | 类型 / 省略值 | 范围 | 说明 |
|---|---|---|---|
duration | 整数 / 0 | 0～72000 tick | 缓动时长；0 表示立即变化 |
delay | 整数 / 0 | 0～72000 tick | 开始缓动前等待 |
easing | 字符串 / linear | linear、ease-in、ease-out、ease-in-out | 速度曲线 |
首次有效值直接显示，不从零播放。
trail
| 字段 | 类型 / 省略值 | 说明 |
|---|---|---|
image | 图片 ID / 必填 | 拖尾图片 |
delay | 整数 / 8 | 开始追赶前等待 tick |
duration | 整数 / 12 | 追赶时长 tick |
easing | 字符串 / ease-out | 速度曲线 |
拖尾要求存在 fill。回血时拖尾与主条同步，不保留错误的受伤残量。
预制图片列表 list
以下仅演示结构，必须先登记各个 bar_* 图片。
list:
- bar_100
- bar_80
- bar_60
- bar_40
- bar_20
- bar_0
variables:
total: "100"
current: "player health"列表按进度选择整张图片，不能与 image 或自动 fill 混用。
重复分段 units
不写 fill 时，可以用 image.full/empty 加 variables.units 重复分段。每张图片就是一个完整分段，不会按数值自动裁切；此模式不支持 trail。
image:
full: health_full_segment
empty: health_empty_segment
variables:
units: 10
total: "player max health"
current: "player health"以上图片 ID 需自行登记。新配置优先使用 fill，不必为每个百分比准备图片。
资源限制
自动裁切仅支持静态 PNG：
- 源图单边不超过 2048 像素。
- 显示高度
1～512GUI 像素。 - 单组
源图宽 × 高 × (步数 + 1)不超过 16,777,216。
超过限制时减小源图或 steps。