GUI 配置

锻造界面和配方书的模板怎么写, 有哪些槽位类型, 以及能用哪些变量和文案

Forge 的界面配置放在 gui/ 目录, 包含锻造界面和配方书两个模板. 界面不只是摆菜单看, 它还负责保护输入槽, 处理点击, 返还物品和触发锻造流程

文件说明

文件	作用
forge_gui.yml	玩家执行锻造时看到的主界面
recipe_book.yml	玩家查看已经加载的配方用的配方书

这两个文件属于静态资源: 缺失时启动流程会按内置副本创建一份, 已经存在的文件不会被改写

模板通用字段

模板使用 CoreLib GUI 模板格式. 顶层字段:

字段	类型	必填	默认值	取值范围	说明
id	string	是	—	非空字符串	模板 ID, 也就是配方里 gui_template 引用的那个名字. 留空时这个模板被跳过
gui_type	string	否	CHEST	任意 Bukkit InventoryType 名, 大小写不敏感	容器类型. 解析不出来时会不报错地退回 CHEST
title	string | object	否	GUI	字符串或文本配置对象	界面标题. 写成对象时按文本配置渲染 (可以做动态标题); 字符串支持 MiniMessage
rows	integer	否	3	1 ~ 6 (超范围截断)	行数. 只有 gui_type 支持自定义行数时才生效, 否则按类型固定. 内置 forge_gui 是 5 行, recipe_book 是 6 行
slots	map	否	空	key 为槽位组名	槽位组定义, 见槽位组字段. 某个组的 slots 解析不出槽位位置时, 这个组被丢掉
virtual_items	map	否	空	key 为虚拟物品名	不占固定槽位的动态展示物品, 见虚拟物品
texts	map	否	空	见 texts 文案	各种状态下的文案片段

发货默认值 (forge_gui.yml 的头部):

id: "forge_gui"
gui_type: CHEST
title: "<dark_gray>锻造台 - %recipe%</dark_gray>"
rows: 5

可复制的最小自定义模板:

id: "my_forge_gui"
gui_type: CHEST
title: "<dark_gray>我的锻造台</dark_gray>"
rows: 6
slots:
  blueprint_inputs:
    slots: 10
  required_materials:
    slots: [19, 20, 21]
  optional_materials:
    slots: [28, 29, 30]
  capacity_display:
    slots: 16
  confirm:
    slots: 49

槽位组字段

字段	类型	必填	默认值	取值范围	说明
slots	integer | list<integer>	是	—	容器内的合法槽位索引	这个组占用的槽位. 写成整数或索引列表都行; 解析不出槽位位置时, 整组被丢掉
type	string	否	由组名推断	见下方两张槽位类型表	功能类型. 省略时按组名推断 (blueprint_inputs, required_materials, optional_materials, capacity_display, confirm_button, recipe_list, prev_page, next_page, close 等); 推断不出来就当成纯装饰槽
item	object | string	否	空	物品源字符串, 或含 source / components 的对象	槽位默认展示的物品, 见物品定义
amount	integer	否	1	>= 1 (小于 1 提升为 1)	没写 item 对象时显示的数量
sounds	map	否	空	见点击音效	点击音效配置. 不认识的 key 会被忽略, 并记一条模板问题

锻造界面槽位类型

forge_gui.yml 里由 type 决定功能用途的槽位 (Forge 实际会读的类型):

type	作用
blueprint_inputs	图纸输入槽. Forge 按放进去的图纸物品来源自动匹配配方
required_materials	必需材料输入槽
optional_materials	可选材料输入槽, 会消耗锻造容量
capacity_display	展示当前容量, 容量上限和容量状态的地方
confirm	确认锻造按钮 (组名写 confirm_button 也会被推断成 confirm)

没有 type 的槽位组 (比如内置模板里的 top_frame, side_frame, core_frame) 只用来填充背景

WARNING

内置 forge_gui 不提供目标物品槽. 目标物品只能由调用 API 的一方通过 ForgeInputs.targetItem 提供; 走界面这条路时, 应该给配方配置 result.success.outputs

配方书槽位类型

recipe_book.yml 中由 type 驱动的功能槽位:

type	作用
recipe_list	配方条目的展示区域, 槽位的先后顺序就是配方条目的排列顺序
prev_page	上一页
next_page	下一页
close	关闭菜单

物品定义

item 写成对象时, 交给 CoreLib 的配置物品解析器处理:

字段	类型	必填	默认值	取值范围	说明
item.source	string	否	空	物品源, 如 anvil, minecraft-anvil	展示物品的来源. 留空时这个槽位不显示物品
item.amount	integer	否	1	>= 1 (小于 1 提升为 1)	展示数量
item.components	map	否	空	key 为组件 ID, 值按组件的含义解释	组件补丁, 用来改物品的各个组件. 常用的是 custom_name, lore, tooltip_display
item.$unset	list<string>	否	空	组件 ID 列表	移除指定的组件
item.$reset	list<string>	否	空	组件 ID 列表	把指定的组件重置为默认值

  blueprint_inputs:
    slots:
      - 10
      - 19
    type: "blueprint_inputs"
    item:
      source: "guster_banner_pattern"
      components:
        custom_name: "<light_purple>放入图纸</light_purple>"
        lore:
          - "<gray>配方会按图纸物品源自动匹配"

  confirm:
    slots:
      - 34
    type: "confirm"
    item:
      source: "ANVIL"
      components:
        custom_name: "<green>确认锻造</green>"
        lore:
          - "<gray>当前容量: <yellow>%current%/%max%</yellow>"
          - "<yellow>点击后开始执行锻造"
    sounds:
      click:
        sound: "ui.button.click"
        volume: 1.0
        pitch: 1.0

