AstralRaces | All-in-one Races Plugin v2

# AstralRaces v2.0 — Full Revival Update
---
## Active Abilities System (NEW) - 7 built-in abilities that players activate with Sneak + Right-Click (empty hand) - Dash — teleport forward in the direction you're facing - Leap — launch into the air with configurable power - Fire Breath — cone of fire damage, ignites nearby enemies - Heal Burst — AoE heal for yourself and nearby same-race allies - War Cry — AoE strength buff for yourself and nearby allies - Berserk — gain Strength + Resistance at the cost of Slowness - Shadow Step — temporary invisibility and speed boost - Per-ability cooldowns with configurable duration - Custom particles and sound effects for each ability - Abilities assigned per-race in races.yml - Cooldowns clear on race change and disconnect - Developer API: registerActiveAbility() for third-party plugins

## Race Leveling System (NEW) - Players earn XP from mob kills, PvP, block breaking, crafting, and fishing - Scaling XP requirements per level (configurable formula) - Max level cap (default 50) - Level milestone system — run commands and send messages at specific levels - XP progress bar in /race info - Configurable reset on race change - All three storage backends (File, MySQL, MongoDB) persist level/XP data

## MiniMessage Support (NEW) - Full MiniMessage tag support alongside legacy & color codes - Use gradients: <gradient:purple:blue>Text</gradient> - Use hover text: <hover:show_text:'Info'>Text</hover> - Use click events: <click:run_command:/race info>Text</click> - Auto-detection — the plugin detects which format you're using - Fully backwards compatible with existing & code configs

## Multi-Language Support (NEW) - New locale setting in config.yml - Ships with English, Spanish, French, and German translations - Falls back to English for any missing translation keys - Create custom locale files: message_{locale}.yml - Hot-reloadable with /race reload

## BossBar Integration (NEW) - Persistent bossbar showing race name, level, and XP progress - XP bar fills as you earn XP, resets on level-up - Configurable format, color, overlay style, and update interval - Automatically shows on join, hides on quit - Toggle with bossbar.enabled in config - Supports MiniMessage formatting in the bossbar text

## Enhanced Selection GUI - Dynamic lore on race items showing: - Player count — how many players are in each race - Abilities — ability name, cooldown, and description - Effects — potion effects with roman numeral levels - mcMMO Boosts — skill boosts listed per race - Items are fully locked — no shift-clicking, dragging, or moving items out - Confirmation panel also locked ## New Commands - /race info — shows your race, level, XP progress bar, coins, effects, and abilities - /race list — lists all available races with their effects - Tab completion for race names on all commands

## New PlaceholderAPI Placeholders - %races_level% / %races_race_level% - %races_xp% / %races_race_xp% - %races_xp_needed% / %races_race_xp_needed% - %races_progress% / %races_race_progress% - %races_coin_multiplier% - %races_booster_active%

## Bug Fixes - Fixed: Soul Gem / Race Coin / Booster NBT crash (NBTReflectionUtil) — migrated to Paper's native PersistentDataContainer API - Fixed: AsyncCommandAction race condition — command blocking now uses synchronous user lookup - Fixed: Ability cooldowns properly cleared on quit and race change

## Config Changes - New abilities.enabled toggle - New race-levels section with XP rewards, milestones, and scaling - New bossbar section with format, color, overlay, and update interval - New locale setting for language selection - New active-abilities list in races.yml per race

## Dependencies - MiniMessage included via Paper API (no extra dependency) ---

• Plugin updated to support 1.21.4 & 1.21.5
• Fixed an issue when interacting with NPCs would throw a race is null NPE.

1.1.7

Recoded Sections
This update, I've revisited the existing systems and recoded a handful of the current events, management classes and effects system.

New Effects
As of today, I have started working on a new effects system for the plugin which aims to introduce custom effects, this new system will allow me to greatly expand upon the current and very basic potion effect system, the api will allow for custom effect creation in v2.0

Here are the new effects:

• PLAYER_ATTACK_DAMAGE
• PLAYER_DEFENCE
• MOB_ATTACK_DAMAGE
• MOB_DEFENCE

Below is how your configuration should look after implementation.

