darwincereska
84e05eff7f
- 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
277 lines
9.1 KiB
Markdown
277 lines
9.1 KiB
Markdown
# 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.
|