Snowygems

菜单配置

gui/ 目录下工作台菜单的字符网格布局、五种槽位类型、宝石分类限制与实战示例。

菜单配置

除了内置的通用镶嵌台（/sgem embed），你可以在 plugins/SnowyGems/gui/ 下自定义任意工作台菜单，用 /sgem open <菜单名> 打开。

菜单适合做「多宝石槽同时镶嵌」「按颜色分槽的符文台」「一键分解/合成」这类内置镶嵌台做不到的界面。

字符网格布局

菜单用字符画描述布局：Slots 每行一个字符串，每个字符对应一个格子，Items 里定义每个字符是什么。

符文分解台:                                 # 菜单名，/sgem open 用它
  Title: "&8&l&k||&c&l符文分解台&8&l&k||"    # 界面标题
  Slots:
    - TTTTTTTTT                            # 第一行 9 格
    - TGTTBTTIT                            # 第二行
    - TTTTTTTTT                            # 第三行
  Items:
    T:
      Type: TIP
      Material: RED_STAINED_GLASS_PANE
      Display: "&c在左侧放置符文, 点击按钮分解"
    G:
      Type: EQUIP_SLOT
      Require:
        - GEM:ALL
    B:
      Type: USE_GEM
      Material: ANVIL
      Glow: true
      Display: "&c&l点击分解符文"
      Gem: 符文分解券
    I:
      Type: TIP
      Material: BOOK
      Display: "&a分解材料表"
      Tips:
        - "&f分解 &6I &f级符文, 可获得 &610 &f符文碎片"

每行必须是 9 个字符（Minecraft 箱子界面固定 9 列）。行数决定界面高度，最多 6 行。Slots 里出现但 Items 里没定义的字符，那个格子会是空的。

菜单文件里可以定义多个菜单，顶层每个键就是一个菜单名。

菜单字段

字段	说明
`Title`	界面标题，支持 `&` 颜色码。不填则用菜单名
`Slots`	字符网格，每行 9 字符
`Items`	字符 → 格子定义

Page 和 Locations 目前不生效。 内置的 gui.yml 里写了这两个字段，但代码中没有任何地方读取它们——没有翻页功能，也没有「在世界某个坐标放置工作台方块」的功能。想让玩家打开菜单只能通过命令（命令方块、NPC、其他插件代为执行 /sgem open）。

格子定义

字段	说明
`Type`	格子类型，见下文。默认 `EMPTY`
`Material`	图标材质
`Display`	图标显示名
`Tips`	图标 lore
`Glow`	是否附魔光效
`Amount`	图标堆叠数量
`Texture`	头颅 base64 材质（填了会强制用 PLAYER_HEAD）
`Require`	限制这个槽能放什么（仅 `GEM_SLOT` / `EQUIP_SLOT` 有意义）
`Gem`	`USE_GEM` 引用的宝石 ID
`Gui`	`PAGE_JUMP` 跳转到的菜单名

五种槽位类型

类型	玩家能否放东西	作用
`EQUIP_SLOT`	能	放待强化的装备。一个菜单只认第一个
`GEM_SLOT`	能	放宝石。可以有多个
`USE_GEM`	不能	按钮，点击时执行 `Gem` 指定的宝石效果
`PAGE_JUMP`	不能	按钮，点击跳转到 `Gui` 指定的菜单
`TIP` / `EMPTY` / 其他	不能	纯装饰，点击无反应

TIP、EMPTY、PAGE_PREV、PAGE_NEXT、PAGE_TIP 在代码里的处理完全一样——都只是「点击时取消事件」的装饰格。PAGE_* 这几个名字是为将来的翻页功能预留的，当前没有实际行为。

EQUIP_SLOT + 多个 GEM_SLOT

这是菜单最有价值的用法：玩家一次放入多颗宝石，点击后依次全部镶嵌到装备上。

符文镶嵌台:
  Title: "&6&l符文镶嵌台"
  Slots:
    - LLBTITRKK
    - LBBMGMRRK
    - BBMGGGMRR
    - BBMGGGMRR
    - LBBMGMRRK
    - LLBDSDRKK
  Items:
    I:
      Type: EQUIP_SLOT
    R:
      Type: GEM_SLOT
      Require: 红色符文        # 只接受名字/lore 含「红色符文」的宝石
      Amount: 1
    G:
      Type: GEM_SLOT
      Require: 绿色符文
    B:
      Type: GEM_SLOT
      Require: 蓝色符文
    S:
      Type: GEM_SLOT
      Require: 技能符文
    L:
      Type: TIP
      Material: BLUE_STAINED_GLASS_PANE
      Display: "&9在左侧镶嵌蓝色符文"

GEM_SLOT 的 Require：与宝石的 Require 语义完全不同

这是最容易混淆的地方。

宝石配置里的 Require 是「这颗宝石能镶到什么装备上」，用的是物品分类关键字（WEAPON、ARMOR、_SWORD…）。

菜单 GEM_SLOT 的 Require 是「这个槽能放什么宝石」，用的是文本包含匹配：拿宝石的 ID、Name、Display、Tips 逐个去找有没有包含这个关键词。

所以 Require: 红色符文 的含义是「宝石 ID 或名字或 lore 里含『红色符文』四个字」，不是任何预定义的分类。

