Soul Harvester

Soul Harvester & Soul Powers

This page explains the Soul Harvester feature and how it ties into Soul Powers.

• Soul Harvester lets items collect “souls” from different methods and permanently unlock upgrades as thresholds are met.
• Upgrades can boost attributes, add enchantments, unlock a Soul Power and more.
• Soul Powers are custom abilities that can trigger on attack, defence, or kill.

How it works

Example assumes the gain method is KILL

• When a player kills an entity, eligible Soul Harvester items on that player gain souls.
• Each item defines how many souls are earned per kill and a maximum capacity.
• Upgrades specify a souls-required threshold. When reached, the upgrade is applied once and marked so it won’t reapply.
• Upgrades can optionally limit soul gain to a specific entity-type and include a chance to apply plus an unlock sound.
• If an upgrade type is POWER, it grants a Soul Power by ID. That power can activate on its matching trigger type.

Soul Powers (overview)

• Powers are small Java classes loaded at runtime. They can be triggered onAttack, onDefence, or onKill.
• Each power defines its chance and cooldown via metadata and is executed for the player holding/wearing the source item.
• Use a POWER upgrade (soul-power: ) to grant the power to an item when the threshold is met.

Soul Powers (detailed)

Soul Powers are small Java classes compiled at runtime from the plugin data folder. They define when they trigger and how often via an annotation, and implement a single execute(data, player) method.

Supported triggers: onAttack, onDefence, onKill

Metadata annotation (all fields are strings):

• type: one of the supported triggers
• cooldown: seconds (e.g., "5.0")
• chance: activation chance percent (e.g., "100.0")
• failCooldown: "true" to consume cooldown even if chance fails

Where to place files:

• Put your .java files in plugins/RareSpawns/soulpowers/
• The filename without .java is the power ID (used in config)
• Use /rarespawns reload to (re)compile powers

Note: You don’t need imports—RareSpawns injects common imports automatically. Simple (no-package) classes are expected.

Example: FlameBurst power

File: plugins/RareSpawns/soulpowers/FlameBurst.java

@SoulPowerInfo(
  type = "onAttack",
  cooldown = "5.0",
  chance = "100.0",
  failCooldown = "false"
)
public class FlameBurst implements SoulPower {
  @Override
  public void execute(ItemData data, Player player) {
    // Small fiery burst around the player
    player.getWorld().spawnParticle(org.bukkit.Particle.FLAME, player.getLocation(), 20, 0.5, 0.5, 0.5, 0.02);
    player.getWorld().playSound(player.getLocation(), org.bukkit.Sound.ENTITY_BLAZE_SHOOT, 1.0f, 1.2f);
  }
}

Granting this power via Soul Harvester upgrade:

soul-harvester:
  gain-method: KILL
  souls-per-gain: 1
  max-souls: 1000
  unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:1.0:1.0
  unlock-particle: REVERSE_PORTAL:20:0.5:0.02
  spawners: false
  upgrades:
    grant-flameburst:
      type: POWER
      souls-required: 250
      soul-power: FlameBurst  # matches FlameBurst.java

Configuration (items/template.yml)

Basic example of the soul-harvester section:

soul-harvester:
  souls-per-kill: 1             # Souls granted per qualifying kill
  max-souls: 1000               # Maximum souls this item can store
  upgrades:
    upgrade1:                   # Arbitrary key; use any unique name
      uniqueid: 029f5437-f0e1   # Optional stable id; generated if missing
      type: ATTRIBUTE           # ATTRIBUTE | ENCHANTMENT | POWER
      souls-required: 100       # Souls needed before this upgrade can apply
      entity-type: ZOMBIE       # Optional: only kills of this type add souls
      chance: 30.0              # Optional: % chance to apply when checked
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:1.0:1.0
      attribute:
        attribute: GENERIC_ATTACK_DAMAGE
        amount: 0.2
        operation: ADD_SCALAR
        slot: MAINHAND

    upgrade2:
      type: ENCHANTMENT
      souls-required: 250
      enchantment:
        enchant: FIRE_ASPECT
        level: 2

    upgrade3:
      type: POWER
      souls-required: 400
      soul-power: template  # The ID of the power to grant

