Mytheria Races

MytheriaRaces

MytheriaRaces adds five playable races, race-specific powers, progression, specializations,
artifacts, and boss/dungeon tracking to Paper servers.

Server Setup

• Requires Paper 1.21 or newer.
• Place the plugin JAR in the server's plugins folder and restart the server.
• Optional integrations: Vault plus an economy provider for paid race changes; LuckPerms

for race permission syncing; PlaceholderAPI for placeholders; MythicMobs and
MythicDungeons for boss/dungeon hooks; ExecutableItems for item-triggered powers.

• The core race and progression systems work without these optional plugins. Features

that depend on a missing integration will not be available.

New players are prompted to choose a race when they first join. Available races are
Gnome, Titan, Elf, Dwarf, and Giant. A race provides different attributes, passive
effects, strengths and drawbacks, an active ability, and an ultimate:

Race · Ability · Ultimate
Gnome · Blink · Mischief
Titan · Seismic Slam · Fortify
Elf · Wildheart · Moonwell
Dwarf · Stoneform · Deep Delve
Giant · Stomp · Earthquake

The first race choice is free. Switching an existing race requires Vault and costs
exactly 100,000,000 economy units, with a seven-day cooldown for all players, including
operators. Changing race resets
race XP and level. Staff race assignment also starts the player at level 1.

Commands

Commands without a subcommand generally open a profile or show status. Commands marked
Staff require the matching mytheriaraces.admin.* node (or the mytheriaraces.admin group). Console-only hooks are
intended for integrations and require the target player to be online where applicable.
Use /races as an alias for /race. Race subcommands also accept compact forms, such as
/racestats or /racesstats for /race stats. Every command works as /race… or /races…, spaced or unspaced (for example /race progress quest,
/races progress quest, /raceprogressquest, /racesprogressquest), and all forms tab-complete. Every other command also has unspaced
forms for its subcommands, such as /raceprogressquest, /racedungeonstatus, and /racepowerscapstone.

New players see a short "Welcome / to MytheriaMC" title on first join, then the race menu opens.

