FortunePillars

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

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

 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

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

// 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+ **