Feature Reference

Athena is organized around the classic soup KitPvP loop: lobby safe zone, kit selection, fast combat, soup healing, credits, streaks, clans, and progression unlocks.

Player Flow

• Players are teleported to spawn on join and respawn.
• Join and quit messages are suppressed.
• All worlds have immediate respawn enabled on plugin startup.
• Hunger is locked at full food with no saturation-based natural regeneration.
• The lobby hotbar is applied on join, respawn, and when entering safe zone.
• Leaving safe zone applies the player's current kit, previous kit, or the first free kit fallback.
• Juggernaut players receive the configured juggernaut loadout when leaving safe zone.

Lobby hotbar items open kit selection, statistics, perks, options, and tiers.

Soup Combat

• Mushroom stew heals instantly on right click.
• Soup restores soup.restore_health health, defaulting to 6.5 health points.
• Used soup becomes a bowl.
• Duplicate soup usage during the same server tick is ignored.
• Off-hand soup is controlled by config.yml with off_hand_usage_enabled.
• Glistering melon brewing is blocked.
• Sword, pickaxe, and axe drops are blocked.
• Dropped bowls, bottles, and buckets are removed.
• Death drops are limited to soup.max_soup_drop_on_death.
• The Conartist perk can cancel soup drops.

Refill signs are created by placing a sign with [Refill] while holding athena.refill.signs. Right clicking a refill sign opens a soup inventory and applies the configured cooldown.

Regions

Regions are cuboids managed with /region and the region wand.

Region flags:

Flag	Behavior
PvP	Allows or blocks player-vs-player damage.
PvE	Allows or blocks player-vs-entity damage.
Safe zone	Blocks player damage and drives lobby/kit transitions.
Buttons	Allows or blocks button interaction.
Ender pearls	Allows or blocks pearl launches and can refund cancelled pearls.

Block and entity explosions, block ignition, and creeper ignition are globally cancelled by the protection listeners.

Build Mode

/buildmode toggles staff build mode.

When enabled:

• The player's inventory and armor are saved.
• Inventory and armor are cleared.
• Health and food are restored.
• Game mode is set to creative.

When disabled, the saved inventory and armor are restored and game mode is set back to survival.

Players outside build mode cannot break/place blocks, use buckets, edit signs, open many protected utility blocks, or trigger protected physical interactions.

Staff Mode

/staffmode toggles live staff mode for moderators.

When enabled:

• The player's inventory, armor, game mode, flight allowance, and flying state are saved.
• Health, food, saturation, and fire ticks are refreshed.
• Inventory and armor are cleared.
• Game mode is set to creative.
• The player is automatically vanished.
• Staff mode items from staff-mode.yml are placed into their configured slots.

When disabled, Athena unvanishes the player and restores the saved inventory, armor, game mode, and flight state. If no snapshot exists, the player is returned to survival with flight disabled. Quitting while in staff mode disables staff mode and restores the snapshot.

Staff mode restrictions:

• Staff mode players cannot place or break blocks.
• Staff mode players cannot change game mode.
• Staff mode players cannot pick up or drop items.
• Staff mode players cannot take damage.
• Inventory clicks are blocked except inside the online staff and possible xrayers menus.
• PvP is cancelled when either player is in staff mode or vanished.
• Physical interactions such as pressure plates are cancelled.

Default staff mode items:

Slot	Item	Behavior
0	Teleportation compass	Configured staff item.
1	Inspection tool	Right click a player to open a live inventory view with armor, held items, hunger, active effects, and location.
2	WorldEdit wand	Configured staff item.
3	Online staff	Opens a paginated list of online players with athena.staffmode; clicking teleports to that staff member.
4	Freeze	Right click a player to run /freeze <player>.
6	Possible xrayers	Opens a paginated list of non-staff players at Y 20 or below; clicking teleports to that player.
7	Vanish toggle	Toggles vanish and swaps between the enabled/disabled vanish item.
8	Random teleport	Teleports to a random online player other than yourself.

Vanish

/vanish toggles vanish independently of staff mode. Vanished players are hidden from players who do not have athena.vanish or athena.vanish.see. When vanish_on_join is enabled in staff-mode.yml, players with athena.vanish are vanished automatically on join.

Vanished players cannot place or break blocks. Right clicking a chest or trapped chest while vanished opens a silent chest view instead of the real container.

Freeze

