EmakiGem

EmakiGem 的基本信息, 配置目录, 主配置键与各功能页面入口, 以及几条常见流程的分步说明, 可以按顺序照做

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

基本信息

项目	值
模块版本	`2.8.11`
主命令	`/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/open/`	开孔界面

主配置键

config.yml 的顶层键:

字段	类型	必填	默认值	取值范围	说明
`version`	string	否	`"2.8.11"`	—	配置结构标记, 由资源同步流程维护, 不是功能开关
`language`	string	否	`"zh_CN"`	`lang/` 下的文件名 (如 `zh_CN`, `en_US`)	语言文件名, 对应 `lang/<language>.yml`
`release_default_data`	boolean	否	`true`	`true` / `false`	是否在启动时释放内置默认数据 (`gems/`, `items/`, `resonances/`). 设为 `false` 后这三类默认文件不再补齐, 但 `gui/`, `conditions/`, `config.yml` 与 `lang/*.yml` 不受影响
`socket_openers`	object	否	空 (无开孔器)	见开孔器系统	开孔器定义
`inlay_success`	object	否	空 (按源码回退)	见镶嵌成功率	镶嵌成功率
`number_format.default`	string	否	`"0.##"`	—	默认数值格式. 整节缺失或值为空白时改用 `0.##`
`op_bypass`	boolean	否	`false`	`true` / `false`	OP 是否绕过镶嵌, 开孔与取出的消耗和条件检查. 旧键 `permission.op_bypass` 仍会被读取, 但顶层键优先
`reroll.session_ttl_seconds`	integer	否	`120`	≥ 1	洗炼候选会话的存活秒数; 超时后候选作废并退费. 改动只影响新生成的候选
`gui.default_mode`	string	否	`"inlay"`	`inlay` / `upgrade` / `open` (别名 `open_socket`, `socket_open`)	GUI 的默认打开模式; 其他值 (含 `extract`, `reroll`, `recalibrate`) 一律改用 `inlay`. 命令仍要明确写出模式参数
`gui.save_on_close`	boolean	否	`false`	`true` / `false`	关闭界面时是否保存当前操作状态
`condition`	object	否	空条件组	见 CoreLib 条件	全局条件组配置; 缺失时为空条件组, 类型 `all_of`

随包默认值 (与顶层键相关的部分):

yaml

version: "2.8.11"
language: "zh_CN"
release_default_data: true
number_format:
  default: "0.##"
op_bypass: false
reroll:
  session_ttl_seconds: 120
gui:
  default_mode: "inlay"
  save_on_close: false

使用示例:

yaml

language: "en_US"
op_bypass: true
gui:
  default_mode: "open"
  save_on_close: true
reroll:
  session_ttl_seconds: 60

NOTE

op_bypass 原本写在 permission.op_bypass 下. 旧键仍会被读取 (顶层键优先), 启动时会自动迁移到顶层, 并在控制台留一条提示

WARNING

version 有两条互不相干的版本线, 不要混用: config.yml 中的默认资源值是 2.8.11; 源码内部另有迁移常量 CURRENT_VERSION = 2.7.8, 仅用于配置迁移比对. 两者用途不同

功能页面

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

典型流程

开孔

玩家打开开孔界面
放入目标装备
检查插槽物品配置, 当前已经开放的插槽, 条件和费用
成功后解锁一个新的插槽
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
宝石被提取导致不再满足条件时, 自动撤销共鸣效果

EmakiGem ​

基本信息 ​

核心概念 ​

默认配置目录 ​

主配置键 ​

功能页面 ​

典型流程 ​

开孔 ​

镶嵌 ​

提取 ​

升级 ​

洗炼 ​

共鸣激活 ​