Skip to content

soulharvestercomponent

Jump to bottom
Valor edited this page Nov 11, 2025 · 4 revisions

Soul Harvester

This page documents the Soul Harvester feature (items that accumulate "souls" and unlock upgrades/powers).

Table of Contents

Overview

  • Soul Harvester items accumulate "souls" from player activity (kills, mining, fishing, defending, building) and unlock configurable upgrades when thresholds are reached.
  • Upgrades can change attributes, add enchantments, grant soul powers, change model data, set item names/lore, and more.
  • Souls and applied upgrades are stored on the item via the plugin's PersistentDataContainer (PDC) so progression persists with the item.

https://youtu.be/XBV-M6mL2rQ

RareSpawns-SoulHarvester.mp4
Example: 9-step Soul Harvester upgrade chain (one of each type) — click to expand

Below is a compact, copy‑pasteable example that demonstrates one upgrade of each supported type. Drop this into an item file under soul-harvester.upgrades to test all upgrade behaviours.

soul-harvester:
  gain-method: KILL
  souls-per-gain: 1
  max-souls: 200
  spawners: false
  worlds:
    - world
  blacklist: false
  upgrades:
    # 1) ATTRIBUTE - adds an attribute modifier (flat +2 attack damage)
    mighty_strike:
      uniqueid: aa11bb22
      type: ATTRIBUTE
      souls-required: 5
      chance: 100.0
      attribute:
        attribute: GENERIC_ATTACK_DAMAGE
        amount: 2.0
        operation: ADD_NUMBER
        slot: MAINHAND

    # 2) ENCHANTMENT - adds an enchantment (Fire Aspect II)
    ember_brand:
      uniqueid: cc33dd44
      type: ENCHANTMENT
      souls-required: 20
      chance: 90.0
      enchantment:
        enchant: FIRE_ASPECT
        level: 2
        override: true
      unlock-sound: ENTITY_BLAZE_AMBIENT:1.0:1.0

    # 3) POWER - grants a Soul Power id (runtime power must exist)
    broodcaller:
      uniqueid: ee55ff66
      type: POWER
      souls-required: 40
      chance: 50.0
      soul-power: broodCallPower
      unlock-particle: REVERSE_PORTAL:30:0.5:0.02

    # 4) MODELDATA - set custom model data
    visual_upgrade:
      uniqueid: 1122aabb
      type: MODELDATA
      souls-required: 60
      chance: 100.0
      modeldata: 123456

    # 5) ITEMMODEL - set an item model key (namespaced)
    model_swap:
      uniqueid: 3344ccdd
      type: ITEMMODEL
      souls-required: 80
      chance: 100.0
      itemmodel: 'minecraft:cool-model'

    # 6) ITEMNAME - set an internal item name (metadata, informational)
    christen_item:
      uniqueid: 5566eeff
      type: ITEMNAME
      souls-required: 90
      chance: 100.0
      itemname: 'Blade of the Collected'

    # 7) DISPLAYNAME - change the displayed name (color codes allowed)
    titled_blade:
      uniqueid: 7788gg99
      type: DISPLAYNAME
      souls-required: 100
      chance: 100.0
      displayname: '&4Blade of the Collected'

    # 8) LORE - replace the item's lore entirely
    storied_blade:
      uniqueid: aabb1122
      type: LORE
      souls-required: 120
      chance: 100.0
      lore:
        - '&7Forged from the remnants of fallen foes.'
        - '&7It hungers for more souls.'

    # 9) LOREADD - append extra lore lines
    legend_append:
      uniqueid: ccdd3344
      type: LOREADD
      souls-required: 140
      chance: 100.0
      loreadd:
        - '&6Legend: Once a great hunter'
        - '&6Now bound to the blade.'

What to expect

  • Upgrades apply when the item's stored souls reach or exceed the configured souls-required.
  • Chance <100.0 means the upgrade may not apply the first time the threshold is reached.
  • POWER (broodCallPower) requires a compiled Soul Power class with that ID to do anything after unlock.

