箱子界面转接

很多插件用「箱子」当选单：领地设定、商店、任务、职业、抽奖……这些插件不认识云界面，但你可以不改它们的任何设定，就让它们的箱子选单变成云界面画面。

它是怎么运作的

1. 玩家用原本的方式打开那个插件的选单（指令、点 NPC、点方块都行）。
2. 原插件在服务器开了一个箱子，CloudUI 看到箱子的标题符合某个画面的 proxy: 设定，就由那个画面接手。
3. 玩家看到的是云界面画面，箱子里的每一格依你的排版显示在画面上。
4. 玩家点了画面上的格子，CloudUI 把这次点击原封不动交回原插件，就像玩家点了箱子一样。原插件要扣钱、给东西、换页、关闭，都照它自己的规则。
5. 原插件换页（重新打开箱子）时，画面原地更新；原插件关掉选单时，画面也跟着关闭。

自己先试试

管理员在游戏里输入 /cui proxydemo，会打开一个示范用的普通箱子（标题「雲介面轉接示範」），CloudUI 立刻把它转接成画面，可以点、可以换页。对应的画面文件是 screens/proxy_demo.yml，后面的教学就是复制它来改。

一步步教学

第 1 步：记下原选单的资料

在游戏里打开你要转接的插件选单，记下三件事：

要记的	怎么看	例子
标题	箱子上方的文字（颜色码不算）	领地 Lin 的设定
行数	箱子有几行（1–6）	6
控制按钮的格号	上一页、关闭、下一页在第几格	上一页 45、关闭 49、下一页 53

格号怎么算：左上角是 0，往右每格 +1，往下每行 +9。

第 1 行： 0  1  2  3  4  5  6  7  8
第 2 行： 9 10 11 12 13 14 15 16 17
第 3 行：18 19 20 21 22 23 24 25 26
第 4 行：27 28 29 30 31 32 33 34 35
第 5 行：36 37 38 39 40 41 42 43 44
第 6 行：45 46 47 48 49 50 51 52 53

第 2 步：复制范本

把 plugins/CloudUI/screens/proxy_demo.yml 复制一份，取个新名字，例如 screens/residence.yml。文件名就是这个画面的 ID，随便取，玩家不会看到。

第 3 步：改 proxy 设定

打开新文件，最上面的 proxy: 就是转接设定：

proxy:
  match:
    title: ['领地 * 的设定*']   # 原选单的标题，* 代表任意文字，可以写好几个
    rows: 6                     # 原选单的行数（可省略）
  grid: items                   # 物品要排进画面上哪个格子（grid 元素的名称）
  layout: compact               # compact 自动排列；exact 照原格位
  slots: 0-44                   # 哪些格子算「物品」（最下面一排是控制按钮）
  skip: ['*_STAINED_GLASS_PANE', 'GLASS_PANE']   # 这些装饰不显示
  buttons:                      # 固定按钮：名称: 格号
    prev: 45
    close: 49
    next: 53

第 4 步：重新载入、测试

输入 /cui reload，再用原本的方式打开那个插件的选单，就会看到云界面画面。

怎么比对选单：match

设定	说明
match.title	箱子标题，可写一个或一串。不分大小写、不看颜色码，* 代表任意文字。例如 '商店*' 符合「商店」「商店 - 第 2 页」
match.holder	选单的类别名称（插件内部的名字），标题会变来变去时用，例如 'com.example.shop.*'。需要问插件作者或看插件的原始码
match.rows	箱子必须是几行；不写 = 不检查

title 与 holder 至少要写一个，符合任何一个就会接手。

标题太宽

title: ['*'] 会把所有箱子都接手，包括普通的箱子、末影箱。请尽量写得具体一点，例如带上插件特有的字。

自动排列：compact 与 exact

这是转接最重要的设定，决定箱子里的东西怎么放到画面的格子上。

compact（默认）：自动排列

有东西的格子依序排进画面的格子，空格和装饰略过。

想像原插件的箱子长这样（· 是空格，▒ 是玻璃片装饰）：

▒ ▒ ▒ ▒ ▒ ▒ ▒ ▒ ▒
▒ A · B · · C ▒ ▒
▒ D E · · F · · ▒

compact 会只拿出 A、B、C、D、E、F，按格号顺序排进画面的格子：

画面格子：  A  B  C  D  E  F  (空)  (空) …

好处：

• 原插件新增一个商品，它会自动排进下一格，不用改画面。
• 原插件的排版再乱（中间空一堆、四周一圈玻璃片），画面上都是整整齐齐的一排排卡片。
• 物品比画面格子多时，云界面自己分页：{page} / {pages} 显示页码，按钮写 custom: page next / custom: page prev 翻页。

exact：照原格位

画面第 N 格就放箱子第 N 格，空格就是空格。

适合「位置有意义」的选单，例如：九宫格的设定面板、仓库、装备栏。用 exact 时，画面格子的数量通常和箱子格数一样（例如 9 栏 × 6 行）。

slots 与 skip

