![Nucleus](https://cdn.modrinth.com/data/cached_images/5eb77217c8f4bebdad6f0d2e2016258e028619ed.png) # ⚔️ Nucleus ### PvP Practice Plugin [![Paper](https://img.shields.io/badge/Paper-1.21.8+-blue?style=for-the-badge&logo=paper)](https://papermc.io/) [![Java](https://img.shields.io/badge/Java-21+-orange?style=for-the-badge&logo=openjdk)](https://adoptium.net/) [![License](https://img.shields.io/badge/License-Proprietary-red?style=for-the-badge)](LICENSE) *A feature-rich, high-performance practice plugin built for competitive PvP servers.*

--- ## ✨ Features

### ⚔️ Duels - **1v1 Matchmaking** with ELO-based ranking - **Ranked & Unranked** queues - **Best-of-X** rounds (Bo3, Bo5, etc.) - **Duel Requests** with kit selection - **Spectator Mode** with live stats

### 💀 FFA (Free-for-All) - **Multiple Arenas** with unique kits - **Join Protection** (spawn immunity) - **Anti-Cleanup** system - **Arena Regeneration** (Built-in) - **Session Stats** tracking - **Kill Streaks** with rewards

### 📊 Stats & Rankings - **ELO System** with divisions - **Per-Kit Statistics** - **Global Leaderboards** - **Kill/Death Tracking** - **Win Streaks** - **MySQL** support

### 🎨 Additional Features | Feature | Description | |---------|-------------| | **Player Profiles** | Shift+right-click players to view stats & challenge | | **Kit Editor** | Full customization with armor trims, enchants, and potions | | **Flicker-Free Scoreboards** | Packet-based using FastBoard with animation support | | **Custom Animations** | Create animated text with `` placeholders | | **Per-Kit Scoreboards** | Different scoreboard layouts per kit | | **Spectator Scoreboard** | Live match stats when spectating | | **PlaceholderAPI** | Full integration with 50+ placeholders | | **Vault Integration** | Economy support for rewards | | **Configurable Hotbar** | Customizable lobby items | | **Beautiful GUIs** | Modern menu system with hex color support | --- ## 🚀 Quick Start ```bash # 1. Install the plugin Drop Nucleus.jar into your plugins/ folder # 2. Start your server The plugin will generate default configs # 3. Set the lobby spawn /nucleus setspawn # 4. Create a duel arena /dsetup create # Follow the interactive setup wizard # 5. Create a kit /akit create # Customize in the kit editor GUI ``` --- ## 📝 Commands ### Player Commands | Command | Description | |---------|-------------| | `/duel ` | Send a duel request | | `/duel ` | Duel with specific kit | | `/duel queue [kit]` | Join ranked matchmaking | | `/duel leave` | Leave queue or forfeit match | | `/ffa join ` | Join an FFA arena | | `/ffa leave` | Leave FFA | | `/ffa list` | List available arenas | | `/stats [player]` | View player statistics | | `/leaderboard` | Open leaderboard GUI | | `/spectate ` | Spectate a match | | `/spawn` | Return to lobby | ### Admin Commands | Command | Description | |---------|-------------| | `/nucleus` | Open admin panel GUI | | `/nucleus reload` | Reload all configurations | | `/nucleus setspawn` | Set the lobby spawn point | | `/dsetup create ` | Create a new duel arena | | `/dsetup delete ` | Delete a duel arena | | `/dsetup list` | List all duel arenas | | `/ffasetup create ` | Create an FFA arena | | `/ffasetup delete ` | Delete an FFA arena | | `/akit create ` | Create a new kit | | `/akit delete ` | Delete a kit | | `/akit edit ` | Edit kit in GUI | | `/akit list` | List all kits | --- ## 🔐 Permissions | Permission | Description | Default | |------------|-------------|---------| | `nucleus.use` | Access to basic commands | Everyone | | `nucleus.duel` | Send and accept duel requests | Everyone | | `nucleus.queue` | Join ranked matchmaking | Everyone | | `nucleus.ffa` | Join FFA arenas | Everyone | | `nucleus.spectate` | Spectate matches | Everyone | | `nucleus.kiteditor` | Access kit editor | Everyone | | `nucleus.stats` | View statistics | Everyone | | `nucleus.admin` | All admin commands | OP | | `nucleus.bypass.queue` | Bypass queue cooldowns | OP | --- ## ⚙️ Configuration ### File Structure ``` plugins/Nucleus/ ├── config.yml # Main configuration ├── arenas.yml # Duel arena data ├── kits.yml # Kit configurations ├── divisions.yml # ELO divisions & ranks ├── messages.yml # All plugin messages ├── scoreboards.yml # Scoreboard layouts ├── animations.yml # Custom animations ├── settings.yml # Player settings GUI ├── hotbar.yml # Lobby hotbar items └── menus.yml # GUI configurations ```

📄 config.yml - Main Configuration

```yaml # Nucleus Configuration # Premium PvP plugin with Duels, FFA, and Kit management # Debug mode - enables verbose logging to console debug: false # Blocked Commands - commands players cannot use while in FFA or Duels # These are checked as prefixes (e.g. "/tp" blocks "/tp", "/tpa", "/tphere", etc.) blocked-commands: ffa: - /spawn - /hub - /lobby - /home - /tp - /tpa - /tpaccept - /back - /warp - /sethome - /duel - /queue - /kit - /give - /i - /item - /gamemode - /gm - /fly - /god - /heal - /feed - /ec - /enderchest - /workbench - /craft - /kill - /suicide - /die duel: - /spawn - /hub - /lobby - /home - /tp - /tpa - /tpaccept - /back - /warp - /sethome - /ffa - /queue - /kit - /give - /i - /item - /gamemode - /gm - /fly - /god - /heal - /feed - /ec - /enderchest - /workbench - /craft - /kill - /suicide - /die # Join Protection Settings join-protection: enabled: true # Enable/disable join protection duration: 10 # Duration in seconds clear-effects: true # Clear active potion effects on join # Anti-Cleanup Settings anti-cleanup: enabled: true # Toggle the entire anti-cleanup system regen: enabled: true # Toggle the regeneration effect duration: 3 # Duration in seconds resistance: enabled: true # Toggle the resistance effect duration: 5 # Duration in seconds level: 2 # Resistance level (0-255) # Regeneration Settings # Arena regeneration uses Paper's async chunk API for efficient block restoration regen: enabled: true # Global toggle to enable/disable all arena regeneration blocks-per-tick: 1000 # Number of blocks to process per tick (higher = faster but more CPU) batch-size: 500 # Blocks to restore per tick for FFA optimized regen (only changed blocks) default-interval: 300 # Default interval (seconds) applied by /ffasetup setregen true clear-entities: true # Remove dropped items/projectiles in region before regen ffaregen-teleport: surface # Where to teleport FFA players during regen: spawn or surface warning: enabled: true # Show warning before arena regeneration seconds: 10 # Seconds before regen to show warning message: "&c&lWARNING: &eArena regenerating in %seconds%s!" sound: "minecraft:block.note_block.pling" # Arena Defaults arenas: default-build-enabled: false # New arenas allow building by default default-regen-enabled: false # Automatically enable regen on /ffasetup create default-regen-interval: 300 # Interval in seconds when regen is enabled # Gameplay Settings settings: kit-previews: enabled: true # Toggle kit previews command readonly: true # Prevent players from taking items from preview instant-respawn-delay: 1 # Ticks before kit re-application after respawn # Duels Settings duels: countdown: seconds: 3 # Seconds before duel starts spectator: seconds: 4 # Seconds loser stays in spectator before end match-timeout-minutes: 15 # Auto-end matches after this many minutes (0 = disabled) start: title: "Starting in %seconds%" # Title subtitle template during countdown teleport: safety: ticks: 40 # Temporary flight/invulnerability ticks after teleport to avoid void falls # Queue Settings queue: max-wait-seconds: 60 # Not strictly enforced yet; for UI/feedback expand-per-5s: 50 # Elo window expansion per 5s arena-reserve-retries: 3 # Number of retry attempts if arena reservation fails match-found: delay-seconds: 3 # Delay before teleporting after match found # Sound to play on match found (namespaced id recommended) # Example: minecraft:entity.experience_orb.pickup sound: "minecraft:entity.experience_orb.pickup" boosting-cooldown-seconds: 0 # Disable queue cooldown (0 = no cooldown) # Elo/Ranked Settings elo: enabled: true global: true # Track global Elo per-kit: true # Track per-kit Elo initial: 1000 k-factor: 32 # Arena Boundary Settings boundary: enabled: false # Enable boundary enforcement (knockback when leaving arena) knockback-strength: 1.5 # How hard to push players back into arena damage: 0 # Damage to deal when hitting boundary (0 = no damage) message: "&cYou cannot leave the arena!" # Lobby Settings # FFA arenas are configured in ffa-arenas.yml lobby: spawn: "" # Lobby spawn location (set via /nucleus setspawn) # Player data storage options storage: type: YAML # YAML or MYSQL mysql: host: localhost port: 3306 database: nucleus username: root password: password use-ssl: false table-prefix: nucleus_ # ═══════════════════════════════════════════════════════════════ # PREMIUM FEATURES (Ignored in Free version) # ═══════════════════════════════════════════════════════════════ # Armor Trim Editor (Premium) # Allows players to customize armor trim patterns per kit armor-trims: enabled: true save-per-kit: true # Save different trims for each kit # Custom Items Support (Premium) # Integration with ItemsAdder and Oraxen custom-items: enabled: true itemsadder: true # Enable ItemsAdder integration oraxen: true # Enable Oraxen integration # Party System (Premium) party: enabled: true max-size: 10 # Maximum party size friendly-fire: false # Allow party members to damage each other # Discord Webhooks (Premium) discord: enabled: false webhook-url: "" # Your Discord webhook URL events: match-end: true # Send match results leaderboard-update: false # Send leaderboard changes division-change: true # Send division promotions/demotions embed-color: "#5865F2" # Discord embed color # Redis Cross-Server Sync (Premium) redis: enabled: false host: localhost port: 6379 password: "" channel: "nucleus" # Web Leaderboard API (Premium) web-api: enabled: false port: 8080 # HTTP server port auth-token: "" # API authentication token (leave empty to disable auth) ```

📄 divisions.yml - ELO Divisions & Ranks

```yaml divisions: unranked: display-name: "&7Unranked" min-elo: 0 max-elo: 999 bronze: display-name: "&6Bronze" min-elo: 1000 max-elo: 1199 silver: display-name: "&7Silver" min-elo: 1200 max-elo: 1399 gold: display-name: "&eGold" min-elo: 1400 max-elo: 1599 diamond: display-name: "&bDiamond" min-elo: 1600 max-elo: 1899 master: display-name: "&dMaster" min-elo: 1900 max-elo: 9999 ```

📄 scoreboards.yml - Scoreboard Layouts

```yaml # ═══════════════════════════════════════════════════════════════ # Nucleus Scoreboard Configuration (FastBoard - Flicker-Free) # ═══════════════════════════════════════════════════════════════ # # Supports hex colors (&#RRGGBB) and legacy colors (&a) # Use format for Nucleus placeholders # # ───────────────────────────────────────────────────────────── # STANDARD PLACEHOLDERS: # ───────────────────────────────────────────────────────────── # - Player name # - Player ping # - Online players # - Total kills # - Total deaths # - Kill/Death ratio # - Current killstreak # - Global ELO rating # - Current division # - Duel wins # - Duel losses # - Duel wins # - Duel losses # - Duel winstreak # - Duel win percentage # - Current kit # - Current arena # - FFA session kills # - FFA session deaths # - FFA session streak # - Players in queue # - Players fighting # - Players in FFA # - Server TPS # - Server time # # ───────────────────────────────────────────────────────────── # DUEL/SPECTATOR PLACEHOLDERS (only in duel/spectator context): # ───────────────────────────────────────────────────────────── # - Match duration (m:ss) # - Current round number # - Total rounds in match # - Your current health # - Your health as percentage # - Your total hits # - Your current combo # - Your longest combo # - Opponent's health # - Opponent's health % # - Opponent's total hits # - Opponent's current combo # - Opponent's longest combo # - Player 1 name (spectator) # - Player 1 health (spectator) # - Player 1 hits (spectator) # - Player 2 name (spectator) # - Player 2 health (spectator) # - Player 2 hits (spectator) # # ───────────────────────────────────────────────────────────── # ANIMATIONS (from animations.yml): # ───────────────────────────────────────────────────────────── # Use to insert animations defined in animations.yml # Example: or # # ───────────────────────────────────────────────────────────── # PER-KIT SCOREBOARDS: # ───────────────────────────────────────────────────────────── # Add under duel.kits. or ffa.kits. # Example: # duel: # kits: # nodebuff: # enabled: true # title: "&c&lNoDebuff" # lines: [...] # # ═══════════════════════════════════════════════════════════════ enabled: true update-interval: 10 # ticks (10 = 0.5 second for smoother updates) animation-interval: 5 # ticks for animation frame changes # ───────────────────────────────────────────────────────────── # LOBBY SCOREBOARD # ───────────────────────────────────────────────────────────── lobby: enabled: true title: "&f&lɴᴜᴄʟᴇᴜꜱ" lines: - "&8&m " - "" - " &fᴘʀᴏꜰɪʟᴇ" - " &8▸ &7ʀᴀɴᴋ: &f" - " &8▸ &7ᴇʟᴏ: &f" - "" - " &fꜱᴛᴀᴛꜱ" - " &8▸ &7ᴋɪʟʟꜱ: &f" - " &8▸ &7ᴅᴇᴀᴛʜꜱ: &f" - " &8▸ &7ᴋ/ᴅ: &f" - "" - " &fꜱᴇʀᴠᴇʀ" - " &8▸ &7ᴏɴʟɪɴᴇ: &f" - " &8▸ &7ꜰɪɢʜᴛɪɴɢ: &f" - "" - "&8&m " - " " # ───────────────────────────────────────────────────────────── # FFA ARENA SCOREBOARD # ───────────────────────────────────────────────────────────── ffa: enabled: true title: "&f&lꜰꜰᴀ" lines: - "&8&m " - "" - " &fᴀʀᴇɴᴀ" - " &8▸ &7ᴍᴀᴘ: &f" - " &8▸ &7ᴋɪᴛ: &f" - "" - " &fꜱᴇꜱꜱɪᴏɴ" - " &8▸ &7ᴋɪʟʟꜱ: &f" - " &8▸ &7ᴅᴇᴀᴛʜꜱ: &f" - " &8▸ &7ꜱᴛʀᴇᴀᴋ: &f" - "" - "&8&m " - " &7/ꜰꜰᴀ ʟᴇᴀᴠᴇ" # ───────────────────────────────────────────────────────────── # DUEL MATCH SCOREBOARD # ───────────────────────────────────────────────────────────── duel: enabled: true title: "&f&lᴅᴜᴇʟ" lines: - "&8&m " - "" - " &fᴍᴀᴛᴄʜ &8[&f&8]" - " &8▸ &7ᴏᴘᴘᴏɴᴇɴᴛ: &f%nucleus_opponent%" - " &8▸ &7ᴋɪᴛ: &f" - " &8▸ &7ʀᴏᴜɴᴅ: &f/" - "" - " &fʏᴏᴜ" - " &8▸ &7ʜᴇᴀʟᴛʜ: &f &8(&f&8)" - " &8▸ &7ʜɪᴛꜱ: &f &8| &7ᴄᴏᴍʙᴏ: &f" - "" - " &fᴏᴘᴘᴏɴᴇɴᴛ" - " &8▸ &7ʜᴇᴀʟᴛʜ: &f &8(&f&8)" - " &8▸ &7ʜɪᴛꜱ: &f &8| &7ᴄᴏᴍʙᴏ: &f" - "" - "&8&m " # Per-kit scoreboards (optional) # kits: # nodebuff: # enabled: true # title: "&f&lɴᴏᴅᴇʙᴜꜰꜰ" # lines: [...] # ───────────────────────────────────────────────────────────── # SPECTATOR SCOREBOARD # ───────────────────────────────────────────────────────────── spectator: enabled: true title: "&f&lꜱᴘᴇᴄᴛᴀᴛɪɴɢ" lines: - "&8&m " - "" - " &fᴍᴀᴛᴄʜ &8[&f&8]" - " &8▸ &7ᴋɪᴛ: &f" - " &8▸ &7ʀᴏᴜɴᴅ: &f/" - "" - " &f" - " &8▸ &7ʜᴇᴀʟᴛʜ: &f" - " &8▸ &7ʜɪᴛꜱ: &f" - "" - " &f" - " &8▸ &7ʜᴇᴀʟᴛʜ: &f" - " &8▸ &7ʜɪᴛꜱ: &f" - "" - "&8&m " - " &7/ꜱᴘᴇᴄᴛᴀᴛᴇ ʟᴇᴀᴠᴇ" # ───────────────────────────────────────────────────────────── # QUEUE SCOREBOARD # ───────────────────────────────────────────────────────────── queue: enabled: true title: "&f&lǫᴜᴇᴜᴇ" lines: - "&8&m " - "" - " &fꜱᴇᴀʀᴄʜɪɴɢ " - " &8▸ &7ᴋɪᴛ: &f%nucleus_queue_kit%" - " &8▸ &7ᴍᴏᴅᴇ: &f%nucleus_queue_mode%" - " &8▸ &7ɪɴ ǫᴜᴇᴜᴇ: &f" - "" - " &fʏᴏᴜʀ ʀᴀᴛɪɴɢ" - " &8▸ &7ᴇʟᴏ: &f" - " &8▸ &7ʀᴀɴᴋ: &f" - " &8▸ &7ᴡɪɴʀᴀᴛᴇ: &f" - "" - "&8&m " ```

📄 animations.yml - Custom Animations

```yaml # Rainbow text animation rainbow: change-interval: 100 # milliseconds texts: - "&#FF0000&lN&#FF7F00&lU&#FFFF00&lC..." - "&#FF7F00&lN&#FFFF00&lU�FF00&lC..." # Dots loading animation dots: change-interval: 300 texts: - "&7ʟᴏᴀᴅɪɴɢ" - "&7ʟᴏᴀᴅɪɴɢ&f." - "&7ʟᴏᴀᴅɪɴɢ&f.." - "&7ʟᴏᴀᴅɪɴɢ&f..." # Pulse animation pulse: change-interval: 150 texts: - "&#FFFFFF&lNUCLEUS" - "&#DDDDDD&lNUCLEUS" - "&#BBBBBB&lNUCLEUS" - "󴈿&lNUCLEUS" ``` Use in scoreboards: `` or ``

📄 hotbar.yml - Lobby Hotbar Items

```yaml items: unranked: slot: 0 material: IRON_SWORD name: "&f&lᴜɴʀᴀɴᴋᴇᴅ" lore: - "&7Click to open unranked menu" action: "open_menu:unranked" ranked: slot: 1 material: DIAMOND_SWORD name: "&b&lʀᴀɴᴋᴇᴅ" lore: - "&7Click to open ranked menu" action: "open_menu:ranked" settings: slot: 8 material: COMPARATOR name: "&7&lꜱᴇᴛᴛɪɴɢꜱ" action: "open_menu:settings" ```

📄 settings.yml - Player Settings

```yaml settings: scoreboard: enabled: true default: true duel-requests: enabled: true default: true public-chat: enabled: true default: true private-messages: enabled: true default: true player-visibility: enabled: true default: false ```

### Placeholders **All placeholders are available in scoreboards.yml** --- ## 💎 Free vs Premium | Feature | Free | Premium | |---------|:----:|:-------:| | **Duel System (1v1)** | ✅ | ✅ | | **FFA Arenas** | ✅ | ✅ | | **Kit Editor** | ✅ | ✅ | | **Scoreboards & Animations** | ✅ | ✅ | | **Statistics & Leaderboards** | ✅ | ✅ | | **Ranked Queue (ELO)** | ✅ | ✅ | | **Divisions System** | ✅ | ✅ | | **MySQL Support** | ✅ | ✅ | | **PlaceholderAPI** | ✅ | ✅ | | **Max Arenas** | 20 | ∞ Unlimited | | **Max Kits** | 7 | ∞ Unlimited | | **Armor Trim Editor** | ❌ | ✅ | | **2v2 Duels** | ❌ | ✅ | | **Party System** | ❌ | ✅ | | **Custom Items (ItemsAdder/Oraxen)** | ❌ | ✅ | | **Discord Webhooks** | ❌ | ✅ | | **Redis (Cross-Server Sync)** | ❌ | ✅ | | **Web Leaderboard** | ❌ | ✅ | | **Priority Support** | ❌ | ✅ |

### 🚧 Premium Coming Soon 🚧 *Premium features are currently in development. Stay tuned!*

--- ## �� Requirements | Requirement | Version | Required | |-------------|---------|----------| | Paper (or fork) | 1.21.8+ | ✅ Yes | | Java | 21+ | ✅ Yes | | Vault | 1.7+ | ❌ Optional | --- ## 📦 Installation 1. **Download** the latest release 2. **Place** `Nucleus.jar` in your `plugins/` folder 3. **Restart** your server 4. **Configure** the plugin via `/nucleus` GUI or config files 5. **Create** arenas and kits using the setup commands --- ## 🆘 Support - **Documentation**: [Wiki](https://nucleus.ayosynk0.workers.dev/) - **Discord**: [Join our Discord](https://discord.gg/pAPPvSmWRK) ---

TheCMK

Mellow

Reverie