/freeze <target> toggles a target's frozen state. Frozen players are locked to their current block, cannot place or break blocks, cannot damage other players, and cannot be damaged by other players. Frozen players can only run /msg, /message, /w, /tell, /reply, and /r unless they have athena.freeze.

Staff with athena.freeze are notified when a frozen player quits or rejoins. The frozen player receives the configured freeze reminder once per minute while still frozen.

Xray Alerts

/xray toggles whether a staff member receives ore alerts. Alerts are sent only to online staff who have athena.xray and have enabled alerts.

Athena watches natural ore breaks for coal, copper, lapis, redstone, iron, gold, diamond, emerald, nether gold, and nether quartz ore, including deepslate variants where applicable. Ores placed by players are tagged and ignored. Alerts include the player's rank-colored name when a rank provider is available, the ore type, and the connected vein size. Diamond ore findings also broadcast the configured found-diamonds message.

Rank Providers and API

The rank handler supplies rank names, prefixes, and colored player names to staff menus and xray alerts. Configure rank.yml with rank_provider.

Supported values:

Value	Behavior
AUTO	Tries HEPHAESTUS, AKUMA, PHOENIX, AQUACORE, then VAULT, based on installed plugin availability.
HEPHAESTUS	Uses the Hephaestus API.
AKUMA	Uses the Akuma API.
PHOENIX	Uses the Phoenix shared API.
AQUACORE	Uses the AquaCore API.
VAULT	Uses Vault Chat for primary group and prefix.
BASIC or FALLBACK	Uses built-in defaults: rank Default, empty prefix, and the raw player name.

Unknown or unavailable providers fall back to BASIC.

Common-API exposes these staff/rank bindings through AthenaAPI: IRankHandler, IRankProvider, IStaffModeHandler, IStaffModeItemHandler, StaffModeItem, IVanishHandler, IFreezeHandler, and IXrayHandler.

Kits

Kits are stored as data objects with:

• Internal id/name
• Display name
• Icon
• Inventory contents
• Armor contents
• Potion effects
• Cooldown
• Price
• Free/enabled state
• Menu slot
• Lore
• Allowed users

Players select kits through the kit menu or command flow. Paid kits require confirmation, deduct credits, and add the player to the kit's allowed-user list. athena.kit.admin bypasses locked and paid kit checks in the kit menus.

Abilities

Abilities are registered at startup and are mostly granted as item abilities through /ability give. Some passive kit abilities look at the player's active kit instead of only checking the held item.

Ability	Type	Summary
Palioxis	Item	Ender pearl movement ability with cooldown and cancelled-launch refund handling.
Grappler	Item	Fishing rod based grappling movement.
Kangaroo	Item	Mobility leap with fall-damage handling.
Viper	Passive kit	Poison chance on attack for the Viper kit. Not grantable as an item.
Cactus	Passive kit	Reflects damage chance/multiplier for the Cactus kit.
Phantom	Item	Temporary flight.
Melon	Item	Melon projectile that knocks enemies away and upward.
Cyclops	Item	Laser stream projectile attack.
Zeus	Item	Lightning projectile attack.
Fireman	Passive kit	Fire and lava protection with water damage behavior.
Chemist	Passive kit	Refills splash harming potions after valid kills.
Switcheroo	Item	Swaps location with a snowball target.
Torch	Item	Dragon-breath projectile burst that ignites targets.
Stomper	Item	Upward launch and fall/stomp area damage.
Spiderman	Item	Web projectile trap with rollback.
Rogue	Item	Backstab damage when attacking from behind.
Vampire	Item	Bat blast plus kill regeneration.
Yoda	Item	Pulls nearby players.
Eskimo	Item	Temporary ice dome with strength.
Ninja	Item	Shuriken projectile, debuffs, armor repair, and shuriken refill.
Fisherman	Item	Hooks and teleports a target to the user.
Enhancer	Item	Places a temporary stim beacon and buffs Enhancer users.
Dwarf	Item	Charge/blast knockback ability.
Barbarian	Item	Summons silverfish swarm and applies slowness interactions.
Avatar	Hybrid	Water projectile, fire jump, fall reduction, and armor repair behavior.
Archer	Item/passive	Bow ability with tracked arrows and bow damage behavior.

See Ability Reference for the full runtime list, cooldowns, item materials, grantability notes, and behavior details. ability.yml also contains Jett-related config values, but no Jett ability is registered by the default ability registration handler.

Combat Timers

Athena registers default combat and spawn timers.

Combat timer behavior:

