# Minigame Framework **Extensible minigame framework plugin for Paper Minecraft 1.21.x** [![Java](https://img.shields.io/badge/Java-17+-orange.svg)](https://www.oracle.com/java/) [![Paper](https://img.shields.io/badge/Paper-1.21.x-blue.svg)](https://papermc.io/) [![Minecraft](https://img.shields.io/badge/Minecraft-1.21.x-green.svg)](https://www.minecraft.net/) 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`](src/main/java/com/gamingoasis/minigames/framework/minigame/Minigame.java) 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`](src/main/resources/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`](src/main/resources/config.yml) `sumo` section for shrink timing settings - **Arena Setup**: Arenas stored in `arenas/sumo/*.yml`. See [`arenas/sumo/README.md`](src/main/resources/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`](src/main/resources/config.yml) `pillars` section for mode weights and timing - [`itempools/pillars.yml`](src/main/resources/itempools/pillars.yml) for item pool configuration - Per-arena YAML files in `arenas/pillars/`. See [`arenas/pillars/README.md`](src/main/resources/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`](src/main/resources/config.yml) for the default configuration with comments. ### Arena Configuration Arenas are configured per-minigame: - **Sumo**: Create arenas with `/mg sumo create `, then configure using commands like `setworld`, `setspawn`, `addcorner`, `setdqlevel`, and `setfloorlevel` - **Pillars**: Create arenas with `/mg pillars create `, then configure using `setworld`, `setspawn`, and `setdqlevel` For detailed arena file formats, see: - [`arenas/sumo/README.md`](src/main/resources/arenas/sumo/README.md) - [`arenas/pillars/README.md`](src/main/resources/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 ` | Join a Sumo queue (`type1` or `type2`) | | `/mg sumo leave` | Leave the Sumo queue | | `/mg pillars join ` | 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 ` | Force a player to win their current match | `minigames.admin` | #### Sumo Admin Commands | Command | Description | |---------|-------------| | `/mg sumo create ` | Create a new Sumo arena configuration | | `/mg sumo setworld ` | Set the world for an arena (stand in the world) | | `/mg sumo setspawn ` | Set a spawn location (stand at the location) | | `/mg sumo addcorner ` | Set platform corner coordinates | | `/mg sumo setdqlevel ` | Set disqualification Y level (stand at the level) | | `/mg sumo setfloorlevel ` | Set platform floor Y level (stand at the level) | #### Pillars Admin Commands | Command | Description | |---------|-------------| | `/mg pillars create ` | Create a new Pillars arena configuration | | `/mg pillars setworld ` | Set the world for an arena (stand in the world) | | `/mg pillars setspawn ` | Set a spawn location (stand at the location) | | `/mg pillars setdqlevel ` | 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](https://www.spigotmc.org/resources/placeholderapi.6245/) 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](https://www.spigotmc.org/resources/placeholderapi.6245/) 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__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__kills%` - Kills for a specific minigame (currently tracked for Pillars) - Example: `%minigames_pillars_kills%` → "12" **Top Players (Leaderboards):** - `%minigames__top__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__top__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___arenas_available%` - Count of available arenas - Example: `%minigames_pillars_type1_arenas_available%` → "2" - `%minigames___arenas_in_use%` - Count of arenas currently in use - Example: `%minigames_pillars_type1_arenas_in_use%` → "1" - `%minigames___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__wins%` - Kills placeholders automatically work: `%minigames__kills%` - Arena placeholders automatically work: `%minigames___arenas_available%` - **Top player leaderboard placeholders automatically work**: `%minigames__top__name%` and `%minigames__top__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.

SaturnX