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 (the gem presentation layer the plugin maintains on the item) managed by EmakiGem

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

Top-level fields

Field	Type	Required	Default	Range	Description
id	string	Yes	—	—	Unique resonance id. Lowercased on load; the file is skipped when blank
display_name	string	No	id	MiniMessage text	Display name
priority	integer	No	0	any integer	Match priority; higher values are evaluated first
exclusive_group	string	No	"" (no group)	any string	Mutually exclusive group; only the first successfully matched resonance in the same group is activated
chain	object	Yes	—	must contain at least one pattern entry	Matching chain; when chain is missing or pattern is empty the file is not loaded
effects	object	No	empty	see Effects below	Effects and actions applied when the resonance is active

IMPORTANT

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 these rules to let a low-tier 2-piece and a high-tier 3-piece resonance coexist: the advanced resonance reserves the gems first so the basic one cannot steal them

Chain

Field	Type	Required	Default	Range	Description
mode	string	No	"unordered"	unordered / ordered	Matching mode; unrecognized values are treated as unordered
pattern	list	Yes	—	each entry is a condition object	Required gem conditions; the resonance is skipped when the list is empty

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 fits 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	Default	Range	Description
id	string	No	empty	gem id	Match a specific gem id, such as ruby_attack
type	string	No	empty	gem type	Match a gem type, such as attack or defense
min_level	integer	No	0	≥ 0	Minimum required inlaid gem level; gems below it do not take part in the match

The entry's priority: when both id and type are configured, id takes priority. When 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	Required	Default	Range	Description
actions	list<string>	No	empty list	CoreLib action lines	CoreLib action lines executed when the resonance activates
ea_attributes	object	No	empty	keys are attribute ids; values may be numbers or expressions	Extra EmakiAttribute PDC attributes; keys resolved earlier in the same block are available as variables to later expressions
es_skills	list<string>	No	empty list	EmakiSkills skill ids	EmakiSkills skill ids attached by this resonance
name_actions	object/list	No	empty	CoreLib name operations	CoreLib name operation config
lore_actions	object/list	No	empty	CoreLib lore operations	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:
    - 'send_message text="<gold>Fire resonance activated!</gold>"'
    - "play_sound 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