GUI 系统

CoreLib GUI 系统提供菜单模板、打开请求、会话管理和交互控制基础设施。业务模块不需要从零处理 InventoryClickEvent，而是定义自己的 GUI 配置，再交由 CoreLib 统一管理。

使用 GUI 系统的模块

模块	用途
EmakiForge	锻造界面、配方书、编辑器。
EmakiStrengthen	强化界面、材料槽、保护材料槽。
EmakiGem	镶嵌、提取、开孔、升级界面。
EmakiSkills	技能界面、触发器选择界面。
EmakiCooking	蒸锅、烤炉、榨汁机、发酵桶 GUI。

GUI 模板配置

GUI 模板是菜单的静态定义，描述界面的标题、大小、槽位布局和按钮。

顶层字段

字段	类型	必填	默认值	说明
id	string	是	—	模板唯一标识，模块内部引用时使用。
title	string / object	是	—	界面标题。支持 MiniMessage 格式字符串或 TextConfig 对象。
rows	integer	是	—	界面行数，取值范围 1–6，对应 9–54 个槽位。
slots	map	是	—	槽位定义，key 为槽位名称，value 为槽位配置对象。

槽位配置字段

每个槽位定义了一组格子的外观和行为：

字段	类型	必填	默认值	说明
key	string	是	—	槽位名称，用于业务代码引用。
slots	list<integer>	是	—	对应的格子索引列表（0 起始，从左到右、从上到下）。
type	string	否	""	槽位类型标签，用于业务分类（如 input、output、button、decoration）。
item	string/object	否	""	当前推荐的槽位物品来源字段，用于渲染默认物品。Web GUI 编辑器只把结构化物品来源写回此字段。
components	object	否	—	物品组件覆盖，控制显示名、Lore、模型等。
sounds	map	否	—	点击音效配置，按点击类型区分。

当前字段约定

• 新配置和 Web Console 结构化编辑统一使用 item 表示槽位基础物品来源。
• item_source、item_sources、material 等旧写法不再作为 Web GUI 编辑器的当前字段读取或回写来源；如果旧 YAML 中仍存在这些键，应按普通未知字段看待并手动迁移。
• 动态 GUI 槽位如果只是按钮、说明、空态、预览或确认物品，会优先读取模板中的 item、display_name、lore 与组件配置；没有配置时才使用模块代码中的业务默认展示。
• 玩家真实放入的目标物、材料、真实产物或用于隐藏的 AIR 槽位仍由业务状态决定，不会被模板物品强行覆盖。

物品组件（components）

物品组件用于覆盖槽位物品的显示属性：

字段	别名	类型	说明
display_name	—	string / TextConfig	物品显示名（MiniMessage 格式）。
lore	—	list<string> / TextConfig	物品 Lore 列表。空列表会清除 Lore。
item_model	item-model	string	物品模型 NamespacedKey（1.21+ 物品模型系统）。
custom_model_data	custommodeldata	integer	自定义模型数据（旧版资源包兼容）。
enchantments	—	map / list	附魔配置。map 格式 {enchant_id: level} 或列表格式 ["enchant_id:level"]。
hidden_components	—	list<string>	隐藏的物品组件列表。
hide_tooltip	hide-tooltip	boolean	是否隐藏整个 tooltip。

hidden_components 可选值

值	别名	效果
enchantments	enchants、enchant	隐藏附魔显示。
attributes	attribute_modifiers、attribute_modifier	隐藏属性修饰符。
unbreakable	—	隐藏"不可破坏"标签。
can_destroy	—	隐藏"可破坏"列表。
can_place_on	—	隐藏"可放置于"列表。
trim	armor_trim	隐藏盔甲纹饰。
dye	dyed_color	隐藏染色信息。
tooltip	tooltip_display、*	隐藏整个 tooltip。

点击类型

GUI 系统识别以下点击类型：

类型	说明
CLICK	通用点击（作为 fallback，当没有匹配到具体类型时使用）。
LEFTCLICK	左键点击。
RIGHTCLICK	右键点击。

音效查找优先级：先查 LEFTCLICK / RIGHTCLICK，未找到时回退到 CLICK。

完整 GUI 配置示例

强化界面示例