Spoiler: races.yml

YAML:

races:
  Human:
    tag: '&8[&bHuman&8]'
    color: '&b'
    chat-format: '&8[&bHuman Chat&8] &f%player%: &7%message%'
    spawn-point: world;0.5;50;0.5;280;0
    broadcast-message: '&b&l(!) &b%player% has joined the Humans!'
    mcMMO-boost:
      - SWORDS:15
      - TAMING:15
      - FISHING:15
    effects:
      - HEALTH_BOOST:0
      - PLAYER_ATTACK_DAMAGE:20;2 # 20 represents proc percentage and 2 represents the modifier
      - PLAYER_DEFENCE:20;2 # 20 represents proc percentage and 2 represents the modifier
      - MOB_ATTACK_DAMAGE:20;2 # 20 represents proc percentage and 2 represents the modifier
      - MOB_DEFENCE:20;2 # 20 represents proc percentage and 2 represents the modifier
    commands:
      - 'tellraw %player% {"text":"+15 Swords Levels","color":"green","bold":true}'
      - 'tellraw %player% {"text":"+15 Taming Levels","color":"green","bold":true}'
      - 'tellraw %player% {"text":"+15 Fishing Levels","color":"green","bold":true}'
      - 'kit starter %player%'

These effects are basic and more complex effects will come in the future.

Cooldown System
The cooldown system has been recoded and some of the issues have been patched.

The new system will require some config adjustments, the cooldown-time section now requires your time in hours instead of seconds so adjust the default from 86400 to 24 to keep the timer at the default of 1 day.

/race removecooldown <target> - New command has been added to remove active cooldowns from players after soul gem usage.

Some other notable changes are as follows:

• Fixed an issue where cooldown would apply without confirming race change via soul gem
• Fixed an issue where race cooldown would corrupt after a server reboot
• Fixed cooldowns file resetting randomly when a new value is added

API Changes
The api has been updated, please view below an example of how the new system will work.

Spoiler: api-test

Java:

@AllArgsConstructor
public class APITest implements Listener {

    public RaceAPI raceAPI;

    public APITest() {
        RegisteredServiceProvider<RaceAPI> provider = Bukkit.getServer().getServicesManager().getRegistration(RaceAPI.class);
        if (provider != null) {
            this.raceAPI = provider.getProvider();
        } else {
            throw new IllegalStateException("RaceAPI service not found. Ensure it's registered.");
        }
    }

    @EventHandler
    public void onMove(PlayerMoveEvent event) {
        raceAPI.getUser(event.getPlayer().getUniqueId(), usersData -> {
            if (usersData.getRace().equals("Dwarf")) {
                Chat.msg(event.getPlayer(), "Since you're a Dwarf, you will see this every time you move!");
            }
        });
    }
}

That's all for this update, the next build will be 2.0 which will feature an abundance of new content and features. Have a great day!

1.1.6

This update brings some important bug fixes, most notably an issue with the Auto ConfigUpdater.

ConfigUpdater changes
The old config updater was slightly flawed, it meant that users configurations would reset to the default on server restart as it was pulling the default config from resources/config.yml and using those values, instead of just updating new values when they become available. This has now been patched.

Soul Gems
I have added a new cooldown system to soul-gems, a reset command is not yet functional but from the next update it will be, players can now specify if they want a cooldown on the usage of soul gems.

I have also fixed an issue with soul gems throwing an NPE if the itemStack is changed from ENDER_EYE, my bad.

Teleportation Updates
A new option has been added into the config, race-settings.teleport-on-race-change if this is set to true, it will no longer teleport players when they select a new race, they will stay in the same spot, set to false to have them teleport to your chosen spawn location.

Placeholders
Below is a list of the current placeholders for the plugin as there has been some confusion.

%races_race% - Will return the Players race (ex: Elf)
%races_tag% - Will return the players chosen Race Tag specified in races.yml
%races_race_color% - Will return the players chosen Race Color specified in races.yml

Bugs Fixed

• Fixed an NPE on onDisable() relating to player inventories.
• Fixed an array of issues when certain config options are set as false
• Fixed first-join.enabled, this will now allow you to enable/disable without constantly staying enabled
• Fixed Cooldown cooldowns not initialising correctly on server startup.

