OverflowClaim v1.0

# OverflowClaim BuiltByBit Resource Description
## Suggested Resource Title
OverflowClaim - Premium Reward Mailbox | No Lost Rewards | GUI Inbox | File/SQLite/MySQL | 1.21-1.21.11
## Suggested Short Tagline
Stop players losing crate, vote, store, event, and admin rewards when their inventory is full.
## Suggested Tags
rewards, crate rewards, vote rewards, mailbox, claim, inventory full, anti loss, admin tools, mysql, sqlite, paper, spigot, bukkit, 1.21+
## Paste-Ready BuiltByBit Description

---

What Is OverflowClaim?
OverflowClaim is a focused Minecraft plugin that protects players from losing rewards when their inventory is full.
When a reward cannot safely fit into a player's inventory, OverflowClaim stores the undelivered item in a persistent claim mailbox. The player can collect it later through plugin-specific commands or a clean chest-style GUI.
This is perfect for:

• Crate rewards
• Vote rewards
• Store or webshop rewards
• Donor rewards
• Event prizes
• Admin compensation
• Offline gifts
• Returned items from other plugins
• Command-based reward systems
• Any server workflow that gives items to players

OverflowClaim is not a backpack plugin, not an RPG storage system, and not a generic reward core. It is intentionally focused on one job: preventing reward loss safely and professionally.

---

Why Servers Need This
On many servers, reward delivery can go wrong when a player's inventory is full. Depending on the plugin or setup, items may be dropped on the ground, partially delivered, silently lost, or never given at all.
That is frustrating for players and painful for staff.
OverflowClaim solves this by giving your server a durable overflow system:

• If an item fits, it can be delivered normally by your reward workflow.
• If an item cannot fit, the undelivered reward can be queued safely.
• Players can open their inbox and collect rewards later.
• Staff can inspect, send, clear, remove, expire, export, and audit entries.
• Server owners can customize commands, aliases, messages, GUI layout, expiry rules, storage, sources, and safety behavior.

The result is simple: fewer support tickets, fewer angry players, and fewer missing reward problems.

---

Core Features

• Persistent reward mailbox - queued entries are stored by player UUID.
• No database required by default - file storage works out of the box.
• SQLite support - local database storage for admins who prefer a database file.
• MySQL support - shared storage option for multi-server networks.
• Safe offline queueing - queue rewards even when the player is offline.
• Configurable GUI inbox - chest-style menu with pages, buttons, filler, lore, sorting, and source filters.
• Separate owner/admin GUI panel - configurable panel for stats, exports, purge, reload, debug, and quick testing.
• Whole-entry claiming - entries are only claimed when they safely fit.
• Collect all command - players can claim every fitting entry in one action.
• Source tagging - track where rewards came from, such as crate, vote, admin, webshop, event, or custom plugin sources.
• Expiry system - global expiry, per-source expiry, permanent sources, cleanup, and audit support.
• Audit history - track queued, claimed, expired, admin sent, removed, cleared, and collect-for actions.
• Admin tools - inspect players, send rewards, queue held items, clear mailboxes, export data, and more.
• Command conflict protection - uses namespaced commands instead of risky generic roots like /claim.
• Configurable commands - root command, aliases, subcommands, help text, usage, and tab completion are configurable.
• Optional PlaceholderAPI support - works fully without PlaceholderAPI installed.
• Developer API - public Java API and custom Bukkit events for integrations.
• No NMS - built with Bukkit API-facing behavior for safer 1.21.x compatibility.

---

Default Commands Are Conflict-Safe
OverflowClaim does not use /claim by default.
Generic commands like /claim, /mail, /reward, /rewards, and /inbox often conflict with land claim plugins, mail plugins, crate plugins, and reward systems. OverflowClaim avoids that problem by using plugin-specific command roots:

• /overflowclaim
• /oc
• /ocmail

Aliases are configurable. If a configured alias conflicts with another plugin, OverflowClaim is designed to continue startup and log a clean warning instead of crashing the server.

---

Player Commands
All labels can be renamed in the configuration.

---

Admin Commands
Console can use admin commands where safe. Player-only commands, such as the GUI inbox and givehand behavior, correctly require a player sender.

---

Configurable GUI Inbox
OverflowClaim includes a chest-style GUI designed for easy player claiming.
The GUI supports:

• Configurable title
• Configurable rows
• Configurable slot layout
• Filler items
• Empty-state item
• Next page button
• Previous page button
• Refresh button
• Sort button
• Filter button
• Info/help button
• Close button
• Queued item display lore
• Click instruction text
• Source display formatting
• Expiry display formatting
• Pagination
• Source filtering
• Sorting

Each queued item can show useful information such as:

• Item name
• Amount
• Source
• Received time
• Expiry or permanent status
• Unique entry ID
• Click instructions

The GUI is built with safety in mind and blocks normal menu item movement, decorative item taking, drag abuse, shift-click abuse, number-key swaps, and hotbar swap behavior.

---

