宝石共鸣

宝石共鸣是当装备上镶嵌的宝石满足特定组合条件时触发的额外效果。共鸣会写入装备的 gem layer，并随宝石镶嵌、提取或升级后的展示重建自动重新评估。

定义文件位于 plugins/EmakiGem/resonances/*.yml，文件名通常与 id 保持一致。

顶层字段

字段	类型	必填	说明
id	string	是	共鸣唯一 ID。加载时会转为小写。
display_name	string	否	共鸣显示名，默认使用 id。支持 MiniMessage。
priority	integer	否	匹配优先级，默认 0。数值越高越先匹配。
exclusive_group	string	否	互斥组。同一组内只激活优先级最高且成功匹配的共鸣。为空表示不参与互斥。
chain	object	是	共鸣链条件。必须包含至少一条 pattern。
effects	object	否	共鸣激活后应用的效果与动作。

注意：当前源码读取的是 effects 对象结构，不是带 type 字段的效果列表。共鸣动作也写在 effects.actions 下，而不是根节点 actions。

匹配顺序与占用规则

共鸣评估由 GemResonanceService 完成，规则如下：

1. 所有共鸣按 priority 从高到低排序。
2. 高优先级共鸣成功匹配后，会占用用于匹配的宝石索引。
3. 已被占用的宝石不会再参与低优先级共鸣。
4. 如果设置了 exclusive_group，同组内只会保留第一个成功激活的共鸣。
5. 未设置互斥组的共鸣仍会受宝石占用影响。

这意味着你可以设计“低阶 2 件套”和“高阶 3 件套”共存的体系：高阶共鸣优先占用宝石，避免低阶共鸣抢走关键宝石。

共鸣链（chain）

字段	类型	说明
mode	string	unordered 或 ordered，默认 unordered。
pattern	list	需要匹配的宝石条件列表。

mode: unordered

无序匹配。系统会为 pattern 中的每条条件寻找一颗尚未被当前共鸣占用、也未被高优先级共鸣占用的宝石。

适合“任意两颗攻击宝石”“一攻一防”等组合。

mode: ordered

有序匹配。系统会在当前镶嵌宝石列表中寻找一段连续窗口，窗口内宝石依次满足 pattern 条件，且这些宝石没有被高优先级共鸣占用。

适合设计插槽顺序谜题或固定顺序共鸣。

pattern 条件

每个 pattern 条件支持以下字段：

字段	类型	必填	说明
id	string	否	按宝石 ID 精确匹配，例如 ruby_attack。
type	string	否	按宝石类型匹配，例如 attack、defense。
min_level	integer	否	宝石最低等级要求，默认 0 表示不限制。当前镶嵌宝石等级低于该值时不参与匹配。

匹配优先级：同一条件中如果写了 id，则按 id 匹配；否则如果写了 type，则按 type 匹配；两者都不写时表示任意宝石，但仍会检查 min_level。

chain:
  mode: "unordered"
  pattern:
    - type: "attack"
      min_level: 3
    - id: "ruby_attack"
      min_level: 4

上例要求至少一颗 3 级以上攻击宝石，以及一颗 4 级以上的 ruby_attack。

共鸣效果（effects）

effects 是对象结构，字段如下：

字段	类型	说明
actions	list<string>	共鸣激活时执行的 CoreLib 动作行。
ea_attributes	object	写入 EmakiAttribute PDC 的额外属性。键为属性 ID，值为数值。
es_skills	list<string>	附加的 EmakiSkills 技能 ID。
name_actions	object/list	交给 CoreLib 名称操作系统处理的名称修改。
lore_actions	object/list	交给 CoreLib Lore 操作系统处理的 Lore 修改。

name_actions 与 lore_actions 使用 CoreLib 的名称与 Lore 操作语法，例如 prepend_prefix、append_suffix、append、insert_below 等。

完整示例

id: "fire_resonance"
display_name: "<red>火焰共鸣</red>"
priority: 10
exclusive_group: "elemental"

chain:
  mode: "unordered"
  pattern:
    - type: "attack"
      min_level: 3
    - type: "attack"
      min_level: 3

effects:
  actions:
    - 'sendmessage text="<gold>火焰共鸣已激活！</gold>"'
    - "playsound sound=minecraft:item.firecharge.use volume=0.5 pitch=1.2"
  ea_attributes:
    physical_attack: 5
    fire_damage: 3
  es_skills:
    - "fire_resonance_passive"
  name_actions:
    - action: "prepend_prefix"
      value: "<red>[焰] </red>"
  lore_actions:
    - action: "append"
      content:
        - ""
        - "<red>◆ 火焰共鸣</red>"
        - "<gray>  物理攻击 +5</gray>"
        - "<gray>  火焰伤害 +3</gray>"
        - "<gray>  技能: 火焰共鸣被动</gray>"

设计建议

• 用 min_level 把高级共鸣绑定到宝石升级线，形成“升级宝石 → 解锁共鸣”的追求目标。
• 高阶共鸣应设置更高 priority，避免低阶共鸣先占用宝石。
• 同一元素或同一流派的互斥共鸣建议使用相同 exclusive_group。
• ordered 模式更难理解，建议只用于明确强调插槽顺序的玩法。
• 共鸣 Lore 应写得清楚，让玩家能区分单颗宝石效果与组合奖励。