EasyFFA - Ultimate Free-For-All 0.1

Feature Highlights

• Safe Zones — Protect spawn/areas with a simple two-point selection flow.
• Map Rotation — Automated rotation with messages, countdowns, and teleports.
• Kits & Map Kits — Create kits from inventory and assign per-world.
• Stats & Ranks — Track kills, deaths, points, exp; configurable rank ladder.
• Killstreaks — Broadcast milestones (3, 5, 7, 10, 15, 20, 25 by default).
• Bounties — Players spend points to place bounties; killers earn rewards.
• Combat Logging — Tag timer + optional punishments/commands.
• Scoreboard & Tablist — Show player stats/rank; configurable formatting.
• Join Flow & Spawn — Spawn countdown, world-specific spawns, optional force-adventure-mode, and QoL rules (prevent drops/breaking/durability).
• Build Mode — Admins can toggle build mode for editing during FFA.
• Chat Control — Quick clear your own chat or global chat via admin commands.
• Game Rule Loader — Automatically (re)applies sensible world gamerules on startup.
• Config-First — Everything is configurable in config.yml.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Requirements & Compatibility

• Spigot/Paper 1.21+
• Java 21 recommended (built for modern runtimes)
• Optional: MySQL/MariaDB if you enable database storage (driver included)

Note: EasyFFA is designed for network setups. The scoreboard, join/leave handling, and related messages/mechanics are always active by design. 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Installation

1. Place the EasyFFA jar into your server's plugins folder.
2. Start the server once to generate config files.
3. Open plugins/EasyFFA/config.yml and adjust settings (messages, points/exp, ranks, killstreaks, chat format, combat tag, etc.).
4. (Optional) Enable MySQL in the config and set credentials (details below).
5. Create kits, set map spawns, and (optional) define safe zones.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Quick Start 

• Set spawn for your current world: /ffa setspawn
• Create a kit from your inventory: /ffa kit create <name>
• Assign that kit to the current world: /ffa kit setmap <name>
• (Optional) Define a safe zone: /ffa zone set (twice to complete the two corners)
• (Optional) Choose default active world (when map rotation is off): /ffa activemap <world>
• (Optional) Start map rotation: /ffa mapchange start

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Maps & Safe Zones

• Spawn Per World
  /ffa setspawn sets the FFA spawn point for the current world. Players can use /spawn; a configurable countdown prevents abuse.
• Safe Zone Setup
  • Stand at corner 1 and run: /ffa zone set
  • Stand at the opposite corner and run: /ffa zone set again
  • Done — the region is protected, with clear titles on enter/leave
  If you make a mistake: /ffa zone del cancels the setup.
  Zones are saved per-world and automatically loaded on server start.
• Active Map (Join Behavior, No Rotation)
  If automatic map rotation is not used, the world configured under ActiveWorldName in config.yml is treated as the active FFA world. All players are teleported to this world on join. For the best FFA experience, make sure this world has a properly defined safe zone and spawn.
  
  Use /ffa activemap <world> to update the default active world. This command immediately updates the config value and teleports all online players to the newly set world.
  
  If you do not enable map rotation and also leave ActiveWorldName unset/unused, players will join in a random/default world as defined by the server. This behavior is not controlled by EasyFFA.
• Map Rotation
  Use /ffa mapchange start to begin rotation across your configured worlds, with broadcasted countdowns and automatic teleports. Stop anytime with /ffa mapchange stop. If enabled in config and at least two maps are available, rotation can auto-start on server boot.
  When map rotation is enabled, ActiveWorldName is ignored and players will always join the current rotating map.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Kits

• Create from Inventory: Equip items/armor, then run /ffa kit create <name>.
• List Kits: /ffa kit list
• Delete Kit: /ffa kit delete <name>
• Assign Kit to World: /ffa kit setmap <name> (applies to your current world)
• Players can use assigned map kits automatically on join.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Stats, Points, EXP, Ranks & Killstreaks

• Stats GUI: /stats to view personal stats (kills, deaths, points, K/D, rank, exp).
• Points: Gain on kills, lose on death — fully configurable.
• Experience: Award EXP per kill; define rank thresholds in config.
• Ranks: Displayed in tablist/scoreboard; define names and thresholds in FFA.Ranks.
• Killstreaks: Broadcast messages at configured thresholds.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Bounties (Optional PvP Economy Twist)
Players can spend points to place bounties on others; rewards are paid out to the killer.