id: strengthen_gui
title: '<dark_gray>装备强化'
rows: 6
slots:
  background:
    slots: [0,1,2,3,4,5,6,7,8,9,10,11,12,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39,40,41,42,43,44,45,46,47,48,50,51,52,53]
    type: decoration
    item: minecraft-black_stained_glass_pane
    components:
      display_name: ' '
      hidden_components:
        - '*'
  target:
    slots: [13]
    type: input
    item: minecraft-air
    components:
      display_name: '<gray>放入目标装备'
      lore:
        - '<dark_gray>将需要强化的装备放在这里'
  confirm:
    slots: [49]
    type: button
    item: minecraft-anvil
    components:
      display_name: '<green>开始强化'
      lore:
        - '<gray>放入装备和材料后点击'
        - ''
        - '<yellow>左键点击开始强化'
      enchantments:
        unbreaking: 1
      hidden_components:
        - enchantments
    sounds:
      LEFTCLICK:
        sound: minecraft:block.anvil.use
        volume: 0.8
        pitch: 1.0

锻造界面示例

id: forge_gui
title: '<dark_gray>锻造台'
rows: 6
slots:
  background:
    slots: [0,1,2,3,4,5,6,7,8,9,17,18,26,27,35,36,44,45,46,47,48,49,50,51,52,53]
    type: decoration
    item: minecraft-gray_stained_glass_pane
    components:
      display_name: ' '
  blueprint_slot:
    slots: [10]
    type: input
    components:
      display_name: '<aqua>图纸槽'
      lore:
        - '<gray>放入锻造图纸'
  material_slots:
    slots: [11,12,13,14,15,16,19,20,21,22,23,24,25]
    type: input
    components:
      display_name: '<yellow>材料槽'
      lore:
        - '<gray>放入锻造材料'
  target_slot:
    slots: [28]
    type: input
    components:
      display_name: '<gold>目标装备'
      lore:
        - '<gray>放入需要锻造的装备'
  result_preview:
    slots: [34]
    type: output
    components:
      display_name: '<green>预览结果'
  confirm:
    slots: [43]
    type: button
    item: minecraft-smithing_table
    components:
      display_name: '<green>确认锻造'
    sounds:
      LEFTCLICK:
        sound: minecraft:block.anvil.use
        volume: 1.0
        pitch: 1.2

GUI 会话

GUI 会话用于记录玩家当前打开的界面状态。会话由 CoreLib 自动管理，业务模块通过 GuiSessionHandler 接口处理交互逻辑。

会话记录的信息包括：

• 玩家正在操作哪一个配方或流程。
• 哪些槽位是输入槽（允许放入物品），哪些槽位禁止拿取。
• 点击按钮后应该调用哪个业务流程。
• 关闭界面时是否需要返还输入物品。
• 当前界面的临时状态数据。

会话的核心作用是防止玩家通过快速点击、Shift 点击、拖拽或异常关闭复制物品或绕过流程。

槽位索引参考

6 行界面的槽位索引布局：

行 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

常用位置：

• 中心位置（6 行）：22（第 3 行中间）或 31（第 4 行中间）
• 底部中间：49
• 四角：0、8、45、53

修改 GUI 的建议

1. 先只改显示文本：确认语言、颜色、布局是否符合预期。
2. 再改槽位位置：移动按钮时确认不会和输入槽、输出槽冲突。
3. 最后改交互逻辑：例如确认按钮、返回按钮、分页按钮。
4. 每次修改后测试异常操作：Shift 点击、拖拽、双击、关闭界面、背包满。

MiniMessage 与颜色

GUI 文本建议统一使用 MiniMessage 格式：

display_name: '<gold>传说锻造台'
lore:
  - '<gray>放入图纸、材料和目标装备。'
  - '<yellow>点击开始锻造。'
  - ''
  - '<dark_gray>消耗：<white>500 金币'

常用 MiniMessage 标签：

标签	效果
<red>	红色文本
<green>	绿色文本
<gold>	金色文本
<gray>	灰色文本
<dark_gray>	深灰色文本
<yellow>	黄色文本
<aqua>	青色文本
<bold>	粗体
<italic>	斜体
<strikethrough>	删除线
<gradient:gold:yellow>	渐变色

如果某个模块仍兼容传统颜色符（&a、§b），也建议逐步迁移到 MiniMessage，方便统一风格。