EmakiGem brings a complete gem socketing experience to your server. From socket creation to embedding, extraction to upgrading, every step features carefully designed interactions. The unique resonance system lets specific gem combinations trigger bonus effects, adding strategic depth to equipment building.

Core Features

Complete Gem Lifecycle

Four stages form the full gem gameplay loop:

1. Socket Creation

Equipment starts with only some slots open; the rest require socket openers to unlock.

• Socket openers are defined in config.yml under socket_openers, each specifying which gem types it can open
• Openers are matched by item_sources (e.g. minecraft-blaze_rod for attack openers)
• opens_gem_types specifies which slot types this opener can unlock (any for universal)
• consume_on_success controls whether the opener is consumed
• Success/failure actions (messages, sounds) are fully configurable
• Operated through a dedicated GUI: place equipment and opener, select target slot, confirm

2. Embedding

Insert gems into opened slots with immediate effect activation.

• Gems declare compatible slot types via socket_compatibility
• Equipment restricts accepted gem types via allowed_gem_types
• max_same_type limits same-type gem count; max_same_id prevents duplicate gems
• Embedding costs include currencies (Vault-compatible, formula supports {base_cost} and {level}) and materials
• On success, name_action and lore_action automatically modify equipment appearance
• GUI operation: place equipment, drag gem onto empty slot, confirm embedding

3. Extraction

Remove embedded gems from slots.

• Extraction has independent cost configuration (currencies and materials)
• Return modes (extract_return.mode): original (return as-is), destroy (gem is lost), downgrade (return at lower level)
• degraded_chance controls downgrade probability
• All name_action and lore_action modifications are automatically reverted on extraction
• Built on CoreLib's item operation ledger for accurate rollback

4. Upgrading

Enhance gem levels for stronger effects.

• Each gem defines upgrade.levels with independent effects, materials, and economy costs per level
• Success rates configurable per level (success_rates) or using global defaults
• Failure penalties: none / downgrade / destroy (configurable per level)
• Each level can override economy config and failure penalty
• Max level can unlock bonus skill effects
• Operated through a dedicated upgrade GUI: place gem, add materials, confirm

Resonance System

When embedded gems meet specific combination conditions, bonus resonance effects activate. Resonance configs are placed in plugins/EmakiGem/resonances/.

Matching Modes (chain.mode):

• unordered — Only requires sufficient matching gems on the equipment, regardless of slot order
• ordered — Matches by slot index order; specific slots must contain specific gems

Match Conditions (chain.pattern):

• type — Match by gem type (e.g. 2 attack-type gems trigger fire resonance)
• id — Match by exact gem ID (e.g. specific ruby + sapphire combination)

Resonance Effects:
When activated, effects stack onto equipment independently of individual gem effects. Supports all effect types: ea_attribute, es_skill, name_action, lore_action.

Resonance Actions:
Activation can trigger messages, sounds, and other actions for clear player feedback.

Gem Effect System

Gem effects are unified under the effects list with a type discriminator:

• variables — Expression engine variables for lore placeholder rendering (e.g. {physical_attack})
• ea_attribute — EmakiAttribute PDC attributes, written to equipment PDC on embedding
• es_skill — EmakiSkills skill attachment, player gains skills when gem is embedded
• name_action — Modifies equipment name on embedding (prepend_prefix / append_suffix)
• lore_action — Modifies equipment lore on embedding (append / prepend / insert)

name_action and lore_action values support {display_name} and variable placeholders. All modifications are automatically reverted on gem extraction.

Slot Item Matching

Define which items can have gem slots in plugins/EmakiGem/items/:

Match Rules:

• item_sources — Match by item source (format: provider-item_id, e.g. minecraft-diamond_sword, ei-example_item)
• slot_groups — Match by equipment slot group (weapon / armor / offhand)
• lore_contains — Match by lore content (empty list = no restriction)

Slot Definition:
Each slot has index, type, and display_name. Slot type determines which gems can be embedded.

Default Open Slots:
Lists initially open slot indexes; unlisted slots require socket openers to unlock.

Gem Type Restrictions:

• allowed_gem_types — Whitelist of accepted gem types
• max_same_type — Max same-type gems (0 = unlimited)
• max_same_id — Max same-ID gems

Embedding Success Rate

The success rate system is configured in config.yml under inlay_success:

• enabled — Set to false for guaranteed 100% success
• default_chance — Default success rate (percentage)
• rate_formula — Formula with variables: {default_chance}, {level_chance}, {configured_chance}, {level}
• Example: {default_chance} - ({level} - 1) * 5 (higher gem level = lower success rate)
• failure_action: return_gem (no loss), destroy_gem (gem consumed), destroy_both (gem consumed, cost refunded)

GUI System

Three independent GUI interfaces with all text configurable in language files:

• Inlay/Extract GUI — Shows all slot states after placing equipment. Supports inlay mode and extract mode switching. Drag gem onto empty slot for embedding preview; click embedded slot for extraction confirmation.
• Socket Opening GUI — Place equipment and opener, select target locked slot, confirm to execute.
• Upgrade GUI — Place unembedded gem, shows current level, target level, required materials and success rate. Add materials then confirm upgrade.

GUI templates are specified in the gui config; each slot item can use different templates. Default open mode is configurable in config.yml.

Commands

• /eg help — Display help information (emakigem.use)
• /eg gui inlay — Open gem embedding/extraction GUI (emakigem.use)
• /eg gui open — Open socket creation GUI (emakigem.use)
• /eg gui upgrade — Open gem upgrade GUI (emakigem.use)
• /eg inspect [player] — View gem state of held equipment (emakigem.use)
• /eg clearstate — Remove gem layer from held item (admin debug) (emakigem.admin)
• /eg reload — Reload all configs and gem definitions (emakigem.reload)

Command aliases: /emakigem, /egem, /eg

Permissions

• emakigem.use — Basic commands and GUI access — Default: all players
• emakigem.admin — Admin commands (clearstate, etc.) — Default: OP
• emakigem.reload — Reload configuration — Default: OP

The permission.op_bypass option in config.yml controls whether OPs skip embedding, socketing, extraction, and upgrade cost/condition checks.

PAPI Placeholders

• %emakigem_mainhand_opened_slots% — Number of opened slots on held equipment
• %emakigem_mainhand_total_slots% — Total slot count on held equipment
• %emakigem_mainhand_filled_slots% — Number of embedded slots on held equipment
• %emakigem_mainhand_item_definition_id% — Slot item definition ID of held equipment
• %emakigem_mainhand_resonance_count% — Number of active resonances on held equipment
• %emakigem_mainhand_slot_N_gem% — Gem ID in slot N
• %emakigem_mainhand_slot_N_level% — Gem level in slot N
• %emakigem_mainhand_slot_N_opened% — Whether slot N is opened (true/false)
• %emakigem_mainhand_slot_N_type% — Slot type of slot N

Requirements

• Server: Spigot / Paper 1.21+
• Java: 21+
• Hard Dependencies: EmakiCoreLib
• Soft Dependencies: EmakiAttribute (stat system), EmakiSkills (skill system), PlaceholderAPI (placeholders)