• /bounty — Help and subcommands
• /bounty add <player> <level> — Place a bounty (costs points, configurable per level)
• /bounty level — View bounty tiers and their costs/rewards
• /bounty list — List all active bounties on the server
• Important: Adding a bounty to a player who already has one will overwrite the previous bounty level. The levels do not stack - the new bounty completely replaces the old one.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Combat Logging Control
Tag players in combat for a set duration. Optionally execute server commands, deduct points, or reset stats if they log out.
Configure under FFA.CombatLogging in config.yml.
Common options:
• TagDurationSeconds: how long a player stays in combat after the last hit.
• Punishments.CommandsEnabled + Punishments.Commands: run console commands (e.g., warn/kick).
• Punishments.ResetAllStatsEnabled: reset the offender's stats.
• Punishments.DeductPointsEnable + DeductPointsValue: remove points on combat logout.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scoreboard and Tablist

• Scoreboard: Toggle and customize titles/lines in FFA.Scoreboard.
• Tablist: Show rank and format names (e.g., Format: '&f[%RANK%&r&f] %NAME%').

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Storage Options

• Flatfile (Default) — Simple YAML storage; no setup required. Files: kits.yml, stats.yml, bounties.yml.
• MySQL/MariaDB (Optional) — Enable in config.yml under FFA.MySQL. The MariaDB JDBC driver is bundled so you don’t need to install it. Stats support MySQL; other data may remain YAML depending on your setup.

FFA:
  MySQL:
    Enabled: true
    Host: 'localhost'
    Port: 3306
    Username: 'minecraft'
    Password: 'password'

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Optional Chat Styling
You can optionally enable EasyFFA's chat formatting and styling in config.yml:

• Path: FFA.Chat
• Enabled: true/false
• Format: e.g. "%PREFIX% %RANK% >> %PLAYER%&7: %MESSAGE%"
• DefaultPrefix: e.g. "&7"

When enabled, EasyFFA will format player chat according to your Format. You can include rank/prefix placeholders.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Commands & Usage

• /stats — View your FFA stats
• /spawn — Teleport to the map spawn (with optional countdown/cooldown)
• /points
  • /points — Help
  • /points add <player> <amount>
  • /points set <player> <amount>
  • /points remove <player> <amount>
• /bounty
  • /bounty — Help
  • /bounty level — View bounty levels
  • /bounty add <player> <level> — Place a bounty
  • /bounty list — List all active bounties
  • /bounty remove <player> — Remove a bounty (if enabled/authorized)
• /ffa
  • /ffa — Info & help
  • /ffa tp <world> — Teleport to a world
  • /ffa activemap <world> — Set the default active world (updates ActiveWorldName) and teleport all players there
  • /ffa zone set — Start/complete a safe-zone selection
  • /ffa zone del — Cancel a safe-zone selection
  • /ffa spawn — Teleport to current world’s map spawn
  • /ffa setspawn — Set/update spawn for current world (admin)
  • /ffa build — Toggle build mode (admin)
  • /ffa mapchange <start|stop|state> — Control map rotation
  • /ffa kit list — List kits and map assignments
  • /ffa kit create <name> — Create a kit from your inventory (admin)
  • /ffa kit delete <name> — Delete a kit (admin)
  • /ffa kit setmap <name> — Assign kit to current world (admin)
  • /ffa resetstats <stats|points|exp|ranks|killstreaks|bounties|all> — Reset stats (admin)
  • /ffa cc — Clear your own chat (admin)
  • /ffa ccg — Clear global chat (admin)

Note: /ffa resetstats lets you target a specific category (e.g., points only) or all.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

API Documentation
You can find detailed API documentation in the documentation, including event subscription examples and integration tips.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Permissions Overview

• easyffa.* — Full access
• easyffa.ffa — Use /ffa (default: true)
• easyffa.world.tp — World teleport (default: op)
• easyffa.kit — Use kits (default: true)
• easyffa.admin.kit — Manage kits (default: op)
• easyffa.admin.setspawn — Set spawn (default: op)
• easyffa.admin.cc — Clear chat (default: op)
• easyffa.admin.zone — Manage safe zones (default: op)
• easyffa.admin.resetstats — Reset player statistics (default: op)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Configuration Tips

• Tweak points/exp gain under FFA.Points and FFA.Exp.
• Define rank thresholds and names under FFA.Ranks.
• Adjust killstreak broadcasts under FFA.Killstreaks.
• Customize scoreboard and tablist in their respective sections.
• Use the action bar kill messages to keep feedback snappy and non-intrusive.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Performance & Quality

• Optimized for modern Spigot APIs; no NMS.
• Asynchronous operations where appropriate.
• Lightweight runtime footprint and clean config defaults.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━


Quick Setup (recommended order) 

