FortunePillars

Recreation of Pillars of Fortune gamemode of Cubecraft.........

Download

joingui.png

win effect gui.png

cagecolorgui.png

cosmeticgui.png

Description

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

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

```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> 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<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+

Need a server to run FortunePillars?
Get 24/7 high-performance hosting from reliable hosting for your community!
Click here to get started with KCB Hosting