Soul Debt

Soul Debt is a configurable keep-inventory punishment mod for Minecraft 1.21.1 NeoForge.

Instead of deleting the entire inventory on death, Soul Debt makes players pay a debt: stored lives are consumed first, and if no lives are available, random eligible items and optionally XP are sacrificed.

Keep your loot. Pay your debt.

Why Soul Debt? ⚖️

🧭 Keeps survival progression moving without full inventory wipes.
💀 Makes death meaningful without turning keep-inventory into a free pass.
❤️ Adds a life economy through the Soul Apple.
🧳 Gives Wandering Traders and combat progression more value.
🌐 Works well for single-player, multiplayer servers, and curated modpacks.
🛠️ Uses a server-side config so pack makers can tune the experience.

Core Features ✨

Configurable life system with max lives and lives consumed per death.
Players keep inventory on death, but Soul Debt applies its own penalty logic.
Soul Apples grant stored lives when consumed.
Wandering Traders can sell marked Soul Apples.
Vanilla mobs killed by players can drop marked Soul Apples through configurable tiers.
Random item sacrifice when the player has no usable lives.
Optional XP loss when item sacrifice happens.
Protected item list for valuable items and backpack-style storage items.
Built-in HUD life counter with audiovisual feedback.

Soul Apple Sources 🍎

Soul Apples are special marked enchanted golden apples used by Soul Debt.

By default, they can be obtained in two ways:

🧑‍🌾 Buy them from a Wandering Trader.
⚔️ Kill configured vanilla mobs for a chance to drop them.

Mob drops are grouped into configurable tiers:

Tier	Default Chance	Default Amount
Common	1%	1
Medium	5%	1
Strong	10%	2
Elite	20%	2
Boss / Extreme Threat	100%	5

Mob drop tiers, chances, amounts, and enabled mobs can be changed in config/souldebt-server.toml.

Default Death Flow 💀

When a player dies:

Soul Debt captures the player's inventory and XP state.
The normal player drops are cleared.
The inventory is restored after death.
If the player has enough stored lives, lives are consumed.
If the player does not have enough lives, random eligible items are removed.
If enabled, XP is also reduced when item sacrifice happens.
The client HUD is synced with the updated life count.

Creative and spectator players are ignored by default, and the HUD is hidden while the local player is in creative or spectator mode.

Configuration 🛠️

The server config is generated at:

config/souldebt-server.toml

Main configurable areas:

Death penalty behavior.
Maximum stored lives.
Lives consumed per death.
Wandering Trader Soul Apple offer.
Soul Apple mob drop tiers.
Protected item IDs.

The generated config is intentionally focused on gameplay balance. HUD and audiovisual effect settings use internal defaults and are no longer exposed in the TOML.

Protected Items 🛡️

Soul Debt excludes protected items from random item sacrifice.

The default protection list includes high-value vanilla items such as netherite gear, elytra, mace, heavy core, nether star, dragon egg, dragon head, beacon, end crystal, enchanted golden apple, totem of undying, recovery compass, trial keys, and all shulker boxes.

It also includes compatibility-oriented protection for common backpack items from:

Travelers Backpack
Sophisticated Backpacks

The internal critical protection list is merged with the user's TOML list, so older configs still benefit from newly protected critical items.

Compatibility Notes 🔧

Soul Debt is server-authoritative for death handling and life accounting.
Designed for multiplayer and modpack usage with one shared server config.
Test carefully if you use other death overhaul, grave, corpse, or keep-inventory mods.
Naturally overlaps with mods such as Corpse, You Are in Grave Danger, and similar inventory-on-death systems.
Missing modded item IDs in the protected list are harmless; they only matter when those items exist in the current pack.

Documentation 📚

See Documentation.md for:

Complete mechanic breakdown.
Full TOML reference.
Balance preset examples.
Troubleshooting and FAQ.

Useful link:

🐛 GitHub Issues: https://github.com/II-mirai-II/Soul-Debt/issues