Command · Use
/race, /races · List race commands and descriptions.
/race choose, /race switch · Choose or switch race.
/race ability, /race ultimate · Use your race powers.
/race guide · Open the step-by-step progression guide; steps unlock and reveal as you level up.
/race stats, /race profile · Open the race stats GUI.
/race info · View your race and progression in chat.
/race top · View the race leaderboard.
/race inspect · View an online player's race profile. Requires mytheriaraces.race.inspect (default: everyone).
/race set · Staff: Set an online player's race (gnome, titan, elf, dwarf, or giant).
/race reset · Staff: Remove an online player's race profile.
/race reload · Staff: Reload config.yml and every configs/*.yml file, save profiles, and re-apply races to online players. Changes apply immediately; only a new jar needs a restart.
/race logs [on\ · off], /racelogs · Staff (mytheriaraces.logs): Toggle a live in-chat feed of race picks, level-ups, prestiges, ability use and staff actions.
/race admin xp set · Staff: Set an online player's race XP (level is recalculated from it).
/race admin level set · Staff: Set an online player's race level (XP is set to that level's threshold).
/race admin cutscene · Staff: Replay the full welcome intro, then open the race menu (does not mark the intro as seen).
/race admin, /raceadmin, /racehelp admin · Staff: Open the race admin help menu.
/race shop · Open the token shop (same as /raceprogress shop).
/raceprogress [profile · quest · talent · shop · prestige] · View progression, daily quest, choose a talent, open the token shop, or prestige (each prestige gives +1 permanent heart and 250 tokens).
/raceartifacts [profile] · View race tokens and equipped artifact power.
/raceartifacts grant · Staff: Give an online player a common, rare, or legendary artifact cache. Console may also grant caches.
/racecontracts [profile · leaderboard] · View boss/dungeon contract progress or the combined leaderboard.
/racetalents [info · choose · ability] · View or choose a race specialization and use its ability.
/racepowers [info · mastery · capstone] · View or use race mastery (level 20) and capstone (level 25) powers.
/racecodex · Open the race codex menu.
/raceei [ability · specialization · mastery · capstone] · Trigger a race power from an ExecutableItems player-command action.
/racedungeon [status · leaderboard] · View dungeon run status or leaderboard.
/raceboss [profile · leaderboard] · View boss contributions or leaderboard.
/racehud · Toggle the race, level, and token action-bar HUD (on by default).
/racehelp [admin] · Open player help; admin opens staff help.

Integration Console Hooks

These command forms are for server console or plugin integrations, not player use:

raceprogress reward
racecontracts reward
raceboss hit
raceboss complete
racedungeon start
racedungeon complete

For dungeon completion, `` is the run difficulty. Boss and dungeon integrations
can use these hooks to record progress and award race XP/tokens.

Features

• Race progression: Earn race XP from mob kills, player kills (100 XP, rate-limited)

and ore mining; level up to the
configured cap (25 by default).

• Daily quests and talents: Complete a rotating daily race quest, select a talent

path, and spend race tokens in the progression shop.

• Prestige: Prestige at the level cap; race level and XP reset, and the player gains

250 race tokens.

• Specializations and powers: Select from race-specific specializations. Mastery

unlocks at level 20 and capstone powers at level 25.

• Artifacts: Earn or receive cache items in common, rare, and legendary tiers; view

equipped artifact power and race-token balance.

• Boss and dungeon tracking: Track boss contributions, clears, dungeon runs, and

leaderboards. MythicMobs/MythicDungeons integrations can connect reward and completion
hooks.

• Race codex and HUD: Provide an in-game reference menu and an action-bar

summary of race, level, and tokens.

• Data protection: Player data can use Bukkit persistent data or separate YAML

profiles. Automatic saves and daily backups are enabled by default.

• Anti-farming: Limit mob and ore rewards per hour and apply repeat boss/dungeon

reward cooldowns.

• Audit options: Optionally send race selections, level-ups, prestige, and staff

actions to a Discord webhook.

PlaceholderAPI support is provided by a MytheriaRaces expansion, registered
automatically when PlaceholderAPI is installed (check with /papi list). The identifier
is case-insensitive, so %mytheriaraces_race% and %MytheriaRaces_race% both work.

Placeholder · Value
%mytheriaraces_race% · Selected race, or None
%mytheriaraces_has_race% · true if the player has chosen a race
%mytheriaraces_level% · Race level
%mytheriaraces_max_level% · Configured level cap
%mytheriaraces_xp% · Race XP
%mytheriaraces_xp_needed% · XP required for the next level
%mytheriaraces_xp_remaining% · XP still needed for the next level
%mytheriaraces_xp_percent% · Progress to the next level (0-100)
%mytheriaraces_tokens% · Race tokens
%mytheriaraces_prestige% · Prestige level
%mytheriaraces_talent% · Selected talent, or None
%mytheriaraces_specialization% · Selected specialization, or None
%mytheriaraces_boss_clears% · Boss clears
%mytheriaraces_dungeon_clears% · Dungeon clears
%mytheriaraces_ability_cooldown% · Seconds until the race ability is ready (0 if ready)
%mytheriaraces_ultimate_cooldown% · Seconds until the race ultimate is ready (0 if ready)
%mytheriaraces_switch_cooldown% · Seconds until the player may switch race again (0 if allowed)

Permissions

Every command and subcommand has its own node, so you can grant or deny them
individually (for example with LuckPerms). Player nodes default to true, so players
keep normal access unless you negate a node (-mytheriaraces.race.top). Staff nodes
default to operators. The console is never restricted.

Group nodes: mytheriaraces.player grants every player node, and mytheriaraces.admin
grants every admin.* and bypass.* node. Individual staff nodes can be granted without
the group.

Permission · Default · Purpose
mytheriaraces.race.choose · Everyone · Choose a first race (/race, /race choose).
mytheriaraces.race.switch · Everyone · Switch to a different race.
mytheriaraces.race.ability · Everyone · /race ability.
mytheriaraces.race.ultimate · Everyone · /race ultimate.
mytheriaraces.race.guide · Everyone · /race guide.
mytheriaraces.race.stats · Everyone · /race, stats, profile, info.
mytheriaraces.race.top · Everyone · /race top.
mytheriaraces.race.inspect · Everyone · /race inspect .
mytheriaraces.progress.profile · Everyone · /raceprogress and /raceprogress profile.
mytheriaraces.progress.quest · Everyone · /raceprogress quest.
mytheriaraces.progress.talent · Everyone · /raceprogress talent.
mytheriaraces.progress.shop · Everyone · /raceprogress shop.
mytheriaraces.progress.prestige · Everyone · /raceprogress prestige.
mytheriaraces.artifacts.profile · Everyone · /raceartifacts.
mytheriaraces.contracts.profile · Everyone · /racecontracts, profile.
mytheriaraces.contracts.leaderboard · Everyone · /racecontracts leaderboard.
mytheriaraces.talents.info · Everyone · /racetalents, info.
mytheriaraces.talents.choose · Everyone · /racetalents choose.
mytheriaraces.talents.ability · Everyone · /racetalents ability.
mytheriaraces.powers.info · Everyone · /racepowers, info.
mytheriaraces.powers.mastery · Everyone · /racepowers mastery.
mytheriaraces.powers.capstone · Everyone · /racepowers capstone.
mytheriaraces.codex · Everyone · /racecodex.
mytheriaraces.hud · Everyone · /racehud.
mytheriaraces.help · Everyone · /racehelp.
mytheriaraces.ei.ability · Everyone · /raceei ability.
mytheriaraces.ei.specialization · Everyone · /raceei specialization.
mytheriaraces.ei.mastery · Everyone · /raceei mastery.
mytheriaraces.ei.capstone · Everyone · /raceei capstone.
mytheriaraces.dungeon.status · Everyone · /racedungeon, status.
mytheriaraces.dungeon.leaderboard · Everyone · /racedungeon leaderboard.
mytheriaraces.boss.profile · Everyone · /raceboss, profile.
mytheriaraces.boss.leaderboard · Everyone · /raceboss leaderboard.
mytheriaraces.admin.set · Operators · /race set .
mytheriaraces.admin.reset · Operators · /race reset .
mytheriaraces.admin.reload · Operators · /race reload.
mytheriaraces.admin.progress · Operators · /race admin xp set and /race admin level set.
mytheriaraces.logs · Operators · /race logs feed. Separate from mytheriaraces.admin, so it can be given to mods alone.
mytheriaraces.admin.help · Operators · /race admin, /raceadmin, or /racehelp admin.
mytheriaraces.admin.artifacts.grant · Operators · /raceartifacts grant .
mytheriaraces.dependency-notify · Operators · Receive an optional dependency status report on join.

Editing Menus and Configs

Every menu and feature has its own file, generated on first start and reloaded with /race reload:

File · Controls
config.yml · Core plugin settings (XP, cooldowns, storage, anti-farm, Discord, ...).
configs/shop.yml · Token shop prices and relic cooldown.
configs/talents.yml · Talent bonuses.
configs/artifacts.yml · Artifact powers and cache token rewards.
configs/abilities.yml · Specialization, mastery and capstone cooldowns.
guis/.yml · One per menu: race-select, race-profile, codex, guide, help-member, help-admin, shop, talents, specialization.

In a guis/*.yml file you can change title, rows and the filler, and for each entry under items:
enabled, slot, material, name, lore, glow and (where supported) command. Colour codes use & and &#RRGGBB;
placeholders such as {level} or {tokens} are filled in by the plugin. Guide steps also have unlock-level.

Configuration

Edit plu