布局、坐标与槽位
查阅面板尺寸、父容器起点、字符布局和所有槽位写法。
想把按钮放到指定格子，先看布局操作教程。本页查阅字段与位置换算。
面板位置字段
字段写在 panels 的某一项，或 pages 中的某一页面板，不写进 menu。
| 字段 | 类型 | 必填 | 省略行为 | 说明 |
|---|---|---|---|---|
layout | 文字列表 | 普通、生成器可省；滚动、物品交互必填 | 普通、生成器不建立字符布局；固定分页不读取此字段 | 每项为一行，字符或反引号分组匹配图标 ID |
scale | 两项整数列表 | 固定 pages 必填；其他可省 | 其他面板优先取 layout 的最长原始行宽和行数；普通、生成器都未指定时宽 9，顶层高度采用窗口行数 | 第一项宽度，第二项高度；应为正数，不是左右下标 |
locate | 两项整数列表 | 否 | 普通父容器选择最靠上的未占用起点；固定分页的每页默认从其区域的 0x0 开始 | 第一项 x，第二项 y；相对于父容器，不是图标坐标或窗口槽位 |
普通面板、生成器若既无 layout 又无 scale，在顶层可按窗口行数确定高度；嵌套在 pages 内时不要依赖这一省略方式，应明确写 layout 或 scale。
自动起点只寻找一个未占用格子，不保证从它开始的整个面板矩形都空闲；父容器已满也不能继续自动放置。组合区域应像普通面板一样明确填写 locate。
字符布局
layout:
- '#########'
- '# A #'
- '####C####'
icons:
'#':
material: GRAY_STAINED_GLASS_PANE
name: ' '
A:
material: DIAMOND
name: '&b按钮'
C:
material: BARRIER
name: '&c关闭'
action: 'menu close'- 每个字符占一格。相同 ID 出现多次，同一个图标会显示在这些格子上，并共享状态与动作。
- 空格通常表示不放固定图标；它在滚动面板中还确定滚动区域，在物品交互面板中标示可存取区。
- 未定义图标的字符不会自动生成物品。不要把未定义字符当成“锁定”槽位的方法。
- 图标显式设置
id（别名key）后，布局匹配这个 ID，不再匹配icons下原来的键。 - 保留行首、行尾空格；每行等宽便于核对。整行空白按最长原始行宽展开；较短的非空行不会自动补出图标。
多字 ID
反引号将一个多字 ID 合成一格。例如下面仍将 confirm 放在第五格：
scale:
- 9
- 1
layout:
- ' `confirm` '
icons:
confirm:
material: DIAMOND
name: '&b确认'使用这种写法时显式填写 scale。省略尺寸时，行宽按原始文字长度计算，包含反引号与 ID 的全部字符，不等于分组后的实际格数。
图标槽位字段
字段写在图标的 display 内；没有 display 时，也可直接写在图标下。动画帧可单独填写同一字段。
| 字段 | 类型 | 必填 | 省略行为 | 说明 |
|---|---|---|---|---|
slot（slots、pos、position、positions） | 整数、位置文字或这些值的列表 | 否 | 初次使用布局中匹配图标 ID 的位置；无匹配且无显式位置时不显示 | 使用所在面板的局部位置；显式设置会替换该图标的整组布局位置，而不是追加 |
| 写法 | 位置与效果 |
|---|---|
slot: 0 | 面板局部槽位 0 |
slot: '4x1' | 面板第五列、第二行；也可写 '4,1' |
slot: '0~8' | 0 至 8，含两端；也支持 '0-8'、'0..8' |
slot: '0;8;4x1' | 分号连接多个序号、范围或坐标；写在同一个文字值中 |
| 多项列表 | 将各项位置合并，例如下方的四角写法；两项整数列表表示两个槽位，不是一对坐标 |
slot:
- 0
- 8
- 18
- 26数字槽位按面板宽度换算：宽 9 时，13 是 4x1；宽 3 时，4 是 1x1。范围使用从小到大的非负序号；槽位不支持占位符表达式。
小布局选择位置
slot 还可写成包含真正换行的文字：
material: PAPER
slot: |-
.........
....X....
.........它会选中多行文字中出现次数最少的非空白标记，本例为 X，对应 4x1。不是固定识别 X，也不是选中所有非空格；并列最少时按首次出现的标记选择。绘制时只让目标标记最少，避免混入其他少量装饰符号。
局部位置与窗口槽位
- locate:
- 0
- 1
scale:
- 9
- 2
icons:
button:
slot: 0
material: PAPER该面板局部 slot: 0 位于窗口第二行第一格，即窗口槽位 9。在九列箱子中：
| 计算 | 结果 |
|---|---|
| 局部槽位 | 局部 y × 面板宽度 + 局部 x |
| 窗口坐标 | 面板局部坐标加上各级父面板的 locate |
| 窗口槽位 | 窗口 y × 9 + 窗口 x |
icon at 0 和 storage at 0 使用对应面板的局部槽位，不是整个窗口左上角。固定分页的子面板位置也相对于分页区域。滚动内容的位置由分组与当前偏移安排，不应再用 slot 强行排列每项。
显式尺寸不是扩容窗口：面板实际可见尺寸不会超过父容器，越出面板的图标不能正常显示。scale、locate 与 slot 应共同落在所需区域内；窗口行数及下方背包区域见窗口设置。
状态或动画改变位置
子图标或动画帧显式填写 slot 时，会应用这组新位置。后续外观更新 icon update 不重新应用槽位；重新选中状态或切换到有 slot 的帧才会应用位置。
后续帧或状态省略 slot，不会自动把图标搬回字符布局。需要来回移动时，每个位置变化都显式给出目标槽位；参见动画配置。
Last updated on