点击音效

sounds 的 key 是点击类型, 不认识的 key 会被忽略:

key	触发
click	任意点击
left_click / right_click	左键 / 右键
shift_left_click / shift_right_click	Shift + 左键 / 右键
middle_click	中键
double_click	双击
number_key	数字键
swap_offhand	交换副手
drop / control_drop	丢弃 / Ctrl + 丢弃

值支持 sound / volume / pitch 三个键; sound 可写原版音效键或命名空间 ID

锻造界面变量

forge_gui 的 title 和各槽位 item 的文案里可以用:

变量	说明
%recipe%	当前匹配到的配方显示名; 没匹配到配方时是 通用锻造
%current%	当前已经占用的容量
%max%	容量上限; 没匹配到配方 (上限为 0) 时是 ?
%capacity_state%	容量状态的文案, 来自 texts.capacity_state
%recipe_count%	当前这张图纸能匹配到的候选配方数量
%blueprint_requirements%	图纸需求行, 每一项各占一行; 配方还没确定时按配方分组列出 (最多 3 组). 数量的说法是"已经放进界面的量 / 需要的量"

texts.capacity_state 支持四个状态键, 没写时退回内置文案:

键	条件	内置回退
waiting	上限为 0 (还没匹配到配方)	<gray>等待图纸</gray>
overflow	当前容量超出上限	<red>已超限</red>
warning	当前容量达到上限的 80% 及以上	<gold>接近上限</gold>
normal	其它情况	<green>正常</green>

配方书变量

recipe_book 的槽位文案里可以用:

变量	说明
%page%	当前页码, 从 1 开始
%pages%	总页数
%recipe_name%	配方显示名 (只在 virtual_items.recipe_entry 里可用)
%recipe_id%	配方 ID (只在 virtual_items.recipe_entry 里可用)
%unlock_state%	解锁状态的文案, 来自 texts.recipe_entry.unlocked / locked
%crafted_state%	锻造完成状态的文案, 来自 texts.recipe_entry.crafted / uncrafted
%click_hint%	点击提示, 来自 texts.recipe_entry.click_hint

虚拟物品

virtual_items 用来定义不占固定槽位, 动态展示的物品. Forge 会读下面这两个:

字段	类型	必填	默认值	取值范围	说明
virtual_items.confirm_blocked.item	object	否	内置 BARRIER 文案	同物品定义	容量超限时, 用来替换确认按钮的那个展示物品
virtual_items.recipe_entry.item	object	否	内置 book 文案	同物品定义	配方书里每个配方条目的展示物品

virtual_items:
  confirm_blocked:
    item:
      source: "BARRIER"
      components:
        custom_name: "<red>无法锻造</red>"
        lore:
          - "<gray>当前容量: <yellow>%current%/%max%</yellow></gray>"
          - "<red>可选材料容量已超出上限</red>"

texts 文案

字段	类型	必填	默认值	取值范围	说明
texts.capacity_state.waiting	string	否	<gray>等待图纸</gray>	MiniMessage 文本	还没匹配到配方时的容量状态文案
texts.capacity_state.overflow	string	否	<red>已超限</red>	MiniMessage 文本	容量超出上限时的文案
texts.capacity_state.warning	string	否	<gold>接近上限</gold>	MiniMessage 文本	容量达到上限 80% 时的文案
texts.capacity_state.normal	string	否	<green>正常</green>	MiniMessage 文本	正常状态文案
texts.recipe_entry.unlocked	string	否	<green>可用</green>	MiniMessage 文本	配方权限满足时的状态文案
texts.recipe_entry.locked	string	否	<red>未解锁</red>	MiniMessage 文本	配方权限不满足时的状态文案
texts.recipe_entry.crafted	string	否	<green>已完成过锻造</green>	MiniMessage 文本	已经锻造过这个配方时的文案
texts.recipe_entry.uncrafted	string	否	<gray>尚未完成锻造</gray>	MiniMessage 文本	还没锻造过这个配方时的文案
texts.recipe_entry.click_hint	string	否	<yellow>点击打开锻造界面</yellow>	MiniMessage 文本	配方条目的点击提示

玩家体验建议

• 你在图纸槽和材料槽默认展示物品的 Lore 里写清楚这个槽位收什么
• 你用 texts.capacity_state 把等待图纸, 接近上限和已超限分清楚, 少让玩家困惑
• 容量超限时 confirm_blocked 会替换确认按钮, 建议你在 Lore 里直接说明怎么解决
• 装饰槽位组用来分隔功能区, 你调整布局时注意别和功能槽位的序号撞上