Owner/Admin Panel
OverflowClaim includes a separate owner/admin GUI panel so staff do not need to remember every maintenance command during normal operation.
Open it with:
Default panel shortcuts include:

• /overflowclaim panel
• /overflowclaim adminpanel
• /overflowclaim owner
• /overflowclaim ownergui

The admin panel can include buttons for:

• Global mailbox statistics
• CSV export
• Expired-entry purge
• Plugin reload
• Runtime debug toggle
• Opening your own test inbox
• Help
• Close

Every admin panel button is configurable in gui.yml, including slot, material, amount, display name, lore, and enabled state.

---

Storage Options
OverflowClaim supports three storage modes:
File storage is enabled by default:
SQLite is enabled by changing the storage type:
MySQL is enabled by changing the storage type and filling in connection details:

---

Source Tags
Every queued reward has a source string. This makes it easier to filter, audit, expire, and understand where rewards came from.
Example sources:

• crate
• vote
• event
• admin
• voucher
• webshop
• command
• compensation
• plugin:exampleplugin
• auction-return

Sources can have custom display names, colors, expiry rules, aliases, and filtering behavior.

---

Expiry System
OverflowClaim includes a configurable expiry system so servers can control how long rewards remain claimable.
Supported expiry behavior:

• Global default expiry
• Per-source expiry overrides
• Permanent sources
• Permission-based expiry bypass
• Manual expiry command
• Automatic cleanup task
• Manual purge command
• Audit records for expired entries
• Configurable expiry lore/display

Examples:

• Vote rewards expire after 7 days.
• Crate rewards expire after 30 days.
• Store purchases are permanent.
• Admin compensation never expires.

---

Queue Limits
OverflowClaim includes queue limits to protect your server from unlimited pending data.
Configurable options include:

• Max entries per player
• Max total queued items per player
• Permission-based limit overrides
• Bypass permission
• Full-queue behavior

Possible full-queue behaviors include:

• Reject the new entry
• Replace the oldest entry
• Drop to world, if explicitly configured
• Log warning only

The safe default is to reject instead of dropping rewards on the ground.

---

Anti-Dupe And Safety Design
OverflowClaim treats reward safety as a core feature, not an afterthought.
Safety behavior includes:

• Per-player claim locks
• Whole-entry claiming
• No async inventory mutation
• No removing entries before transfer resolution
• Rollback handling if a storage mark fails after inventory transfer
• Full-inventory checks before claiming
• Non-fitting entries remain queued
• GUI click cancellation
• Drag prevention
• Shift-click prevention
• Number-key swap prevention
• Hotbar swap prevention
• Rapid-click protection behavior
• Corrupted entry validation
• Invalid item handling
• Safe shutdown wait for pending writes
• Audit trail for important actions

The claim strategy is intentionally conservative: if a queued item cannot fit safely, it stays queued.

---

PlaceholderAPI Support
PlaceholderAPI is optional. OverflowClaim works fully without it.
Available placeholders:

• %overflowclaim_pending_entries%
• %overflowclaim_pending_items%
• %overflowclaim_has_pending%
• %overflowclaim_oldest_age%
• %overflowclaim_newest_age%
• %overflowclaim_pending_sources%

If PlaceholderAPI is not installed, OverflowClaim simply disables placeholder support cleanly.

---

Developer API
OverflowClaim includes a public Java API for plugin developers who want to queue or inspect rewards from their own plugins.
API methods include:

• queueItem(Player player, ItemStack item, String source)
• queueItem(UUID uuid, ItemStack item, String source)
• queueItems(UUID uuid, Collection<ItemStack> items, String source)
• getPendingEntries(UUID uuid)
• getPendingEntryCount(UUID uuid)
• getPendingItemCount(UUID uuid)
• claimAll(Player player)
• removeEntry(UUID uuid, String entryId)
• clearEntries(UUID uuid)

Custom events include:

• OverflowClaimQueueEvent
• OverflowClaimCollectEvent
• OverflowClaimExpireEvent
• OverflowClaimInspectEvent

This makes OverflowClaim useful for crate plugins, vote systems, custom reward plugins, server stores, event managers, and compensation tools.

---

Permissions
Core player permissions:

• overflowclaim.use
• overflowclaim.inbox
• overflowclaim.collectall
• overflowclaim.notify
• overflowclaim.inspect.self

Admin permissions:

• overflowclaim.admin
• overflowclaim.admin.panel
• overflowclaim.admin.reload
• overflowclaim.admin.inspect
• overflowclaim.admin.history
• overflowclaim.admin.send
• overflowclaim.admin.givehand
• overflowclaim.admin.clear
• overflowclaim.admin.remove
• overflowclaim.admin.expire
• overflowclaim.admin.collectfor
• overflowclaim.admin.stats
• overflowclaim.admin.debug
• overflowclaim.admin.purge
• overflowclaim.admin.export

Bypass permissions:

• overflowclaim.bypass.limit
• overflowclaim.bypass.expiry

Example LuckPerms setup for players:
Example LuckPerms setup for admins:

