界面模板

plugins/EmakiAccessory/gui/accessory_gui.yml 界面模板这样写: 每种格子类型是做什么的, 点击后会发生什么, 以及关闭界面时会做哪些检查

饰品栏界面就由 plugins/EmakiAccessory/gui/accessory_gui.yml 描述

槽位必须显式写 type

饰品格一定要显式写 type: "accessory_slot"; 不写 type 的格子只是纯装饰

可用类型

type	作用
accessory_slot	饰品格. 键名必须等于槽位实例 id
orphan_slot	孤儿格, 展示该页不再声明的槽位里的饰品供玩家取回
page_enable	启用格. 点击把当前页设为生效页; 只有生效页的饰品产生效果
page_switch	切页格. 键名必须等于目标页的 page_id, 点击切换到该页

一个布局可以被多页共用: pages/*.yml 的 gui_template 指向布局 id. 共用时注意, 布局里摆放的槽位实例要被该页的 parts 声明, 否则该格在该配件页上不可用

accessory_slot

键名必须等于槽位实例 id, 格式为 <部位id>_<序号>, 序号从 1 开始, 对应 parts.yml 里该部位的 count

比如 ring 部位配了 count: 2, 你就要摆 ring_1 和 ring_2 两格:

slots:
  ring_1:
    slots: [12]
    type: "accessory_slot"
    item:
      source: "LIGHT_GRAY_STAINED_GLASS_PANE"
      components:
        custom_name: "<gray>戒指</gray>"
        lore:
          - "<dark_gray>放入饰品以生效</dark_gray>"
  ring_2:
    slots: [13]
    type: "accessory_slot"

每个 accessory_slot 只能占一格. 你写了多格时只有第一格生效, 其余会记录警告

parts.yml 里声明了但这里没摆放的槽位同样会记录警告, 玩家用不了该槽位

槽位的 item 段定义空槽时显示的占位物品, 放入饰品后由真实物品替换

orphan_slot

该页不再声明的槽位里的饰品会显示在这里供玩家取回, 取走后不能再放回. 你缩减 parts.yml 的 count, 删除部位, 或把部位从某页的 parts 移除, 都会产生孤儿

slots:
  orphan:
    slots: "37-43"
    type: "orphan_slot"
    item:
      source: "GRAY_STAINED_GLASS_PANE"
      components:
        custom_name: "<gray>"
        tooltip_display:
          hide_tooltip: true

孤儿格可以占多格. 判定按"所属页是否声明该槽位", 所以其他页的饰品不会被当成孤儿

你不摆孤儿格也不会丢东西: 数据仍在文件里, 只是玩家没有界面取回入口, 只能靠 /eacc retrieve <页> 或改回配置

page_enable

点它就把当前打开的页设为生效页. 只有生效页的饰品提供属性, 技能与套装件数, 其余页保留数据但不生效

slots:
  page_enable:
    slots: [8]
    type: "page_enable"
    item:
      source: "lime_dye"

page_switch

键名必须等于目标页的 page_id, 点击就切到该页. 切页只是换界面, 不改变生效页; 想让新页生效还要点 page_enable

slots:
  main:
    slots: [0]
    type: "page_switch"
    item:
      source: "gold_ingot"
  secondary:
    slots: [1]
    type: "page_switch"
    item:
      source: "iron_ingot"

目标页设了 permission 且玩家没有该权限时, 切页会被拒绝

装饰格

不写 type 的格子是纯装饰, 例如边框:

slots:
  frame:
    slots: "0-8,45-53"
    item:
      source: "BLACK_STAINED_GLASS_PANE"
      components:
        custom_name: "<gray>"
        tooltip_display:
          hide_tooltip: true

点击行为

点击格子一律被取消 (不交给原版处理), 接着按 type 分开处理:

操作	结果
放入饰品	先按饰品槽声明规则检查: 没有 accessory_slots 声明 (且附加来源未命中) 提示 gui.not_declared; 声明不匹配提示 gui.slot_mismatch; 再按 unique 查同页重复, 重复提示 gui.unique_conflict. 拒绝时物品留在光标上, 不会进入槽位
取出饰品	光标为空时点击格内饰品即取出
双击, 数字键, 换手, 丢弃, Ctrl+丢弃	不支持, 提示 gui.click_unsupported
玩家背包侧的快捷搬运	不支持, 提示 gui.transfer_unsupported, 请逐格放取
只读窗口内的任何修改	被拒绝, 提示 gui.read_only
向孤儿格放入物品	被拒绝, 提示 gui.orphan_read_only
点击已生效页的 page_enable	提示 gui.page_already_enabled, 不改变状态
点击当前页自身的 page_switch	无动作; 目标页不存在提示 gui.page_unknown, 无权限提示 gui.page_no_permission
会话数据已被重新加载	编辑被拒绝, 提示 gui.session_stale, 请关闭并重新打开饰品栏

切页会先关闭当前窗口, 下一游戏刻 (1 个游戏刻 = 1/20 秒) 再打开目标页; 切换过程中不会触发关闭时该做的写到文件和租约释放, 数据会话保持连续

孤儿格按槽位 id 升序逐格填充, 格子不够时, 超出的孤儿只能在 /eacc retrieve <页> 里取回

关闭时的校验与状态标识

关闭窗口 (切页之外的任何关闭方式) 时, 系统会对该玩家全部页做一次声明校验: 槽位仍被该配件页声明, 但物品已不在该槽位声明内的, 会被取出并退回玩家背包 (背包放不下就掉在脚下), 逐件提示 gui.invalid_returned. 孤儿格里的物品不参与这次校验, 仍按孤儿流程只能取出

物品放对了槽位但效果被停用时, 界面会额外加一行状态提示 (只影响界面显示, 不写回物品):

状态	提示行	原因
条件不满足	gui.condition_unmet	EmakiItem 定义的 condition 未通过, 属性, 技能与套装件数停止生效
耐久耗尽	gui.durability_broken	耐久扣满, 属性, 技能与套装件数停止生效; 物品仍在槽内, 可取出修复

这两行什么时候判定, 见属性与技能接入

顶层键

字段	类型	必填	默认值	取值范围	说明
id	string	是	—	—	模板 id, 供 pages/*.yml 的 gui_template 引用; 为空时该模板不加载, 引用它的页打不开 (记录 accessory.gui_template_missing)
gui_type	string	否	CHEST	Bukkit InventoryType 名 (不区分大小写), 非法值回退 CHEST	界面类型
title	string	否	"GUI"	—	界面标题, 支持 MiniMessage; 也可写成文本配置节 (CoreLib 文本格式)
rows	integer	否	3	1~6, 超出范围被钳制	行数; 仅对支持自定义行数的类型 (如 CHEST) 生效
slots	map<string, object>	否	{}	—	槽位定义, 键名即格子标识

槽位键

slots.<键名> 的键名在不同类型下含义不同 (见上文"可用类型"). 它的嵌套字段:

字段	类型	必填	默认值	取值范围	说明
slots.<键名>.slots	integer / list / string	是	—	单格号, 格号列表, 或 "1-3,5" 形式的范围串; 解析为空时该格被忽略	该格占用的容器格号, 从 0 开始
slots.<键名>.type	string	否	空	accessory_slot / orphan_slot / page_enable / page_switch	格子行为; 留空即纯装饰. accessory_slot 与 page_switch 依赖键名, 见上文
slots.<键名>.item	object / string	否	空	—	该格显示的物品定义; 也可直接写物品来源字符串
slots.<键名>.item.source	string	否	空	—	物品来源 (原版材质名或 EmakiItem 定义等 CoreLib 物品来源写法); 留空时回退到部位 icon, 两者都为空则显示屏障物品
slots.<键名>.item.amount	integer	否	1	≥ 1, 小于 1 时按 1 处理	物品数量
slots.<键名>.item.components	map	否	{}	—	物品组件补丁, 键为组件 id, 值透传给该组件
slots.<键名>.item.components.custom_name	string	否	—	—	物品名称, 支持 MiniMessage (组件 custom_name)
slots.<键名>.item.components.lore	list<string>	否	—	—	物品描述行, 支持 MiniMessage (组件 lore)
slots.<键名>.item.components.tooltip_display.hide_tooltip	boolean	否	—	true / false	隐藏物品悬浮提示 (组件 tooltip_display 的嵌套字段)
slots.<键名>.sounds	map<string, object>	否	{}	键为 click, left_click, right_click, shift_left_click, shift_right_click, middle_click, double_click, number_key, swap_offhand, drop, control_drop	点击音效; 未识别的键记录问题并被忽略

item.components 是 CoreLib 的通用物品组件补丁, 除了上表列出的三个键, 还接受任意 Minecraft 组件 id. 饰品栏的实际交互由 type 决定, 音效与自定义组件只影响外观. 完整发货样例见 plugins/EmakiAccessory/gui/accessory_gui.yml

示例: 一页只用一格饰品, 再加一个启用格和一个切页格

id: "compact_gui"
gui_type: CHEST
title: "<dark_gray>饰品栏</dark_gray>"
rows: 3
slots:
  ring_1:
    slots: [11]
    type: "accessory_slot"
    item:
      source: "LIGHT_GRAY_STAINED_GLASS_PANE"
  page_enable:
    slots: [15]
    type: "page_enable"
    item:
      source: "lime_dye"
  main:
    slots: [16]
    type: "page_switch"
    item:
      source: "gold_ingot"