VRandomItemBattle

A complete Random Item Battle minigame for Paper and Purpur servers.

Players enter an arena, vote for a map and receive random items at a configurable interval. Every delivery can change the fight: weapons, blocks, utilities, enchantments and even throwable spawn eggs are available. The final surviving player or team wins.

VRandomItemBattle is designed for both a single multigame server and full proxy networks. It combines guided setup, automatic world restoration, multi-map arenas, parallel rounds, persistent statistics and a deeply configurable interface in one standalone plugin.

One universal JAR: the same file runs on every currently published Paper 1.21.x and 26.x version listed below.

Developed by Veldran Studios.

Why VRandomItemBattle?

• Fast to set up: an interactive setup studio guides administrators through every required decision
• Different every round: weighted loot, rarity profiles, map-specific pools and optional modifiers keep matches unpredictable
• Built for real networks: run multiple arenas and parallel rounds or split lobby and game servers behind Velocity/BungeeCord
• Safe arena resets: each template-backed match runs in a fresh map copy without destroying the original world
• Highly configurable: menus, hotbar items, messages, signs, scoreboards, sounds, titles, effects and gameplay rules are editable
• Persistent statistics: use local file storage or shared asynchronous MySQL with independent visibility controls
• No required dependencies: install the JAR, restart and begin setup

Core gameplay

• Solo and team battles with configurable team sizes and automatic balancing
• Random item deliveries with configurable intervals, blocked materials, rarity weights, amounts and enchantments
• Optional duplicate protection and fairness rules
• Per-map loot profiles, icons, spawn positions, boundaries and player capacities
• Throwable spawn eggs that create their matching mob on impact
• Owned mobs, projectiles, TNT, fishing pulls and delayed effects retain correct kill attribution
• Friendly-fire protection for teammates, owned mobs, explosions and player-built Withers
• Configurable combat attribution for fall, void and environmental eliminations
• Five-second synchronized spawn freeze before combat begins
• Configurable halftime and tied-match extensions
• Clean inventories, controlled weather, permanent daytime and isolated arena difficulty

Modifiers and Sudden Death

Optional round modifiers can be enabled individually:

• Double Items
• Fast Items
• Hotbar Only
• No Regeneration
• Speed
• Glowing
• Explosive Projectiles

Sudden Death supports faster loot, survivor glowing, a shrinking world border and an optional dedicated final arena with its own spawn list. New item deliveries can stop during the final phase so every decision matters.

Multi-map arenas and voting

Each arena can contain multiple independent battle maps. Players vote before the round begins, while unavailable or full maps are excluded automatically.

The map voter stays compact:

• 1-9 maps use one inventory row
• 10-18 maps use two rows
• 19-27 maps use three rows
• Additional rows are added automatically
• With the default layout, page navigation begins only when more than 45 maps exist

Open voting menus update immediately after every vote and remain linked to the correct parallel round. Cancelling the Add another map setup step safely restores the previous selection instead of leaving that map unavailable.

Guided setup studio

Run /setup and answer only the current question. The setup flow includes:

• Branded chat panels, breadcrumbs and clickable actions
• Clear validation and examples for every input
• Separate lobby, rules, map, network and optional-system sections
• Exact world positions, map corners, spawns, icons and item pools
• Twelve explicit optional-system decisions
• A complete final review before anything is activated or restarted
• change actions for correcting individual sections without restarting the complete setup
• Safe repeat, cancellation and recovery behavior

Existing installations receive non-destructive configuration migrations. Custom values and arena data are preserved, with backups created before incompatible configuration changes.

Statistics and storage

VRandomItemBattle can track:

• Games played
• Wins
• Kills and deaths
• Damage dealt and received
• Items received
• Disconnects
• Current and best win streaks

Every statistic can be configured independently:

• Whether it is collected
• Whether it is stored
• Whether it appears in /stats
• Whether it can be used in /top
• Its display name, order and formatting

Choose between optimized local FILE storage or shared MySQL storage. Database work and batched writes run asynchronously so normal gameplay is not blocked by statistics persistence.

Spectators, reconnects and private games

• Configurable reconnect grace periods for lobby, combat and ending phases
• Correct restoration of inventory, position and player state
• Spectator teleport menu with pagination and live player information
• Next/previous player controls, flight, invisibility and isolated spectator chat
• Configurable Play Again and Return items
• Code- and invite-based private matches with owner settings
• Configurable best-of tournament series

Interface and presentation

The interface is not hard-coded. Administrators can customize:

