Minigames Framework

Minigame Framework

Extensible minigame framework plugin for Paper Minecraft 1.21.x

Java

Paper

Minecraft

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

Features

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

Minigames

Sumo Arena

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

- Arena Setup: - `type1` - 1v1 (2 players) - `type2` - 4 FFA (4 players) - Arena Setup: See Arena Setup `sumo` section for shrink timing settings - Arena Setup: Arenas stored in `arenas/sumo/*.yml`. See %%MD1%% 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.

- Configuration: - `type1` - 1v1 (2 players) - `type2` - 4 FFA (4 players) - `type3` - 8 FFA (8 players) - `type4` - 16 FFA (16 players) - Configuration (randomly weighted): - Configuration: Standard gameplay with item distribution - Configuration: Lava rises periodically, forcing players upward - Configuration: Reduced gravity effect for unique gameplay - Configuration: Inventory shuffles periodically instead of item distribution - Configuration: - Configuration `pillars` section for mode weights and timing - %%MD1%% for item pool configuration - Per-arena YAML files in `arenas/pillars/`. See %%MD2%% 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:

- Pillars: 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.