NeptuneFFA

Overview

NeptuneFFA is a high-performance, kit-based Free-For-All (FFA) engine designed specifically for the Neptune Core practice framework.

Core Features

Selector Menu

The player interface is built around a dynamic Graphical User Interface (GUI) accessible via /ffa or by interacting with the designated lobby item.

• Real-Time Arena Diagnostics: When hovering over any kit icon, the GUI displays the number of active combatants, the active map name, and the exact seconds remaining before the arena undergoes a scheduled reset.
• Dynamic GUI Resets: The GUI updates its timers and player counts in real time (every 1 second) while open, eliminating the need for players to close and reopen the interface.
• Custom Slot Mapping and Fillers: Server administrators can set a custom GUI size (9 to 54 slots) and manually assign specific slots to popular kits. Remaining kits are auto-allocated, and empty slots can be filled with customizable materials (such as colored stained glass panes) with custom display names.
• One-Click Interaction: Left-clicking a kit joins the corresponding active arena. Right-clicking the active kit leaves the arena and returns the player to the lobby.

Admin Control

The /ffaadmin interface provides real-time control over active arenas and configurations directly in-game.

• Session Monitor: Provides a visual list of all active sessions, showing player counts, current arena settings, and remaining time before automated resets. It supports right-clicking a session to force an immediate map rollback and player kick.
• Kit Settings Panel: Enables admins to toggle FFA status, toggle worldgen block rollbacks, adjust reset intervals, and manage spawn locations.
• Interactive Spawn Editor: Opens a sub-menu showing all registered spawn points for a kit. Admins can click to add their current location, teleport to existing spawn points, or clear them.
• Live Slot Arranger: Allows admins to rearrange kit icons in the player GUI visually. Left-clicking increments the slot index, right-clicking decrements it, and shift-clicking jumps the icon by whole rows. All changes save to configuration files instantly.

Mechanics

Block Rollbacks

For kits that permit placing or breaking blocks (e.g., CrystalPVP or BuildUHC), NeptuneFFA tracks block interactions. Upon session resets (triggered manually or when the countdown timer expires):

1. All players in the session are safely teleported back to the lobby.
2. Placed blocks are automatically reverted in-memory or via schematic files.
3. The arena session is re-opened and made available for players after a 3-second delay.

Combat Tagging

To prevent combat logging, NeptuneFFA features a built-in combat tag tracker:

• Combat Tag Timer: Displays a countdown directly in the player's action bar (e.g., "Combat Tag: 8s") supporting full hex codes and MiniMessage formatting.
• Command & Log Protection: Prevents command preprocess events and teleportation while in combat. Disconnecting while tagged triggers a death penalty, transferring kills and updating statistics.

Formatting

