EmakiGem
EmakiGem 是宝石与插槽模块，提供装备插槽、开孔器、宝石镶嵌、提取、升级、宝石共鸣与可选 Attribute 属性输出。它适合给装备添加长期养成和个性化搭配空间。
基本信息
| 项目 | 值 |
|---|---|
| 模块版本 | 2.8.0 |
| 主命令 | /emakigem |
| 别名 | /egem、/eg |
| 硬依赖 | EmakiCoreLib |
| 软依赖 | EmakiItem、EmakiAttribute、PlaceholderAPI |
| 主要权限 | emakigem.use、emakigem.reload、emakigem.admin、emakigem.debug |
核心概念
| 概念 | 说明 |
|---|---|
| 插槽物品配置 | 定义某类装备允许拥有多少插槽、可镶嵌什么宝石。 |
| 插槽 | 装备上的宝石位置，有类型限制（attack/defense/utility/universal）。 |
| 开孔 | 解锁装备上未开放的插槽。 |
| 宝石 | 可镶嵌到插槽中的物品，提供属性、技能和外观效果。 |
| 提取 | 将已镶嵌宝石取出，可能消耗材料或有失败风险。 |
| 升级 | 提高宝石等级，解锁更强效果。 |
| 共鸣 | 当装备上的宝石满足特定组合条件时触发的额外效果。 |
| gem layer | 写入装备的宝石展示层，由 EmakiGem 自身的状态服务管理。 |
默认配置目录
text
plugins/EmakiGem/
├── config.yml
├── conditions/
├── gems/
├── items/
├── resonances/
├── gui/
│ ├── gem/
│ └── open/
└── lang/目录说明：
| 目录 | 作用 |
|---|---|
gems/ | 宝石定义。 |
items/ | 插槽物品配置（定义哪些装备可拥有插槽）。 |
resonances/ | 宝石共鸣定义。 |
conditions/ | 镶嵌、开孔、提取、升级条件。 |
gui/gem/ | 镶嵌 / 提取 / 升级 / 洗炼 GUI。 |
gui/open/ | 开孔 GUI。 |
主配置键
config.yml 的顶层键：
| 键 | 默认值 | 说明 |
|---|---|---|
version | "2.8.0" | 配置结构标记，由资源同步流程维护，不是功能开关。 |
language | "zh_CN" | 语言文件名，对应 lang/<language>.yml。 |
release_default_data | true | 是否在启动时释放内置默认数据（gems/、items/、resonances/）。设为 false 后这三类默认文件不再补齐，但 gui/、conditions/、config.yml 与 lang/*.yml 不受影响。 |
socket_openers | — | 开孔器定义，见开孔器系统。 |
inlay_success | — | 镶嵌成功率，见镶嵌成功率。 |
number_format.default | "0.##" | 默认数值格式。整节缺失或值为空白时回退为 0.##。 |
op_bypass | false | OP 是否绕过镶嵌、开孔与取出的消耗及条件检查。 |
reroll.session_ttl_seconds | 120 | 洗炼候选会话存活秒数，最小 1；超时后候选作废并退费。变更只影响新生成的候选。 |
gui.default_mode | "inlay" | GUI 服务的默认打开模式。可写 inlay、upgrade、open（别名 open_socket、socket_open）；无法识别的值回退为 inlay。命令仍需显式带模式参数。 |
gui.save_on_close | false | 关闭界面时是否保存当前操作状态。 |
condition | — | 全局条件组配置，缺失时为空条件组、类型 all_of。 |
NOTE
op_bypass 曾位于 permission.op_bypass。旧键仍可被读取（顶层键优先），启动时会自动迁移到顶层并在控制台留一条提示。
WARNING
version 有两条互不相干的版本线，不要混用：config.yml 中的默认资源值是 2.8.0；源码内部另有迁移常量 CURRENT_VERSION = 2.7.8，仅用于配置迁移比对。两者用途不同。
功能页面
| 页面 | 内容 |
|---|---|
| 命令与权限 | GUI、检查、清理状态、重载和调试命令。 |
| 宝石定义 | 宝石效果、费用、提取、升级和插槽类型。 |
| 开孔器系统 | socket_openers、开孔材料、插槽解锁和失败反馈。 |
| 镶嵌成功率 | inlay_success、成功率公式和失败处理。 |
| 宝石共鸣 | 多宝石组合、共鸣效果和撤销规则。 |
| GUI 模板 | 镶嵌、开孔、升级界面配置。 |
| 提取流程 | 提取费用、返还模式和效果回退。 |
| 镶嵌与开孔流程 | 镶嵌与开孔的执行顺序与校验点。 |
| 占位符 | PlaceholderAPI 输出。 |
| CoreLib 动作 | EmakiGem 注册的 CoreLib 动作。 |
| API | 运行时集成与外部调用。 |
| 事件 API | 可监听的 Bukkit 事件。 |
典型流程
开孔
- 玩家打开开孔 GUI。
- 放入目标装备。
- 检查插槽物品配置、当前已开放插槽、条件和费用。
- 成功后解锁新插槽。
- CoreLib 重建装备展示。
镶嵌
- 玩家放入目标装备和宝石。
- 模块检查插槽类型、宝石
socket_compatibility、数量限制和条件。 - 扣除镶嵌费用（
inlay_cost）。 - 写入宝石状态和效果（属性、技能、名称/Lore 操作）。
- 检查并激活满足条件的共鸣。
- 重建 gem layer。
提取
- 玩家选择要提取的宝石。
- 检查费用（
extract_cost）、权限和条件。 - 成功时按
extract_return配置返还宝石并清空插槽。 - 撤销该宝石的所有效果（通过 ItemOperationLedger 精确回退）。
- 重新检查共鸣状态。
升级
NOTE
升级有独立 GUI 入口：/emakigem gui upgrade，镶嵌界面里也有升级模式按钮。但材料、费用与成功率判定由 EmakiStrengthen 的强化配方决定，宝石定义只负责各等级的效果。
- 读取目标宝石，检查
stages是否启用、是否已达max_level、目标等级是否已配置。 - 检查 EmakiStrengthen 是否可用，把材料与费用交给对应强化配方结算。
- 成功后提升宝石等级，应用新等级的 effects。
- 失败时按该强化配方的规则处理。
洗炼
- 玩家手持宝石，通过命令或界面按钮生成洗炼候选。
- 校验宝石
reroll是否启用、词缀池是否可用，然后立即扣费并开启候选会话。 - 确认时校验配置指纹与物品实例，通过后把候选词缀写入主手宝石。
- 超时、取消或校验失败时作废候选并退费。
共鸣激活
- 镶嵌或提取宝石后，系统自动检查所有共鸣定义。
- 按
chain.mode和chain.pattern匹配当前装备上的宝石组合。 - 满足条件时激活共鸣，应用
effects并执行actions。 - 宝石被提取导致不再满足条件时，自动撤销共鸣效果。