EmakiGem

EmakiGem 是宝石与插槽模块，提供装备插槽、开孔器、宝石镶嵌、提取、升级、宝石共鸣与可选 Attribute 属性输出。它适合给装备添加长期养成和个性化搭配空间。

基本信息

项目	值
模块版本	2.1.0
主命令	/emakigem
别名	/egem、/eg
硬依赖	EmakiCoreLib
软依赖	EmakiAttribute、EmakiSkills、PlaceholderAPI
主要权限	emakigem.use、emakigem.reload、emakigem.admin

核心概念

概念	说明
插槽物品配置	定义某类装备允许拥有多少插槽、可镶嵌什么宝石。
插槽	装备上的宝石位置，有类型限制（attack/defense/utility/universal）。
开孔	解锁装备上未开放的插槽。
宝石	可镶嵌到插槽中的物品，提供属性、技能和外观效果。
提取	将已镶嵌宝石取出，可能消耗材料或有失败风险。
升级	提高宝石等级，解锁更强效果。
共鸣	当装备上的宝石满足特定组合条件时触发的额外效果。
gem layer	写入装备的宝石展示层，由 CoreLib 统一管理。

默认配置目录

plugins/EmakiGem/
├── config.yml
├── conditions/
├── gems/
├── items/
├── resonances/
├── gui/
│   ├── gem/
│   ├── open/
│   └── upgrade/
└── lang/

目录说明：

目录	作用
gems/	宝石定义。
items/	插槽物品配置（定义哪些装备可拥有插槽）。
resonances/	宝石共鸣定义。
conditions/	镶嵌、开孔、提取、升级条件。
gui/gem/	镶嵌 / 提取相关 GUI。
gui/open/	开孔 GUI。
gui/upgrade/	升级 GUI。

功能页面

页面	内容
命令与权限	GUI、检查、清理状态、重载和调试命令。
宝石定义	宝石效果、费用、提取、升级和插槽类型。
开孔器系统	socket_openers、开孔材料、插槽解锁和失败反馈。
镶嵌成功率	inlay_success、成功率公式和失败处理。
宝石共鸣	多宝石组合、共鸣效果和撤销规则。
GUI 模板	镶嵌、开孔、升级界面配置。
提取流程	提取费用、返还模式和效果回退。
占位符	PlaceholderAPI 输出。
API	运行时集成与外部调用。

典型流程

开孔

1. 玩家打开开孔 GUI。
2. 放入目标装备。
3. 检查插槽物品配置、当前已开放插槽、条件和费用。
4. 成功后解锁新插槽。
5. CoreLib 重建装备展示。

镶嵌

1. 玩家放入目标装备和宝石。
2. 模块检查插槽类型、宝石 socket_compatibility、数量限制和条件。
3. 扣除镶嵌费用（inlay_cost）。
4. 写入宝石状态和效果（属性、技能、名称/Lore 操作）。
5. 检查并激活满足条件的共鸣。
6. 重建 gem layer。

提取

1. 玩家选择要提取的宝石。
2. 检查费用（extract_cost）、权限和条件。
3. 成功时按 extract_return 配置返还宝石并清空插槽。
4. 撤销该宝石的所有效果（通过 ItemOperationLedger 精确回退）。
5. 重新检查共鸣状态。

升级

1. 玩家在升级 GUI 中选择宝石。
2. 检查升级材料、经济费用和等级上限。
3. 按成功率判定结果。
4. 成功后提升宝石等级，应用新等级的 effects。
5. 失败时按 failure_penalty 处理。

共鸣激活

1. 镶嵌或提取宝石后，系统自动检查所有共鸣定义。
2. 按 chain.mode 和 chain.pattern 匹配当前装备上的宝石组合。
3. 满足条件时激活共鸣，应用 effects 并执行 actions。
4. 宝石被提取导致不再满足条件时，自动撤销共鸣效果。