SoulLedger v0.5.1

─────────────────────────────────────────────────────────────

What is SoulLedger?

SoulLedger is a lightweight item ownership plugin for Spigot servers.
Unlike basic soulbound plugins that simply lock items to a player, SoulLedger treats each registered item as an asset with a passport — recording its origin, current owner, transfer history, and status.

Every bound item carries its identity with it across worlds, server restarts, and inventory changes — with no database required.

Perfect for RPG, Survival, Economy, and Roleplay servers that need:

• Proof of who owns an item
• An auditable record of every ownership change
• Protection against theft, duplication exploits, and inventory abuse
• A solid foundation for item-based economy systems

─────────────────────────────────────────────────────────────

Current Features

Ownership & Binding

• Bind any item to a specific player via command
• Bind to yourself or directly to another player
• Bind-on-pickup — items automatically bind to the first player who picks them up (configurable)
• Bind-on-use — items automatically bind when a player first right-clicks with them (configurable)
• Each bound item receives a unique Soul ID, owner name, and bind date — written visually into the item's lore
• Inspect the full ownership record of any bound item at any time
• Transfer ownership through transfer contracts — the recipient must accept before ownership changes
• Recipients can accept or decline pending transfer contracts
• Owners can lock items to prevent transfers until they explicitly unlock them
• Unbind items (admin action) — cleanly removes all ownership data and lore without touching original lines from other plugins

Listing & History

• /sl list — any player can list their own bound items without any extra permission
• /sl list <player> — admins can list another player's bound items
• /sl history — any player can view the transfer history of their own bound items
• /sl history <player> — admins can view transfer history for any player
• Each history entry shows the sender, receiver, and timestamp of every ownership change

Built-in Group Ownership

• Create and manage SoulLedger groups directly inside the plugin — no guild/faction dependency required
• Bind items to a group instead of a single player
• Transfer existing bound items from a player or group to another SoulLedger group
• Group members can access group-owned items
• Group managers can bind, transfer, lock, and manage group-owned items
• Groups are stored in groups.yml, keeping SoulLedger fully standalone and database-free

Protection System

• Prevent owners from accidentally dropping their bound items
• Prevent other players from picking up items that belong to someone else or to a group they are not part of
• Prevent bound items from being placed inside chests, barrels, or any container
• Hoppers and dispensers cannot steal or move bound items

Death Handling

• Keep on death — bound items automatically return to the owner's inventory on respawn (permission-based or global)
• Delete on death — bound items are permanently destroyed on death (permission-based or global)
• Both modes can be configured globally in config.yml or granted per-player via permissions

Item Passport

• Every bound item displays a clean lore section showing the current owner, Soul ID, and bind date
• Lore is automatically updated whenever ownership is transferred
• Locked items display their lock state in the item passport/lore
• Unbinding cleanly removes SoulLedger lore without touching lore from other plugins

Administration

• Hot reload — apply config changes without restarting the server
• Debug mode toggle — detailed console logging for diagnostics, persisted to disk
• Full tab completion for all commands
• All messages fully configurable in messages.yml
• All behavior settings configurable in config.yml
• Versioned config/message migration — existing files are backed up and regenerated from the newest commented templates
• Transfer contract timeout configurable in config.yml
• Per-player bind limits via permission nodes (e.g. soulledger.limit.5)

─────────────────────────────────────────────────────────────

Commands

Main command: /soulledger — Aliases: /sl, /soul


─────────────────────────────────────────────────────────────

Permissions


─────────────────────────────────────────────────────────────

Configuration

SoulLedger uses two separate files for clean organization:

config.yml — Server behavior settings:

• Enable or disable drop prevention for bound items
• Enable or disable pickup prevention by non-owners
• Enable or disable container and hopper storage prevention
• Global keep-on-death and delete-on-death toggles
• Bind-on-pickup — automatically bind items when first picked up (on/off)
• Bind-on-use — automatically bind items on first right-click (on/off)
• Group ownership — enable/disable built-in group item ownership
• Group-owned item keep-on-death behavior
• Transfer contract timeout in seconds
• Debug mode on/off

messages.yml — All player-facing messages:

• Every message is fully customizable
• Supports & color codes (&6, &a, &c, etc.)
• Supports placeholders: {player}, {item}, {from}, {target}, {label}, {group}, {action}, {id}, {date}, {type}, {status}, {locked}, {count}, {entry}, {max}
• Customize the plugin prefix, all notifications, inspect lines, list/history output, and more

groups.yml — Built-in group ownership data:

• Stores SoulLedger group IDs, display names, owners, members, and managers
• No database required
• Reloadable with /sl reload

Safe file updates

• config.yml and messages.yml include version fields
• Older files are backed up as config.old-vX.yml and messages.old-vX.yml
• New files are regenerated from the newest commented templates
• Existing compatible settings/messages are copied back into the new files

─────────────────────────────────────────────────────────────

Compatibility & Requirements


─────────────────────────────────────────────────────────────

Recommended Use Cases

• RPG servers — Register rare weapons, artifacts, and quest items with a verified owner
• Survival servers — Protect players' most valuable gear from theft and accidental drops
• Economy servers — Establish a clear chain of ownership for traded goods
• Roleplay servers — Give items a history and identity tied to characters
• Guild/Faction-style servers — Share ownership of important items through SoulLedger's built-in groups
• Event servers — Award unique items to winners that cannot be stolen or duplicated

─────────────────────────────────────────────────────────────

Planned Features / Roadmap

Completed items are marked below; remaining items are planned for future versions.

Version 0.5.x

• Transfer contracts — recipient must accept before ownership changes (Done in 0.5)
• Item lock — owner can lock an item to prevent transfers without explicit unlock (Done in 0.5)
• Multi-owner support through built-in SoulLedger groups (Done in 0.5.1)
• PlaceholderAPI integration (%soulledger_item_owner%)
• Import tool for legacy soulbound plugins
• Compatibility with popular custom item plugins: ItemsAdder, Oraxen, MMOItems, SlimeFun, ExecutableItems

Version 1.0

• Optional database storage (SQLite / MySQL) for large-scale audit logs
• Web dashboard for server admins to browse item ownership history
• Economy plugin integration for item-secured systems

─────────────────────────────────────────────────────────────

Final Notes

SoulLedger stores all ownership data directly inside the item using Minecraft's built-in data system.
This means there is no separate database to set up for normal use.
Item data travels with the item across worlds and server restarts automatically.

This is version 0.5.1 — stable and production-ready for all features listed above.
Future updates will be released progressively as outlined in the roadmap.