Minigame Framework

Extensible minigame framework plugin for Paper Minecraft 1.21.x

A powerful, extensible minigame framework for Paper servers featuring queue-based matchmaking, arena management, and two built-in minigames: Sumo Arena and Pillars of Fortune. The framework is designed to be easily extended with custom minigames via the Minigame interface.

Features

• Queue System: Join/leave queues with per-arena-type support (type1, type2, etc.)
• Match Lifecycle: Configurable countdown (default 3 seconds), match states, and win/loss handling
• Arena Management: Create and configure arenas via in-game commands; YAML configuration files under plugins/MinigameFramework/arenas/
• Spawn/Lobby Configuration: Flexible spawn world settings and optional winner reward commands
• Minigame Toggles: Enable/disable minigames and customize timings in config.yml

Minigames

Sumo Arena

Knock your opponents off the platform! The last player standing wins. The platform automatically shrinks over time to keep matches intense.

• Modes:
  • type1 - 1v1 (2 players)
  • type2 - 4 FFA (4 players)
• Configuration: See config.yml sumo section for shrink timing settings
• Arena Setup: Arenas stored in arenas/sumo/*.yml. See arenas/sumo/README.md for detailed arena format

Pillars of Fortune

Build and survive on pillars! Players are eliminated by falling below the disqualification level (dq_y) or taking lethal damage. Features item distribution from a configurable pool and a world border around the arena.

• Modes:
  • type1 - 1v1 (2 players)
  • type2 - 4 FFA (4 players)
  • type3 - 8 FFA (8 players)
  • type4 - 16 FFA (16 players)
• Round Modes (randomly weighted):
  • Normal: Standard gameplay with item distribution
  • Rising Lava: Lava rises periodically, forcing players upward
  • Low Gravity: Reduced gravity effect for unique gameplay
  • Shuffle: Inventory shuffles periodically instead of item distribution
• Configuration:
  • config.yml pillars section for mode weights and timing
  • itempools/pillars.yml for item pool configuration
  • Per-arena YAML files in arenas/pillars/. See arenas/pillars/README.md for arena format

Configuration

Main Configuration

Edit plugins/MinigameFramework/config.yml to configure:

• Spawn/lobby world settings
• Match countdown duration
• Winner reward command (optional, uses {player} placeholder)
• Enable/disable minigames
• Minigame-specific timing and options

See config.yml for the default configuration with comments.

Arena Configuration

Arenas are configured per-minigame:

• Sumo: Create arenas with /mg sumo create <name> <type>, then configure using commands like setworld, setspawn, addcorner, setdqlevel, and setfloorlevel
• Pillars: Create arenas with /mg pillars create <name> <type>, then configure using setworld, setspawn, and setdqlevel

For detailed arena file formats, see:

• arenas/sumo/README.md
• arenas/pillars/README.md

After editing arena files, use /mg reload to load changes.

Commands

Command Aliases: /minigame, /mg, /game

Player Commands

Command	Description
/mg list	List all available minigames and queue status
/mg leave	Leave your current queue or match
/mg sumo join <type>	Join a Sumo queue (type1 or type2)
/mg sumo leave	Leave the Sumo queue
/mg pillars join <type>	Join a Pillars queue (type1, type2, type3, or type4)
/mg pillars leave	Leave the Pillars queue

Admin Commands

Command	Description	Permission
/mg reload	Reload all configuration files and arenas	minigames.reload
/mg win <player>	Force a player to win their current match	minigames.admin

Sumo Admin Commands

Command	Description
/mg sumo create <name> <type>	Create a new Sumo arena configuration
/mg sumo setworld <arenaName>	Set the world for an arena (stand in the world)
/mg sumo setspawn <arenaName> <spawnIndex>	Set a spawn location (stand at the location)
/mg sumo addcorner <arenaName> <corner1|corner2>	Set platform corner coordinates
/mg sumo setdqlevel <arenaName>	Set disqualification Y level (stand at the level)
/mg sumo setfloorlevel <arenaName>	Set platform floor Y level (stand at the level)

Pillars Admin Commands

Command	Description
/mg pillars create <name> <type>	Create a new Pillars arena configuration
/mg pillars setworld <arenaName>	Set the world for an arena (stand in the world)
/mg pillars setspawn <arenaName> <spawnIndex>	Set a spawn location (stand at the location)
/mg pillars setdqlevel <arenaName>	Set disqualification Y level (stand at the level)
/mg pillars reload	Reload the item pool configuration

Note: All admin commands require the minigames.admin permission or OP status.

Permissions

Permission	Description
minigames.reload	Allows use of /mg reload command
minigames.admin	Allows use of /mg win and all minigame admin commands (create, setworld, setspawn, etc.)

Note: Server operators (OPs) have access to all commands without explicit permissions.

PlaceholderAPI Integration

The plugin integrates with PlaceholderAPI to provide placeholders for player statistics and arena availability. This is perfect for creating scoreboards with plugins like FancyHolograms or other scoreboard/hologram plugins.

Installation

1. Install PlaceholderAPI on your server
2. The Minigame Framework will automatically detect and register its expansion on startup
3. Use /papi reload to reload placeholders after installing the plugin

Player Statistics Placeholders

Wins:

• %minigames_<minigame>_wins% - Wins for a specific minigame
  • Example: %minigames_pillars_wins% → "5"
  • Example: %minigames_sumo_wins% → "3"
• %minigames_total_wins% - Total wins across all minigames
  • Example: %minigames_total_wins% → "8"

Kills:

• %minigames_<minigame>_kills% - Kills for a specific minigame (currently tracked for Pillars)
  • Example: %minigames_pillars_kills% → "12"

Top Players (Leaderboards):

• %minigames_<minigame>_top_<rank>_name% - Player name at rank (1-20)
  • Returns the player's name at the specified rank, sorted by wins (descending)
  • Returns empty string if no player exists at that rank
  • Example: %minigames_pillars_top_1_name% → "PlayerName"
  • Example: %minigames_sumo_top_5_name% → "AnotherPlayer"
  • Example: %minigames_pillars_top_20_name% → "LastPlacePlayer"
• %minigames_<minigame>_top_<rank>_wins% - Win count at rank (1-20)
  • Returns the number of wins for the player at the specified rank
  • Returns empty string if no player exists at that rank
  • Example: %minigames_pillars_top_1_wins% → "25"
  • Example: %minigames_sumo_top_5_wins% → "12"
  • Example: %minigames_pillars_top_20_wins% → "3"

Leaderboard Details:

• Leaderboards are sorted by wins in descending order (highest wins first)
• Ties are broken by UUID for consistent ordering
• Only players with at least 1 win are included in the leaderboard
• Supports ranks 1-20 for all minigames
• Works automatically for all current and future minigames

Arena Availability Placeholders

Track how many arenas are available or in use for specific minigame types:

• %minigames_<minigame>_<arenaType>_arenas_available% - Count of available arenas
  • Example: %minigames_pillars_type1_arenas_available% → "2"
• %minigames_<minigame>_<arenaType>_arenas_in_use% - Count of arenas currently in use
  • Example: %minigames_pillars_type1_arenas_in_use% → "1"
• %minigames_<minigame>_<arenaType>_arenas_total% - Total count of arenas
  • Example: %minigames_pillars_type1_arenas_total% → "3"

Arena Type Examples:

• For Pillars: type1, type2, type3, type4
• For Sumo: type1, type2

Usage Examples

FancyHolograms Scoreboard Example:

Top Pillars Players:
1. %player_name% - %minigames_pillars_wins% wins, %minigames_pillars_kills% kills
2. ...

Global Stats Scoreboard:

Your Stats:
Wins: %minigames_total_wins%
Pillars: %minigames_pillars_wins% wins, %minigames_pillars_kills% kills
Sumo: %minigames_sumo_wins% wins

Arena Status Display:

Pillars Type1 Arenas:
Available: %minigames_pillars_type1_arenas_available%
In Use: %minigames_pillars_type1_arenas_in_use%
Total: %minigames_pillars_type1_arenas_total%

Top Players Leaderboard Examples:

Complete Pillars Top 20 Leaderboard:

Top Pillars Players:
1. %minigames_pillars_top_1_name% - %minigames_pillars_top_1_wins% wins
2. %minigames_pillars_top_2_name% - %minigames_pillars_top_2_wins% wins
3. %minigames_pillars_top_3_name% - %minigames_pillars_top_3_wins% wins
4. %minigames_pillars_top_4_name% - %minigames_pillars_top_4_wins% wins
5. %minigames_pillars_top_5_name% - %minigames_pillars_top_5_wins% wins
6. %minigames_pillars_top_6_name% - %minigames_pillars_top_6_wins% wins
7. %minigames_pillars_top_7_name% - %minigames_pillars_top_7_wins% wins
8. %minigames_pillars_top_8_name% - %minigames_pillars_top_8_wins% wins
9. %minigames_pillars_top_9_name% - %minigames_pillars_top_9_wins% wins
10. %minigames_pillars_top_10_name% - %minigames_pillars_top_10_wins% wins
11. %minigames_pillars_top_11_name% - %minigames_pillars_top_11_wins% wins
12. %minigames_pillars_top_12_name% - %minigames_pillars_top_12_wins% wins
13. %minigames_pillars_top_13_name% - %minigames_pillars_top_13_wins% wins
14. %minigames_pillars_top_14_name% - %minigames_pillars_top_14_wins% wins
15. %minigames_pillars_top_15_name% - %minigames_pillars_top_15_wins% wins
16. %minigames_pillars_top_16_name% - %minigames_pillars_top_16_wins% wins
17. %minigames_pillars_top_17_name% - %minigames_pillars_top_17_wins% wins
18. %minigames_pillars_top_18_name% - %minigames_pillars_top_18_wins% wins
19. %minigames_pillars_top_19_name% - %minigames_pillars_top_19_wins% wins
20. %minigames_pillars_top_20_name% - %minigames_pillars_top_20_wins% wins

Complete Sumo Top 20 Leaderboard:

Top Sumo Players:
1. %minigames_sumo_top_1_name% - %minigames_sumo_top_1_wins% wins
2. %minigames_sumo_top_2_name% - %minigames_sumo_top_2_wins% wins
3. %minigames_sumo_top_3_name% - %minigames_sumo_top_3_wins% wins
4. %minigames_sumo_top_4_name% - %minigames_sumo_top_4_wins% wins
5. %minigames_sumo_top_5_name% - %minigames_sumo_top_5_wins% wins
6. %minigames_sumo_top_6_name% - %minigames_sumo_top_6_wins% wins
7. %minigames_sumo_top_7_name% - %minigames_sumo_top_7_wins% wins
8. %minigames_sumo_top_8_name% - %minigames_sumo_top_8_wins% wins
9. %minigames_sumo_top_9_name% - %minigames_sumo_top_9_wins% wins
10. %minigames_sumo_top_10_name% - %minigames_sumo_top_10_wins% wins
11. %minigames_sumo_top_11_name% - %minigames_sumo_top_11_wins% wins
12. %minigames_sumo_top_12_name% - %minigames_sumo_top_12_wins% wins
13. %minigames_sumo_top_13_name% - %minigames_sumo_top_13_wins% wins
14. %minigames_sumo_top_14_name% - %minigames_sumo_top_14_wins% wins
15. %minigames_sumo_top_15_name% - %minigames_sumo_top_15_wins% wins
16. %minigames_sumo_top_16_name% - %minigames_sumo_top_16_wins% wins
17. %minigames_sumo_top_17_name% - %minigames_sumo_top_17_wins% wins
18. %minigames_sumo_top_18_name% - %minigames_sumo_top_18_wins% wins
19. %minigames_sumo_top_19_name% - %minigames_sumo_top_19_wins% wins
20. %minigames_sumo_top_20_name% - %minigames_sumo_top_20_wins% wins

Custom Formatting Example: You can customize the display format in FancyHolograms or other plugins:

§6§lTop Pillars Players
§7Rank §eName §7- §aWins
1. §e%minigames_pillars_top_1_name% §7- §a%minigames_pillars_top_1_wins%
2. §e%minigames_pillars_top_2_name% §7- §a%minigames_pillars_top_2_wins%
...

Future-Proof Design

The placeholder system automatically supports new minigames without code changes. When you add a new minigame:

• Wins placeholders automatically work: %minigames_<newgame>_wins%
• Kills placeholders automatically work: %minigames_<newgame>_kills%
• Arena placeholders automatically work: %minigames_<newgame>_<arenaType>_arenas_available%
• Top player leaderboard placeholders automatically work: %minigames_<newgame>_top_<rank>_name% and %minigames_<newgame>_top_<rank>_wins%

Simply use the minigame's name (from Minigame.getName()) and arena types in your placeholders. The leaderboard will automatically track and sort players by wins for any new minigame you add.

Statistics Storage

Player statistics are stored in plugins/MinigameFramework/stats.yml and are automatically saved:

• Periodically (every 5 minutes)
• On server shutdown
• After each win/kill (async save)

Stats persist across server restarts and are tracked per player UUID.