1. Go to your FFA world and set the spawn: /ffa setspawn
2. Create your first kit from your inventory: /ffa kit create <name>
3. Assign that kit to the current world: /ffa kit setmap <name>
4. (Optional) Define a safe zone (see section below).
5. (Optional) Not using rotation? Set the default active world: /ffa activemap <world>
6. (Optional) Enable Map Rotation (see section below).

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Maps & Safe Zones

• World spawn
  Use /ffa setspawn in each world where you run FFA. Players can use /spawn; a countdown prevents abuse (configurable).
• Safe zone setup (two corners)
  • Stand at corner 1 and run: /ffa zone set
  • Stand at the opposite corner and run: /ffa zone set again
  • Done - the region is protected, with titles on enter/leave
  If you make a mistake: /ffa zone del cancels the setup.
  Safe zones are saved per-world and auto-loaded on server start.
• Active map when rotation is OFF
  If you are not using Map Rotation, the world set under ActiveWorldName in config.yml is considered the active FFA world. On join, players are teleported to this world automatically. For best results, ensure the world has a safe zone and a valid spawn.
  
  Use /ffa activemap <world> to update ActiveWorldName. Executing this command also teleports all online players to the newly set world immediately.
  
  If Map Rotation is disabled and ActiveWorldName is not set/used, players will join a random/default world defined by the server. This fallback is not controlled by EasyFFA.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Kits Management

• Create from inventory: equip items/armor, then run /ffa kit create <name>
• List kits: /ffa kit list
• Delete kit: /ffa kit delete <name>
• Assign kit to current world: /ffa kit setmap <name>
  Players joining that world will receive the assigned map kit automatically.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Map Rotation

• Start: /ffa mapchange start
• Stop: /ffa mapchange stop
• Status: /ffa mapchange state
  Rotation broadcasts countdowns and teleports players when switching. If FFA.UseMapchange is enabled and at least two maps are configured/available, rotation can auto-start on boot.

Note: When Map Rotation is enabled, ActiveWorldName is ignored. Players always join the current rotating map.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Points, Stats, EXP, Ranks & Killstreaks

• View stats: /stats
• Manage points (admin):
  • /points add <player> <amount>
  • /points set <player> <amount>
  • /points remove <player> <amount>
• Configuration: tune gain/loss in FFA.Points and FFA.Exp; define rank thresholds in FFA.Ranks; killstreak broadcasts under FFA.Killstreaks.
• Reset stats (admin): /ffa resetstats <stats|points|exp|ranks|killstreaks|bounties|all>
  Use categories to target specific subsets or all.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Bounties

• Help: /bounty
• Place bounty: /bounty add <player> <level>
• View levels: /bounty level
• List active bounties: /bounty list
  • Configure costs/rewards per level in FFA.Bounties.Levels (config.yml).
  • Rewards are granted automatically to the killer.
  • Note: Adding a bounty to a player who already has one will overwrite the previous bounty level. The levels do not stack.

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Combat Logging Control 
Tag players in combat and punish logout during tag time.

• Config path: FFA.CombatLogging
• Key options:
  • TagDurationSeconds - duration after last hit
  • Punishments.CommandsEnabled + Punishments.Commands - console cmds (e.g., warn/kick)
  • Punishments.ResetAllStatsEnabled - reset offender stats
  • Punishments.DeductPointsEnable + DeductPointsValue - remove points

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Chat Styling (optional)
Enable EasyFFA chat formatting to standardize PvP chat style.

• Config path: FFA.Chat
• Keys: Enabled, Format, DefaultPrefix
• Example Format: "%PREFIX% %RANK% >> %PLAYER%&7: %MESSAGE%"

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Scoreboard & Tablist

• Scoreboard: configure visibility/lines under FFA.Scoreboard
• Tablist: format and rank display (example format provided in description)

Note: EasyFFA targets network setups. The scoreboard, join/leave handling, and related messages/mechanics are always active. 

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Subscribing to EasyFFA Events
Integrate with EasyFFA by subscribing to custom events. This allows you to easily integrate your own money/currency systems.

• BountySetEvent - Triggered when a player's bounty level changes.
• BountyResolvedEvent - Triggered when a bounty is claimed by a killer.
• KillstreakStartEvent - Triggered when a player's killstreak starts.
• KillstreakChangeEvent - Triggered when a player's killstreak changes.
• KillstreakEndEvent - Triggered when a player's killstreak ends.
• EasyFFAKillEvent - Triggered when a player kills another player.
• EasyFFADeathEvent - Triggered when a player dies from a non-PvP cause.
• PlayerRankUpEvent - Triggered when a player ranks up.