**FortunePillars - Complete Plugin Overview --- Description **FortunePillars** is a high-altitude Battle Royale minigame plugin designed for Paper Minecraft servers (1.21.1 - 1.21.8). Players are teleported onto individual floating pillars high in the sky, trapped in glass cages during countdown. Once the game starts, cages break and players receive random loot every few seconds. The objective is simple: **be the last player standing**. The plugin combines elements of luck (random loot), strategy (resource management), and skill (PvP combat) to create an exciting, fast-paced minigame experience. With multiple game modes, cosmetic customization, and comprehensive statistics tracking, FortunePillars provides endless replayability for players of all skill levels. --- Core Concept ``` ┌─────────────────────────────────────────────────────────────────┐ │ │ │ CAGE CAGE CAGE CAGE │ │ ┃ ┃ ┃ ┃ │ │ ┃ ┃ ┃ ┃ ← Players spawn │ │ ┃ ┃ ┃ ┃ in glass cages │ │ ▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓ ▓▓▓▓▓ ← Floating pillars │ │ ┃ ┃ ┃ ┃ │ │ ┃ ┃ ┃ ┃ │ │ ▼ ▼ ▼ ▼ │ │ │ │ ════════════════════════════════════════ │ │ VOID (Death) │ │ ════════════════════════════════════════ │ │ │ └─────────────────────────────────────────────────────────────────┘ ``` Game Flow ``` ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │ WAITING │───▶│ STARTING │───▶│ IN_GAME │───▶│ ENDING │ │ │ │ │ │ │ │ │ │ Players join │ │ Countdown │ │ Battle until │ │ Winner │ │ Vote modes │ │ 30 seconds │ │ 1 remains │ │ celebration │ │ In cages │ │ In cages │ │ Random loot │ │ Stats saved │ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ │ ▼ ┌──────────────┐ │ RESETTING │ │ │ │ Arena resets │ │ via schematic│ └──────────────┘ ``` --- ✨ Features ️ Arena System | Feature | Description | |---------|-------------| | **Manual Creation** | Admins create arenas using simple commands | | **Flexible Height** | Pillars can be at any Y level (not height-sensitive) | | **8 Spawn Points** | Support for up to 8 players per arena | | **Glass Cages** | Customizable spawn cages during waiting phase | | **Auto-Reset** | Arena automatically restores using saved schematic | | **Multiple Arenas** | Run several games simultaneously | | **Boundary Protection** | Players can't build/break outside arena bounds | Loot System ("The Fortune") | Feature | Description | |---------|-------------| | **Timed Drops** | Every 3-5 seconds (configurable) | | **Random Items** | 1-3 items per drop | | **Smart Filtering** | Excludes operator items (bedrock, command blocks, etc.) | | **Spawn Eggs** | Includes mob spawn eggs for chaos! | | **Random Enchants** | 30% chance for enchanted weapons/armor | | **Random Potions** | Potions have randomized effects | | **Balanced Mode** | Option to exclude OP items | Included Loot Categories: - ⚔️ **Weapons**: Swords, axes, bows, crossbows, tridents - ️ **Armor**: All tiers (leather → netherite) - **Blocks**: Building materials, TNT, obsidian - **Food**: Cooked meats, golden carrots, golden apples - **Potions**: Random positive/negative effects - **Spawn Eggs**: Zombies, skeletons, creepers, and more! - **Tools**: Pickaxes, flint & steel, fishing rods - ✨ **Special**: Ender pearls, fireworks, totems Excluded Items (Operator): - Command blocks - Barriers - Structure blocks - Bedrock - Light blocks - Debug stick - Spawners Game Modes | Mode | Icon | Description | |------|------|-------------| | **Normal** | ️ | Full loot table with all items | | **Balanced** | ⚖️ | Mid-tier only (no netherite, no OP apples) | | **Swapper** | | Positions swap every 30 seconds | | **Shuffle** | | Inventories randomize every 60 seconds | Spectator System | Feature | Description | |---------|-------------| | **No Death Screen** | Death event cancelled, instant spectator mode | | **Invisible** | Spectators hidden from alive players | | **No Interaction** | Can't drop items, pick up arrows, or interfere | | **Spectator Chat** | Chat only visible to other spectators | | **Arena View** | Teleported to center spectator spawn | Statistics & Leaderboards | Stat | Description | |------|-------------| | **Wins** | Total games won | | **Kills** | Total eliminations | | **Deaths** | Times eliminated | | **K/D Ratio** | Kills divided by deaths | | **Games Played** | Total matches participated | | **Winstreak** | Current consecutive wins | | **Best Winstreak** | Highest winstreak achieved | | **Win Rate** | Percentage of games won | Cosmetics Cage Colors (18 Options) | Free | Premium | |------|---------| | White, Orange, Magenta | Clear Glass | | Light Blue, Yellow, Lime | Tinted Glass | | Pink, Gray, Light Gray | | | Cyan, Purple, Blue | | | Brown, Green, Red, Black | | Win Effects (6 Options) | Effect | Description | |--------|-------------| | **Firework** | Classic firework celebration | | ⚡ **Lightning** | Lightning strikes around winner | | **Explosion** | Explosion particles (no damage) | | **Dragon** | Dragon breath spiral effect | | **Rainbow** | Colorful rainbow spiral | | ❌ **None** | No celebration effect | ️ Voting System - Players vote during waiting phase - GUI menu or command-based voting - Vote counts displayed in real-time - Winning mode selected by majority - Ties resolved randomly Quick Join System - `/tof join` finds the best available arena - Priority: Arena with most players in WAITING state - Automatic matchmaking for players --- ️ Technical Features Database Support | Type | Description | |------|-------------| | **SQLite** | Default, no setup required | | **MySQL** | For multi-server/BungeeCord setups | Performance Optimizations - ✅ Async database operations - ✅ Efficient schematic compression (palette-based) - ✅ Rate-limited block placement (1000 blocks/tick) - ✅ Cached leaderboards (5-minute refresh) - ✅ Lazy loading of player data Integration Support | Plugin | Integration | |--------|-------------| | **PlaceholderAPI** | Full placeholder support | | **BungeeCord** | MySQL database sharing | | **Custom Plugins** | Developer API with events | PlaceholderAPI Placeholders ``` %fortunepillars_stats_wins% - Player's total wins %fortunepillars_stats_kills% - Player's total kills %fortunepillars_stats_deaths% - Player's total deaths %fortunepillars_stats_kdr% - K/D ratio (2 decimals) %fortunepillars_stats_winstreak% - Current winstreak %fortunepillars_stats_best_winstreak% - Highest winstreak %fortunepillars_stats_games% - Games played %fortunepillars_stats_winrate% - Win percentage %fortunepillars_arena% - Current arena name %fortunepillars_arena_state% - Arena state %fortunepillars_arena_players% - Players in arena %fortunepillars_in_game% - true/false %fortunepillars_is_spectator% - true/false %fortunepillars_is_alive% - true/false ``` --- Commands Player Commands | Command | Description | |---------|-------------| | `/tof join [arena]` | Join arena (or quick join) | | `/tof leave` | Leave current arena | | `/tof vote [mode]` | Vote for game mode | | `/tof stats [player]` | View statistics | | `/tof cosmetics` | Open cosmetics menu | | `/tof arenas` | Browse available arenas | | `/tof leaderboard [type]` | View leaderboards | | `/tof list` | List all arenas | Admin Commands | Command | Description | |---------|-------------| | `/tof create ` | Create new arena | | `/tof delete ` | Delete an arena | | `/tof setpos <1\|2>` | Set arena boundaries | | `/tof setcage <1-8>` | Set cage spawn location | | `/tof setspectatorspawn ` | Set spectator spawn | | `/tof setlobby` | Set main lobby location | | `/tof setminplayers ` | Set minimum players | | `/tof setmaxplayers ` | Set maximum players | | `/tof save ` | Save arena schematic | | `/tof forcestart ` | Force start game | | `/tof forceend ` | Force end game | | `/tof info ` | View arena information | | `/tof reload` | Reload configuration | --- Permissions | Permission | Description | Default | |------------|-------------|---------| | `fortunepillars.player` | Basic player commands | `true` | | `fortunepillars.admin` | Admin commands | `op` | | `fortunepillars.stats` | View statistics | `true` | | `fortunepillars.cosmetic.cage.clear` | Clear glass cage | `op` | | `fortunepillars.cosmetic.cage.tinted` | Tinted glass cage | `op` | | `fortunepillars.cosmetic.win.lightning` | Lightning win effect | `op` | | `fortunepillars.cosmetic.win.explosion` | Explosion win effect | `op` | | `fortunepillars.cosmetic.win.dragon` | Dragon win effect | `op` | | `fortunepillars.cosmetic.win.rainbow` | Rainbow win effect | `op` | --- Use Cases 1. **Mini-Game Server** Perfect as one of many minigames on a network. Quick rounds (5-10 minutes) keep players engaged. 2. **Event Server** Host tournaments with the leaderboard system. Track kills and wins across multiple rounds. 3. **Standalone Server** Run as the main game mode with multiple arenas running simultaneously. 4. **Content Creator** Great for YouTube/Twitch content - the chaos of random loot and game modes creates entertaining moments. 5. **Private Server** Fun for small friend groups - 2-8 players per game makes it accessible. --- Player Experience Flow ``` ┌─────────────────────────────────────────────────────────────────────────┐ │ PLAYER JOURNEY │ └─────────────────────────────────────────────────────────────────────────┘ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ JOIN │────▶│ VOTE │────▶│ WAIT │────▶│ COUNTDOWN│ │ Server │ │ for Mode│ │ in Cage │ │ 30 secs │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ ┌───────────────────────────────────────────────┘ ▼ ┌─────────┐ ┌─────────┐ ┌─────────┐ ┌─────────┐ │ START │────▶│ GRACE │────▶│ BATTLE! │────▶│ GET LOOT│ │ Cages │ │ PERIOD │ │ PvP │ │ Every │ │ Break │ │ 10 secs │ │ Enabled │ │ 3-5 sec │ └─────────┘ └─────────┘ └─────────┘ └─────────┘ │ │ └───────┬───────┘ │ ┌──────────────────────────┼──────────────────────────┐ │ │ │ ▼ ▼ ▼ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ DIE │ │ SURVIVE │ │ WIN! │ │ │ │ │ │ │ │ → Spectator │ │ Keep │ │ → Celebrate │ │ → Watch │ │ Fighting │ │ → +1 Win │ │ → /tof leave│ │ │ │ → Lobby │ └─────────────┘ └─────────────┘ └─────────────┘ ``` --- ⚙️ Configuration Overview config.yml Highlights ```yaml Game Settings game: min-players: 2 Minimum to start max-players: 8 Maximum per arena countdown-seconds: 30 Countdown duration grace-period-seconds: 10 No PvP period Loot Settings loot: interval-min: 3 Min seconds between drops interval-max: 5 Max seconds between drops items-min: 1 Min items per drop items-max: 3 Max items per drop include-spawn-eggs: true Include mob eggs Game Mode Intervals game-modes: swapper: interval: 30 Seconds between swaps shuffle: interval: 60 Seconds between shuffles ``` --- Setup Requirements Server Requirements | Requirement | Minimum | Recommended | |-------------|---------|-------------| | **Server** | Paper 1.21.1 | Paper 1.21.4+ | | **Java** | Java 21 | Java 21 | | **RAM** | 2GB | 4GB+ | | **Storage** | 100MB | 500MB+ | Dependencies | Plugin | Required | Purpose | |--------|----------|---------| | **Paper** | ✅ Yes | Server software | | **PlaceholderAPI** | ❌ Optional | Placeholders | --- Arena Setup Checklist ``` □ Step 1: Create arena └── /tof create □ Step 2: Set boundaries ├── /tof setpos 1 (corner 1) └── /tof setpos 2 (corner 2) □ Step 3: Set cage spawns (2-8 locations) ├── /tof setcage 1 ├── /tof setcage 2 ├── /tof setcage 3 ├── /tof setcage 4 ├── /tof setcage 5 (optional) ├── /tof setcage 6 (optional) ├── /tof setcage 7 (optional) └── /tof setcage 8 (optional) □ Step 4: Set spectator spawn └── /tof setspectatorspawn □ Step 5: Save schematic └── /tof save □ Step 6: Test! └── /tof join ``` --- Gameplay Tips for Players Survival Strategies 1. **Don't Stand Still** - You're a target on a pillar 2. **Build Quickly** - Use blocks to create cover 3. **Save Ender Pearls** - They can save your life 4. **Use Spawn Eggs** - Mobs distract enemies 5. **Watch Your Inventory** - Don't let it fill up 6. **Golden Apples > Everything** - Use them wisely 7. **Bow > Sword** - Range advantage on pillars Mode-Specific Tips | Mode | Strategy | |------|----------| | **Normal** | Save best items for endgame | | **Balanced** | Focus on skill, not luck | | **Swapper** | Don't build elaborate bases | | **Shuffle** | Organize inventory constantly | --- Developer API Checking Player State ```java // Check if player is in game boolean inGame = FortunePillarsAPI.isInGame(player); // Check if player is alive boolean alive = FortunePillarsAPI.isAlive(player); // Get player's arena Optional arena = FortunePillarsAPI.getPlayerArena(player); // Get player stats PlayerStats stats = FortunePillarsAPI.getPlayerStats(player); ``` Listening to Events ```java @EventHandler public void onGameStart(GameStartEvent event) { Arena arena = event.getArena(); GameModeType mode = event.getGameMode(); List players = event.getPlayers(); // Cancel if needed event.setCancelled(true); } @EventHandler public void onGameEnd(GameEndEvent event) { Player winner = event.getWinner(); GameEndEvent.EndReason reason = event.getReason(); } @EventHandler public void onPlayerEliminated(PlayerEliminatedEvent event) { Player eliminated = event.getEliminated(); Player killer = event.getKiller(); // Can be null int remaining = event.getRemainingPlayers(); } ``` --- What's Included Files Generated on First Run ``` plugins/FortunePillars/ ├── config.yml Main configuration ├── messages.yml All plugin messages ├── database.db SQLite database (if using SQLite) ├── signs.yml Join sign locations ├── npcs.yml Join NPC data ├── arenas/ Arena configuration files │ └── .yml Per-arena settings └── schematics/ Arena schematic files └── .fpschem Compressed arena data ``` --- Summary **FortunePillars** is a complete, production-ready Battle Royale minigame that offers: | Category | Highlights | |----------|------------| | **Gameplay** | Fast-paced, luck-based PvP with 4 unique modes | | **Features** | Cosmetics, stats, leaderboards, voting | | **Technical** | Optimized, async, multi-database support | | **Integration** | PlaceholderAPI, developer API, events | | **Administration** | Easy setup, auto-reset, multiple arenas | | **Customization** | Configurable loot, timings, messages | Perfect for any server looking to add an exciting, unique minigame that keeps players coming back for more! --- **Version:** 1.0.0 **Compatibility:** Paper 1.21.1 - 1.21.8 **Java:** 21+ **

Sahar