设定	说明
slots	哪些格子算物品，例如 0-44（前 5 行）、10-16。不写 = 整个箱子
skip	哪些物品种类不显示，* 代表任意文字。不写时默认略过所有玻璃片（*_STAINED_GLASS_PANE、GLASS_PANE）；写了就以你写的为准，写 [] = 全部显示

控制按钮（上一页、下一页、关闭）通常不要放进 slots，用下面的 buttons 另外放。

固定按钮：buttons

把原选单里位置固定的按钮取个名字：

buttons:
  prev: 45
  close: 49
  next: 53
  info: 4

画面上就能用 {button.名称.*} 读那一格的资料，用 custom: button 名称 点它。名称随你取。

原插件在第一页时，上一页的位置常常放玻璃片当装饰：玻璃片（skip 里的种类）在固定按钮的位置算作空的，{button.prev.state} 会是 hidden，正好用来隐藏「上一页」按钮。

画面上的变量

格子里（grid 的 cell 里）

在格子里直接写下面这些，每一格会自动对应到它的那个物品：

变量	内容
{icon}	物品图示，用在 item: '{icon}'
{name}	物品名称（原版物品自动显示中文名称）
{amount}	数量；只有 1 个时是空白
{lore}	全部说明文字（lore），一行
{lore1} ~ {lore9}	第几行说明
{state}	这一格有东西时是 on，没有时是 hidden，用来隐藏空格的底图与按钮
{type}	物品种类，例如 diamond_sword

指定箱子的任意一格

画面任何地方都能读箱子的某一格：{slot.格号.栏位}，栏位同上表。

info-name:
  type: text
  text: '{slot.4.name}'      # 箱子第 4 格的物品名称
info-icon:
  type: item
  item: '{slot.4.icon}'

固定按钮

{button.名称.栏位}，例如 {button.close.name}、{button.next.state}。

其他

变量	内容
{title}	原选单的标题（含颜色）
{page} / {pages}	云界面自己的页数（compact 物品比格子多时）
{prev} / {next}	有上一页 / 下一页时是 on，没有时是 hidden
{count}	物品总数

点击动作

动作	放在哪	作用
custom: slot	格子里的按钮	点这一格对应的箱子格（左键 / 右键照玩家点的）
custom: slot shift	格子里的按钮的 shift-left / shift-right	Shift 点击这一格
custom: slot 13	任何按钮	点箱子的第 13 格
custom: button 名称	任何按钮	点 buttons 里取名的那一格，例如 custom: button close
custom: page next / custom: page prev	翻页按钮	云界面自己翻页（compact 物品比格子多时）

格子里的按钮一般这样写：

hit:
  type: button
  hover: main/tile_s_hover.png
  state: '{state}'            # 空格不能点
  hit: [0, 0, 164, 111]
  click:
    left: ['custom: slot']
    right: ['custom: slot']
    shift-left: ['custom: slot shift']

原插件翻页 vs 云界面翻页

• 原插件自己有上一页 / 下一页按钮（会重新打开箱子）：用 custom: button prev / custom: button next，画面会原地换成新的一页。
• 原插件一页就放得下所有物品，但画面格子比较少：用 custom: page next / custom: page prev，由云界面分页。

说明框（lore）

游标停在格子上时，自动显示那个物品的名称与说明（lore），跟在箱子里看到的一样。前提是画面要有 tooltip: 区段（范本里已经有，照抄即可），见 画面文件 · tooltip。

一般的按钮（不是转接格子）也可以显示说明框：在按钮写 tooltip:，第一行是标题：

my-button:
  type: button
  image: main/tile_s.png
  hit: [100, 100, 164, 111]
  tooltip:
    - '每日奖励'
    - '每天可以领一次'
    - '连续 7 天有额外奖励'

物品名称

箱子里的原版物品，客户端会自己翻译名称；但云界面是自己画字，所以 CloudUI 内置了原版物品的中文名称，{name} 会直接显示「钻石剑」而不是 diamond_sword。插件自订了名称的物品照它的名称显示。

常见问题

打开原插件的选单还是普通箱子？

• 标题没对上：检查 match.title，记得 *，颜色码不用写。
• 写了 match.rows 但行数不同。
• 改完没有 /cui reload。
• 这位玩家不能使用云界面（基岩版、拒绝资源包、/cui classic），会看到原本的箱子。

物品排得乱七八糟？

• 想照原本的位置：layout: exact。
• 想整齐排列：layout: compact，再用 slots 去掉控制按钮那一排、用 skip 去掉装饰。

点了没反应？

• 格子按钮的 click 要写 custom: slot。
• 原插件可能只认左键或 Shift 点击，照原插件的说明试试 right / shift-left。

限制

• 用封包做的「假选单」不支援：有些插件不是真的打开箱子，而是直接送封包给客户端，服务器看不到，就无法转接。
• 一般转接不会搬物品：点击交回原插件，原插件要不要让玩家拿走东西是它决定的。要在画面上拖放、搬动物品（仓库、末影箱、背包），请看 背包投影。
• 一个画面最多 48 个没有 state 的按钮；格子很多时，每个格子按钮都加上 state（转接的格子本来就有 state: '{state}'），就没有上限。