命令与权限
EmakiGem 的主命令是 /emakigem，别名为 /egem、/eg。玩家用它打开镶嵌或开孔界面；管理员用它检查装备宝石状态、清理异常状态、重载配置和输出调试信息。
命令列表
| 命令 | 权限 | 说明 |
|---|---|---|
/emakigem help | 无 | 输出命令帮助列表。不带参数执行 /emakigem 时同样显示。 |
/emakigem gui <inlay|upgrade|extract|reroll|recalibrate|open> | emakigem.use 或 emakigem.admin | 打开指定模式的宝石 GUI。当前命令需要显式填写模式，写错模式按参数错误处理。 |
/emakigem reload | emakigem.reload 或 emakigem.admin | 重载主配置、宝石定义、插槽物品、共鸣、条件、GUI 和语言文件。 |
/emakigem inspect [player] | emakigem.use 或 emakigem.admin | 查看指定玩家或自己的主手装备宝石状态。 |
/emakigem reroll <full|value|confirm|cancel|status> | emakigem.use 或 emakigem.admin | 对主手宝石生成或接受洗炼候选。见下方洗炼命令。 |
/emakigem clearstate | emakigem.admin | 清除主手物品的宝石层状态，适合调试或修复异常装备。 |
/emakigem convert-legacy [confirm] | emakigem.admin | 把 items/*.yml 里已废弃的 match 块转换为 matcher + 顶层 slot_groups。不带参数只做预演；confirm（或 --apply）才实际改写，并为每个文件留 .bak 备份。详见模板与插槽。 |
/emakigem debug | emakigem.debug 或 emakigem.admin | 输出运行时调试信息。 |
GUI 模式
gui 命令支持六种模式：
| 模式 | 作用 | 常见用途 |
|---|---|---|
inlay | 镶嵌宝石 | 玩家日常宝石操作。界面内可切换到取出。 |
extract | 取出宝石 | 直接以取出模式打开。 |
upgrade | 升级宝石 | 消耗 EmakiStrengthen 配方材料提升等级。 |
reroll | 全量洗炼 | 重抽主手宝石的词缀。 |
recalibrate | 数值洗炼 | 只重掷主手宝石现有词缀的数值。 |
open | 开孔 | 使用开孔器解锁装备预留插槽。 |
示例：
text
/emakigem gui inlay
/emakigem gui open洗炼命令
reroll 子命令针对主手宝石操作，需要 emakigem.use 或 emakigem.admin：
| 子命令 | 作用 |
|---|---|
full | 生成全量洗炼候选（重抽词缀本身），立即扣除 full_cost。 |
value | 生成数值洗炼候选（只重掷数值），立即扣除 value_cost。 |
confirm | 确认候选并写入主手宝石。 |
cancel | 放弃候选并退费。 |
status | 查看当前候选的类型、原词缀数、候选词缀数与剩余秒数。 |
已有未结束的候选会话时，再次执行 full 或 value 会直接返回现有会话，不会重复扣费也不会重新生成候选。候选存活时间由 config.yml 的 reroll.session_ttl_seconds 控制。配置与结算规则见宝石定义。
如果希望玩家只通过菜单入口进入某一类操作，可以在其他菜单插件或 NPC 插件中执行对应命令，并把权限控制交给 emakigem.use。
权限节点
| 权限 | 默认 | 说明 |
|---|---|---|
emakigem.use | true | 允许使用基础宝石功能和打开 GUI。 |
emakigem.reload | op | 允许重载配置。 |
emakigem.admin | op | 允许检查、清理状态等管理操作。 |
emakigem.debug | op | 允许输出调试信息。 |
先用哪个命令
| 场景 | 先执行 | 目的 |
|---|---|---|
| 玩家要镶嵌或提取宝石 | /emakigem gui inlay | 打开镶嵌界面。 |
| 玩家要给装备开孔 | /emakigem gui open | 打开开孔界面。 |
| 装备宝石状态异常 | /emakigem inspect [player] | 查看主手装备 gem layer、插槽和共鸣状态。 |
| 主手装备需要清理宝石层 | /emakigem clearstate | 移除主手物品的宝石状态。先备份。 |
| 改了宝石、插槽物品、共鸣或 GUI | /emakigem reload | 重载运行配置。 |
常见操作
打开宝石界面
text
/emakigem gui inlay命令模式必须明确写 inlay 或 open。gui.default_mode 只作为 GUI 服务默认值，不替代命令参数。
检查装备宝石状态
text
/emakigem inspect Steve检查内容包括物品定义 ID、物品识别来源、已开放插槽索引和插槽宝石分配。排查“属性未生效”“宝石显示残留”“提取后效果未撤销”等问题时优先使用该命令。
清理异常状态
text
/emakigem clearstate该命令会清除主手物品上的宝石状态。使用前建议备份玩家物品数据，并先通过 inspect 确认目标物品。清理后装备会失去宝石层记录，原有宝石效果不会再按正常流程保留。
排查建议
- GUI 打不开：检查玩家是否拥有
emakigem.use，并确认 GUI 模板目录存在。 - 开孔失败：检查目标装备是否匹配
items/*.yml，并确认存在未开放且类型匹配的预留插槽。 - 镶嵌失败：检查宝石
socket_compatibility、插槽类型、条件配置、费用配置和inlay_success。 - 升级失败：检查宝石
stages是否启用、是否已达max_level，以及 EmakiStrengthen 是否安装并存在可用的强化配方。 - 洗炼失败：检查宝石
reroll.enabled、词缀池是否为空、主手是否握着该宝石，以及候选是否已超时。 - 属性未刷新：检查 EmakiAttribute 是否安装，装备是否重建，宝石效果是否写入
ea_attribute。