SoulLedger v0.5

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

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

Protection System

• Prevent owners from accidentally dropping their bound items
• Prevent other players from picking up items that belong to someone else
• 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
• 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)
• 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}, {id}, {date}, {type}, {status}, {locked}, {count}, {entry}, {max}
• Customize the plugin prefix, all notifications, inspect lines, list/history output, and more

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

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
• 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

• 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 (guilds / factions)
• 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 — stable and production-ready for all features listed above.
Future updates will be released progressively as outlined in the roadmap.