Quick test steps

  1. Add this soul-harvester section to your item file under items/ and restart the server.
  2. Give the item to a test player (/rarespawns.item).
  3. Kill mobs to accumulate souls and watch the item for attribute/enchant/model/name/lore changes and SFX/particles.
  4. If using the POWER upgrade, ensure broodCallPower exists in plugins/RareSpawns/soulpowers/ (runtime-compiled) and restart/compile.

Notes & safety

  • Keep uniqueid stable once the item is distributed.
  • Test on a staging server; Soul Powers execute arbitrary Java code.
  • Adjust souls-required and chance to tune progression pacing for your players.

Primary config snippet (reference)

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
 worlds:
  - worldName
  - worldName_nether
 blacklist: false
 upgrades:
  upgrade1:
   uniqueid: 9307b8ed
   type: ATTRIBUTE
   souls-required: 100
   entity-type: ZOMBIE
   chance: 30.0
   unlock-sound: BLOCK_RESPAWN_ANCHOR_SET_SPAWN:1.0:1.0
   unlock-particle: REVERSE_PORTAL:20:0.5:0.02
   attribute:
    attribute: GENERIC_ATTACK_DAMAGE
    amount: 0.2
    operation: ADD_SCALAR
    slot: MAINHAND

Config -> Runtime mapping

  • soul-harvester (object) → SoulHarvesterComponent
    • gain-method → SoulHarvesterComponent.gainType (enum SoulHarvesterGainType: KILL, MINING, DEFENCE, FISHING, BUILDING)
      • Controls which event types increase souls (see "How souls are added").
    • souls-per-gain → SoulHarvesterComponent.soulsPerGain (Integer)
      • How many souls to add per qualifying event.
    • max-souls → SoulHarvesterComponent.maxSouls (Integer)
      • Maximum souls the item can hold.
    • unlock-sound / unlock-particle → SoulHarvesterUpgrade.unlockSound / unlockParticle
      • Default feedback used when an upgrade is unlocked (upgrade may override).
    • spawners → SoulHarvesterComponent.spawners (boolean)
      • If false, kills from spawner-spawned mobs are ignored.
    • worlds → SoulHarvesterComponent.worlds (List)
      • List of world names; used with blacklist to allow/deny worlds.
    • blacklist → SoulHarvesterComponent.isBlacklist (boolean)
      • If true, worlds acts as a blacklist (disallowed worlds); if false, as whitelist (allowed worlds).
    • upgrades → list of upgrade entries → SoulHarvesterComponent.upgrades (List)

Upgrade entries (structure and mapping) Each upgrade has a unique identifier (configured key like "upgrade1") and nested fields. They map to SoulHarvesterUpgrade fields.

Common top-level upgrade keys:

  • uniqueid — upgrade uuid string used for namespacing and persistent applied-tracking (recommended; generated if missing).
    • WARNING: editing uniqueid on an item that already exists may break previously applied upgrades.
  • type — SoulHarvesterUpgradeType (ATTRIBUTE, ENCHANTMENT, POWER, MODELDATA, ITEMMODEL, ITEMNAME, DISPLAYNAME, LORE, LOREADD)
    • Controls what the upgrade does when applied.
  • souls-required — integer threshold of souls required to attempt this upgrade.
  • entity-type — optional entity filter; only apply if the configured entity type was involved in the soul-gain event.
  • chance — percent chance (0.0–100.0) the upgrade will actually apply when conditions are met.
  • unlock-sound / unlock-particle — optional per-upgrade SFX.

Type-specific subkeys (examples)

  • ATTRIBUTE
    • attribute: e.g., GENERIC_ATTACK_DAMAGE
    • amount: numeric change value (for ADD_SCALAR 0.2 = +20%).
    • operation: ADD_NUMBER, ADD_SCALAR, MULTIPLY_SCALAR_1
    • slot: MAINHAND, OFFHAND, HEAD, etc.
  • ENCHANTMENT
    • enchant: enchantment id/name
    • level: integer
    • override: boolean — whether to overwrite equal/higher existing enchants
  • POWER
    • soul-power: string id of a Soul Power (runtime-compiled or pre-registered power)
      • When this upgrade is applied, the SKU (power id) is set on the item and becomes available as a Soul Power trigger.
  • MODELDATA
    • modeldata: integer custom model data to set
  • ITEMMODEL
    • itemmodel: namespaced model key to set (requires Items/Resourcepack support)
  • ITEMNAME / DISPLAYNAME / LORE / LOREADD
    • itemname / displayname / lore / loreadd: modify item metadata (lore replaces vs loreadd appends)