Extended example:

item-name: Soul Harvester
lore:
- ' '
- '&7&oGains powers when slaying monsters'
- ' '
- '&8Requires souls to evolve:'
- '&7 - &f5 Souls &8→ &cSharpened Edge'
- '&7 - &f20 Souls &8→ &eInfernal Wrath'
- '&7 - &f45 Souls &8→ &bSoul Eater'
- '&7 - &f75 Souls &8→ &dReaper’s Grace'
- '&7 - &f100 Souls &8→ &6Final Awakening'
material: NETHERITE_SWORD

soul-harvester:
  souls-per-kill: 1 # Souls granted per kill.
  max-souls: 200 # Max souls the item can hold.
  upgrades:
    sharpened_edge:
      type: ATTRIBUTE
      souls-required: 5
      chance: 100.0
      attribute:
        attribute: GENERIC_ATTACK_DAMAGE
        amount: 0.2
        operation: ADD_SCALAR
        slot: MAINHAND
      uniqueid: 34c08235-bbe2
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    infernal_wrath:
      type: ENCHANTMENT
      souls-required: 20
      chance: 60.0
      enchantment:
        enchant: FIRE_ASPECT
        level: 2
      uniqueid: e2f96e46-0b18
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    soul_eater:
      type: ATTRIBUTE
      souls-required: 45
      chance: 40.0
      attribute:
        attribute: GENERIC_ATTACK_SPEED
        amount: 0.15
        operation: ADD_SCALAR
        slot: MAINHAND
      uniqueid: e4646c68-7c35
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    reapers_grace_attribute:
      type: ATTRIBUTE
      souls-required: 75
      chance: 30.0
      attribute:
        attribute: GENERIC_LUCK
        amount: 1.0
        operation: ADD_NUMBER
        slot: MAINHAND
      uniqueid: a54544e3-c102
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    reapers_grace_enchant:
      type: ENCHANTMENT
      souls-required: 75
      chance: 30.0
      enchantment:
        enchant: LOOTING
        level: 2
      uniqueid: 709e30e1-0248
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    final_awakening_attribute:
      type: ATTRIBUTE
      souls-required: 100
      chance: 20.0
      attribute:
        attribute: GENERIC_MAX_HEALTH
        amount: 4.0
        operation: ADD_NUMBER
        slot: MAINHAND
      uniqueid: 6deae365-d224
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0
    final_awakening_enchant:
      type: ENCHANTMENT
      souls-required: 100
      chance: 20.0
      enchantment:
        enchant: SWEEPING_EDGE
        level: 3
      uniqueid: 48152bef-a954
      unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:2.0:1.0

Full config entry:

