Gem Resonance

Gem resonance is an extra effect activated when the gems socketed on an item match a configured combination. Resonances are evaluated when gem state changes and are written through the gem layer rebuilt by CoreLib.

Definition files are stored in plugins/EmakiGem/resonances/*.yml.

Top-level fields

Field	Type	Required	Description
id	string	Yes	Unique resonance id. It is normalized to lowercase when loaded.
display_name	string	No	Display name. Defaults to id. MiniMessage is supported.
priority	integer	No	Match priority. Default 0; higher values are evaluated first.
exclusive_group	string	No	Mutually exclusive group. Only the first successfully matched resonance in the same group is activated. Empty means no group.
chain	object	Yes	Matching chain. It must contain at least one pattern entry.
effects	object	No	Effects and actions applied when the resonance is active.

Current source code reads effects as an object, not as a list with type entries. Resonance actions are read from effects.actions, not from root-level actions.

Evaluation order and gem occupation

GemResonanceService evaluates resonances with these rules:

1. Resonances are sorted by priority in descending order.
2. A successfully matched high-priority resonance occupies the matched gem indexes.
3. Occupied gems cannot be reused by lower-priority resonances.
4. If exclusive_group is set, only the first matched resonance in that group is activated.
5. Resonances without an exclusive group are still affected by occupied gems.

Use this to make advanced resonances win over basic resonances that use the same gems.

Chain

Field	Type	Description
mode	string	unordered or ordered. Default: unordered.
pattern	list	Required gem conditions.

mode: unordered

Each pattern entry searches for one available gem that has not been occupied by this resonance or by a higher-priority resonance.

This is suitable for combinations such as “any two attack gems”.

mode: ordered

The matcher searches for a consecutive window in the current inlaid gem list. Gems in that window must match the pattern entries in order, and none of them can be occupied by a higher-priority resonance.

Use it for socket-order puzzles or strict sequence builds.

Pattern entries

Field	Type	Required	Description
id	string	No	Match a specific gem id, such as ruby_attack.
type	string	No	Match a gem type, such as attack or defense.
min_level	integer	No	Minimum required inlaid gem level. Default 0 means no level gate.

If both id and type are configured, id takes priority. If neither is configured, the entry matches any gem but still checks min_level.

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

Effects

effects is an object with the following fields:

Field	Type	Description
actions	list<string>	CoreLib action lines executed when the resonance activates.
ea_attributes	object	Extra EmakiAttribute PDC attributes. Keys are attribute ids and values are numbers.
es_skills	list<string>	EmakiSkills skill ids attached by this resonance.
name_actions	object/list	CoreLib name operation config.
lore_actions	object/list	CoreLib lore operation config.

name_actions and lore_actions use the CoreLib structured presentation operation syntax, such as prepend_prefix, append_suffix, append, and insert_below.

Complete example

id: "fire_resonance"
display_name: "<red>Fire Resonance</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>Fire resonance activated!</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>[Flame] </red>"
  lore_actions:
    - action: "append"
      content:
        - ""
        - "<red>◆ Fire Resonance</red>"
        - "<gray>  Physical Attack +5</gray>"
        - "<gray>  Fire Damage +3</gray>"
        - "<gray>  Skill: Fire Resonance Passive</gray>"

Design notes

• Use min_level to link advanced resonances to gem upgrades.
• Give advanced resonances higher priority so they reserve gems first.
• Use the same exclusive_group for mutually exclusive elements or build paths.
• Prefer unordered unless socket order is an intentional part of the gameplay.