Souls

Souls are collected through custom soul orbs and stored in the Soul Cage.

Soul Cage Storage

The Soul Cage stores a single total called SoulTotal. Its tooltip shows:

Souls: <amount>

When a soul orb reaches a player, the units are added to the first Soul Cage found in this order:

1. Offhand
2. Hotbar
3. Main inventory

Drop Requirements

Soul drops are controlled by server config and several hard safety rules.

A soul can drop only when:

• Soul drops are enabled.
• The victim is allowed by whitelist/blacklist rules.
• The victim is not a player unless PvP drops are enabled.
• A living, non-spectator player is within 30 blocks of the death location.
• The drop chance roll succeeds.
• A soul tier can be selected for the victim.

Tiers

Soul orbs have four tiers:

• Small
• Medium
• Large
• Extra Large

The tier controls the rendered size and the number of soul units credited to the Soul Cage.

Tier Selection Models

HP Thresholds

The default model compares the victim's max hearts to tier minimums and chooses the highest matching tier.

Default minimum hearts:

Ratio

The ratio model converts max HP into units:

units = floor(maxHp * hpToSoulsRatio)

It then chooses the largest tier whose configured unit threshold is less than or equal to that value.

Default tier units:

Clumping

Soul orbs clump together like XP clump mods.

When a new orb would spawn, the mod checks for existing soul orbs within 3 blocks. If it finds one, it merges the new units into the nearby group instead of spawning another orb.

The kept orb:

• Receives the combined units.
• Updates its tier from the combined unit count.
• Refreshes its lifetime from the current moment.

Lifetime And Despawn

Soul orbs do not persist across restarts.

They are also removed when:

• They were somehow loaded from disk.
• No living, non-spectator player is within 30 blocks.
• Their configured lifetime expires.

Setting the configured lifetime to 0 makes newly spawned soul orbs permanent while the world is running, but they still do not persist across restarts.

Homing And Collection

Soul orbs idle by hovering around their spawn height. If a player with a Soul Cage enters the configured collection range, the orb starts homing toward the nearest eligible player.

Once homing starts, the orb continues accelerating toward that target. If it gets within 1 block, it credits its stored units to the player's Soul Cage and removes itself.