🏰 Mini Nations

Mini Nations is a fast-paced Minecraft Nations PvP gamemode plugin built for Paper 1.21.x.

Compete in one of four powerful nations, defend your Nexus, and conquer enemy kingdoms in strategic battles where teamwork, roles, and survival matter.

The world is divided into four nations:

• 🌳 Jungle Nation (Green)
• 🏜️ Desert Nation (Yellow)
• ❄️ Ice Nation (White)
• ⛰️ Mountain Nation (Gray)

Each nation fights to protect its Nexus — the core of their kingdom. Destroy the enemy Nexus to eliminate their nation. The last surviving nation wins the game.

---

⚔️ Core Gameplay

Every player belongs to a nation and a role:

• 👑 King (3 Hearts)
• ⚔️ General (2 Hearts)
• 🛡️ Player (1 Heart)

The heart system is a custom progression system that replaces vanilla survival balance.

Players lose hearts on death. When hearts reach zero, the player is eliminated (configurable: Ban / Spectator / Temporary Ban).

---

💙 Heart System

• Custom hearts stored per player (UUID-based)
• No vanilla health dependency
• Hearts decrease on death (configurable)
• ActionBar displays current status:

Example: 💙💙🩶

• 💙 = remaining hearts
• 🩶 = lost hearts
• Updates every second
• Always synchronized with player data

---

🧿 Nexus System

Each nation has exactly ONE Nexus.

The Nexus is NOT a block, but a visual entity system using:

• ItemDisplay (main core)
• TextDisplay (label)

Features:

• Large floating object (2.5x - 4x scale)
• Smooth continuous rotation
• Nation-specific particle effects
• Visible from long distance

Example: 🌳 Jungle Nation NEXUS

---

⛏️ Nexus Capture System

Nexus capture is the core mechanic of the game.

To capture a Nexus:

• Player must sneak (shift) continuously for 10 seconds
• Progress is shown via BossBar (0% → 100%)
• Capture is interrupted if:
  • Player stops sneaking
  • Player takes damage
  • Player dies
  • Player leaves range

If interrupted:

• Progress resets
• BossBar is removed
• Capture task is cancelled

---

🏆 Capture Result

When capture is successful:

• Nexus is destroyed (all display entities removed)
• Nation is marked as eliminated
• Player receives the Nexus item in their inventory

The Nexus item is a normal item representing the conquered nation. It includes name, lore, and future-proof metadata (CustomModelData + PersistentDataContainer).

No trophy system is used — only the item reward.

---

🔁 Recapture System

• Nations can be captured again at any time
• No cooldowns
• Infinite war cycles possible
• Nations can fall and rise repeatedly throughout the match

---

🧠 Features

• Fully configurable system (config.yml)
• Role system (King, General, Player)
• Custom ActionBar HUD
• BossBar capture system
• Display entity Nexus system
• Smooth rotation + particles
• Clean modular architecture
• Fully expandable for future features

---

⚙️ Technical Requirements

• Paper 1.21.x
• Java 21+
• Gradle (Kotlin DSL preferred)
• Adventure API for messaging
• Bukkit Scheduler for tasks (ActionBar, rotation, capture logic)
• PersistentDataContainer for player data

---

🚀 Planned Features

• Alliances system
• War declarations
• Territory claiming system
• Seasons / resets
• Economy system
• Advanced nation upgrades

---

📌 Summary

Mini Nations is a strategic PvP nations plugin focused on:

• Team-based warfare
• Tactical Nexus captures
• Custom progression system
• Fast-paced competitive gameplay
• Unique visual Nexus mechanics