# SoulHarvester, Custom Mechanics Feature, ever-growing items.
# Attributes of the same attribute overwrite eachother.
soul-harvester:
 gain-method: KILL # KILL, MINING, DEFENCE, FISHING, BUILDING
 souls-per-gain: 1 # Souls granted per gain.
 max-souls: 1000 # Max souls the item can hold.
 # sound:volume:pitch - If only sound, volume & pitch will be 1.0.
 unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:1.0:1.0 # Sound played when unlocked, default if no upgrade sound is chosen.
 # particle:amount:offset:extra - Missing values will be defaulted.
 unlock-particle: REVERSE_PORTAL:20:0.5:0.02 # Particles when unlocked, default is no upgrade particle is chosen.
 spawners: false # Should spawner mobs give souls?
 upgrades:
  upgrade1: # Upgrade name, can be anything.
   uniqueid: 9307b8ed # Unique id, generated if missing, editing this may cause issues on existing items.
   type: ATTRIBUTE # Attribute, Enchantment, Power, Modeldata, Itemmodel, Itemname, Displayname, Lore, Loreadd
   souls-required: 100 
   entity-type: ZOMBIE # Souls will only add to the item if this entity type is killed.
   chance: 30.0 # 30% chance to apply per check.
   # sound:volume:pitch - If only sound, volume & pitch will be 1.0.
   unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:1.0:1.0 # Sound played when unlocked.
   # particle:amount:offset:extra - Missing values will be defaulted.
   unlock-particle: REVERSE_PORTAL:20:0.5:0.02 # Particles when unlocked.
   # if type Attribute.
   attribute:
    attribute: GENERIC_ATTACK_DAMAGE # https://helpch.at/docs/1.21.1/org/bukkit/attribute/Attribute.html
    amount: 0.2 # 20% with ADD_SCALAR
    operation: ADD_SCALAR # https://helpch.at/docs/1.21.1/org/bukkit/attribute/AttributeModifier.Operation.html
    slot: MAINHAND # https://helpch.at/docs/1.21.1/org/bukkit/inventory/EquipmentSlotGroup.html
   # if type Enchantment.
   enchantment:
    enchant: FIRE_ASPECT # https://helpch.at/docs/1.21.1/org/bukkit/enchantments/Enchantment.html
    level: 2 # Fire Aspect II
    override: false # Should we exist any enchantment of the same kind, which is higher level?
   # if type Power.
   soul-power: template # Custom soul power.
   # if type Modeldata
   modeldata: 12345 # Custom Model Data
   # if type Itemmodel
   itemmodel: 'minecraft:cool-model'
   # if type Itemname
   itemname: 'Soul Harvester'
   # if type Displayname
   displayname: '&4Soul Harvester'
   # if type Lore
   lore: # Replaces existing lore
   - line1
   - line2
   # if type Loreadd
   loreadd: # Adds onto existing lore
   - line1
   - line2

Field notes

• gain-method: How souls are gained, though kills, mining, defence, building, or fishing.
• souls-per-gain: Souls awarded per gain.
• max-souls: Cap; prevents further accumulation above this value.
• unlock-sound: Plays once when the upgrade is applied.
• unlock-particle: Spawns once when the upgrade is applied.
• spawners: Whether mobs from spawners award souls.
• upgrades: Map of named upgrade steps. Each is applied once when requirements are met.
  • uniqueid: Used internally to tag the item so the same upgrade won’t reapply.
  • type:
    • ATTRIBUTE: Adds an attribute modifier (attribute/amount/operation/slot).
    • ENCHANTMENT: Adds an enchantment (enchant/level/override).
    • POWER: Grants a Soul Power (soul-power: <id>).
    • MODELDATA: Sets the CustomModelData of the item (modeldata: <value>).
    • ITEMMODEL: Sets the ItemModel of the item (itemmodel: <namespace:key>).
    • ITEMNAME: Sets the name of the item (itemname: <text>).
    • DISPLAYNAME: Sets the displayname of the item (displayname: <text>).
    • LORE: Sets the lore of the item, replacing existing lore. (lore: <string list>).
    • LOREADD: Sets the lore of the item, adding to existing lore. (loreadd: <string list>).
  • souls-required: Minimum souls on the item to consider applying this upgrade.
  • entity-type: Optional filter; only kills of this entity add souls.
  • chance: Roll to apply when conditions are met; 100.0 means always apply.
  • unlock-sound: Plays once when this upgrade is applied.
  • unlock-particle: Spawns once when this upgrade is applied.

Tips

• Keep uniqueid stable once items are in circulation; changing it creates a new upgrade tag.
• Verify names for attributes, operations, slots, enchantments, and entity types against your server version.
• For Soul Powers, ensure the power ID matches the compiled class you intend to load.
• Lists for lore should be formatted as:

lore:
- line 1
- line 2

• Sound formatting: KEY : VOLUME : PITCH, example: ENTITY_EVOKER_CAST_SPELL:1.0:1.0.
  (If only the key, volume and pitch are defaulted to 1.0)
• Particle formatting: KEY : AMOUNT : OFFSET : EXTRA (possibly velocity), example: REVERSE_PORTAL:20:0.5:0.02.
  (Any format entry missing will be defaulted)