Configuration Reference

Athena generates one YAML file per major system. The example files in toReference/configs show the expected shape and useful defaults for a live server.

Most config entries are read during startup and by /reloadathena. Restart the server after changing dependencies, plugin jars, storage wiring, or anything that is not purely config-backed.

Value Rules

• Message strings support legacy color codes with &.
• Lists of strings are usually sent as chat, menu lore, or help text.
• Placeholder tokens use the exact %name% format shown in each example. Unknown placeholders are left to the caller or PlaceholderAPI path that renders the message.
• Durations use compact strings such as 15s, 1m, or 45s where the config key already expects a duration.
• Inventory slots are zero-based Bukkit inventory indexes. Most menu sizes are multiples of 9.
• Locations use world, x, y, z, yaw, and pitch.
• Empty strings often disable optional display text or indicate that a location/database field still needs to be configured.

Enum Names

When editing item, entity, sound, particle, and potion names, use the enum names expected by the XSeries/Bukkit parser. Prefer uppercase constants with underscores, for example DIAMOND_SWORD, PLAYER_HEAD, ENTITY_CHICKEN_EGG, or HAPPY_VILLAGER.

Config value type	Reference enum
Item, block, icon, weapon, replacement, and spawn material names such as type, item_type, icon, icon_type, weapon_type, block_spawn_type, replaceable_materials, and removable_formed_snow_materials	XMaterial
Entity names such as security_guard.entity_type	XEntityType
Sound names such as kill_streak_rewards.nuke.sound.type	XSound
Trail particles in trail.yml	XParticle
Stored kit potion effect names	XPotion
The fire resistance reward's potion_type	Bukkit PotionType, for example LONG_FIRE_RESISTANCE
The nuke reward's particle.type	Bukkit/Paper Particle name

Do not use display names like Diamond Sword or namespaced IDs like minecraft:diamond_sword unless the specific parser supports them. The safest source is the matching XSeries enum: XMaterial, XSound, XEntityType, XParticle, or XPotion.

Config Files

File	Covers	Important sections
ability.yml	Ability menu, item metadata, cooldowns, passive ability settings, and ability-specific tuning.	*_ability, ability_list_menu, ability_help_message
bounty.yml	Bounty menu display and bounty placement/claim messages.	bounty_menu, bounty command messages
build-mode.yml	Staff build mode toggle messages.	build_mode_enabled, build_mode_disabled
chat.yml	Optional global chat formatting through PlaceholderAPI.	chat_format_enabled, chat_format
clan.yml	Clan command messages, clan chat, color menus, member rules, and clan kill requirements.	clan_color_menu, clan_color_confirmation_menu, clan_info_format
coinflip.yml	Coinflip permissions, wager limits, animations, menu items, and result messages.	command, wager, animation, menu, messages
config.yml	Global Athena flags and reload message.	off_hand_usage_enabled, athena_reloaded
credentials.yml	Storage backend and database connection values.	storage_type, mongo, mysql
credit.yml	Credit command help, economy messages, and credits per kill.	credit_help_message, credits_per_kill
death-messages.yml	Combat logger, PvP, projectile, environmental, and custom death messages.	death_messages.causes, death_credit_receive
events.yml	Event menu, LMS/OITQ/Sumo settings, messages, kits, rewards, timing, and arena locations.	events_menu, lms, oitq, sumo
juggernaut.yml	Juggernaut messages, bounty bonus, effects, inventory, and armor.	effects, items, armor
kill-streak.yml	Killstreak command messages, security guards, reward commands, and built-in reward tuning.	security_guard, kill_streak_rewards
kit.yml	Kit admin messages, lobby hotbar buttons, kit selector, refill sign, and kit menu text.	kit_*_button, kit_list_menu, kit_button
leaderboards.yml	Leaderboard menu layout and PlaceholderAPI entry format.	leader_board_menu, kills_item, deaths_item, highest_killstreak_item, guild_kills_item
options.yml	Player options menu, toggle markers, reset statistics flow, and lobby item.	options_menu, reset_confirmation_menu, option_item
perk.yml	Perk shop, equipped slot display, reset flow, perk effect tuning, and purchasable perk definitions.	perk_menu, adjust_menu, perks, per-perk tuning sections
profile.yml	Profile management command help and admin repair/profile stat messages.	profile_manage_command_help
rank.yml	Rank provider selection for staff menus and xray alerts.	rank_provider
region.yml	Region command messages, list menu, wand item, and pearl refund behavior.	region_list_menu, region_wand_item, refund_pearl_on_cancel
shop.yml	Shop and bartender menu titles, prices, display text, and purchase messages.	shop_menu, bartender_menu, shop
soup.yml	Soup healing, death drop cap, and refill sign behavior.	soup_restore_health, max_soup_drop_on_death, refill_sign
sponge.yml	Sponge launcher item text, invalid velocity message, and fall-damage handling.	sponge_item, fall_damage
spawn.yml	Spawn location and spawn teleport messages.	spawn, spawn_message_teleporting
staff-mode.yml	Staff mode item loadout, menus, vanish, freeze, xray alerts, and staff-mode messages.	staff_mode_items, staff_gui, xrayer_gui, inspect_inventory
statistics.yml	Statistics menu item and /statistics output.	statistic_item, statistics_message
tier.yml	Tier experience, tier menu, and tier lobby item.	experience_per_kill, tiers_menu, tier_item
timer.yml	Combat and spawn timers, timer labels, durations, and action bar flags.	combat, spawn
trail.yml	Trail menu, trail movement task, clear button, built-in trail defaults, and unlock costs.	trail_task, defaults, trail_defaults
warp.yml	Warp command messages, default warp data, warp list menu, teleport delay, and permissions.	default_warp, warp_list_menu, warp_menu_rows

