点击与动作

按钮的 click 决定每种点击要做什么。

五种点击

键名	什么时候
`left`	左键
`right`	右键
`shift-left`	按住 Shift + 左键（没写时改用 `left`）
`shift-right`	按住 Shift + 右键（没写时改用 `right`）
`release`	在另一个按钮按住左键、拖到这个按钮上放开（拖放物品、把东西拖进格子）

简单写法

每种点击直接写一串动作，从上到下依序执行：

click:
  left: ['open: teleport']
  right: ['message: <gray>右键是快速传送', 'console: spawn {player}']

完整写法：权限、花费、拒绝

click:
  left:
    permission: vip.warp          # 选填：没有权限就不执行
    cost:                         # 选填：执行前先扣，不够就不执行
      money: 500                  # Vault 金钱
      points: 10                  # PlayerPoints 点券
      levels: 5                   # 经验等级
      items: ['DIAMOND 3', 'ce:mypack:ticket 1']
    actions:
      - 'console: warp vip {player}'
      - 'notice: <green>已传送到 VIP 区'
    deny:                         # 选填：权限不足或花费不够时改做这些
      - 'notice: <red>需要 VIP 才能前往'

权限与花费

permission：没有权限时播放拒绝音效（sounds.deny）并显示「没有权限」；写了 deny 就改执行 deny。
cost：先检查全部花费都够，才一次扣掉。不够时显示缺少的项目（例如「不足：金錢 500、等級 5」），写了 deny 就改执行 deny。
- 金钱需要 Vault 与经济插件，点券需要 PlayerPoints；没有装时视为不足并说明原因。
- items 每一项是 物品写法数量（数量省略 = 1），物品写法同 item 元素。普通物品只比对种类；有自定义名称或模型资料的物品要完全相同才算。
按钮本身也可以写 permission，整个按钮的所有点击都需要该权限，见 button。

动作

每一行是 动作: 内容。内容里的变量会先换掉（见变量）。

动作	说明	例子
`command`	以玩家身份执行指令（开头的 `/` 可写可不写），别名 `player`	`command: spawn`
`plugin-command`	指定插件有安装才以玩家身份执行；没装时提示「这个功能需要安装 …」	`plugin-command: StarMail sm`
`console`	以控制台执行指令	`console: give {player} diamond 1`
`message`	发聊天讯息给玩家（MiniMessage），别名 `msg`	`message: <gold>欢迎！`
`notice`	画面顶端的通知横幅；选单没打开时改用动作列，别名 `toast`	`notice: <green>领取成功`
`actionbar`	动作列文字（MiniMessage）	`actionbar: <gray>冷却中`
`title`	大标题，`\|` 后面是副标题	`title: <gold>升级！\|<gray>等级 {level}`
`sound`	播放音效：`音效ID [音量] [音调]`	`sound: entity.player.levelup 1 1.2`
`delay`	等几 tick 再继续执行后面的动作，别名 `wait`	`delay: 20`
`open`	切换到另一个画面	`open: teleport`
`back`	回到上一个画面（第一个画面就关闭）	`back`
`close`	关闭选单；之后的动作会在选单关闭后才执行	`close`
`refresh`	重新整理目前画面的资料	`refresh`
`custom`	交给插件处理（插件注册的动作或画面资料），见开发者 API	`custom: claim`

先关选单再执行

要打开箱子 GUI、传送、或开别的插件的介面时，先写 close 再写指令，例如 ['close', 'command: warp shop']，画面关闭后才执行指令，比较不会冲突。 plugin-command 用在主选单的「邮箱」「公会」这类入口：插件有装就打开，没装就提示，不用为每台服务器改画面。

旧写法

旧版的 action: {type, value, close} 仍可读取，等于 click.left：

action:
  type: command   # close / back / open / message / command / console / custom / none
  value: 'spawn'
  close: true     # command、console 默认 true：先关闭选单

变量

文字、动作、state、visible、tint、color、value 都可以用变量。

内建变量

变量	内容
`{player}`	玩家名称
`{level}`	经验等级
`{exp}`	目前等级的经验进度（0–1）
`{exp_percent}`	经验进度百分比，例如 `42%`
`{health}`	目前血量（无条件进位）
`{max_health}`	最大血量
`{world}`	所在世界名称
`{online}`	在线人数

插件提供的资料

本系列插件（或用开发者 API 的插件）会为自己的画面提供更多 {键名}，例如邮件数量、公会名称、清单里每一格的内容。在网页编辑器里可以看到每个画面可用的键名与说明。

键名有 .（例如 {rows.2.name}）但插件没有提供时，换成空白；没有 . 的未知键名保持原样，方便发现打错字。

PlaceholderAPI

装了 PlaceholderAPI 时，%变量% 会在最后换掉，例如 %vault_eco_balance%、%starmail_unread_badge%。

数字整理

{num:…} 包住的数字会整理成好读的样子：1286.00 → 1,286、24.50% → 24.5%，例如：

text: '金币 {num:%vault_eco_balance%}'

五种点击​

简单写法​

完整写法：权限、花费、拒绝​

权限与花费​

动作​

旧写法​

变量​

内建变量​

插件提供的资料​

PlaceholderAPI​

数字整理​