Require 可以写单个字符串或列表（OR 语义）。写 ALL 或 GEM:ALL 表示接受任意本插件宝石。

不是本插件的普通物品一律被拒绝放入 GEM_SLOT——插件靠 NBT 标记识别宝石，普通钻石剑放不进去。

USE_GEM：按钮宝石

USE_GEM 是一个按钮，点击时执行 Gem 指定宝石的 Rewards：

B:
  Type: USE_GEM
  Material: ANVIL
  Glow: true
  Display: "&c&l点击分解符文"
  Gem: 符文分解券       # 引用一个已存在的宝石 ID

行为规则：

如果这个菜单有 EQUIP_SLOT 但槽里是空的，点击会提示「先放入目标物品」，不会空跑
成功时消耗装备槽里的物品（适合做分解、合成这类「吃掉输入物」的功能）
失败时物品原样留在槽里，玩家不会白丢东西
如果菜单里没有 EQUIP_SLOT，按钮直接执行，不需要目标物品

PAGE_JUMP：菜单间跳转

N:
  Type: PAGE_JUMP
  Material: ARROW
  Display: "&a前往符文分解台"
  Gui: 符文分解台        # 目标菜单名

完整示例：三级菜单

符文中心:
  Title: "&6&l符文中心"
  Slots:
    - TTTTTTTTT
    - TTAT TBTTT
    - TTTTTTTTT
  Items:
    T:
      Type: TIP
      Material: GRAY_STAINED_GLASS_PANE
      Display: " "
    A:
      Type: PAGE_JUMP
      Material: ANVIL
      Glow: true
      Display: "&a&l符文镶嵌"
      Tips:
        - "&7把符文镶嵌到装备上"
      Gui: 符文镶嵌台
    B:
      Type: PAGE_JUMP
      Material: GRINDSTONE
      Glow: true
      Display: "&c&l符文分解"
      Tips:
        - "&7把符文分解成碎片"
      Gui: 符文分解台

符文镶嵌台:
  Title: "&6&l符文镶嵌台"
  Slots:
    - TTTTITTTT
    - TRTGTBTST
    - TTTTXTTTT
  Items:
    T:
      Type: TIP
      Material: BLACK_STAINED_GLASS_PANE
      Display: " "
    I:
      Type: EQUIP_SLOT
    R:
      Type: GEM_SLOT
      Require: 红色符文
    G:
      Type: GEM_SLOT
      Require: 绿色符文
    B:
      Type: GEM_SLOT
      Require: 蓝色符文
    S:
      Type: GEM_SLOT
      Require: 技能符文
    X:
      Type: TIP
      Material: PAPER
      Display: "&f放入装备与符文, 点击符文格镶嵌"

符文分解台:
  Title: "&c&l符文分解台"
  Slots:
    - TTTTTTTTT
    - TGTTBTTIT
    - TTTTTTTTT
  Items:
    T:
      Type: TIP
      Material: RED_STAINED_GLASS_PANE
      Display: "&c在左侧放置符文, 点击中间分解"
    G:
      Type: EQUIP_SLOT
      Require:
        - GEM:ALL
    B:
      Type: USE_GEM
      Material: ANVIL
      Glow: true
      Display: "&c&l点击分解"
      Gem: 符文分解券
    I:
      Type: TIP
      Material: BOOK
      Display: "&a分解材料表"
      Tips:
        - "&f I 级符文 → &610 &f碎片"
        - "&f II 级符文 → &620 &f碎片"

内置镶嵌台 vs 自定义菜单

	`/sgem embed` 内置镶嵌台	自定义菜单
宝石槽数量	1	任意多个
分类限制	无	每槽可独立限制
布局	固定	完全自定义
成功率提示	有（显示在确认按钮 lore 上）	无
宝石的 `Gui` 字段	会检查（限定 `宝石镶嵌台`）	不检查
配置成本	零	需要画字符网格

宝石配置里的 Gui 字段用来限定某颗宝石只能在特定界面使用。内置镶嵌台的界面名是 宝石镶嵌台：

某颗宝石:
  Gui:
    - 宝石镶嵌台        # 只能在 /sgem embed 里用

不写 Gui 则任何界面都能用。

常见问题

打开菜单提示「不存在名为 xxx 的菜单」

菜单名是 YAML 顶层的键，注意中文和空格。用 /sgem open 后按 Tab 会补全所有已加载的菜单名。

宝石放不进 GEM_SLOT

开 /sgem debug Menu，日志会打印 gemSlotAccepts: 槽位 'R' require=[红色符文] 待放入=xxx 可匹配文本=[...] -> false，直接看出是哪个关键词没匹配上。

点了 USE_GEM 按钮没反应

检查 Gem 引用的宝石 ID 是否存在。开 /sgem debug Menu,Reward 能看到按钮宝石的每条 Rewards 执行结果。

改了菜单文件没生效

/sgem reload。菜单配置不是热重载的（只有 lang.yml 是）。

Edit this pageorReport an issue

技能与 BUFF

技能行语法、24 个内置函数、触发标记、条件与概率、形态切换、常驻 BUFF 的完整配置参考。

多版本兼容

SnowyGems 如何在 1.21.4 到 26.x 之间通用：注册表探测原理、版本模块开关、混服配置策略。