画面元素

画面文件的 elements 下，每个键是一个元素。type 决定元素类型（不写 = image）：

type	用途
`image`	图片：背景、卡片底图、装饰、角标
`button`	按钮：可以点，有悬停图、点击动作、说明框
`text`	文字：可以带变量，执行时才决定内容
`item`	物品图标：原版、ItemsAdder、CraftEngine 物品，或插件提供的物品
`bar`	进度条：经验、血量、任务进度
`grid`	格子：同一组元素按行列排好几份（卡片列表、分页清单）

坐标、宽高都是 1920 × 1080 画布的像素。

共同选项

选项	说明
`type`	元素类型，默认 `image`
`x`、`y`	左上角坐标（`text` 依 `align` 决定 x 是左边、中间还是右边）
`enabled`	`false` = 文件里保留，但不出现在画面上（网页编辑器的「隐藏这张卡」就是这个）
`motion`	进场动画：`{x: 160, y: 0, delay: 0}` 从偏移 x / y 的位置滑入，`delay` 是延后的 tick；不写 = 不滑动

logo:
  type: image
  image: main/logo.png
  x: 990
  y: 30
  motion: {x: 0, y: -24}   # 从上方 24 像素滑下来

image：图片

backdrop:
  type: image
  image: main/backdrop.png   # images/ 里的相对路径
  x: 0
  y: 0
  fit: cover                 # 铺满整个画面（背景）
  resolution: 0.25           # 以 1/4 尺寸储存、放大绘制

选项	默认	说明
`image`	—	图片路径（`plugins/CloudUI/images/` 下）
`width`、`height`	原图大小	改变显示大小；写了其中一个就会缩放
`slice`	`0`	九宫格边宽：缩放时四个角与边框不变形，适合框线、面板
`fit`	`canvas`	`cover`：铺满整个画面（背景用）
`behind`	`0`	只有 `fit: cover`：背景放在镜头前几格（0–64）、角色后面，角色与脚下的地面会画在背景前面；`0` = 盖在所有东西上
`resolution`	`1`	以这个比例储存、放大绘制（0.25–1）。大张、柔和的背景图设 `0.25`，资源包小很多。同一画面所有 `fit: cover` 的图要用相同的 `resolution`
`tint`	无	染色，`#RRGGBB` 或变量（例如 `{tab.accent}`）
`state` / `states`	无	依变量切换图片，见状态切换
`timeline` / `timeline-play`	无	关键帧动画，见 timeline
`show`	`always`	`third-person`：只在玩家切到第三人称时显示（例如「按 F5 回到第一人称」提示）
`anchor`	无	`portrait`：跟着角色走（名牌旁的装饰），不论玩家的视野设定都贴在角色身上

button：按钮

mail:
  type: button
  image: main/tile_s.png          # 平常的图
  hover: main/tile_s_hover.png    # 游标停在上面时叠上的图
  x: 1510
  y: 226
  hit: [1510, 226, 164, 111]      # 点击范围 [x, y, 宽, 高]
  click:
    left: ['plugin-command: StarMail sm']
  tooltip:
    - '星月邮箱'
    - '查看信件与领取奖励'
  motion: {x: 160, delay: 0}

选项	说明
`image`	按钮图片（可省略，但 `image` 与 `hit` 至少要有一个）
`hover`	游标停在按钮上时叠上的图片
`hit`	点击范围 `[x, y, 宽, 高]`。最外层按钮是画布的绝对坐标；在 `grid` 的 `cell` 里时是相对格子左上角的坐标。不写就以图片范围为准
`width`、`height`、`slice`	同 image
`click`	各种点击要做的事，见点击与动作
`permission`	点这个按钮需要的权限：没有权限的玩家点了只会听到拒绝音效、看到「没有权限」；箱子选单里直接不显示这个按钮
`tooltip`	游标停住时显示的说明行（第一行是标题），可以带变量；画面要有 `tooltip:` 外框设定。插件也可以直接提供说明行
`state` / `states`	依变量切换按钮图片

文字放在按钮上

按钮本身不写字：把 text 元素放在按钮范围里就好。箱子选单会把按钮范围里最大的文字当成物品名称、其他文字与 tooltip 当成说明。

text：文字

title:
  type: text
  text: '选单'
  font: title
  size: 96
  color: '#E6D3A1'
  x: 1420
  y: 66
  align: center

