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 <player>	View an online player's race profile. Requires mytheriaraces.race.inspect (default: everyone).
/race set <player> <race>	Staff: Set an online player's race (gnome, titan, elf, dwarf, or giant).
/race reset <player>	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 <player> <xp>	Staff: Set an online player's race XP (level is recalculated from it).
/race admin level set <player> <level>	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
/raceartifacts [profile]	View race tokens and equipped artifact power.
`/raceartifacts grant <common	rare
`/racecontracts [profile	leaderboard]`
`/racetalents [info	choose
`/racepowers [info	mastery
/racecodex	Open the race codex menu.
`/raceei [ability	specialization
`/racedungeon [status	leaderboard]`
`/raceboss [profile	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 <player> <xp> <tokens>
racecontracts reward <player> <boss | dungeon> <name> <xp> <tokens>
raceboss hit <player> <boss-id> <damage>
raceboss complete <boss-id> <base-xp> <base-tokens>
racedungeon start <player> <dungeon_id> <normal | hard | mythic>
racedungeon complete <player> <dungeon_id> <tier> <xp> <tokens>

For dungeon completion, <tier> 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 <player>.
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 <player> <race>.
mytheriaraces.admin.reset	Operators	/race reset <player>.
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 <player> <tier>.
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/<menu>.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 plugins/MytheriaRaces/config.yml while the server is stopped, or edit it and run /race reload as an operator. Defaults:

Setting	Default	Effect
enabled-worlds	[]	Empty means all worlds are enabled; otherwise list worlds where race XP and effect refreshes apply.
announce-race-choices	true	Broadcast player race selections.
progression.max-level	25	Maximum race level.
progression.xp-per-level-squared	75	XP curve multiplier; XP to the next level is this value times the current level squared.
progression.mob-kill-xp	12	Race XP per eligible mob kill.
progression.player-kill-xp	100	Race XP per eligible player kill.
progression.ore-break-xp	8	Race XP per eligible ore block.
cooldowns.ability-seconds	35	Base race ability cooldown.
cooldowns.ultimate-seconds	300	Race ultimate cooldown.
combat.gnome-dodge-chance	0.12	Gnome dodge chance.
combat.dwarf-underground-damage-multiplier	0.80	Dwarf damage multiplier underground.
combat.dwarf-bonus-ore-chance	0.20	Dwarf chance to find bonus ore.
storage.type	pdc	pdc stores profiles in player data; yaml uses plugins/MytheriaRaces/profiles/.
player-data.enabled	true	Enable scheduled profile saving.
player-data.save-interval-minutes	5	Save interval.
player-data.daily-backups	true	Create daily player-data backups.
player-data.backup-retention-days	30	Retain backups for this many days.
anti-farm.enabled	true	Enable reward limits.
anti-farm.mob-rewards-per-hour	250	Maximum mob reward events per player per hour.
anti-farm.player-kill-rewards-per-hour	10	Maximum player-kill XP rewards per killer per hour.
anti-farm.same-player-kill-reward-minutes	10	Delay before the same killer can earn player-kill XP from the same victim again.
anti-farm.ore-rewards-per-hour	800	Maximum ore reward events per player per hour.
anti-farm.same-boss-reward-minutes	30	Repeat reward delay for the same boss.
anti-farm.same-dungeon-reward-minutes	15	Repeat reward delay for the same dungeon.
discord-webhook.enabled	false	Enable webhook logging.
discord-webhook.url	""	Discord webhook URL.
discord-webhook.log-race-selection	true	Log race selections.
discord-webhook.log-level-ups	true	Log race level-ups.
discord-webhook.log-prestige	true	Log prestige.
discord-webhook.log-admin-actions	true	Log staff actions.

The plugin also creates YAML files under plugins/MytheriaRaces/configs/. In this release, their settings are loaded but are not currently read by the feature code; use the main config.yml for the active settings listed above.