# Minigame Framework<\/p>\n
**Extensible minigame framework plugin for Paper Minecraft 1.21.x**<\/p>\n
\n
\n<\/p>\n
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.<\/p>\n
## Features<\/p>\n
– **Queue System**: Join\/leave queues with per-arena-type support (`type1`, `type2`, etc.)
\n– **Match Lifecycle**: Configurable countdown (default 3 seconds), match states, and win\/loss handling
\n– **Arena Management**: Create and configure arenas via in-game commands; YAML configuration files under `plugins\/MinigameFramework\/arenas\/`
\n– **Spawn\/Lobby Configuration**: Flexible spawn world settings and optional winner reward commands
\n– **Minigame Toggles**: Enable\/disable minigames and customize timings in [`config.yml`](src\/main\/resources\/config.yml)<\/p>\n
## Minigames<\/p>\n
### Sumo Arena<\/p>\n
Knock your opponents off the platform! The last player standing wins. The platform automatically shrinks over time to keep matches intense.<\/p>\n
– **Modes**:
\n – `type1` – 1v1 (2 players)
\n – `type2` – 4 FFA (4 players)
\n– **Configuration**: See [`config.yml`](src\/main\/resources\/config.yml) `sumo` section for shrink timing settings
\n– **Arena Setup**: Arenas stored in `arenas\/sumo\/*.yml`. See [`arenas\/sumo\/README.md`](src\/main\/resources\/arenas\/sumo\/README.md) for detailed arena format<\/p>\n
### Pillars of Fortune<\/p>\n
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.<\/p>\n
– **Modes**:
\n – `type1` – 1v1 (2 players)
\n – `type2` – 4 FFA (4 players)
\n – `type3` – 8 FFA (8 players)
\n – `type4` – 16 FFA (16 players)
\n– **Round Modes** (randomly weighted):
\n – **Normal**: Standard gameplay with item distribution
\n – **Rising Lava**: Lava rises periodically, forcing players upward
\n – **Low Gravity**: Reduced gravity effect for unique gameplay
\n – **Shuffle**: Inventory shuffles periodically instead of item distribution
\n– **Configuration**:
\n – [`config.yml`](src\/main\/resources\/config.yml) `pillars` section for mode weights and timing
\n – [`itempools\/pillars.yml`](src\/main\/resources\/itempools\/pillars.yml) for item pool configuration
\n – Per-arena YAML files in `arenas\/pillars\/`. See [`arenas\/pillars\/README.md`](src\/main\/resources\/arenas\/pillars\/README.md) for arena format<\/p>\n
## Configuration<\/p>\n
### Main Configuration<\/p>\n
Edit `plugins\/MinigameFramework\/config.yml` to configure:<\/p>\n
– Spawn\/lobby world settings
\n– Match countdown duration
\n– Winner reward command (optional, uses `{player}` placeholder)
\n– Enable\/disable minigames
\n– Minigame-specific timing and options<\/p>\n
See [`config.yml`](src\/main\/resources\/config.yml) for the default configuration with comments.<\/p>\n
### Arena Configuration<\/p>\n
Arenas are configured per-minigame:<\/p>\n
– **Sumo**: Create arenas with `\/mg sumo create For detailed arena file formats, see: After editing arena files, use `\/mg reload` to load changes.<\/p>\n ## Commands<\/p>\n **Command Aliases**: `\/minigame`, `\/mg`, `\/game`<\/p>\n ### Player Commands<\/p>\n | Command | Description | ### Admin Commands<\/p>\n | Command | Description | Permission | #### Sumo Admin Commands<\/p>\n | Command | Description | #### Pillars Admin Commands<\/p>\n | Command | Description | **Note**: All admin commands require the `minigames.admin` permission or OP status.<\/p>\n ## Permissions<\/p>\n | Permission | Description | **Note**: Server operators (OPs) have access to all commands without explicit permissions.<\/p>\n ## PlaceholderAPI Integration<\/p>\n 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.<\/p>\n ### Installation<\/p>\n 1. Install PlaceholderAPI on your server ### Player Statistics Placeholders<\/p>\n **Wins:** **Kills:** **Top Players (Leaderboards):** **Leaderboard Details:** ### Arena Availability Placeholders<\/p>\n Track how many arenas are available or in use for specific minigame types:<\/p>\n – `%minigames_ **Arena Type Examples:** ### Usage Examples<\/p>\n **FancyHolograms Scoreboard Example:** **Global Stats Scoreboard:** **Arena Status Display:** **Top Players Leaderboard Examples:**<\/p>\n **Complete Pillars Top 20 Leaderboard:** **Complete Sumo Top 20 Leaderboard:** **Custom Formatting Example:** ### Future-Proof Design<\/p>\n The placeholder system automatically supports new minigames without code changes. When you add a new minigame:<\/p>\n – Wins placeholders automatically work: `%minigames_ 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.<\/p>\n ### Statistics Storage<\/p>\n Player statistics are stored in `plugins\/MinigameFramework\/stats.yml` and are automatically saved: Stats persist across server restarts and are tracked per player UUID.<\/p>\n","protected":false},"excerpt":{"rendered":" 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.<\/p>\n","protected":false},"featured_media":0,"template":"","meta":{"_minecraft_slug":"minigames-framework","_minecraft_project_id":"3LIXuqln","_minecraft_author":"Freddymac48999","_minecraft_license":"LicenseRef-All-Rights-Reserved","_minecraft_downloads":34,"_minecraft_follows":1,"_minecraft_client_side":"unsupported","_minecraft_server_side":"required","_minecraft_storage_type":"zip","_minecraft_archive_name":"minigames-framework.zip","_minecraft_size_bytes":127510,"_minecraft_version_count":1,"_minecraft_updated_at":"2026-05-15T21:52:15.463018Z","_minecraft_date_created":"2026-01-24T23:34:54.779575Z","_minecraft_date_modified":"2026-01-25T02:07:40.727493Z","_minecraft_project_url":"https:\/\/modrinth.com\/mod\/minigames-framework","_minecraft_icon_attachment_id":0,"_minecraft_imported_at":"2026-06-05T21:37:47+00:00","_minecraft_import_hash":"4ba45b6495a03dcba1f24b9beabbaadd","_minecraft_versions":"","_minecraft_links":"","_minecraft_gallery":"","_minecraft_api_metadata":""},"mod_category":[127],"mod_loader":[132],"minecraft_version":[41],"class_list":["post-102699","mod","type-mod","status-publish","hentry","mod_category-paper","mod_loader-paper","minecraft_version-1-21-11"],"yoast_head":"\n
\n– **Pillars**: Create arenas with `\/mg pillars create
\n– [`arenas\/sumo\/README.md`](src\/main\/resources\/arenas\/sumo\/README.md)
\n– [`arenas\/pillars\/README.md`](src\/main\/resources\/arenas\/pillars\/README.md)<\/p>\n
\n|———|————-|
\n| `\/mg list` | List all available minigames and queue status |
\n| `\/mg leave` | Leave your current queue or match |
\n| `\/mg sumo join
\n| `\/mg sumo leave` | Leave the Sumo queue |
\n| `\/mg pillars join
\n| `\/mg pillars leave` | Leave the Pillars queue |<\/p>\n
\n|———|————-|————|
\n| `\/mg reload` | Reload all configuration files and arenas | `minigames.reload` |
\n| `\/mg win
\n|———|————-|
\n| `\/mg sumo create
\n| `\/mg sumo setworld
\n| `\/mg sumo setspawn
\n| `\/mg sumo addcorner
\n| `\/mg sumo setdqlevel
\n| `\/mg sumo setfloorlevel
\n|———|————-|
\n| `\/mg pillars create
\n| `\/mg pillars setworld
\n| `\/mg pillars setspawn
\n| `\/mg pillars setdqlevel
\n| `\/mg pillars reload` | Reload the item pool configuration |<\/p>\n
\n|————|————-|
\n| `minigames.reload` | Allows use of `\/mg reload` command |
\n| `minigames.admin` | Allows use of `\/mg win` and all minigame admin commands (create, setworld, setspawn, etc.) |<\/p>\n
\n2. The Minigame Framework will automatically detect and register its expansion on startup
\n3. Use `\/papi reload` to reload placeholders after installing the plugin<\/p>\n
\n– `%minigames_
\n – Example: `%minigames_pillars_wins%` \u2192 “5”
\n – Example: `%minigames_sumo_wins%` \u2192 “3”
\n– `%minigames_total_wins%` – Total wins across all minigames
\n – Example: `%minigames_total_wins%` \u2192 “8”<\/p>\n
\n– `%minigames_
\n – Example: `%minigames_pillars_kills%` \u2192 “12”<\/p>\n
\n– `%minigames_
\n – Returns the player’s name at the specified rank, sorted by wins (descending)
\n – Returns empty string if no player exists at that rank
\n – Example: `%minigames_pillars_top_1_name%` \u2192 “PlayerName”
\n – Example: `%minigames_sumo_top_5_name%` \u2192 “AnotherPlayer”
\n – Example: `%minigames_pillars_top_20_name%` \u2192 “LastPlacePlayer”
\n– `%minigames_
\n – Returns the number of wins for the player at the specified rank
\n – Returns empty string if no player exists at that rank
\n – Example: `%minigames_pillars_top_1_wins%` \u2192 “25”
\n – Example: `%minigames_sumo_top_5_wins%` \u2192 “12”
\n – Example: `%minigames_pillars_top_20_wins%` \u2192 “3”<\/p>\n
\n– Leaderboards are sorted by wins in descending order (highest wins first)
\n– Ties are broken by UUID for consistent ordering
\n– Only players with at least 1 win are included in the leaderboard
\n– Supports ranks 1-20 for all minigames
\n– Works automatically for all current and future minigames<\/p>\n
\n – Example: `%minigames_pillars_type1_arenas_available%` \u2192 “2”
\n– `%minigames_
\n – Example: `%minigames_pillars_type1_arenas_in_use%` \u2192 “1”
\n– `%minigames_
\n – Example: `%minigames_pillars_type1_arenas_total%` \u2192 “3”<\/p>\n
\n– For Pillars: `type1`, `type2`, `type3`, `type4`
\n– For Sumo: `type1`, `type2`<\/p>\n
\n“`
\nTop Pillars Players:
\n1. %player_name% – %minigames_pillars_wins% wins, %minigames_pillars_kills% kills
\n2. …
\n“`<\/p>\n
\n“`
\nYour Stats:
\nWins: %minigames_total_wins%
\nPillars: %minigames_pillars_wins% wins, %minigames_pillars_kills% kills
\nSumo: %minigames_sumo_wins% wins
\n“`<\/p>\n
\n“`
\nPillars Type1 Arenas:
\nAvailable: %minigames_pillars_type1_arenas_available%
\nIn Use: %minigames_pillars_type1_arenas_in_use%
\nTotal: %minigames_pillars_type1_arenas_total%
\n“`<\/p>\n
\n“`
\nTop Pillars Players:
\n1. %minigames_pillars_top_1_name% – %minigames_pillars_top_1_wins% wins
\n2. %minigames_pillars_top_2_name% – %minigames_pillars_top_2_wins% wins
\n3. %minigames_pillars_top_3_name% – %minigames_pillars_top_3_wins% wins
\n4. %minigames_pillars_top_4_name% – %minigames_pillars_top_4_wins% wins
\n5. %minigames_pillars_top_5_name% – %minigames_pillars_top_5_wins% wins
\n6. %minigames_pillars_top_6_name% – %minigames_pillars_top_6_wins% wins
\n7. %minigames_pillars_top_7_name% – %minigames_pillars_top_7_wins% wins
\n8. %minigames_pillars_top_8_name% – %minigames_pillars_top_8_wins% wins
\n9. %minigames_pillars_top_9_name% – %minigames_pillars_top_9_wins% wins
\n10. %minigames_pillars_top_10_name% – %minigames_pillars_top_10_wins% wins
\n11. %minigames_pillars_top_11_name% – %minigames_pillars_top_11_wins% wins
\n12. %minigames_pillars_top_12_name% – %minigames_pillars_top_12_wins% wins
\n13. %minigames_pillars_top_13_name% – %minigames_pillars_top_13_wins% wins
\n14. %minigames_pillars_top_14_name% – %minigames_pillars_top_14_wins% wins
\n15. %minigames_pillars_top_15_name% – %minigames_pillars_top_15_wins% wins
\n16. %minigames_pillars_top_16_name% – %minigames_pillars_top_16_wins% wins
\n17. %minigames_pillars_top_17_name% – %minigames_pillars_top_17_wins% wins
\n18. %minigames_pillars_top_18_name% – %minigames_pillars_top_18_wins% wins
\n19. %minigames_pillars_top_19_name% – %minigames_pillars_top_19_wins% wins
\n20. %minigames_pillars_top_20_name% – %minigames_pillars_top_20_wins% wins
\n“`<\/p>\n
\n“`
\nTop Sumo Players:
\n1. %minigames_sumo_top_1_name% – %minigames_sumo_top_1_wins% wins
\n2. %minigames_sumo_top_2_name% – %minigames_sumo_top_2_wins% wins
\n3. %minigames_sumo_top_3_name% – %minigames_sumo_top_3_wins% wins
\n4. %minigames_sumo_top_4_name% – %minigames_sumo_top_4_wins% wins
\n5. %minigames_sumo_top_5_name% – %minigames_sumo_top_5_wins% wins
\n6. %minigames_sumo_top_6_name% – %minigames_sumo_top_6_wins% wins
\n7. %minigames_sumo_top_7_name% – %minigames_sumo_top_7_wins% wins
\n8. %minigames_sumo_top_8_name% – %minigames_sumo_top_8_wins% wins
\n9. %minigames_sumo_top_9_name% – %minigames_sumo_top_9_wins% wins
\n10. %minigames_sumo_top_10_name% – %minigames_sumo_top_10_wins% wins
\n11. %minigames_sumo_top_11_name% – %minigames_sumo_top_11_wins% wins
\n12. %minigames_sumo_top_12_name% – %minigames_sumo_top_12_wins% wins
\n13. %minigames_sumo_top_13_name% – %minigames_sumo_top_13_wins% wins
\n14. %minigames_sumo_top_14_name% – %minigames_sumo_top_14_wins% wins
\n15. %minigames_sumo_top_15_name% – %minigames_sumo_top_15_wins% wins
\n16. %minigames_sumo_top_16_name% – %minigames_sumo_top_16_wins% wins
\n17. %minigames_sumo_top_17_name% – %minigames_sumo_top_17_wins% wins
\n18. %minigames_sumo_top_18_name% – %minigames_sumo_top_18_wins% wins
\n19. %minigames_sumo_top_19_name% – %minigames_sumo_top_19_wins% wins
\n20. %minigames_sumo_top_20_name% – %minigames_sumo_top_20_wins% wins
\n“`<\/p>\n
\nYou can customize the display format in FancyHolograms or other plugins:
\n“`
\n\u00a76\u00a7lTop Pillars Players
\n\u00a77Rank \u00a7eName \u00a77- \u00a7aWins
\n1. \u00a7e%minigames_pillars_top_1_name% \u00a77- \u00a7a%minigames_pillars_top_1_wins%
\n2. \u00a7e%minigames_pillars_top_2_name% \u00a77- \u00a7a%minigames_pillars_top_2_wins%
\n…
\n“`<\/p>\n
\n– Kills placeholders automatically work: `%minigames_
\n– Arena placeholders automatically work: `%minigames_
\n– **Top player leaderboard placeholders automatically work**: `%minigames_
\n– Periodically (every 5 minutes)
\n– On server shutdown
\n– After each win\/kill (async save)<\/p>\n