# Soul Steal Project Documentation

## Overview

Soul Steal is a server-side Fabric mod that implements a soul economy, player bounties, tracker compasses, a vanilla-style shop GUI, optional HUD elements, and permission-backed admin controls.

The mod is built to run entirely on the server. Players do not need a client mod to use the commands or the shop.

## Runtime Architecture

The entry point is [`SoulStealMod`](../src/main/java/com/g2806/soulsteal/SoulStealMod.java), which performs four jobs:

1. Loads configuration from `config/soulsteal/config.yml`.
2. Loads persistent player data from `config/soulsteal/soulsteal-data.json`.
3. Instantiates the feature services.
4. Registers command, tick, join, death, and disconnect handlers.

The main services are:

- [`SoulService`](../src/main/java/com/g2806/soulsteal/service/SoulService.java): balance reads and mutations.
- [`BountyService`](../src/main/java/com/g2806/soulsteal/service/BountyService.java): bounty placement, expiry, and kill claims.
- [`TrackerCompassService`](../src/main/java/com/g2806/soulsteal/service/TrackerCompassService.java): temporary tracking compasses for player kills.
- [`ShopService`](../src/main/java/com/g2806/soulsteal/service/ShopService.java): server-side shop GUI and purchases.
- [`RewardService`](../src/main/java/com/g2806/soulsteal/service/RewardService.java): validates and grants rewards from shop entries.
- [`PermissionService`](../src/main/java/com/g2806/soulsteal/service/PermissionService.java): permission lookups and fallback storage.
- [`HudService`](../src/main/java/com/g2806/soulsteal/service/HudService.java): scoreboard sidebar, leaderboard, and bounty bossbar.

Shared utilities:

- [`SoulTexts`](../src/main/java/com/g2806/soulsteal/util/SoulTexts.java): formatted feedback, success, warning, and error messages.
- [`DurationFormatter`](../src/main/java/com/g2806/soulsteal/util/DurationFormatter.java): human-readable duration strings.

## Feature Summary

### Soul Economy

Players have a soul balance stored per UUID.

- Killing another player can grant souls.
- Dying can remove souls using configurable flat and percentage penalties.
- Transfers between players can be enabled or disabled in config.
- Admin commands can set, add, or remove balances directly.

Implemented by:

- [`SoulService`](../src/main/java/com/g2806/soulsteal/service/SoulService.java)
- [`SoulCommandRegistrar`](../src/main/java/com/g2806/soulsteal/command/SoulCommandRegistrar.java)

### Bounties

Players can place timed bounties on other players using their souls as the payment source.

Behavior:

- Placement is bounded by min/max value, min/max duration, cooldowns, and active bounty limits.
- Killing the target claims all active bounties on that target.
- If a bounty expires, the target receives a configured survivor payout.
- Bounties are cleared if the target dies to non-player damage and no killer claims them.

Implemented by:

- [`BountyService`](../src/main/java/com/g2806/soulsteal/service/BountyService.java)
- [`SoulStealMod`](../src/main/java/com/g2806/soulsteal/SoulStealMod.java)

### Tracker Compasses

When enabled, killing a player grants a temporary tracker compass.

Behavior:

- The compass tracks the killed player using lodestone-tracker data.
- The item stores target UUID, target name, and expiration time in custom NBT.
- Expired compasses are removed during server ticks.
- Optional behavior can remove the compass if the target is offline.

Admins can also grant a tracker compass directly with `/souls tracker give <player> <target>`. This uses the same tracker data and duration as the kill-granted version.

Implemented by:

- [`TrackerCompassService`](../src/main/java/com/g2806/soulsteal/service/TrackerCompassService.java)

### Shop

The shop is a chest-based GUI rendered entirely with vanilla screen handler APIs.

Behavior:

- The home view lists categories with pagination.
- Category views list entries with pagination.
- Item entries can be direct purchases or quantity-select purchases.
- Purchases can be repeatable or single-unlock.
- Cooldowns can be stored per entry per player.
- Rewards can include items, effects, commands, and permissions.

Implemented by:

- [`ShopService`](../src/main/java/com/g2806/soulsteal/service/ShopService.java)
- [`RewardService`](../src/main/java/com/g2806/soulsteal/service/RewardService.java)
- [`SoulShopScreenHandler`](../src/main/java/com/g2806/soulsteal/shop/SoulShopScreenHandler.java)
- [`ShopCatalog`](../src/main/java/com/g2806/soulsteal/shop/ShopCatalog.java)

### HUD

The HUD layer is optional and configurable per player.

Behavior:

- Scoreboard sidebar can be enabled globally and toggled per player.
- Leaderboard pages are built from stored player names and balance values.
- Wanted-player bossbars show bounty value and remaining time.

Implemented by:

- [`HudService`](../src/main/java/com/g2806/soulsteal/service/HudService.java)

### Permissions

The mod checks permissions in two layers:

1. External permission backends through the Fabric permissions API and optional LuckPerms integration.
2. Internal fallback storage persisted in `soulsteal-data.json`.

This allows reward-granted permissions and admin nodes to keep working even without an external permission mod.

Implemented by:

- [`PermissionService`](../src/main/java/com/g2806/soulsteal/service/PermissionService.java)

## Command Reference

The root command has two aliases:

- `/souls`
- `/soul`

### Player Commands

- `/souls`
  - Shows your current balance.
- `/souls balance`
  - Same as `/souls`.
- `/souls balance <player>`
  - Shows another player’s balance.
- `/souls pay <player> <amount>`
  - Transfers souls to another player.
- `/souls shop [category]`
  - Opens the shop GUI.
- `/souls bounty place <player> <amount> [durationSeconds]`
  - Places a bounty.
- `/souls bounty list [player]`
  - Lists active bounties.
- `/souls scoreboard`
  - Shows scoreboard visibility state.
- `/souls scoreboard toggle`
  - Toggles the player’s scoreboard preference.
- `/souls scoreboard on`
  - Forces scoreboard visibility on.
- `/souls scoreboard off`
  - Forces scoreboard visibility off.
- `/souls top [page]`
  - Shows leaderboard pages.
- `/souls tracker give <player> <target>`
  - Gives a tracker compass to one player that points at another player.

### Admin Commands

- `/souls reload`
  - Reloads config and shop definitions.
- `/souls set <player> <amount>`
  - Sets a balance directly.
- `/souls add <player> <amount>`
  - Adds souls to a balance.
- `/souls take <player> <amount>`
  - Removes souls from a balance.

Permission defaults and node names are configured in `config.yml`.

## Configuration Files

### `config/soulsteal/config.yml`

Primary configuration file. It controls:

- Economy values
- Death penalties
- Transfer rules
- Bounty limits and payouts
- Tracker compass behavior
- Shop UI defaults
- HUD toggles and titles
- Permission node names

The schema is defined in [`SoulStealConfig`](../src/main/java/com/g2806/soulsteal/config/SoulStealConfig.java).

### `config/soulsteal/shop.yml`

Shop catalog definition. It controls:

- Shop title and layout
- Category list
- Entry pricing
- Entry cooldowns
- Reward definitions
- Optional custom quantity selector behavior

The catalog is loaded through [`ConfigBundle`](../src/main/java/com/g2806/soulsteal/config/ConfigBundle.java).

### `config/soulsteal/soulsteal-data.json`

Persistent runtime data. It stores:

- Player soul balances
- Active bounties
- Bounty placement cooldowns
- Shop unlocks
- Shop purchase cooldowns
- Permission fallback grants
- Player name history
- Scoreboard visibility preferences

Loaded and saved by [`SoulStealDataStore`](../src/main/java/com/g2806/soulsteal/data/SoulStealDataStore.java).

## Data Flow

### Player Join

When a player joins:

1. Their name is recorded in persistent data.
2. Their HUD state is refreshed.
3. Any configured scoreboard or bossbar state is pushed to them.

### Player Kill

When one player kills another player:

1. The killer receives kill reward souls if enabled.
2. Any matching bounties on the victim are claimed.
3. The killer receives a tracker compass if the tracker feature is enabled.

### Player Death

When a player dies:

1. The configured death penalty is applied.
2. If the death was not caused by another player, unclaimed bounties on the victim can be cleared.

### Server Tick

On server tick:

1. Tracker compasses are updated and expired compasses are removed.
2. Bounty expirations are processed once per second.
3. HUD elements are refreshed.

### Server Shutdown

On shutdown:

- Persistent data is saved to disk.

## Project Structure

- `src/main/java/com/g2806/soulsteal/`
  - Bootstrap, commands, services, config, data, shop, and utilities.
- `src/main/resources/`
  - Fabric metadata and resource files.
- `build.gradle`
  - Fabric Loom build configuration.

## Development Notes

- The mod targets Java 21.
- It is structured as a server-only feature set, so most behavior is driven by server lifecycle events.
- Persistence is intentionally simple: one JSON data file and YAML-driven configuration.
- External integrations are reflected through reflection-based checks so the mod can run without hard dependencies on permission backends.