RandomItems999

Features

• Automatic Item Distribution: Give random items to every online player on a configurable interval
• Rarity Tiers: Sort items into tiers such as Common, Rare, Epic and Legendary, each with its own weight, colour, name and drop chance
• Rare Drop Celebrations: Announce rare finds in chat and show a title, play a sound and launch a firework for the lucky player
• Custom Items: Create any number of special items with their own name, lore, rarity and effect, including Instant TNT, a Lightning Stick and a Fireball Wand
• Visual Countdown: Boss bar showing the time until the next item distribution
• Statistics: Track how many items each player has received, how many were rare and which item they got last
• Leaderboard: Compare the top ten collectors on the server
• Drop History: Review the most recent drops, newest first
• Give Command: Hand out random items to a chosen player on demand
• Server Overview: Check the current status, interval, next drop, active worlds and rarity chances at any time
• Pause Functionality: Temporarily pause item distribution for events or server maintenance
• Inventory Handling: Choose whether a player with a full inventory skips the item, gets it dropped at their feet, or has it held until there is space
• World-Specific Settings: Configure which worlds receive items and where announcements appear
• Player Controls: Players can toggle the boss bar visibility for themselves
• Excluded Items: Keep dangerous or unwanted items out of the drop pool
• Configurable Interval: Set the time between item distributions, in game or in the configuration
• Everything is Kept: Statistics, recent drops, boss bar preferences and held items survive reloads and restarts

Commands

Permissions

• randomitems.admin - Allows starting, stopping, pausing, changing the interval, giving items, checking other players' statistics and reloading the configuration (Default: OP)
• Every player can use /randomitem togglebossbar, /randomitem stats, /randomitem info, /randomitem history and /randomitem top without any permission

Configuration

Every option lives in the plugin configuration and can be changed and reloaded while the server is running:

• interval: Time in seconds between item distributions. It must be 1 or higher and is saved when changed in game
• distribution-worlds: Worlds that receive items. Leave the list empty to use every world
• excluded-materials: Items that are never handed out by the drop pool, even when they are listed inside a rarity tier
• full-inventory-behavior: What happens when a player has no free inventory slot. SKIP gives nothing that round, DROP_AT_FEET drops the item on the ground next to the player, and QUEUE holds the item and delivers it at the next drop or when the player rejoins with free space
• broadcast-worlds: Worlds that see rare drop announcements and celebrations. Leave the list empty to use every world
• history-size: How many recent drops are remembered for /randomitem history
• rarity-tiers: The tiers items are sorted into, described below
• custom-items: The special items the plugin can give out, described below
• pause-command-enabled: Allows or blocks the /randomitem pause command
• default-pause-duration: Pause length in seconds used when the pause command is used without a number
• bossbar: Colour, style, title and paused title of the countdown boss bar, plus a switch to turn it off entirely
• sounds: Turns the item pickup sound and the boss bar toggle sound on or off
• messages: Every message the plugin sends, with colour codes and placeholders

Rarity Tiers

Each tier supports these options:

• display-name: The name shown in messages, statistics and the history
• color: The colour code used for that name
• weight: The relative chance of the whole tier. A tier with weight 80 is sixteen times as likely as a tier with weight 5
• broadcast: Announces drops from this tier in chat to the configured broadcast worlds
• celebration: Shows a title to the players who see announcements
• firework: Launches a firework at the player who found the item
• sound: The sound played for an announced drop; leave it empty for silence
• items: The items belonging to the tier. Every item inside a tier has the same chance as the others in that tier

Any item that is not listed in any tier is automatically added to the common tier, so the drop pool always covers everything except excluded items. The chance of each tier is its weight divided by the total weight of all tiers that contain items, and /randomitem info shows those chances in game.

Custom Items

Each custom item supports these options:

• enabled: Whether the item is part of the drop pool
• tier: The rarity tier the item belongs to
• material: The item it is based on
• name: The display name of the item
• lore: The lines of text shown under the name
• effect: What happens when the item is used. INSTANT_TNT, LIGHTNING and FIREBALL are available
• explosion-power, break-blocks and set-fire: Only used by INSTANT_TNT to control the size of the blast, whether blocks break and whether fire is left behind

Included by default:

• Instant TNT - explodes the moment it is placed instead of waiting for a fuse
• Lightning Stick - right-click to call down lightning on the block you are looking at, or on yourself when you are not aiming at a block
• Fireball Wand - right-click to launch a fireball in the direction you are facing

Custom items are consumed one at a time when they are used and stack like normal items.

Boss Bar Settings

Customize the visual countdown with your choice of:

• Colors: BLUE, GREEN, PINK, PURPLE, RED, WHITE, YELLOW
• Styles: SOLID, SEGMENTED_6, SEGMENTED_10, SEGMENTED_12, SEGMENTED_20
• Titles: The countdown title and the paused title both accept the %time% placeholder
• Visibility: Players can hide or show the boss bar for themselves, and the choice is remembered

Announcements and Celebrations

Rare drops keep the whole server excited:

• Choose per tier whether a drop is announced, celebrated or both
• Broadcasts, titles and sounds only reach the configured broadcast worlds
• Fireworks are launched at the player who found the item
• Every part of the announcement, including the item, tier and player name, can be reworded in the message settings

Statistics and History

• Every drop is counted for the player who received it, with rare items counted separately
• /randomitem stats shows a player's totals, their last item and their rank, and staff can look up any player who has received items
• /randomitem top ranks the ten players with the most items
• /randomitem history lists the newest drops first, up to the configured history size
• All records are saved to disk and restored after a reload or restart

World Support

• Support for multiple worlds with different distribution settings
• World-specific announcement control
• Players only receive items, boss bars and countdowns in configured distribution worlds

Player Experience

• Players receive a message naming the item and its rarity
• Rare finds are announced to the configured worlds, together with a title and sound
• Players can check their own statistics, the leaderboard and recent drops at any time
• Players are never left with a lost item: depending on the configuration it is skipped, dropped or held until there is space
• Players can hide the countdown boss bar if they prefer a cleaner screen