Prerequisites

• Server: Spigot/Paper 1.16.5+
• Java: 16+ recommended
• Optional: MySQL/MariaDB if you enable database storage

Install / First Run

1. Place the EasyFFA jar into plugins.
2. Start the server once to generate config files.
3. Open plugins/EasyFFA/config.yml and adjust the basics (points/exp, ranks, killstreaks, chat format, combat tag, etc.).
4. Proceed with the Quick Setup below.

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.

For a practical example, see the [GitHub Gist]( https://gist.github.com/liebki/e0aad00ce7e6db7ba710b072675bd74b) with a ready-to-use plugin main file.

Note: All events are fired on the main server thread. Keep your event handlers lightweight.


Admin Utilities ️

• Build Mode: /ffa build — toggle admin build mode
• Clear Chat: /ffa cc (self), /ffa ccg (global)
• Teleport World: /ffa tp <world>
• Active Map: /ffa activemap <world> — set ActiveWorldName and teleport all players to it
• Spawn: /ffa spawn (teleport), /ffa setspawn (set)
• Main Help: /ffa

Storage

• Flatfile (Default): kits.yml, stats.yml, bounties.yml
• MySQL (Optional): enable in FFA.MySQL. Stats can be stored in MySQL; other data may remain YAML.

MySQL Quick Example

Permissions (Summary)

• easyffa.* — everything
• easyffa.ffa — use /ffa (default: true)
• easyffa.world.tp — world teleport
• easyffa.kit — use kits (default: true)
• easyffa.admin.kit — manage kits
• easyffa.admin.setspawn — set spawn
• easyffa.admin.cc — clear chat
• easyffa.admin.zone — manage safe zones
• easyffa.admin.resetstats — reset stats

Troubleshooting ❗

• Map rotation won’t start: ensure FFA.UseMapchange is true and at least 2 maps are available.
• Spawn not set: use /ffa setspawn in the target world.
• Stats not saving to MySQL: verify credentials in FFA.MySQL and check console for connection logs.
• Players keep items/durability changes: review QoL toggles in config (prevent drops/durability/breaking).
• Combat tag not punishing: enable punishments and configure commands/values under FFA.CombatLogging.Punishments.