---

Supported Platforms And Versions
Supported server platforms:

• Bukkit-compatible servers
• Spigot
• Paper

Supported Minecraft versions:

• 1.21
• 1.21.1
• 1.21.2
• 1.21.3
• 1.21.4
• 1.21.5
• 1.21.6
• 1.21.7
• 1.21.8
• 1.21.9
• 1.21.10
• 1.21.11

Implementation notes:

• One jar
• No NMS
• No CraftBukkit internals
• No hardcoded version packages
• No required PlaceholderAPI
• No required Vault
• No required paid services

---

Runtime Testing
The final jar was runtime-tested on separate official Paper servers:
Tested behaviors included:

• Plugin startup
• Config generation
• File storage initialization
• Command registration
• Aliases
• Offline queueing
• Inspect
• History
• Stats
• Export
• Clear
• Reload
• Invalid material handling
• Manual expiry purge
• Clean shutdown
• Log scan for plugin errors

Additional Paper 1.21.11 testing covered:

• SQLite mode startup
• SQLite database creation
• Real joined bot/player command testing
• GUI open
• GUI click claiming
• Full-inventory claim protection
• Restart persistence

MySQL support is included for network use. As with any production MySQL plugin, server owners should test their own host, credentials, firewall, and backup process before moving live reward data.

---

Configuration Files
OverflowClaim generates multiple clear configuration files:

• config.yml - general behavior, commands, aliases, queue rules, expiry, sources, notifications, safety, history, and startup behavior.
• messages.yml - player/admin messages, command feedback, errors, history lines, stats lines, and help text.
• gui.yml - GUI title, rows, layout, buttons, filler, empty state, lore, page controls, sort/filter buttons, and click instructions.
• storage.yml - file, SQLite, and MySQL storage settings.

The plugin is designed for buyer customization instead of hardcoded server behavior.

---

Quick Installation

1. Stop your server.
2. Place OverflowClaim-1.0.0.jar into your plugins folder.
3. Start your server once.
4. Edit plugins/OverflowClaim/config.yml, messages.yml, gui.yml, and storage.yml.
5. Restart the server or run /overflowclaim reload.
6. Test with /overflowclaim send <player> diamond 1 admin.
7. Open the inbox with /overflowclaim inbox or /oc inbox.

File storage works immediately. SQLite and MySQL can be enabled later if needed.

---

Recommended Use Cases
Crate Servers
Prevent rare crate rewards from being lost when players open crates with a full inventory.
Vote Servers
Queue vote rewards safely while players are offline or full.
SMP Servers
Handle event rewards, admin compensation, returned items, and community prizes without unsafe drops.
Network Servers
Use MySQL so multiple servers can access shared pending reward mailboxes.
Store/Webshop Servers
Queue purchased item rewards with clear source tags such as webshop, store, or donor.

---

What OverflowClaim Is Not
OverflowClaim is intentionally focused.
It is not:

• A backpack plugin
• A player vault plugin
• A land claim plugin
• A generic /claim plugin
• An economy core
• An auto-sell plugin
• An RPG storage upgrade system

That focus is what makes it safer and easier to configure for reward overflow use.

---

FAQ
Does this use /claim by default?
No. The default commands are /overflowclaim, /oc, and /ocmail to avoid conflicts.
Does it require MySQL?
No. File storage is the default and requires no database setup.
Can I use SQLite?
Yes. Set storage.type to sqlite.
Can I use this on a network?
Yes. MySQL is the intended storage mode when multiple servers need shared pending mailbox data.
Does it require PlaceholderAPI?
No. PlaceholderAPI is optional.
Does it require Vault?
No.
Does it use NMS?
No. OverflowClaim avoids NMS and CraftBukkit internals.
What happens if the player's inventory is still full?
The entry stays queued. OverflowClaim does not delete it just because it cannot fit.
Can staff send rewards to offline players?
Yes. Entries are stored by UUID.
Can I customize the GUI?
Yes. GUI rows, title, layout, buttons, filler, lore, page controls, empty state, and item display formatting are configurable.
Can I rename commands?
Yes. The root command, aliases, and subcommand labels are configurable.

---

Support Notes
When requesting support, please provide:

• Server platform, such as Paper or Spigot
• Exact Minecraft version
• OverflowClaim version
• Storage mode: file, SQLite, or MySQL
• Relevant config sections
• Any clean console warning or error
• Steps to reproduce the issue

For production servers, always back up your storage before major configuration changes or updates.

---

## Optional Very Short Sales Summary
OverflowClaim is a premium reward mailbox plugin for Bukkit, Spigot, and Paper 1.21-1.21.11. It prevents reward loss when player inventories are full by storing undelivered items in a persistent claim inbox. It includes a configurable GUI, conflict-safe commands, file/SQLite/MySQL storage, offline queueing, expiry, audit history, PlaceholderAPI placeholders, admin tools, and a developer API. File storage works out of the box with no database required, while MySQL is available for multi-server networks.