File Notes

ability.yml

Each ability section follows the same base shape: id, nbt_key, item_type, display names/lore, cooldowns, and any behavior-specific numbers. item_type values should come from XMaterial.

Passive kit abilities such as Viper, Cactus, Fireman, Chemist, and some Archer behavior are configured here but are not all grantable with /ability give. ability_not_grantable is sent for passive abilities.

The bundled jett_ability values exist in config, but the default ability registration handler does not register a Jett ability.

bounty.yml

Controls the bounty list menu and all bounty command feedback. The bounty menu button uses a type value, usually PLAYER_HEAD, which should resolve through XMaterial.

build-mode.yml

Only controls enable/disable messages for /buildmode. The inventory, armor, and game mode behavior is code-driven.

chat.yml

chat_format_enabled decides whether Athena formats global chat. chat_format may include PlaceholderAPI placeholders such as LuckPerms prefix values.

clan.yml

Contains clan command help, validation limits, invite/join/leave/kick messages, clan chat formatting, clan list/info formatting, and color selection menus.

clan_color_menu.colors entries use the pipe-delimited shape CHAT_COLOR|slot|material|display name. The material part should use XMaterial. The chat color part should be a Bukkit/ChatColor name such as RED, GOLD, or DARK_AQUA.

coinflip.yml

command.permission.enabled can require athena.coinflip. wager controls minimum, maximum, broadcast threshold, and cleanup delay. animation and menu define inventory sizes, slots, frame items, confirmation buttons, pagination, and result display.

All item type values in the animation and menus should use XMaterial.

config.yml

off_hand_usage_enabled controls whether soup can be consumed from the off hand. athena_reloaded is the message sent by /reloadathena.

credentials.yml

storage_type accepts the storage enum values listed in setup: SQLITE, MYSQL, and MONGODB. SQLite is the only backend currently registered at runtime. MySQL and MongoDB settings exist for configuration but are not wired as active runtime modules.

credit.yml

Controls credit command help, balance output, admin economy messages, and credits_per_kill.

death-messages.yml

Defines death message templates by damage cause. Empty cause messages suppress or fall back depending on the death-message code path. Common placeholders include %player%, %killer%, %killer-health%, %killer-kills%, %logger%, %distance%, and %killer-hand%.

events.yml

events_menu controls the /events inventory shown to players and staff. host_menu contains the older Sumo-only menu values retained in the generated file; the active administrator command surface is documented in Event Setup Guide. lms (Last Man Standing), oitq (One In The Quiver), wool_shuffle, red_light_green_light, tnt_run, and tnt_tag configure participant limits, queue/countdown timing, rewards, safe-zone requirements, messages, and arena locations. lms and oitq also expose kits. wool_shuffle.colors controls valid floor colors, red_light_green_light controls phase durations, tnt_run.remove_radius controls block removal, and tnt_tag controls round duration and initial tag count. sumo configures the existing Sumo event, including its participant limit, rewards, safe-zone requirement, countdowns, messages, and three locations: spectator, spawn_a, and spawn_b.

Use the administrator commands documented in the Event Setup Guide to write locations. LMS and OITQ locations are stored as semicolon-separated world;x;y;z;yaw;pitch values; Sumo locations retain the existing structured location format. Avoid hand-editing generated location values unless you are migrating a server configuration.

juggernaut.yml

Controls juggernaut command messages, bounty bonus, whether empty inventory slots are filled with soup, permanent effects, held items, and armor.

The items.*.type and armor.*.type values should use XMaterial. Effect keys such as speed map to Bukkit potion effects.

kill-streak.yml

Contains killstreak admin messages, the killstreak menu title, security guard tuning, killstreak reward command help, and built-in reward definitions.

Use these enum sources:

• security_guard.entity_type: XEntityType.
• security_guard.weapon_type, reward item type, material replacement lists, and snow_bomb.block_spawn_type: XMaterial.
• kill_streak_rewards.nuke.sound.type: XSound.
• kill_streak_rewards.nuke.particle.type: Bukkit/Paper Particle.
• kill_streak_rewards.fire_resistance.item.potion_type: Bukkit PotionType.

The top-level killstreak milestones themselves are data objects managed by /killstreak; this file controls messages and built-in reward behavior.

kit.yml

Controls kit command help, admin feedback, lobby/menu buttons, kit selector item, refill sign text/cooldown, purchase text, and kit button status lore.