Coming in Next Update
In the next update, you'll see the ability to use SQL Databases for player-data instead of your regular .json files, this is long anticipated and will allow blazing fast loading/saving times of race data alongside a brand new customisable Race Currency, stay tuned.

Special thanks to visedev for testing some of the fixes for discussed issues.

Have a great rest of your Sunday all!

• Added automatic Configuration updates when a new section is added, no idea why this wasn't implemented from the very beginning but it is now.
• Added a new placeholder, %races_race_color% will now return the color of the race that you set in races.yml, below is how the new races.yml config will look
• Added the ability to blank out both effects and mcmmo-boost options in your config file with []

Spoiler: races.yml layout-new

YAML:

  Human:
    tag: '&8[&bHuman&8]'
    color: '&b'
    chat-format: '&8[&bHuman Chat&8] &f%player%: &7%message%'
    spawn-point: world;0.5;50;0.5;280;0
    broadcast-message: '&b&l(!) &b%player% has joined the Humans!'
    mcMMO-boost:
      - SWORDS:15
      - TAMING:15
      - FISHING:15
    effects:
      - HEALTH_BOOST:0
    commands:
      - 'tellraw %player% {"text":"+15 Swords Levels","color":"green","bold":true}'
      - 'tellraw %player% {"text":"+15 Taming Levels","color":"green","bold":true}'
      - 'tellraw %player% {"text":"+15 Fishing Levels","color":"green","bold":true}'
      - 'kit starter %player%'

• The plugin now depends on Vault going forward, please make sure you have this installed (Recommended Version: 1.7.3)
• Added an Economy system for the usage of Soul Gems, you can now charge $ for usage. This only works with Essentials Economy as of right now, if you'd like any different economy plugins supported, contact me.

Configuration Changes
You can re-generate your config.yml & messages.yml file or add the following:

Spoiler: config.yml changes

YAML:

soul-gem:
  id: 'ENDER_EYE'
  display: '&eSoul Gem'
  lore:
    - '&7Allows you to change your race.'
    - '&eSingle use, right click while equipped.'
  settings:
    charge-for-use: true
    cost: 10000000

Spoiler: messages.yml changes

YAML:

  insufficient-balance: '&c&l(!) &cYou do not have enough money to use this, you need &f$%cost%'
  balance-deducted: '&c&l- $%cost%'
  balance-added: '&a&l+ $%cost%'

• Added the ability to set custom model data. Find an example usage below.

YAML:

soul-gem:
  id: 'ENDER_EYE'
  display: '&eSoul Gem'
  custom-data: 1001
  lore:
    - '&7Allows you to change your race.'
    - '&eSingle use, right click while equipped.'

if you have any issues with this, please contact me.

Hi, please find below, the changes that have been made to the plugin in v1.1.2

• Plugin has been recompiled using Java 17, going forward and version above this will be compatible.
• Added a new section into the config, first-join. This allows you to create custom behaviours when a new player joins the server, if you'd like portals like Minecadia this can be done by customising the configuration files.
• Added a new command /races setfirstspawn - races.setfirstspawn

Spoiler: Add me to your config.yml

YAML:

first-join:
  enabled: true # Should this be enabled?
  settings:
    disable-commands: true # Create a blacklist and a whitelist for commands when a player hasn't got a race selected
    disable-chat: true # Disable the ability to chat when the player does not have a race.
    open-selection-menu: false # Should we open the GUI selection menu? (use this for default behaviour)
  teleport:
    enabled: true # Should the player be teleported to a set spawn-point on first join?
    spawn-point: world;0.5;50;0.5;280;0
  blocked-commands:
    - '*' # This placeholder will block all player commands, apart from those that are specified in allowed-commands
  allowed-commands:
    - 'login'
    - 'register'

Spoiler: Add me to your messages.yml file

YAML:

  set-first-spawn: '&a&l(!) &aYou have set the spawn point for first time players!'
  cannot-use-commands: '&c&l(!) &cYou cannot use commands until you have selected a race!'
  cannot-chat: '&c&l(!) &cYou cannot chat until you have selected a race!'