TQ 插件文档

布局系统 ​

ItemMaster 使用 9 列 × N 行的字符矩阵来描述 GUI 布局（N = rows 的值）。每个字符对应一个槽位，字符的含义由 slots 字段定义。

基本写法 ​

yaml
rows: 6
layout: |
  XXXXXXXXX
  X...I...X
  X.......X
  X...O...X
  X.......X
  XXXXBXXXX
  • . 表示空槽位，玩家可自由放入物品（默认按顶层 match 规则过滤）。
  • 其他字符都必须在 slots 中有对应的槽位定义。
  • 每行必须是 9 个字符，行数必须和 rows 一致。

两种等价的语法 ​

yaml
# 1) 多行字符串（推荐）
layout: |
  XXXXXXXXX
  X...I...X
  X...O...X

# 2) 字符串数组
layout:
  - "XXXXXXXXX"
  - "X...I...X"
  - "X...O...X"

两种写法效果相同，多行字符串形式更紧凑，字符串数组更容易在注释里保留行号。

槽位索引 ​

从左到右、从上到下，从 0 开始。rows=6 的 GUI 共有 54 个槽位：

第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

一般情况下你不会直接用到这些索引，脚本里都是通过槽位 ID 操作。

槽位组：同一字符出现多次 ​

如果某个字符在布局里出现多次，并且对应的槽位定义加了 multiple=true，那么这些槽位会被视为一个槽位组：

yaml
layout: |
  XXXXXXXXX
  X..FFF..X
  X..FIF..X
  X..FFF..X
  X.......X
  XXXXBXXXX

slots:
  F: input(id=food, multiple=true, match="lore.contains('可被吞噬')")

此时 @food 是一个 List<ItemStack>：

表达式类型说明
@foodList<ItemStack>整个物品列表（含空位）
@food.filledNumber有物品的槽位数量
@food.sizeNumber槽位总数
@food.emptyBoolean是否全部为空

槽位组不支持 with @food { ... }，遍历请用 for 循环或 sum_attr / count_filled 等聚合函数。

纯数字字符的陷阱 ​

YAML 会把纯数字键解析成整数，导致 slots 里的字符映射丢失。如果布局用到了数字字符，slots 的键必须加引号：

yaml
layout: |
  .........
  .1.2.3.4.
  .........

slots:
  # ❌ 错误：数字键会被当作整数
  1: toggle(id=锁1, toggleid=lock1, on=LIME_DYE, off=GRAY_DYE)

  # ✓ 正确
  "1": toggle(id=锁1, toggleid=lock1, on=LIME_DYE, off=GRAY_DYE)
  "2": toggle(id=锁2, toggleid=lock2, on=LIME_DYE, off=GRAY_DYE)

中文字符不需要加引号，但为了兼容某些 YAML 解析器，建议统一用单引号包住。

常见布局模板 ​

单槽位操作（3 行） ​

yaml
rows: 3
layout: |
  .........
  ....I....
  .........

强化 / 洗练（6 行，带按钮） ​

yaml
rows: 6
layout: |
  XXXXXXXXX
  X...I...X
  X...M...X
  X...P...X
  X.......X
  XXXBXDXXX

吞噬（6 行，槽位组饲料） ​

yaml
rows: 6
layout: |
  XXXXXXXXX
  X..FFF..X
  X..FIF..X
  X..FFF..X
  X.......X
  XXXXBXXXX

锻造（6 行，3×3 材料网格） ​

yaml
rows: 6
layout: |
  XXXXXXXXX
  X.123...X
  X.456.O.X
  X.789...X
  X.......X
  XXXXBXXXX

转盘抽奖（5 行环形 + 中间结果） ​

yaml
rows: 5
layout: |
  XXXXXXXXX
  X..123..X
  X..8O4..X
  X..765..X
  XXXXBXXXX

环形槽位用 output 类型，每个独立 ID（s1–s8），中间 O 放抽奖结果。配合 delay + slot.set 可以做出动画效果，详见 槽位与 GUI 动作 中的延迟章节。

和 slots 的配合要点 ​

  • layout 只负责位置，每个字符的具体外观、交互都在 slots 里定义。
  • . 是空槽位，不需要在 slots 里写；但如果你希望空位不让玩家放东西，在顶层 match 加过滤即可。
  • 同一个字符在 slots 里只能定义一次，所有使用该字符的格子共享同一定义。
  • 如果布局里用了某字符但 slots 里没有，插件会按空槽位处理（玩家可放入任意物品）。

下一步阅读：槽位类型。

TQ Minecraft Server Plugin Docs

Copyright © 2026 TQ