SoulLedger v0.4

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

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 to any player — online or offline — while keeping the full history log
• 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
• 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
• 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)
• 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}, {id}, {date}, {type}, {status}, {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

The following features are planned for future versions and are not yet available.

Version 0.5

• Transfer contracts — recipient must accept before ownership changes
• Item lock — owner can lock an item to prevent transfers without explicit unlock
• 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 database to set up, no external files to manage, and no performance overhead.
Item data travels with the item across worlds and server restarts automatically.

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

For issues, suggestions, or support, please use the Discussion tab on this page.