feat(commands): add admin tracker compass grant command and document it

- add /souls tracker give <player> <target> as an admin-only command - reuse the existing TrackerCompassService so the command uses the same tracker behavior and duration as kill-granted compasses - gate the command behind soulsteal.admin - update README.md command reference - update docs/PROJECT.md with tracker compass behavior and the new admin command - keep the implementation scoped to the command layer without changing the tracker service API
2026-05-08 15:42:12 -04:00
parent 859e1bc21f
commit 84e05eff7f
14 changed files with 1044 additions and 351 deletions
@@ -0,0 +1,276 @@
+# 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.