Nucleus

⚔️ Nucleus

PvP Practice Plugin

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 `<animation:name>` 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

# 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 <name>
# Follow the interactive setup wizard

# 5. Create a kit
/akit create <name>
# Customize in the kit editor GUI

📝 Commands

Player Commands

Command	Description
`/duel <player>`	Send a duel request
`/duel <player> <kit>`	Duel with specific kit
`/duel queue [kit]`	Join ranked matchmaking
`/duel leave`	Leave queue or forfeit match
`/ffa join <arena>`	Join an FFA arena
`/ffa leave`	Leave FFA
`/ffa list`	List available arenas
`/stats [player]`	View player statistics
`/leaderboard`	Open leaderboard GUI
`/spectate <player>`	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 <name>`	Create a new duel arena
`/dsetup delete <name>`	Delete a duel arena
`/dsetup list`	List all duel arenas
`/ffasetup create <name>`	Create an FFA arena
`/ffasetup delete <name>`	Delete an FFA arena
`/akit create <name>`	Create a new kit
`/akit delete <name>`	Delete a kit
`/akit edit <name>`	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

# 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 <arena> 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

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

# ═══════════════════════════════════════════════════════════════
# Nucleus Scoreboard Configuration (FastBoard - Flicker-Free)
# ═══════════════════════════════════════════════════════════════
# 
# Supports hex colors (&#RRGGBB) and legacy colors (&a)
# Use <placeholder> format for Nucleus placeholders
#
# ─────────────────────────────────────────────────────────────
# STANDARD PLACEHOLDERS:
# ─────────────────────────────────────────────────────────────
#   <player>         - Player name
#   <ping>           - Player ping
#   <players>        - Online players
#   <kills>          - Total kills
#   <deaths>         - Total deaths  
#   <kdr>            - Kill/Death ratio
#   <streak>         - Current killstreak
#   <elo>            - Global ELO rating
#   <division>       - Current division
#   <wins>           - Duel wins
#   <losses>         - Duel losses
#   <duel_wins>      - Duel wins
#   <duel_losses>    - Duel losses
#   <duel_streak>    - Duel winstreak
#   <winrate>        - Duel win percentage
#   <kit>            - Current kit
#   <arena>          - Current arena
#   <session_kills>  - FFA session kills
#   <session_deaths> - FFA session deaths
#   <session_streak> - FFA session streak
#   <in_queue>       - Players in queue
#   <in_fight>       - Players fighting
#   <in_ffa>         - Players in FFA
#   <tps>            - Server TPS
#   <time>           - Server time
#
# ─────────────────────────────────────────────────────────────
# DUEL/SPECTATOR PLACEHOLDERS (only in duel/spectator context):
# ─────────────────────────────────────────────────────────────
#   <match_time>           - Match duration (m:ss)
#   <round>                - Current round number
#   <total_rounds>         - Total rounds in match
#   <your_health>          - Your current health
#   <your_health_percent>  - Your health as percentage
#   <your_hits>            - Your total hits
#   <your_combo>           - Your current combo
#   <your_max_combo>       - Your longest combo
#   <opponent_health>      - Opponent's health
#   <opponent_health_percent> - Opponent's health %
#   <opponent_hits>        - Opponent's total hits
#   <opponent_combo>       - Opponent's current combo
#   <opponent_max_combo>   - Opponent's longest combo
#   <player1>              - Player 1 name (spectator)
#   <player1_health>       - Player 1 health (spectator)
#   <player1_hits>         - Player 1 hits (spectator)
#   <player2>              - Player 2 name (spectator)
#   <player2_health>       - Player 2 health (spectator)
#   <player2_hits>         - Player 2 hits (spectator)
#
# ─────────────────────────────────────────────────────────────
# ANIMATIONS (from animations.yml):
# ─────────────────────────────────────────────────────────────
# Use <animation:name> to insert animations defined in animations.yml
# Example: <animation:rainbow> or <animation:pulse>
#
# ─────────────────────────────────────────────────────────────
# PER-KIT SCOREBOARDS:
# ─────────────────────────────────────────────────────────────
# Add under duel.kits.<kitname> or ffa.kits.<kitname>
# 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<division>"
    - "  &8▸ &7ᴇʟᴏ: &f<elo>"
    - ""
    - " &fꜱᴛᴀᴛꜱ"
    - "  &8▸ &7ᴋɪʟʟꜱ: &f<kills>"
    - "  &8▸ &7ᴅᴇᴀᴛʜꜱ: &f<deaths>"
    - "  &8▸ &7ᴋ/ᴅ: &f<kdr>"
    - ""
    - " &fꜱᴇʀᴠᴇʀ"
    - "  &8▸ &7ᴏɴʟɪɴᴇ: &f<players>"
    - "  &8▸ &7ꜰɪɢʜᴛɪɴɢ: &f<in_fight>"
    - ""
    - "&8&m                              "
    - " <animation:dots>"

# ─────────────────────────────────────────────────────────────
# FFA ARENA SCOREBOARD
# ─────────────────────────────────────────────────────────────
ffa:
  enabled: true
  title: "&f&lꜰꜰᴀ"
  lines:
    - "&8&m                              "
    - ""
    - " &fᴀʀᴇɴᴀ"
    - "  &8▸ &7ᴍᴀᴘ: &f<arena>"
    - "  &8▸ &7ᴋɪᴛ: &f<kit>"
    - ""
    - " &fꜱᴇꜱꜱɪᴏɴ"
    - "  &8▸ &7ᴋɪʟʟꜱ: &f<session_kills>"
    - "  &8▸ &7ᴅᴇᴀᴛʜꜱ: &f<session_deaths>"
    - "  &8▸ &7ꜱᴛʀᴇᴀᴋ: &f<session_streak>"
    - ""
    - "&8&m                              "
    - " &7/ꜰꜰᴀ ʟᴇᴀᴠᴇ"

# ─────────────────────────────────────────────────────────────
# DUEL MATCH SCOREBOARD
# ─────────────────────────────────────────────────────────────
duel:
  enabled: true
  title: "&f&lᴅᴜᴇʟ"
  lines:
    - "&8&m                              "
    - ""
    - " &fᴍᴀᴛᴄʜ &8[&f<match_time>&8]"
    - "  &8▸ &7ᴏᴘᴘᴏɴᴇɴᴛ: &f%nucleus_opponent%"
    - "  &8▸ &7ᴋɪᴛ: &f<kit>"
    - "  &8▸ &7ʀᴏᴜɴᴅ: &f<round>/<total_rounds>"
    - ""
    - " &fʏᴏᴜ"
    - "  &8▸ &7ʜᴇᴀʟᴛʜ: &f<your_health> &8(&f<your_health_percent>&8)"
    - "  &8▸ &7ʜɪᴛꜱ: &f<your_hits> &8| &7ᴄᴏᴍʙᴏ: &f<your_combo>"
    - ""
    - " &fᴏᴘᴘᴏɴᴇɴᴛ"
    - "  &8▸ &7ʜᴇᴀʟᴛʜ: &f<opponent_health> &8(&f<opponent_health_percent>&8)"
    - "  &8▸ &7ʜɪᴛꜱ: &f<opponent_hits> &8| &7ᴄᴏᴍʙᴏ: &f<opponent_combo>"
    - ""
    - "&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<match_time>&8]"
    - "  &8▸ &7ᴋɪᴛ: &f<kit>"
    - "  &8▸ &7ʀᴏᴜɴᴅ: &f<round>/<total_rounds>"
    - ""
    - " &f<player1>"
    - "  &8▸ &7ʜᴇᴀʟᴛʜ: &f<player1_health>"
    - "  &8▸ &7ʜɪᴛꜱ: &f<player1_hits>"
    - ""
    - " &f<player2>"
    - "  &8▸ &7ʜᴇᴀʟᴛʜ: &f<player2_health>"
    - "  &8▸ &7ʜɪᴛꜱ: &f<player2_hits>"
    - ""
    - "&8&m                              "
    - " &7/ꜱᴘᴇᴄᴛᴀᴛᴇ ʟᴇᴀᴠᴇ"

# ─────────────────────────────────────────────────────────────
# QUEUE SCOREBOARD
# ─────────────────────────────────────────────────────────────
queue:
  enabled: true
  title: "&f&lǫᴜᴇᴜᴇ"
  lines:
    - "&8&m                              "
    - ""
    - " &fꜱᴇᴀʀᴄʜɪɴɢ <animation:dots>"
    - "  &8▸ &7ᴋɪᴛ: &f%nucleus_queue_kit%"
    - "  &8▸ &7ᴍᴏᴅᴇ: &f%nucleus_queue_mode%"
    - "  &8▸ &7ɪɴ ǫᴜᴇᴜᴇ: &f<in_queue>"
    - ""
    - " &fʏᴏᴜʀ ʀᴀᴛɪɴɢ"
    - "  &8▸ &7ᴇʟᴏ: &f<elo>"
    - "  &8▸ &7ʀᴀɴᴋ: &f<division>"
    - "  &8▸ &7ᴡɪɴʀᴀᴛᴇ: &f<winrate>"
    - ""
    - "&8&m                              "

📄 animations.yml - Custom Animations

# Rainbow text animation
rainbow:
  change-interval: 100  # milliseconds
  texts:
    - "&#FF0000&lN&#FF7F00&lU&#FFFF00&lC..."
    - "&#FF7F00&lN&#FFFF00&lU&#00FF00&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"
    - "&#999999&lNUCLEUS"

Use in scoreboards: <animation:rainbow> or <animation:dots>

📄 hotbar.yml - Lobby Hotbar Items

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

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

Download the latest release
Place Nucleus.jar in your plugins/ folder
Restart your server
Configure the plugin via /nucleus GUI or config files
Create arenas and kits using the setup commands

🆘 Support

Documentation: Wiki
Discord: Join our Discord