宝石定义

宝石定义描述一颗宝石能提供哪些效果、可以镶嵌到哪些插槽、费用配置以及升级路径。文件位于 gems/*.yml，文件名即为宝石的内部标识。

顶层字段

字段	类型	必填	说明
`id`	string	是	宝石唯一 ID。加载时转为小写；为空则该文件不会加载。
`display_name`	string	否	宝石显示名（MiniMessage 格式）。默认使用 `id`。
`lore`	list	否	宝石物品自身的 Lore。
`gem_type`	string	否	宝石类型，用于插槽兼容性匹配（如 `attack`、`defense`、`utility`、`universal`）。默认 `universal`。
`level`	integer	否	宝石基础等级，升级后递增。默认 1，最小 1。
`base_item_source`	string	是	宝石的构造底材（标量，格式 `"提供者-物品ID"`）。发放宝石时按它造物品——匹配器只能判断"是不是"，造不出物品，所以这一项不能省。无法解析时该宝石不会加载。旧的顶层 `item_sources` 仍被解析器作为构造底材回退读取。
`item_sources`	list	否	识别判定用：允许的物品来源列表。省略表示不限来源。与同级 `matcher` 取 AND。
`matcher`	object	否	识别判定用：通用物品匹配器，只写组件、PDC、Lore 等非物品源条件。省略表示不加额外条件。见物品匹配器。
`custom_model_data`	integer	否	自定义模型数据。
`effects`	list	否	宝石效果列表（统一格式，见下方说明）。
`socket_compatibility`	list	否	允许镶嵌的插槽类型列表。留空表示可镶嵌任意插槽类型。
`required_gems`	list	否	依赖的宝石 ID 列表。
`conflicting_gems`	list	否	冲突的宝石 ID 列表。
`inlay_cost`	object	否	镶嵌费用配置。
`extract_cost`	object	否	拆卸费用配置。
`extract_return`	object	否	拆卸返还模式。
`stages`	object	否	升级阶段配置。解析时优先读 `stages`，见下方升级系统。
`upgrade`	object	否	`stages` 的回退别名。仅当文件里没有 `stages` 键时才会被读取。
`reroll`	object	否	洗炼配置，见下方洗炼系统。
`actions.inlay_success`	list	否	镶嵌成功时执行的动作行。
`actions.extract_success`	list	否	提取成功时执行的动作行。

NOTE

socket_compatibility 中写入 universal 时，该宝石可镶嵌到任意类型插槽。

构造与识别是两组字段

base_item_source 负责造宝石，item_sources + matcher 负责认宝石，互不干扰。识别判定里 item_sources 与 matcher 同级取 AND，两者都省略时这枚宝石永远不会被认出来。

matcher 内部不能写物品源条件（type: item_source / item_sources / source / sources 会被拒绝并告警）。

效果系统（effects）

宝石效果统一使用 effects 列表，通过 type 字段区分类型：

type	载荷键	说明
`variables`	`variables`	表达式引擎变量，用于 Lore 占位符渲染。
`ea_attribute`	`ea_attributes`	EmakiAttribute PDC 属性，写入装备 PDC。
`es_skill`	`es_skills`	EmakiSkills 技能附加。
`name_action`	`name_actions`	镶嵌后对装备名称的修改。
`lore_action`	`lore_actions`	镶嵌后对装备 Lore 的修改。

variables 与 ea_attributes 的值可以是数值或表达式，可引用 %level%；同一块中先解析的键可作为后续表达式的变量。

顶层写法

除 effects 列表外，解析器同样接受直接写在宝石根节点上的 variables、ea_attributes、name_actions、lore_actions：

yaml

variables:
  physical_attack: 8
ea_attributes:
  physical_attack: 8.0

variables 与 ea_attributes 会合并两种写法的结果，effects 中的同名键覆盖顶层键；name_actions 与 lore_actions 在顶层存在时优先，不再读取 effects 中的对应项。技能只能通过 effects 中的 es_skill 声明。

yaml

effects:
  - type: "variables"
    variables:
      physical_attack: 8
      physical_crit_rate: 3
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 8.0
      physical_crit_rate: 3.0
  - type: "name_action"
    name_actions:
      - action: "append_suffix"
        value: " <red>[%display_name%]</red>"
  - type: "lore_action"
    lore_actions:
      - action: "append"
        content:
          - "<red>◆ %display_name%: 物理攻击+%physical_attack% 暴击率+%physical_crit_rate%%</red>"

最小示例

yaml

id: "ruby_basic"
display_name: "<red>红宝石</red>"
gem_type: "attack"
level: 1
base_item_source: "minecraft-redstone"   # 构造底材
item_sources:                            # 识别判定
  - "minecraft-redstone"
socket_compatibility:
  - "attack"
  - "universal"
effects:
  - type: "variables"
    variables:
      physical_attack: 5
  - type: "ea_attribute"
    ea_attributes:
      physical_attack: 5.0

费用配置

镶嵌费用

yaml

inlay_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 1000
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>金币</gold>"
  materials:
    - item_sources:
        - "minecraft-gold_nugget"
      amount: 1

拆卸费用

yaml

extract_cost:
  currencies:
    - provider: "vault"
      currency_id: ""
      base_cost: 500
      cost_formula: "%base_cost% * %level%"
      display_name: "<gold>金币</gold>"

拆卸返还模式

字段	说明
`mode`	`"original"`（原样返还）、`"destroy"`（销毁）、`"downgrade"`（按概率降级返还）。别名：`destroyed` 等同 `destroy`，`degraded` 等同 `downgrade`；无法识别的值回退为 `original`。
`downgrade_levels`	降级时降低的等级数。最小 1，默认 1。
`degraded_chance`	触发降级的概率，取值 0.0~1.0。`0.0` 表示从不降级，`1.0` 表示必定降级。仅在 `mode: downgrade` 时生效。

降级后等级小于等于 0 时，宝石不会返还。

yaml

extract_return:
  mode: "original"
  downgrade_levels: 1
  degraded_chance: 0.0

升级系统

宝石支持按等级递进的升级阶段，每个阶段可以覆盖显示名与效果，解锁更强属性或技能。

阶段配置的顶层键有两个：解析器先取 stages，只有该键不存在时才回退读 upgrade。两者结构完全一致，语义也一致，upgrade 只是历史遗留的别名。

WARNING

同一文件里同时写 stages 和 upgrade 时，upgrade 会被完全忽略（不会与 stages 合并）。新配置请统一写 stages。

阶段顶层字段

字段	说明
`enabled`	是否启用升级。未写时：只要解析出至少一个等级就默认为 `true`，否则为 `false`。
`max_level`	最大等级。未写时默认取已配置等级中的最大值；没有任何等级时为 1。
`gui_template`	会被解析并保留，但当前没有消费点，填写不产生效果。升级界面复用插槽物品配置里的 `gui.gem_template`。
`levels`	各等级详细配置。省略该键时，阶段块自身的数字键会被直接当作等级表读取。

等级的键必须是能解析为整数且大于 1 的值；1 及以下、以及非数字键都会被跳过。

等级配置

每个等级可包含：

字段	说明
`display_name`	该等级的显示名称。默认空字符串。
`variables` / `ea_attributes`	该等级的表达式变量与 PDC 属性。
`effects`	该等级的效果列表，格式与基础 `effects` 相同。
`name_actions`	该等级对装备名称的修改。
`lore_actions`	该等级对装备 Lore 的修改。
`matrices`	该等级的字符串键值表。

DANGER

阶段块与等级块里都不读 materials、economy、success_rate、success_rates、failure_penalty。这些键写进宝石定义不会报错，但完全不生效。升级的材料、费用与成功率判定由 EmakiStrengthen 中对应的强化配方决定；缺少可用配方或 EmakiStrengthen 不可用时，升级入口会直接提示不可用。

升级示例

yaml

stages:
  enabled: true
  max_level: 4
  gui_template: "upgrade/default"
  levels:
    2:
      display_name: "<red>红宝石 II</red>"
      effects:
        - type: "variables"
          variables:
            physical_attack: 12
            physical_crit_rate: 4
        - type: "ea_attribute"
          ea_attributes:
            physical_attack: 12.0
            physical_crit_rate: 4.0
        - type: "lore_action"
          lore_actions:
            - action: "append"
              content:
                - "<red>◆ 红宝石 II: 物理攻击+12 暴击率+4%</red>"
    4:
      display_name: "<red>红宝石 IV</red>"
      effects:
        - type: "variables"
          variables:
            physical_attack: 22
            physical_crit_rate: 7
        - type: "ea_attribute"
          ea_attributes:
            physical_attack: 22.0
            physical_crit_rate: 7.0
        - type: "es_skill"
          es_skills:
            - "ruby_burst"
        - type: "lore_action"
          lore_actions:
            - action: "append"
              content:
                - "<red>◆ 红宝石 IV: 物理攻击+22 暴击率+7%</red>"
                - "<gold>  ★ 解锁技能: 红宝石爆发</gold>"

省略 levels 时可以把等级直接写在阶段块下，效果相同：

yaml

stages:
  2:
    display_name: "<red>红宝石 II</red>"
  3:
    display_name: "<red>红宝石 III</red>"

洗炼系统

洗炼用于重掷宝石的词缀。配置写在宝石定义的 reroll 块里；该块缺失时这颗宝石的洗炼直接关闭。

洗炼顶层字段

字段	说明
`enabled`	是否启用洗炼。写了 `reroll` 块时默认 `true`。
`group`	使用的词缀池分组名。默认 `default`。`pools` 里找不到该分组时，回退使用名为 `default` 的池；连 `default` 也没有则视为池为空，洗炼失败。
`max_affixes`	全量洗炼时生成的词缀条数上限。最小 1，默认 1。
`pools`	词缀池，按分组名分组。回退别名为 `affixes`（仅当没有 `pools` 时读取）。
`full_cost`	全量洗炼费用，结构与 `inlay_cost` 相同。
`value_cost`	数值洗炼费用，结构与 `inlay_cost` 相同。

词缀条目字段

池中每个条目可写：

字段	说明
`id`	词缀 ID。用映射写法时可省略，取该条目的键名；两者都没有则该条目被跳过。
`weight`	抽取权重。默认 1，非正值会被记为诊断信息。
`min` / `max`	数值区间。别名 `min_value` / `max_value`；`max` 缺失时取 `min`。
`min_stage` / `max_stage`	可用阶段区间。默认 1 与无上限；抽取前会按宝石当前阶段过滤掉区间外的条目。
`display_name`	词缀显示名。默认取 `id`。
`attribute_id`	对应的属性 ID。默认取 `id`。

两种洗炼模式

模式	行为	费用键
全量洗炼	按权重重抽词缀本身。条数取 `max_affixes` 与原有词缀条数中的较小值；原本没有词缀时取 `max_affixes`。	`full_cost`
数值洗炼	保留原有词缀 ID 与阶段，只在该词缀的 `min`/`max` 区间内重掷数值。	`value_cost`

结算规则

洗炼采用「先出候选、再确认」的两步流程：

打开时读取主手宝石，生成候选并立即扣费，然后建立一个有存活时间的候选会话。
确认时校验配置指纹与物品实例；校验通过才把候选写入主手宝石。

WARNING

确认前若宝石定义被改动（配置指纹不符）或主手物品发生变化，会话会判定失败并作废。除确认成功外的所有终止路径都会退还已扣费用；若此时玩家已离线，退款转为挂起状态，等玩家可被调度时再执行。

yaml

reroll:
  enabled: true
  group: "default"
  max_affixes: 2
  pools:
    default:
      - id: "physical_attack"
        weight: 10
        min: 5
        max: 12
        min_stage: 1
      - id: "physical_crit_rate"
        weight: 5
        min: 1
        max: 4
  full_cost:
    currencies:
      - provider: "vault"
        currency_id: ""
        base_cost: 3000
        display_name: "<gold>金币</gold>"
  value_cost:
    currencies:
      - provider: "vault"
        currency_id: ""
        base_cost: 800
        display_name: "<gold>金币</gold>"

洗炼的命令入口与会话查询 API 见命令与权限与 API。

插槽类型设计

常见插槽类型分类：

类型	适用装备	推荐宝石方向
`attack`	武器	攻击、暴击、穿透。
`defense`	防具	防御、生命、减伤。
`utility`	饰品	功能性属性（速度、吸血、冷却）。
`universal`	所有装备	通用属性（经验加成、掉落率）。

建议不超过 4 种插槽类型，否则玩家理解成本过高。

宝石定义 ​

顶层字段 ​

效果系统（effects） ​

顶层写法 ​

最小示例 ​

费用配置 ​

镶嵌费用 ​

拆卸费用 ​

拆卸返还模式 ​

升级系统 ​

阶段顶层字段 ​

等级配置 ​

升级示例 ​

洗炼系统 ​

洗炼顶层字段 ​

词缀条目字段 ​

两种洗炼模式 ​

结算规则 ​

插槽类型设计 ​

宝石定义

顶层字段

效果系统（effects）

顶层写法

最小示例

费用配置

镶嵌费用

拆卸费用

拆卸返还模式

升级系统

阶段顶层字段

等级配置

升级示例

洗炼系统

洗炼顶层字段

词缀条目字段

两种洗炼模式

结算规则

插槽类型设计