# Soul Steal

Soul Steal is a server-side Fabric mod that adds a configurable soul economy, bounties, tracker compasses, and a vanilla-compatible soul shop.

Full project documentation is available in [docs/PROJECT.md](docs/PROJECT.md).

## Requirements

| Requirement | Value |
| --- | --- |
| Minecraft | 1.21.11 |
| Loader | Fabric Loader 0.19.2 |
| Fabric API | 0.141.3+1.21.11 |
| Java | 21 |

## How It Works

Players gain souls for killing other players and lose souls whenever they die, with all values driven by `config.yml`. The bounty system lets players spend souls to place timed bounties that pay killers on claim or reward survivors on expiry, while wanted players can see a bounty timer bossbar. The optional HUD sidebar can be toggled per player, and `/souls top` shows the configured leaderboard. The shop is a server-side chest GUI with a category home page, arrow pagination, optional reward display names, and item listings that can open a quantity selector.

## Commands

| Command | Permission | Description |
| --- | --- | --- |
| `/souls` | All players | Shows your current soul balance. |
| `/souls balance <player>` | Admins / `soulsteal.admin` or `soulsteal.admin.balance.others` | Views another player's soul balance. |
| `/souls pay <player> <amount>` | All players | Transfers souls to another player if transfers are enabled. |
| `/souls shop [category]` | All players | Opens the soul shop GUI, optionally on a specific category. |
| `/souls bounty place <player> <amount> [durationSeconds]` | All players | Places a timed bounty on another player. |
| `/souls bounty list [player]` | All players | Lists active bounties globally or for one target. |
| `/souls scoreboard [toggle|on|off]` | All players | Toggles the optional Soul Steal sidebar HUD for your player. |
| `/souls top [page]` | All players | Shows the soul leaderboard using the configured page size. |
| `/souls tracker give <player> <target>` | Admins / `soulsteal.admin` | Gives a tracker compass to one player that points at another player. |
| `/souls contracts` | All players | Opens the contract browser GUI. |
| `/souls contracts selected` | All players | Shows the currently selected contract and progress. |
| `/souls contracts clear` | All players | Clears your selected contract. |
| `/souls reload` | Admins / `soulsteal.admin` or `soulsteal.admin.reload` | Reloads `config.yml` and `shop.yml` without restarting the server. |
| `/souls set|add|take <player> <amount>` | Admins / `soulsteal.admin` or the matching `soulsteal.admin.balance.*` node | Directly manages a player's soul balance. |

## Configuration

| File | Purpose |
| --- | --- |
| `config/soulsteal/config.yml` | Economy values, death penalties, bounty limits, HUD toggles, leaderboard size, bossbar text, and command permission nodes. |
| `config/soulsteal/shop.yml` | Shop categories, GUI entries, prices, cooldowns, reward display names, and optional custom-amount settings for item listings. |
| `config/soulsteal/catalog.yml` | Mining and hunting contract entries, internal ids, player-facing names, icons, targets, progress amounts, and rewards. |
| `config/soulsteal/soulsteal-data.json` | Persistent balances, active bounties, cooldowns, unlocks, internal permission fallback storage, saved player names, and scoreboard preferences. |