• Applied to both players during player-vs-player or projectile-vs-player damage.
• Blocks safe-zone entry while active.
• Kills players who quit while combat tagged.
• Removes the victim's timer on death.
• Killer timer removal is configurable.
• PlaceholderAPI exposes active state and remaining time.

Spawn timer behavior:

• /spawn starts a configured timer unless the player is in combat.
• Movement or damage cancels the pending spawn teleport.
• Timer expiry teleports the player to configured spawn.

Profiles and Statistics

Profiles store:

• Kills and deaths
• Current and highest killstreak
• Credits
• Bounty
• Events won
• Experience and tier
• Current/previous kit
• Selected options
• Perks and trails
• Clan relationship data

Profiles load during async pre-login or are created as defaults. They are saved on quit and during autosaves.

Credits and Bounties

Credits are Athena's built-in economy. Kills grant credits, and credits are used for kit purchases, perks, trails, shop purchases, bounties, repairs, and coinflips.

Bounties:

• /bounty <target> <amount> deducts credits and adds to the target's bounty.
• Players cannot bounty themselves.
• Bounty claims are paid to the killer when the target dies.
• Claimed bounties reset to zero.

Clans

Clans support:

• Creation and disbanding
• Invites and joins
• Leader/officer/member roles
• Rename and tag editing
• Clan colors
• Clan chat
• Callouts
• Member kicking
• Ownership transfer
• Promote/demote
• Clan info, list, and who lookup
• Clan kill tracking

Clan kills increase when a clan member kills a player outside the same clan. Clan color unlocks can require clan kills, with bypass permissions available.

Chat

Global chat is formatted through PlaceholderAPI using chat.yml.

Clan chat is toggled with /clan chat. When enabled, messages are sent only to clan members and use the configured clan chat format.

Killstreaks

Killstreak milestones are data-driven. Each milestone can define:

• Required kills
• Display name
• Menu slot
• Preview item
• Reward type
• Reward item
• Console reward commands

When a player's current streak matches a milestone, Athena grants the item reward or runs configured console commands with player replacement values.

Built-in killstreak reward commands include full repair, golden apples, fire resistance, grandma soup, attack dogs, extra credits, angry snowman, snow bombs, and nuke.

Every 5 kills, Athena can broadcast ongoing streaks and ended streaks. The Incognito perk suppresses streak broadcasts. The Hardline perk reduces required kill counts for streak rewards.

Security Guards

Security guards are spawned and cleared by command. They protect their owner by targeting attackers or the owner's current target. Guards cannot damage their owner, and guard attacks are converted into owner damage attribution. Guard drops and experience are cleared on death.

Juggernaut

Juggernaut mode is assigned and cleared by admin command.

Juggernaut behavior:

• Marks the profile as juggernaut.
• Adds configured bounty bonus.
• Broadcasts assignment.
• Applies the configured juggernaut loadout outside safe zone.
• Reapplies the loadout when leaving safe zone.
• Clears on death.
• Blocks shop and repair purchases while active.

Shop

/shop opens the credit shop. Default shop categories include:

• Armor repair
• Soup refill
• Golden apples
• Milk bucket
• Bartender potions

The bartender submenu sells configured potion items such as fire resistance, splash harming, splash poison, and splash slowness. Purchases are blocked in safe zones and while juggernaut.

/repair repairs player gear for the configured repair cost and is also blocked while juggernaut.

Coinflips

Coinflips are credit wagers.

• /coinflip opens the menu.
• /coinflip create <amount> creates a wager and deducts the stake.
• Accepting a coinflip deducts the accepting player's stake.
• The winner is random and receives the pot.
• Disconnects and unresolved coinflips are refunded/cleaned up.
• Command permission is optional in coinflip.yml.

Perks

Perks are purchased with credits and organized into tiers/slots. Active effects are handled by listeners during combat, damage, kill, death, and movement events.

Default perks:

Tier	Perks
Tier 1	Bounty Hunter, Sore Loser, Martyrdom, Relinquish, Trickster, Nourishment, Refiller, Stunt Devil, Aquaman
Tier 2	Distortion, Jammer, Reverse Copycat, Steady Hands, Armorer, Death Do Us Apart, Taunt, Revenge, Inferno, Hardline
Tier 3	Incognito, Conartist, Creditor, Cana, Bonus Hearts, Fire Fighter, Life Support, Juggernaut

Effects include soup manipulation, damage modifiers, fall damage cancellation, armor repair, bonus credits, revenge tracking, fire handling, kill/death effects, streak broadcast suppression, and temporary regeneration.

