**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 <name>`	Create new arena
`/tof delete <arena>`	Delete an arena
`/tof setpos <arena> <1\|2>`	Set arena boundaries
`/tof setcage <arena> <1-8>`	Set cage spawn location
`/tof setspectatorspawn <arena>`	Set spectator spawn
`/tof setlobby`	Set main lobby location
`/tof setminplayers <arena> <number>`	Set minimum players
`/tof setmaxplayers <arena> <number>`	Set maximum players
`/tof save <arena>`	Save arena schematic
`/tof forcestart <arena>`	Force start game
`/tof forceend <arena>`	Force end game
`/tof info <arena>`	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

Mini-Game Server
Perfect as one of many minigames on a network. Quick rounds (5-10 minutes) keep players engaged.
Event Server
Host tournaments with the leaderboard system. Track kills and wins across multiple rounds.
Standalone Server
Run as the main game mode with multiple arenas running simultaneously.
Content Creator
Great for YouTube/Twitch content - the chaos of random loot and game modes creates entertaining moments.
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

 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 <name>

□ Step 2: Set boundaries
  ├── /tof setpos <arena> 1  (corner 1)
  └── /tof setpos <arena> 2  (corner 2)

□ Step 3: Set cage spawns (2-8 locations)
  ├── /tof setcage <arena> 1
  ├── /tof setcage <arena> 2
  ├── /tof setcage <arena> 3
  ├── /tof setcage <arena> 4
  ├── /tof setcage <arena> 5 (optional)
  ├── /tof setcage <arena> 6 (optional)
  ├── /tof setcage <arena> 7 (optional)
  └── /tof setcage <arena> 8 (optional)

□ Step 4: Set spectator spawn
  └── /tof setspectatorspawn <arena>

□ Step 5: Save schematic
  └── /tof save <arena>

□ Step 6: Test!
  └── /tof join <arena>

Gameplay Tips for Players

Survival Strategies

Don't Stand Still - You're a target on a pillar
Build Quickly - Use blocks to create cover
Save Ender Pearls - They can save your life
Use Spawn Eggs - Mobs distract enemies
Watch Your Inventory - Don't let it fill up
Golden Apples > Everything - Use them wisely
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

// 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> arena = FortunePillarsAPI.getPlayerArena(player);

// Get player stats
PlayerStats stats = FortunePillarsAPI.getPlayerStats(player);

Listening to Events

@EventHandler
public void onGameStart(GameStartEvent event) {
    Arena arena = event.getArena();
    GameModeType mode = event.getGameMode();
    List<Player> 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
│   └── <arena>.yml      Per-arena settings
└── schematics/          Arena schematic files
    └── <arena>.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+ **

FortunePillars

📖About FortunePillars