Button type values and kit_selector_item.type should use XMaterial. Individual kit contents, armor, potion effects, price, free/enabled state, slot, icon, and allowed users are managed through /kit commands and stored separately.

leaderboards.yml

Controls the leaderboard menu and the four built-in leaderboard items: kills, deaths, highest killstreak, and guild kills. Item type values should use XMaterial.

placeholder_entry_format controls PlaceholderAPI leaderboard entry formatting.

options.yml

Controls the player options inventory, toggle markers, action lore, kill/death message toggle, killstreak message toggle, statistics reset purchase flow, confirmation buttons, and the lobby options item.

Item type values should use XMaterial.

perk.yml

Defines the perk shop title/size, tier adjustment menus, equipped slot display, reset/fill buttons, shared perk button lore, per-perk effect tuning, and purchasable perk metadata under perks.

Each entry under perks usually has name, icon, cost, and description. icon values should use XMaterial. Numeric tuning sections such as jammer, revenge, life_support, and conartist drive listener behavior.

profile.yml

Controls /profilemanagement help and profile/stat admin feedback messages. It also contains the admin armor repair message.

rank.yml

rank_provider controls which rank integration powers staff menus and xray alerts. Accepted values are AUTO, HEPHAESTUS, AKUMA, PHOENIX, AQUACORE, VAULT, BASIC, and FALLBACK.

AUTO tries installed providers in this order: Hephaestus, Akuma, Phoenix, AquaCore, then Vault. Unknown values, missing plugins, missing Vault chat services, or provider initialization failures fall back to BASIC.

region.yml

Controls region command help, region list menu, region wand item, region flag messages, and whether cancelled ender pearls are refunded.

The region wand and menu item type values should use XMaterial. Regions and cuboid coordinates are managed with /region.

shop.yml

Controls shop and bartender menu titles, costs, names, lore, potion effects, and purchase feedback. The built-in shop actions are repair durability, soup refill, golden apples, milk bucket, fire resistance, splash harming, splash poison, splash slowness, and bartender.

The preview item types for shop entries are code-defined defaults. This file configures their pricing, display text, and potion metadata.

Each bartender potion has a potion_type and a potion_effects list. The base type defaults to its original vanilla potion type; every list entry adds a custom effect using TYPE,DURATION_TICKS,AMPLIFIER[,AMBIENT,PARTICLES,ICON]. For example:

shop:
  splash_harming:
    potion_type: WATER
    potion_effects:
      - "SPEED,1200,1"
      - "JUMP_BOOST,1200,2"

Set potion_type to WATER when the potion should contain only the listed effects. Effect names accept XPotion names such as SPEED, JUMP_BOOST, and FIRE_RESISTANCE.

soup.yml

soup_restore_health is the instant heal amount from mushroom stew. max_soup_drop_on_death caps soup drops on death. refill_sign controls refill sign display and cooldown.

sponge.yml

Controls the /spongelauncher item display, invalid velocity message, grant message, and whether sponge-launch fall damage handling is enabled.

spawn.yml

Stores the server spawn location and spawn teleport messages. Prefer /setspawn for changing the location.

staff-mode.yml

Controls staff mode command feedback, staff item materials/names/lore/slots, vanish messages and vanish_on_join, freeze messages and frozen-player restrictions, xray alert text, staff menus, inspection inventory labels, silent chest text, and handler registration failure messages.

Staff item material keys use XMaterial names:

• staff_mode_items.teleportation_compass.type
• staff_mode_items.inspection.type
• staff_mode_items.world_edit.type
• staff_mode_items.staff_gui.type
• staff_mode_items.freeze.type
• staff_mode_items.xrayer_gui.type
• staff_mode_items.vanish_enabled.type
• staff_mode_items.vanish_disabled.type
• staff_mode_items.random_teleport.type
• staff_gui.type
• xrayer_gui.button.type

Common placeholders include %player%, %name%, %prefix%, %world%, %x%, %y%, %z%, %ore%, and %size%, depending on the message or menu item.

statistics.yml

Controls the statistics lobby/menu item and /statistics message output. The statistic_item.type value should use XMaterial.

tier.yml

experience_per_kill controls tier progress from kills. tiers_menu controls menu layout and status lore. tier_item controls the lobby/menu item for tiers.

Item type values should use XMaterial.

timer.yml

Defines the default combat and spawn timers. Each timer has a display name, scoreboard text, duration, and action_bar.enabled flag. Combat also has remove_killer_combat_tag.

trail.yml

Controls the trails menu, movement-task throttling, admin bypass permission, trail messages, clear button, and default trail entries.

Trail entry icon values should use XMaterial. Trail entry particle values should use XParticle. Both defaults and trail_defaults contain bundled trail definitions; current built-ins pull some legacy IDs from defaults and the expanded trail IDs from trail_defaults.

warp.yml

Controls warp command help, admin feedback, teleport messages, default values for new warps, list menu display, menu rows, and force-teleport messages.

default_warp.icon_type should use XMaterial. Warps themselves are managed through /warp commands and can include custom per-warp permissions through /warp setpermission.