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, units are added to the first Soul Cage found in offhand, hotbar, then main inventory.

Drop Requirements

A soul can drop only when soul drops are enabled, the victim is allowed by whitelist/blacklist rules, PvP rules allow the drop, a living non-spectator player is within 30 blocks, the chance roll succeeds, and a soul tier can be selected.

Tiers

Soul orbs have four tiers:

• Small
• Medium
• Large
• Extra Large

The tier controls rendered size and the number of 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.

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.

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 and merges into the nearby group when possible.

The kept orb receives the combined units, updates its tier from the combined count, and refreshes its lifetime.

Lifetime And Collection

Soul orbs do not persist across restarts. They are removed if loaded from disk, if no living non-spectator player stays within 30 blocks, or if their lifetime expires.

If a player with a Soul Cage enters collection range, the orb homes toward the nearest eligible player. Within 1 block, it credits its stored units to the player's Soul Cage and removes itself.