Skip to content

Setup & Configuration

Installation

  1. Build Athena with Gradle from the project root.
  2. Install the built Paper plugin jar into the server plugins directory.
  3. Install PlaceholderAPI and ActionBarAPI-Plus.
  4. Install an optional rank provider plugin if rank.yml will use anything other than BASIC.
  5. Start the server once so Athena can generate its config files.
  6. Configure spawn, regions, kits, timers, shops, perks, events, warps, staff tooling, and other server-specific values.

Athena declares Paper API version 1.20 in paper-plugin.yml and the current build is compiled against Paper API 1.21.8. It also declares hard dependencies on PlaceholderAPI and ActionBarAPI-Plus.

Optional rank providers are selected with rank.yml: Hephaestus, Akuma, Phoenix, AquaCore, Vault, or the built-in basic fallback. Vault requires a registered Vault Chat service.

Building

From the repository root:

./gradlew build

The Paper module is the deployable server plugin module.

Data Storage

The storage type is read from credentials.yml.

Supported enum values:

Value Current runtime status
SQLITE Active and registered. This is the usable storage backend.
MYSQL Config and some repositories exist, but runtime module registration is not wired.
MONGODB Config and some repositories exist, but runtime module registration is not wired.

Runtime SQLite modules register storage for kits, regions, profiles, killstreaks, clans, timers, and warps.

Athena autosaves cached data every 60 seconds. Data is also saved during relevant lifecycle operations such as player quit.

Generated Config Files

Athena loads these config files on startup:

File Purpose
config.yml Global options, including off-hand soup usage and reload messages.
credentials.yml Storage backend and database credentials.
kit.yml Kit messages and kit menu behavior.
region.yml Region wand, flags, and protection messages.
soup.yml Soup healing, death soup drops, and refill signs.
ability.yml Ability item names, materials, cooldowns, durations, and effect values.
spawn.yml Spawn location, spawn timer messages, and teleport behavior.
build-mode.yml Build mode messages and protection behavior.
rank.yml Rank provider selection for staff menus and xray alerts.
staff-mode.yml Staff mode items, vanish, freeze, xray alerts, and staff menus.
clan.yml Clan names, tags, member roles, chat, colors, and kills.
kill-streak.yml Killstreak milestones, reward behavior, and built-in reward command values.
credit.yml Credit messages and economy command output.
bounty.yml Bounty placement, claim, and formatting messages.
death-messages.yml Custom kill/death message formats.
chat.yml Global chat format rendered through PlaceholderAPI.
timer.yml Combat and spawn timer names, durations, and action bar text.
shop.yml Shop prices, bartender prices, and purchase messages.
perk.yml Perk costs, tiers, slots, chances, and effect values.
juggernaut.yml Juggernaut equipment, bounty bonus, and broadcast text.
statistics.yml Statistics menu and command formatting.
sponge.yml Sponge launcher display text and fall-damage behavior.
coinflip.yml Coinflip wager rules, permissions, cleanup, and broadcasts.
options.yml Player option menu and toggle text.
tier.yml Tier menu text, experience per kill, and tier display.
events.yml Player event menu, LMS/OITQ arena settings, Sumo arena settings, kits, timing, rewards, and messages.
trail.yml Trail menu, prices, particles, and unlock behavior.
leaderboards.yml Leaderboard menu entries and PlaceholderAPI formats.
profile.yml Profile loading/saving and player data messages.
warp.yml Warp menu, teleport timer, permissions, lore, and messages.

Many bundled YAML files are intentionally minimal. Defaults are generated from the matching *Config.java classes.

For per-file notes and value rules, see the Configuration Reference. Item/material, entity, sound, particle, and potion names should be checked against the matching XSeries enum family such as XMaterial, XEntityType, XSound, XParticle, or XPotion unless a file note says a Bukkit enum is used.

Spawn and Regions

Set the server spawn with:

/setspawn

Create safe zones with /region. Safe-zone regions drive the lobby flow: players receive the lobby hotbar inside safe zones and receive their kit when they leave.

Reloading

Use:

/reloadathena

This reloads Athena config values and sends the configured reload message. Restart the server after changing dependencies, plugin jars, storage backend code, or anything that requires module re-registration.

Resetting Player Data

Use:

/resetathenaplayerdata

This command clears cached and stored player-focused data:

  • Profiles
  • Clans
  • Kit allowed-user lists
  • Timer player maps
  • Active coinflips
  • Security guards

It also kicks online players after the reset. Server-owned objects such as kits, regions, killstreak definitions, timers, and warps are preserved except for per-player kit ownership.

Documentation Site

The docs project lives in toReference/Athena. To build it locally:

cd toReference/Athena
mkdocs build

The included build.sh builds the MkDocs site and deploys it to /var/www/athena-docs.