How souls are accumulated (runtime)

SoulHarvesterListener listens to several events and delegates to SoulPowerManager.addSouls:

  • KILL: onKill (EntityDeathEvent) — adds souls when a player kills a living entity (see the listener; excludes some non-living cases).
  • MINING: onBlockBreak (BlockBreakEvent) — adds souls when breaking blocks that drop XP (exp > 0).
  • DEFENCE: onDefence (EntityDamageByEntityEvent) — defender gains souls when damaged (if configured).
  • FISHING: onPlayerFish (PlayerFishEvent) — when player catches a fish (State.CAUGHT_FISH).
  • BUILDING: onBlockPlace (BlockPlaceEvent) — adds souls on placing a block (if canBuild true). Notes:
  • Spawner-spawned mobs are tagged as "soulless" (SpawnerSpawnEvent / CreatureSpawnEvent) if spawner tracking is enabled; SoulHarvesterComponent.spawners controls inclusion.
  • World whitelist/blacklist is checked using SoulPowerManager.isWorldWhitelisted (matches names; isBlacklist flips meaning).

Applying upgrades and powers

  • After souls are added, SoulPowerManager.checkConditions() checks each configured upgrade in the item's SoulHarvesterComponent:
    • If the item's stored souls >= requiredSouls, it calls SoulHarvesterUpgrade.applyUpgrade(item, player).
  • applyUpgrade performs:
    • Chance check (Utils.Chance).
    • Verifies upgrade not already applied (checks item PDC "upgrades" list for the UUID).
    • Applies the upgrade action (attribute/enchant/model/name/lore/power/etc).
    • Writes applied upgrade marker to the item PDC (list under "upgrades") and, for soul powers, sets a boolean tag PDC.SetBoolean(item, soulPower, true).
    • Plays unlock-sound and unlock-particle if configured.
  • For POWER upgrades: SoulHarvesterUpgrade sets a PDC boolean for the power id; SoulPowerManager.getSoulPowers will detect powers present on items and expose them by id, which the SoulHarvesterListener may invoke when triggers occur.

Soul Powers (runtime-compiled powers)

  • Soul powers are arbitrary code pieces implementing SoulPower and annotated with @SoulPowerInfo.
  • When an upgrade sets soulPower to an id, the SoulPowerManager will include that power in lookups (getSoulPowers/getSoulPowers(player, type)).
  • When the referenced power triggers, SoulPowerCompiler (similar to AbilityCompiler) loads/executes the power by id.
  • SoulPowerInfo fields (type, cooldown, chance, failCooldown) control triggering semantics:
    • type: onAttack, onDefence, onKill, onEquip, etc.
    • cooldown: cooldown in seconds
    • chance: percent activation chance
    • failCooldown: whether to apply cooldown when chance check fails

Persistence & namespacing

  • Souls are stored on the item via PDC under key "souls".
  • Applied upgrade UUIDs are stored as a string list under PDC key "upgrades".
  • Each upgrade has a computed namespaced key / id available via SoulHarvesterUpgrade.getNamespacedId() and .getNamespacedKey() (used for PDC and attribute namespacing).
  • Do NOT change upgrade uniqueid after items have been distributed — editing uniqueid will prevent detecting previously applied upgrades (and may cause duplicate upgrades).

Permissions & protections

  • Soul Harvester mechanics respect protection hooks:
    • WorldGuard — checks build permission where applicable.
    • GriefPrevention — requires Build trust for claim-local actions.
  • Soul Harvester upgrades and powers run on server main thread when triggered — keep power code non-blocking.

