画面文件
plugins/CloudUI/screens/ 里的每个 .yml 是一个画面，文件名就是画面 ID（main.yml → main），可以放在子文件夹。打开画面：/cui open main，或按钮动作 open: main。
画布与坐标
- 画布固定 1920 × 1080，左上角是
(0, 0)，x 往右、y 往下增加，单位是画布像素。 - 不论玩家的视窗大小、GUI 缩放，画面都会等比例贴满。
- 图片放在
plugins/CloudUI/images/，画面里写相对路径，例如image: main/backdrop.png。
整体结构
portrait: # 角色立绘（站位、转身、名牌）
enabled: true
camera: # 镜头（打开 / 关闭动画、跟拍或固定）
fov: 70
transition: # 切换画面时的滑入滑出
slide-x: 160
tooltip: # 游标停在按钮上时的说明框（选填）
frame: common/tooltip.png
notice: # 选单打开时的通知横幅（选填）
stay: 50
back-to: main # 从这个画面按「返回」时回到哪里（选填）
list: # 清单画面（选填），见「清单画面」
rows-grid: rows
elements: # 画面上的所有元素
backdrop:
type: image
image: main/backdrop.png
elements 下每个键是元素 ID（同一画面内不可重复），元素的写法见 画面元素，按钮点击与动作见 点击与动作。
portrait：角色
玩家自己的角色站在画面一侧（镜头前的真实实体，别人看不到这个画面）。
portrait:
enabled: true
screen-x: 0.28 # 角色在画面横向的位置（0–1，0.28 = 偏左）
distance: 3.3 # 镜头离角色的距离（方块）
height: 1.2 # 镜头高度（相对脚底）
look-height: 1.0 # 镜头看向角色的高度
orbit: 18.0 # 镜头绕角色的角度
face-camera: 22.0 # 角色朝镜头转的角度
follow-cursor: true # 游标在角色附近时角色跟着转身
daylight: true # 选单打开期间，这位玩家看到的时间是白天（只有自己看 到），夜晚也不会一片黑
stand: # 选填：角色固定站在场景里的某个位置（用 /cui camera <画面> stand 设定）
world: world
x: 100.5
y: 64
z: -20.5
yaw: 90
| 选项 | 默认 | 说明 |
|---|---|---|
enabled | true | false = 这个画面不显示角色 |
screen-x | 0.28 | 角色在画面横向的位置 |
distance / height / look-height | 3.3 / 1.2 / 1.0 | 镜头与角色的相对位置 |
orbit / face-camera | 18 / 22 | 镜头绕角色的角度、角色朝镜头转的角度 |
follow-cursor | true | 角色跟着游标转身 |
daylight | true | 选单打开期间把这位玩家看到的时间调成白天（只影响自己的画面），关闭后恢复 |
stand | 无 | 角色站的固定位置（世界、坐标、朝向） |
nametag：名牌
在角色头顶显示名牌，玩家能看到自己在别人眼中的样子。
portrait:
nametag:
enabled: true
source: auto # auto / unt / lines
lines: ['{player}'] # source 为 lines 时显示的行
title: '' # 预览中的称号
title-placeholders: ['%clt_use%', '%playerTitle_use%']
y-offset: 0.3
scale: 1.0
shadow: true
background: '' # #AARRGGBB，留空 = 无底色
source: auto：装了 UnlimitedNameTags 就沿用它的名牌行，没有就用lines；unt一定用 UnlimitedNameTags；lines一定用lines。title-placeholders里的变量会先换成title，称号插件就能把「预览中的称号」放在原本佩戴称号的位置（云称号的试戴就是这样做的）。默认包含%clt_use%、%clt_use_static%、%clt_use_small%、%clt_use_small_static%、%playerTitle_use%。
camera：镜头
camera:
open-ticks: 28 # 打开时镜头推进的时间（tick）
close-ticks: 18 # 关闭时拉回的时间
switch-ticks: 10 # 切换画面时镜头移动的时间
fov: 70 # 选单中的视野
mode: follow # follow 跟拍角色；fixed 固定位置
position: # mode: fixed 时必填
world: world
x: 100.5
y: 66.2
z: -24.0
yaw: 180
pitch: 10
follow（默认）：镜头依portrait的设定跟拍角色。- 打开选单时视野固定为 70 度（1.21.10、1.21.11、26.x 都一样），不受玩家自己的 FOV 设定影响，角色在每个玩家画面上都在同一个位置、同样大小。
fixed：镜头固定在position。最方便的设法是站到想要的位置、看向想要的方向，输入/cui camera <画面> fixed，自动写进画面文件并重建资源包。
transition：切换画面
transition:
slide-x: 70 # 旧画面滑出 / 新画面滑入的横向距离（画布像素）
slide-y: 0 # 纵向距离
out-ticks: 3 # 旧画面淡出的时间
in-ticks: 6 # 新画面淡入的时间
exit: back # back（默认）/ aside：打开下一个画面时这个画面滑出的方向
family: '' # 同一个 family 的画面互相切换时无缝变换
family 无缝切换：几个画面共用同一套外框（例如同一个插件的几个分页）时，把它们的 family 设成同一个名字。互相切换时不淡出淡入，相同的元素直接变成新 画面的样子，游标也停在原处。
tooltip：说明框
游标停在按钮上时显示的说明框。说明文字来自按钮的 tooltip:，或插件提供的资料，见 画面元素 · button。
tooltip:
frame: common/tooltip.png # 必填：九宫格外框图片
border: 16 # 外框九宫格的边宽
width: 320 # 说明框宽度
padding: 20
font: text
title-size: 24 # 第一行（标题）的字体大小
size: 16 # 其余行的字体大小
line-height: 25
title-height: 40
max-lines: 14 # 最多几行（1–24）
gap: 14 # 与游标的距离
color: '#E2EEF4'
没有写 tooltip: 的画面不显示说明框。
notice：通知横幅
选单打开时，画面顶端滑出的通知横幅。按钮动作 notice:、没有权限 / 花费不足的提示、以及选单打开期间收到的系统讯息，都用这个横幅显示。
notice:
frame: '' # 底图（九宫格），留空用默认样式
border: 14
width: 1100
height: 50
x: 960 # 横幅中心 x
y: 26 # 横幅 y
font: text
size: 22
color: '#F2F5FA'
accent: '#E6C98A' # 前后装饰符号的颜色
prefix: '◆'
suffix: '◆'
stay: 50 # 停留时间（tick）
slide: -14 # 滑入距离
in-ticks: 5
out-ticks: 6
不写 notice: 时使用上面的默认值。
back-to：返回目标
back-to: main
从这个画面按「返回」（back 动作，或 menu.shift-f: back 时的 Shift / F）时，固定回到这个画面，不管中间打开过哪些画面。不写就回到上一个打开的画面。
list：清单画面
有分类标签、分页、选中预览的清单（例如传送选单），只要在画面里写资料，不用写代码。见 清单画面 。
校验与错误
/cui reload 时会检查所有画面，有错误时提示文件与位置，例如：
camera.mode fixed needs camera.position：固定镜头没有写位置。duplicate element id …：元素 ID 重复（格子里的元素会自动编号，见 grid）。elements.xxx.type '…' (image, button, text, item, bar, grid)：元素类型写错。….color must be #RRGGBB：颜色格式错误。