选项	默认	说明
`text`	—	文字内容，可以带 `{变量}`、`%PlaceholderAPI%` 与 `&` 颜色码（含 `&#RRGGBB`）
`font`	`text`	`text` 或 `title`（大标题字体），见配置文件 · 字体
`size`	`24`	字体大小（像素），会选最接近字体解析度倍数的大小
`color`	`#FFFFFF`	`#RRGGBB`，或变量（例如 `{tab.namecolor}`），执行时决定颜色
`align`	`left`	`left` / `center` / `right`：x 是文字的左边 / 中间 / 右边
`visible`	无	变量的值是 `hidden`、`false`，或 PlaceholderAPI 变量没有被换掉（插件没装）时隐藏这段文字
`show`、`anchor`		同 image

画面里写死的文字会自动加入资源包；插件执行时才给的文字（玩家名称、公会名称…）靠 fonts.text.common 常用字库。

item：物品

icon:
  type: item
  item: 'vanilla:DIAMOND_SWORD'
  x: 400
  y: 300
  size: 64
  spin: 30        # 每秒转 30 度

选项	默认	说明
`item`	—	物品写法，见下表
`size`	`64`	图标大小（像素）
`spin`	`0`	持续旋转，每秒几度
`sway`	`0`	左右摇摆的角度（0–89），和 `spin` 二选一
`dim`	无	变量的值是 `true` 时图标变暗（例如未解锁、已领取）

物品写法	说明
`DIAMOND`、`vanilla:DIAMOND`	原版物品
`ia:命名空间:物品`	ItemsAdder 物品
`ce:命名空间:物品`	CraftEngine 物品
`{键名}`	插件提供的物品（例如背包格、时装、奖励），见开发者 API

找不到的物品显示为屏障。

bar：进度条

xp:
  type: bar
  value: '{exp_percent}'
  x: 300
  y: 900
  width: 400
  height: 6
  color: '#8FD8EA'
  back: '#2A3440'

选项	默认	说明
`value`	—	进度：`0.75`、`75%` 或 `30/40` 都可以，可以用变量
`width`、`height`	`200`、`4`	进度条大小
`color`	`#FFFFFF`	填满部分的颜色，或变量
`back`	`#2A3440`	底色

grid：格子

把一组元素按行列排好几份。cell 里写一格的内容，坐标都是相对格子左上角。

rows:
  type: grid
  x: 120
  y: 300
  columns: 1
  rows: 4
  step: [0, 120]        # 每格之间的距离 [dx, dy]
  stagger: row          # 进场动画依序延后：column（默认）/ row / cell / none
  motion: {x: 160}
  cell:
    card:
      type: button
      image: list/row.png
      hit: [0, 0, 700, 100]          # 相对格子左上角
      state: '{state}'
      states: {empty: ''}
      click:
        left: ['custom: row']
    name:
      type: text
      text: '{name}'
      x: 120
      y: 30

选项	说明
`x`、`y`	第一格的左上角
`columns`、`rows`	几栏、几列（默认 1）
`step`	必填，`[dx, dy]` 每一格移动的距离
`cell`	必填，一格里的元素（任何类型，除了 grid）
`stagger`	进场动画每格延后的方式：`column`（每栏延后 1 tick）、`row`、`cell`（每格）、`none`
`motion`	整组的进场动画

格子里的元素 ID 与变量会自动编号：rows 的第 3 格（从 0 数）里的 name 元素，ID 是 rows.2.name；cell 里写的 {name} 会变成 {rows.2.name}，插件就能给每一格不同的资料。{index} 会换成格子编号；{player}、{level}、{health}、{max_health}、{world}、{online} 这些全域变量不会被编号。

state：状态切换

image 与 button 可以依变量换图：

mail-badge:
  type: image
  image: main/mail_badge.png
  state: '%starmail_has_unread%'
  states: {'false': ''}

state 是一个变量；它的值在 states 里找到时，改用那张图（'' = 不显示）；找不到就用 image。
states 的 true 也对应 on、yes；false 也对应 off、no。
值是 hidden 时不显示；PlaceholderAPI 变量没有被换掉（例如插件没装）时也不显示，不会露出默认图。

timeline：关键帧动画

只有 image：画面进场后（或 timeline-play 变成有值后）依关键帧移动与淡入淡出。

glow:
  type: image
  image: main/glow.png
  x: 800
  y: 200
  timeline:
    - {t: 0, y: -40, alpha: 0}
    - {t: 8, y: 0, alpha: 1}
    - {t: 40, alpha: 1}
    - {t: 60, alpha: 0}
  timeline-play: '{reward_ready}'   # 选填：这个变量有值时才播放

t：第几 tick；x、y：相对原位置的偏移；alpha：不透明度 0–1。没写的值沿用前一个关键帧。
timeline-play 的值为空、hidden、false 或 0 时停在第一个关键帧；变成其他值时开始播放。

共同选项​

image：图片​

button：按钮​

text：文字​

item：物品​

bar：进度条​

grid：格子​

state：状态切换​

timeline：关键帧动画​