EmakiAccessory

EmakiAccessory 是做什么的, 依赖哪些模块, 装好后会用到哪些文件, 以及你第一次怎么把它跑起来

EmakiAccessory 是 Emaki 系列的饰品栏模块. 你装上它, 玩家就多出一套自己的饰品栏 -- 这是一个独立的 GUI (图形界面) 窗口, 不占用原版装备槽位, 戴在里面的饰品照常提供属性与技能

饰品栏可以有多个页面: parts.yml 定义全局部位与槽位实例, pages/*.yml 决定每一页启用哪些部位, gui/accessory_gui.yml 描述页面布局. 每页数据各存一份, 互不覆盖, 但只有当前启用页的饰品才会产生属性, 技能与套装件数 (同一套装已戴的件数). 你不用在 EmakiAttribute 和 EmakiSkills 里另配槽位, 饰品的属性与技能会自动接入这两个模块

基本信息

项目	值
模块版本	1.1.8
API 坐标	emaki.jiuwu.craft:emaki-accessory-api:1.1.7
主类	emaki.jiuwu.craft.accessory.EmakiAccessoryPlugin
主命令	/emakiaccessory
别名	/eaccessory, /eacc
硬依赖	EmakiCoreLib
软依赖	EmakiItem, EmakiAttribute, EmakiSkills, PlaceholderAPI
描述符基线	api-version: "26.1", folia-supported: true
Java	Java 25
主要权限	emakiaccessory.use (默认 true), emakiaccessory.reload (op), emakiaccessory.debug (op), emakiaccessory.admin (op), emakiaccessory.admin.edit (op), emakiaccessory.page.secondary (op, 页权限示例)

功能页面

页面	内容
命令与权限	/emakiaccessory 的子命令, 页面取回, 管理指令与 6 个权限节点
配置详解	config.yml 的槽位来源, 耐久度开关, 掉落, 去重与持久化, 以及 pages/*.yml 的字段
部位与槽位	parts.yml 的部位定义, 槽位实例展开规则与孤儿槽
饰品套装	sets/<套装>.yml 的成员, 槽位规则, 件数阈值与效果
界面模板	gui/accessory_gui.yml 的四种槽位类型与页面切换格
属性与技能接入	饰品属性如何进入 EmakiAttribute, 技能如何进入 EmakiSkills
API 与集成	emaki-accessory-api 的门面, 查询接口与线程约束
事件 API	AccessorySetBonusChangeEvent

核心能力

• 独立饰品栏: 饰品栏是自己的 GUI, 不占用原版装备槽位, 也不与 EmakiItem 的装备栏共享槽位
• 多页与页间隔离: pages/*.yml 定义多页, 同一个槽位实例 id 在不同页各存一件饰品, 互不覆盖
• 只有启用页生效: 非启用页的饰品保留数据但停止提供属性, 技能与套装件数; page_enable 格用于切换生效页
• 按权限开放页: 页的 permission 非空时逐字判定; 失去权限不清数据, 不自动换页, 玩家用 /eacc retrieve <页> 取回
• 部位展开为槽位实例: parts.yml 里一个部位配 count: 2 会展开出 ring_1 与 ring_2 两个槽位实例, 界面上一个格子对应一个实例
• 属性与装备同源解析: 饰品属性走 EmakiAttribute 的同一个解析器, 一件饰品和一顶同数据的头盔产出完全相同的数值, 父属性展开与范围伴生键 (带范围属性的配套键) 一并生效
• 累加式套装阈值: 套装档位是累加的. 戴够 3 件时, 2 件档与 3 件档同时生效, 不是互斥择一
• 饰品套装与装备套装互不干扰: 饰品套装只统计饰品槽内的件数, EmakiItem 只统计装备栏. 同一件物品同时属于两边的套装是允许的, 两边各自独立计数
• 孤儿槽不丢数据: 你缩减 count, 删除部位或把部位从某页移除, 都不会删数据. 该页不再声明的槽位里的饰品会变成"孤儿", 显示在该页孤儿区供玩家取回; 判定按"所属页是否声明该槽位", 其他页的饰品不会被当成孤儿
• 管理员可代看代编: /eacc admin view 是只读查看, /eacc admin edit 还需要额外的 emakiaccessory.admin.edit 权限
• 只收显式声明的饰品: 物品要先在 EmakiItem 定义里用 accessory_slot 效果声明可放入的饰品槽. 声明会写入物品 PDC (插件自定义数据, 即物品身上由插件写入的隐藏字段) 的 emakiitem:accessory_slots. 未声明或声明不匹配的物品放不进去; 已在槽内但不再匹配的, 会在关闭界面时连物带提示退回背包
• 条件与耐久检查: 饰品按自身 EmakiItem 定义的 condition 做检查, 条件不满足或耐久扣满时属性, 技能与套装件数全部停止生效, 物品保留在槽内并在界面标注状态. 耐久扣除由 durability.enabled 控制, 默认关闭

文件结构

服务器运行后, EmakiAccessory 主要使用以下文件:

plugins/EmakiAccessory/
├─ config.yml
├─ parts.yml
├─ pages/
│  ├─ main.yml
│  └─ secondary.yml
├─ sets/
│  └─ example_set.yml
├─ gui/
│  └─ accessory_gui.yml
└─ lang/
   ├─ zh_CN.yml
   └─ en_US.yml

路径	说明
config.yml	主配置: 槽位来源, 耐久度开关, 死亡掉落, 去重, 持久化
parts.yml	饰品部位定义, 决定全局有哪些槽位实例
pages/<页>.yml	饰品页定义. 页 id 取 page_id, 文件名不参与识别; parts 决定该页启用哪些部位
sets/<套装>.yml	饰品套装定义. 一个文件一个套装, 文件名不参与识别
gui/accessory_gui.yml	饰品栏界面模板, 可被多页共用
lang/*.yml	命令, 界面与控制台文案

快速开始

1. 把 EmakiCoreLib-*.jar 与 EmakiAccessory-*.jar 放入服务器 plugins/
2. 想让饰品提供属性和技能, 还要安装 EmakiAttribute, EmakiSkills, 并用 EmakiItem 定义饰品物品 -- 记得在定义的 effects 里用 type: "accessory_slot" 声明可放入的饰品槽, 否则物品放不进饰品栏
3. 注意, 不要把 emaki-accessory-api-*.jar 放进 plugins/; API Jar (提供给开发者编译用的接口包) 只作为编译依赖, 不参与服务器运行
4. 首次启动后检查 plugins/EmakiAccessory/parts.yml, pages/main.yml 与 gui/accessory_gui.yml
5. 打开自己的饰品栏:

/eacc open
/eacc open secondary

6. 查看所有页与当前启用页:

/eacc pages

7. 修改配置后重载配置, 部位, 页与套装:

/eacc reload

使用提示

• 你改了 parts.yml 的部位或 count 之后, 要在 gui/accessory_gui.yml 里为每个展开出的槽位实例摆一格 type: "accessory_slot" 且键名相同的格子, 否则玩家用不到该槽位. 还要确认目标页的 parts 里声明了该部位
• 属性, 技能与套装件数只统计当前启用页. 玩家换页前, 新页的饰品不会生效
• unique: true (只允许放一件同类饰品) 优先按 EmakiItem 的物品定义 id 判定, 且只在同一页内比较. 缺少 EmakiItem 时它不会失效, 而是回退为原版材质判定, 此时同材质的两件饰品会被视为重复
• 饰品套装的 pieces[].item 同样依赖 EmakiItem 的定义 id, 缺少 EmakiItem 时整个套装不生效
• 部位 id 不能以 _<数字> 结尾, 那会与槽位实例 id 撞车
• /eacc retrieve <页> 取回的是该页全部饰品 (已声明槽位与孤儿槽一起取出), 页打不开时可以用它备用取回
• /eacc admin edit 只对在线玩家有效; /eacc admin clear 不可撤销且会记入日志, 执行前先确认
• EmakiSkills 是软依赖: 没装它时饰品与套装的技能不生效, 但模块照常启用 (技能集成按类名查找并加载)