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
9.1 KiB
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, which performs four jobs:
- Loads configuration from
config/soulsteal/config.yml. - Loads persistent player data from
config/soulsteal/soulsteal-data.json. - Instantiates the feature services.
- Registers command, tick, join, death, and disconnect handlers.
The main services are:
SoulService: balance reads and mutations.BountyService: bounty placement, expiry, and kill claims.TrackerCompassService: temporary tracking compasses for player kills.ShopService: server-side shop GUI and purchases.RewardService: validates and grants rewards from shop entries.PermissionService: permission lookups and fallback storage.HudService: scoreboard sidebar, leaderboard, and bounty bossbar.
Shared utilities:
SoulTexts: formatted feedback, success, warning, and error messages.DurationFormatter: 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:
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:
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:
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:
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:
Permissions
The mod checks permissions in two layers:
- External permission backends through the Fabric permissions API and optional LuckPerms integration.
- 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:
Command Reference
The root command has two aliases:
/souls/soul
Player Commands
/souls- Shows your current balance.
/souls balance- Same as
/souls.
- Same as
/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.
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.
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.
Data Flow
Player Join
When a player joins:
- Their name is recorded in persistent data.
- Their HUD state is refreshed.
- Any configured scoreboard or bossbar state is pushed to them.
Player Kill
When one player kills another player:
- The killer receives kill reward souls if enabled.
- Any matching bounties on the victim are claimed.
- The killer receives a tracker compass if the tracker feature is enabled.
Player Death
When a player dies:
- The configured death penalty is applied.
- If the death was not caused by another player, unclaimed bounties on the victim can be cleared.
Server Tick
On server tick:
- Tracker compasses are updated and expired compasses are removed.
- Bounty expirations are processed once per second.
- 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.