Tiers

Kills grant tier experience. The tier ladder runs from level 0 through XX and exposes tier level/display placeholders.

Default tier thresholds:

Tier	Experience
0	0
I	100
II	500
III	1,000
IV	1,500
V	3,000
VI	5,000
VII	10,000
VIII	15,000
IX	20,000
X	30,000
XI	35,000
XII	40,000
XIII	45,000
XIV	50,000
XV	55,000
XVI	60,000
XVII	70,000
XVIII	80,000
XIX	90,000
XX	100,000

Trails

Trails are cosmetic particle effects unlocked by credits, per-trail permission, free state, or athena.trail.admin.

Default trail ids:

flame, heart, happy_villager, angry_villager, critical, cloud, enchant, witch, portal, note, lava, smoke, splash, snow, slime, totem, dragon, soul

Each trail also has a direct permission node: athena.trail.<id>.

Hosted Events

Athena supports one active hosted event at a time: Last Man Standing (LMS), One In The Quiver (OITQ), Sumo, Wool Shuffle, Red Light Green Light, TNT Run, or TNT Tag. Server owners configure arenas in events.yml through /event setup; staff open a queue with /event start <type>. Players view the queue and join or leave it from /events.

All event types isolate participants from normal KitPvP state. Athena snapshots inventory, armor, effects, health, food, game mode, flight, and related state, applies the event kit where applicable, and restores the snapshot when a player leaves, is eliminated, disconnects, or the event is cancelled. The winner receives the configured credits and an Events Won increment.

Last Man Standing

• Requires a cuboid arena, one normal spawn per configured minimum player, and at least two final-stand spawns.
• Players are eliminated on lethal event damage; the configured cuboid is also used to keep non-participants out of the arena.
• When two players remain, Athena moves them to the final-stand locations; the last remaining player wins.
• Queue minimum/maximum players, countdowns, safe-zone joining, rewards, messages, and the diamond kit are configured under lms.

One In The Quiver

• Requires a cuboid arena and one normal spawn per configured minimum player.
• A kill with the event arrow, or a lethal configured wooden-sword hit, scores a point and respawns the victim at a random event spawn.
• The first player to reach oitq.kill_objective wins. The default objective is 20 kills.
• Queue minimum/maximum players, countdowns, safe-zone joining, rewards, messages, sword damage, and the bow/arrow kit are configured under oitq.

Sumo

• Uses participant A, participant B, and spectator locations configured under sumo.locations.
• Matches use knockback and ring-loss rules; normal damage is not applied to round participants.
• Water, lava, or void loss conditions eliminate a round participant.
• Sumo's existing timing, safe-zone, reward, and message settings remain under sumo.

Wool Shuffle

• Uses a flat, prebuilt wool floor. Each round announces a configured wool color; players standing on another color are eliminated when the timer expires.
• Configure colors, round duration, queue limits, rewards, messages, and locations under wool_shuffle.

Red Light, Green Light

• Alternates green and red phases. Movement during red eliminates a participant; reaching the finish bound wins.
• Configure phase durations, queue limits, rewards, messages, and locations under red_light_green_light.

TNT Run

• Removes platform blocks beneath moving players. Falling below the configured platform bounds eliminates a participant; the final survivor wins.
• Removed blocks are restored when the event ends. Configure removal radius, queue limits, rewards, messages, and locations under tnt_run.

TNT Tag

• Assigns one or more tagged players. Hitting another participant transfers the tag; tagged players are eliminated when the round timer expires.
• Configure round duration, initial tag count, queue limits, rewards, messages, and locations under tnt_tag.

For the complete administrator workflow, including spawn-count requirements and troubleshooting, see the Event Setup Guide.

Sponge Launchers

/spongelauncher <velocity> gives a configured sponge launcher item. The sponge listener handles the launch behavior from the item.

Warps

Warps are data-driven and support:

• Enabled/disabled state
• Location
• Icon
• Display name
• Lore
• Menu slot
• Teleport delay
• Optional custom permission

Warps are blocked during combat. Delayed warps cancel on movement, damage, or quit. A teleport time of 0 teleports immediately.

Leaderboards

/leaderboard opens leaderboard menus for kills, deaths, highest killstreak, and guild/clan kills.

PlaceholderAPI exposes top entries for:

• Kills
• Deaths
• Highest killstreak
• Guild/clan kills

See Placeholders for exact placeholder names.