Supports MiniMessage formatting, standard chat colors (e.g., &a), and hexadecimal formatting (e.g., &#FF5555). These styling systems are fully parsed in menus, scoreboards, action bars, and chat alerts.

---

Configuration

The plugin uses three primary files located in the plugins/NeptuneFFA/ folder:

config.yml Governs global parameters, the lobby item layout, global countdowns, and scoreboard configurations.

ffa:
  # Item given to lobby players to access the selector
  lobby-item:
    enabled: true
    slot: 8
    material: DIAMOND_SWORD
    name: "&c&lFree For All &7(Right Click)"
    lore:
      - "&7Jump into an FFA arena"
  respawn-delay-seconds: 5
  reset-warning-seconds: [60, 30, 10, 5]
  track-neptune-kit-stats: true
  # Scoreboard lines for players in the "IN_FFA" state
  scoreboard:
    update-interval-ticks: 20
    title: "&c&lFFA"
    lines:
      - "&7&m--------------------"
      - "&fKit: &c<ffa_kit>"
      - "&fArena: &e<ffa_arena>"
      - "&fPlayers: &a<ffa_players>"
      - " "
      - "&6Reset in: &e<ffa_reset_timer>"
      - " "
      - "&7- Session -"
      - "&fKills: &a<ffa_session_kills>"
      - "&fDeaths: &c<ffa_session_deaths>"
      - "&fStreak: &e<ffa_session_streak>"
      - "&fBest Streak: &6<ffa_session_best_streak>"
      - "&fKDR: &b<ffa_session_kdr>"
      - " "
      - "&7- Lifetime -"
      - "&fKills: &a<ffa_lifetime_kills>"
      - "&fDeaths: &c<ffa_lifetime_deaths>"
      - "&fBest Streak: &6<ffa_lifetime_best_streak>"
      - "&fKDR: &b<ffa_kdr>"
      - " "
      - "&7- Ranking -"
      - "&fGlobal Rank: &d#<ffa_rank>"
      - "&fTop Killer: &e<ffa_top_killer> &7(<ffa_top_killer_kills>)"
      - "&fKills to Pass: &c<ffa_kills_to_next_rank>"
      - " "
      - "&bserver.net"
      - "&7&m--------------------"

kits.yml Stores configurations for each registered kit. Edited automatically by the in-game admin menu.

kits:
  NoDebuff:
    enabled: true                    # Toggle FFA availability
    arena: CastleTop                 # Linked Neptune arena name
    worldgen: false                  # Toggle block resets
    reset-interval-minutes: 10       # Re-open/rollback countdown interval
    respawn-delay-override: -1       # Override global delay (-1 to disable)
    gui-slot: 4                      # GUI button slot override (-1 for auto-slot)
    spawn-points:                    # Serialized spawn locations
      - "world,0.5,64.0,0.5,90.0,0.0"

messages.yml Defines localized text and chat formats. Supports hex codes and MiniMessage tags.

ffa-join:        "&a{player} &7joined FFA &e({kit})&7."
ffa-leave:       "&c{player} &7left FFA &e({kit})&7."
ffa-kill:        "&c{killer} &7killed &c{victim} &8[&e{victim_session_kills} kills&8]"
ffa-reset-warn:  "&6[FFA] &eArena resets in &c{seconds}s&e!"
ffa-reset-kick:  "&6[FFA] &eArena is resetting. Returning you to lobby."
ffa-reset-open:  "&6[FFA] &eArena &a{arena} &ehas reopened!"
ffa-respawn:     "&7Respawning in &e{seconds}&7..."
ffa-no-session:  "&cNo FFA session is open for that kit."
ffa-not-in-ffa:  "&cYou are not in an FFA session."
ffa-already-in:  "&cYou are already in an FFA session."

---

Commands

Command	Description	Permission Node
/ffa	Opens the interactive FFA Kit Selector Menu	None (Default)
/ffa join <kit>	Directly join the FFA session for the specified kit	None (Default)
/ffa leave	Leave the current FFA session and return to the lobby	None (Default)
/ffa list	List all active FFA sessions and current player counts	None (Default)
/ffa stats [player]	View your own or another player's FFA statistics	neptuneffa.stats.others (to view others)
/ffaadmin	Opens the FFA Admin Control Panel GUI	neptuneffa.admin
/ffaadmin reload	Reload configuration files and rebuild sessions	neptuneffa.admin
/ffaadmin reset <kit>	Force-resets the specified kit's arena session	neptuneffa.admin
/ffaadmin addspawn <kit>	Add your current location as a spawn point for a kit	neptuneffa.admin

---

Placeholders

These placeholders resolve dynamically when placed in the scoreboard config or parsed globally via PlaceholderAPI (using the %neptuneffa_% prefix):

Scoreboard Tag	PlaceholderAPI Variable	Description
<ffa_kit>	%neptuneffa_session_kit%	The name of the active session's kit
<ffa_arena>	%neptuneffa_session_arena%	The name of the active session's arena
<ffa_players>	%neptuneffa_session_players%	Total player count in the session
<ffa_reset_timer>	%neptuneffa_session_reset_timer%	Formatted reset countdown (MM:SS)
<ffa_session_kills>	%neptuneffa_session_kills%	Kills achieved in the current session
<ffa_session_deaths>	%neptuneffa_session_deaths%	Deaths suffered in the current session
<ffa_session_streak>	%neptuneffa_session_streak%	Active consecutive killstreak
<ffa_session_best_streak>	%neptuneffa_session_best_streak%	Highest killstreak in the current session
<ffa_session_kdr>	%neptuneffa_session_kdr%	Kill/Death ratio for the current session
<ffa_time_in_session>	%neptuneffa_session_time%	Formatted duration spent in the session
<ffa_lifetime_kills>	%neptuneffa_lifetime_kills%	Cumulative lifetime kills across all sessions
<ffa_lifetime_deaths>	%neptuneffa_lifetime_deaths%	Cumulative lifetime deaths across all sessions
<ffa_lifetime_best_streak>	%neptuneffa_lifetime_best_streak%	Best killstreak achieved lifetime
<ffa_lifetime_sessions>	%neptuneffa_lifetime_sessions%	Cumulative number of FFA sessions joined
<ffa_kdr>	%neptuneffa_lifetime_kdr%	Cumulative lifetime Kill/Death ratio
<ffa_ping>	%neptuneffa_ping%	The player's active ping connection latency
<ffa_rank>	%neptuneffa_rank%	Player's global placement based on kills
<ffa_top_killer>	%neptuneffa_top_killer%	Name of the player with the highest lifetime kills
<ffa_top_killer_kills>	%neptuneffa_top_killer_kills%	Kill count of the top ranked player
<ffa_kills_to_next_rank>	%neptuneffa_kills_to_next_rank%	Kills required to overtake the rank ahead

---

Setup Guide

1. Define your practice kit configuration in the Neptune core settings.
2. Open plugins/NeptuneFFA/kits.yml and add the kit name as a key (matching Neptune's name case-sensitively).
3. Set enabled: true and input the mapped Neptune arena name in the arena configuration block.
4. Stand at the desired spawn point locations in your arena and execute /ffaadmin addspawn <kit> (or add it via the /ffaadmin GUI under Kit Settings -> Spawn Points). Add multiple points to enable random spawn cycling.
5. Execute /ffaadmin reload to instantiate the session. The arena is now open for players.

---

Support

Support Server: Discord Server