Example: small soul-harvester config

soul-harvester:
 gain-method: KILL
 souls-per-gain: 1
 max-souls: 100
 spawners: false
 worlds:
  - world
 blacklist: false
 upgrades:
  quickstrike:
   uniqueid: b3f6c9d2
   type: ATTRIBUTE
   souls-required: 10
   chance: 100.0
   attribute:
    attribute: GENERIC_ATTACK_DAMAGE
    amount: 2.0
    operation: ADD_NUMBER
    slot: MAINHAND
  firebrand:
   uniqueid: 3a9f2c1b
   type: ENCHANTMENT
   souls-required: 50
   enchantment:
    enchant: FIRE_ASPECT
    level: 2
    override: true
  darkcall:
   uniqueid: 5d8e1f4a
   type: POWER
   souls-required: 80
   soul-power: darkcallPower

Testing checklist

  1. Add the configured item file under items/ and restart the server (or reload RareSpawns).
  2. Give the player the item (use /rarespawns.item or admin commands).
  3. Confirm the item has PDC "souls" when you add souls (use server-side debug or observe gameplay).
  4. Perform the configured gain actions (kill mobs / mine / fish / build) and verify souls increase.
  5. When threshold reached, confirm upgrade applies:
    • attribute/enchant/model/lore changes appear on the item
    • unlock sound/particles play for the player
    • for POWER types: after unlock, the power should appear in SoulPowerManager lookups and trigger according to SoulPowerInfo.
  6. Validate that applied upgrades are preserved when the item is moved/stored (they are written to the item's PDC).

Troubleshooting

  • Souls not accumulating:
    • Verify gain-method matches the action you're performing.
    • Confirm SoulHarvesterComponent.spawners is set appropriately if mobs are spawner-spawned.
    • Confirm the world whitelist/blacklist: SoulPowerManager.isWorldWhitelisted enforces this.
  • Upgrades not applying:
    • Check souls count on the item via debug or log; ensure souls >= souls-required.
    • Confirm upgrade chance (if <100) may fail probabilistically.
    • Ensure uniqueid is present; missing uniqueid is generated on load, but editing it later will cause issues.
  • Power not triggering:
    • Ensure the soul-power ID matches a compiled/available SoulPower class.
    • Check SoulPowerInfo for correct type (onAttack/onKill etc.) and cooldown/chance settings.
  • Duplicate/incorrect upgrades:
    • Verify upgrade uniqueid values are stable and not changed after items are issued.
    • Check PDC "upgrades" list contents for applied UUID markers.

Best practices & recommendations

  • Choose sensible max-souls and souls-per-gain values to avoid extremely long or trivially short progression.
  • Keep upgrade chains clear and incremental; large jumps in required souls frustrate players.
  • Make uniqueid values stable: generate UUIDs once and avoid editing them after distribution.
  • Test upgrades and soul powers on a staging server; do not deploy untrusted SoulPower code to production (powers are code that runs on your server).
  • Use unlock-sound/unlock-particle to give players clear feedback when upgrades apply.
  • Prefer whitelist world lists for production (explicitly list allowed worlds) to avoid accidental use in other worlds.

Developer references

  • Loading/compilation and runtime execution:
    • SoulHarvesterListener.java (events; schedules periodic checks)
    • SoulPowerManager.java (adds souls, manages cooldowns, checks/apply upgrades)
    • SoulHarvesterUpgrade.java (upgrade application logic; PDC usage)
    • SoulPowerCompiler / compilers/Compiler.java (compilation and runtime loading of powers)
  • Data persistence: persistentdatacontainer.PDC is used to store "souls" and applied upgrades on the item.

–]===========>

___⎛⎝ ≽ > ⩊ < ≼ ⎠⎞___"It's dangerous to go alone, take this."_____

🐲 RareSpawns Wiki

✅ Getting Started

⚙️ Configuration

🍳 Resources

🔌⚡ Supported Plugins (And why 🤔💭)

👑 Premium Features

</> For Developers

🔎 Tips

  • Use the search box above to quickly jump to a page.

Clone this wiki locally