• GUI titles, sizes, entries, slots and page controls
• Item materials, names, lore, glow, model data and flags
• Lobby hotbar layout and every click sound
• Gameplay titles, subtitles, actionbars and chat messages
• Lobby, fight, halftime, spectator and ending scoreboards
• Winner fireworks, particles, sounds and timing
• Join-sign lines, colors, glow, wax state and placeholders
• Setup panels, prompts, examples, progress indicators and answer labels

The sidebar uses differential updates to avoid unnecessary flicker. Repeated scoreboard, sign and statistics work is cached or batched where possible.

Server and proxy modes

VRandomItemBattle supports two deployment styles:

MULTIGAME

Run lobby and matches on one Paper/Purpur server. Multiple arenas and parallel round pools can operate at the same time.

PROXY NETWORK

Use dedicated lobby and game backends behind Velocity or BungeeCord-compatible messaging. The plugin supports:

• Guided LOBBY/GAME role setup
• Configurable backend and lobby names
• Backend arena assignment and automatic joining
• Reliable player transfer before shutdown or restart
• Per-arena server pools
• Live routing validation and administrative controls
• Safe fallback kicks when a proxy transfer cannot finish

Automatic world handling

• Fresh asynchronously copied runtime worlds for template-backed rounds
• Exclusive world reservations for parallel sessions
• Restoration of blocks, containers, fluids, pistons, explosions and spawned entities
• Correct cleanup of doors, beds and other multi-block structures
• Silent map preparation without technical player-facing messages
• Original template worlds remain reusable for future rounds

Quick start

1. Place VRandomItemBattle.jar in the server's plugins/ directory.
2. Restart the server.
3. Run /setup as an operator.
4. Select multigame or bungee deployment.
5. Complete the guided lobby, rules and map steps.
6. Review the generated setup summary and type confirm.
7. Players can now join, vote for a map and start the battle.

To create a physical join point, place a sign with [rib] on the first line and the arena name on the second. The sign updates automatically and joins players when clicked.

Main commands

• /rib - open the arena browser
• /rib join <arena> - join an arena
• /rib leave - leave the current arena
• /rib vote [map] - vote for a battle map
• /stats [player] - view configured player statistics
• /top [stat] [amount] - view a configured leaderboard
• /private ... - manage private matches
• /tournament ... - manage tournament series
• /setup - open the guided setup studio
• /setup <arena> [map] - edit a specific arena or map
• /rib map ... - manage maps, icons and availability
• /rib loot ... - manage map-specific item pools
• /rib template ... - create, test and manage world templates
• /rib round ... - inspect or control an individual parallel round
• /rib maintenance ... - drain or reopen maps safely
• /rib network ... - inspect and configure proxy routing
• /rib storage - inspect FILE/MySQL storage status
• /rib reload - reload configuration and arenas

Setup and administration require vrandomitembattle.admin, which is granted to operators by default.

Compatibility

Platform	Support
Paper	Fully supported and runtime-tested
Purpur	Supported as a Paper-compatible fork
Spigot	Not supported; required Paper APIs are unavailable
Folia	Not advertised as supported

Supported Paper versions

• 1.21
• 1.21.1
• 1.21.3 through 1.21.11
• 26.1.1
• 26.1.2
• 26.2

Supported Purpur versions

• 1.21
• 1.21.1
• 1.21.3 through 1.21.11
• 26.1.2
• 26.2

Paper did not publish server builds for Minecraft 1.21.2 or 26.1. Purpur additionally has no published 26.1.1 build, so that target is Paper-only.

Java requirements

• Java 21 for Minecraft 1.21.x servers
• Java 25 for Minecraft 26.x servers

The Paper compatibility matrix was validated using the same universal release JAR on all 14 published targets. Purpur inherits the required Paper APIs but was not part of that separate 14-server runtime matrix.

Configuration

Configuration is separated into focused files:

• config.yml - core gameplay and arena behavior
• network.yml - deployment and proxy routing
• messages.yml and language.yml - player-facing and setup text
• scoreboard.yml - phase-specific sidebar layouts
• interface.yml - menus, hotbar items, sounds and visual presentation
• storage.yml - FILE/MySQL and per-statistic behavior
• loot-profiles.yml - weighted item profiles and rarities
• modifiers.yml - optional round modifiers
• matches.yml - private matches, tournaments and optional systems

Use /rib reload after gameplay or presentation changes. Restart the server after changing the storage backend connection.

Metrics

VRandomItemBattle uses anonymous bStats metrics to help understand how the plugin is used. Metrics can be disabled through the standard bStats configuration.