Base Mythical Races Wiki

What is a race?

In the context of our game, a race can be seen as a collection of rules. These rules encompass various attributes and effects, such as potions. Races serve as a method of categorizing and handling characters within the game. It's crucial to note that each race requires a specific set of values to be filled in, which is of utmost importance. In the free version, you are limited to attributes and potion effects, while the premium version offers a wide array of additional options.

How to Create or Edit a Race?

In your plugins folder, you'll find a directory named 'MythicalRaces.' Inside this folder, there's a file called 'config.yml.' In that file, you'll find the list of races, each with its own set of rules that define their characteristics. Let's take the race 'Human' as an example. In the game, it appears in red color as '&cHuman.' It's worth noting that the display name and the actual race name can differ.

Defining a race

Think of races as coded entries, similar to the keys on your keyboard. Suppose "Human" is one such key or code, when you use it, it gives you access to a lot more information related to the "Human" race. This information can include attributes like displayName, material, and more. The more you explore this guide and watch the related video at the end, the more clarity you'll get on how these pieces of information work together to form the overall concept.

Understanding 'Material'

The 'material' defines the icon for the race in the game. It could range from a book to a diamond sword. You can find the material names in all caps here.

Material for Premium Version Users

If you're a premium user, you get more options. You can add custom model data or use a custom head. The material could be 'MATERIAL:ID', where ID is a custom identifier. You can also use a link from this site. Remember to end it with a semicolon. For example:

material: 'https://textures.minecraft.net/texture/5193c89d1df679854f33c2215247b676a159d5395392d0c61b8476f813d9edb0;'

Below is an example of a custom model id with material, this will display the item book with the custom model id of 4, this is useful for servers with resource packs

material: 'BOOK:4'

Example of a Race Definition

Here's an example of a 'Human' race definition:

Example Race Definition


Human:
  displayName: '&cHuman'
  material: 'BOOK'
  isSubRace: false
  subRaceType: ''
  treeSlot: 4
  levelRequire: 0
  guiPage: 1
  slot: 11
  lvlType: 'RUNNING'
  maxLevel: 100
  gainXP: 2
  xpPerLevel: 24
  lore:
    - '&4----- &cHuman Race &4-----'
    - '&cWell I think you know what a human is'
    - ' '
    - '&5----- Day Time Passive Effects -----'
    - 'None'
    - '&5----- Night Time Passive Effects -----'
    - 'None'
  dayPassivePotionEffects:
    - 'null'
  dayPassivePotionEffectsBase:
    - 'null'
  dayRaceDataPotion:
    - 'null'
  dayPassiveGenericAttributes:
    - 'GENERIC_MOVEMENT_SPEED'
  dayPassiveGenericAttributesBase:
    - 0.1
  dayRacePassiveAttributesLevel:
    - 0.0
  dayRaceDataAttribute:
    - 'ALL < -1000 -1 ALL ALL ALL ALL'
  nightPassivePotionEffects:
    - 'null'
  nightPassivePotionEffectsBase:
    - 'null'
  nightRaceDataPotion:
    - 'null'
  nightPassiveGenericAttributes:
    - 'GENERIC_MOVEMENT_SPEED'
  nightPassiveGenericAttributesBase:
    - 0.1
  nightRacePassiveAttributesLevel:
    - 0.0
  nightRaceDataAttribute:
    - 'ALL < -1000 -1 ALL ALL ALL ALL'
  executeCommandUponSwitching:
    - 'null'

Please replace the 'null' values with the relevant data for your game's races.

Understanding Sub Races

A 'Sub Race' is an evolved form of a 'Base Race'. This sub race can be selected from within the race GUI. To turn a race into a sub race of another, you need to adjust four settings of the sub race (not the base race).

Defining a Sub Race

First, set 'isSubRace' to true, like this:

isSubRace: true

Then, specify the base race in 'subRaceType'. If we're creating a sub race for 'Human', we do this:

subRaceType: 'Human'

About Tree Slot

The 'treeSlot' determines the position of the sub race in the GUI when typing /races tree. 'x' stands for the slot number where the race appears in the GUI. Slots are numbered from 0 to 53, starting from the top left and ending at the bottom right. To avoid overlapping within the evolution tree of a given race, each race must have a unique treeSlot among its own race line.

treeSlot: x

Level Requirements

'levelRequire' denotes the minimum level a player must reach to choose a particular race. This doesn't apply to base races as they are the initial choice for players.

levelRequire: x

Slot Placement in GUI

The 'slot' determines the race's position in the /races GUI. This only applies to BASE races. Like treeSlot, the slot number ranges from 0 to 53. Each base race must have a distinct slot number to avoid overlap in the GUI.

slot: x

Replace 'x' in each of the code snippets with the actual value for your specific game's races.

Understanding Levelling Types

There are 13 levelling types, each corresponding to different activities in the game:

  • HUNTING: For killing mobs/animals
  • RUNNING: For running around
  • HARVESTING: For harvesting crops
  • BUILDER: For placing blocks
  • FISHING: For fishing
  • EXCAVATION: For destroying everything
  • MINER: For mining ores/stone/deepslate
  • WOODCUTTER: For cutting down trees
  • TANKER: For taking damage
  • SWIMMING: For swimming
  • FLYING: For flying
  • DIGGER: For digging such as sand/gravel
  • ARCHER: For killing mobs/animals with arrows

GainXP, MaxLevel, and XpPerLevel

'gainXP' is the amount of XP you earn each time you complete an action related to the above levelling types.

'maxLevel' is the highest level you can reach.

'xpPerLevel' represents the XP you need to level up. To calculate the XP needed to level up, use this equation: players xp / xpPerLevel * current level.

Multiple Levelling Types

If you want a race to have multiple levelling types, you can do it like this:

lvlType: 'RUNNING, HUNTING'

Determining Movement Based Levelling Types

We use a distance-based system to track and reward XP for movement-related activities like swimming, running, and flying. If the player's location changes by a 'distance' amount in 600 ticks, they are awarded the corresponding XP.

leveling: 'RUNNING' distance: 10 time: 600

Understanding Lore

The 'Lore' is self-explanatory. Just make sure to enclose the words properly and not to use more than two > ' < on the same line.

Now that we've covered the basics, let's move onto more complex topics. Don't worry, it's not as daunting as it seems!

Data and Potions

This section covers the various data and potion options available for character customization.

Passive Potion Effects

Three key attributes are involved in managing passive potion effects:

  • dayPassivePotionEffects: The potion effect applied during daytime. Can be one of these values.
  • dayPassivePotionEffectsBase: The base amplifier for the daytime potion effect. This can be any number, with higher numbers creating stronger effects. Potions start at 0.
  • dayRaceDataPotion: Specifies when and where the potion effect applies.

Data

'Data' refers to a string of arguments, each separated by a space. Each argument can be a comma-separated list if multiple specifiers are required.

The string format is as follows: 'ALL Y > -1000 -1 ALL ALL ALL ALL'. Let's break it down:

  1. BIOMES: Specifies the biome(s) in which the effect applies. For biome names, use this list.
  2. Y: Indicates the Y axis of the player.
  3. Comparison: Specifies if the player's Y axis should be greater than (>), less than (<), equal to (=), greater than or equal to (>=), or less than or equal to (<=) the number in the next argument.
  4. Number: The Y axis value for comparison.
  5. Amplifier: The potion's power when the player is not in the specified area. Use -1 to remove potion effects, or another number for attribute effects.
  6. Position: Specifies where the effect applies in relation to certain blocks. Options include ALL, ABOVE, MID, BELOW, AROUND. Only one can be chosen.
  7. Blocks: Specifies the blocks that trigger the effect. Use this list for block names.
  8. Storm: Specifies if the effect applies during a storm. Options include TRUE, FALSE, ALL.
  9. World: Specifies the world in which the effect applies. Options include ALL, or the name of your world(s).

Special types of arguments are also available, some of which are only available in premium versions.

Special Data Types and Examples

  • VAMPIRE: The effect is applied if all blocks above the player to the sky limit are not solid blocks.

    • Example: 'ALL Y > -1000 -1 VAMPIRE VAMPIRE ALL ALL'

  • CUSTOM[num]: In an X radius of blocks next to it, the effect is applied. Replace [num] with a specific number to search for a radius.

    • Example: 'ALL Y > -1000 -1 CUSTOM10 [INSERT BLOCKS HERE] ALL ALL'

  • LIGHTA[num]: The effect is applied if the light level is greater than the specified [num]. The [num] can range from 0 to 14 in terms of light levels.

    • Example: 'ALL Y > -1000 -1 LIGHTA6 LIGHT ALL ALL'

  • LIGHTB[num]: The effect is applied if the light level is lower than the specified [num]. The [num] can range from 0 to 14 in terms of light levels.

    • Example: 'ALL Y > -1000 -1 LIGHTB6 LIGHT ALL ALL'

  • TEMPA[num]: The effect is applied if the temperature level is higher than the specified [num].

    • Example: 'ALL Y > -1000 -1 TEMPA25 TEMP ALL ALL'

  • TEMPB[num]: The effect is applied if the temperature level is lower than the specified [num].

    • Example: 'ALL Y > -1000 -1 TEMPB10 TEMP ALL ALL'

    Below are only possible in the premium version of mythical races

    This is for compatibility with placeholder API

  • %placeholder%==[string/number]

    • Example: 'ALL Y > -1000 -1 %mythicalraces_race%==Elf PAPI ALL ALL'

    This can only check for a single string, a sentence will not work

    Check if the placeholder %placeholder& is equal to the right side of the sign > ==

  • %placeholder%!=[string or number]

    • Example: 'ALL Y > -1000 -1 %mythicalraces_race%!=Elf PAPI ALL ALL'

    Check if the placeholder %placeholder& is NOT equal to the right side of the sign > !=

    This can only check for a single string, a sentence will not work

  • %placeholder%>[number]

    • Example: 'ALL Y > -1000 -1 %mythicalraces_get_level%>3 PAPI ALL ALL'

    Check if the placeholder %mythicalraces_get_level% is greater than the number to the sign ->>

    This can only check for a single string, a sentence will not work

  • %placeholder%<[number]

    • Example: 'ALL Y > -1000 -1 %mythicalraces_get_level%<5 PAPI ALL ALL'

Special types of arguments are also available, some of which are onl available in premium versions.

Attributes

Attributes modify different aspects of the player's abilities. Here are some attributes and their usage:

  • dayPassiveGenericAttributes: The attribute that will be applied
  • dayPassiveGenericAttributesBase: The base value of the attribute
  • dayRacePassiveAttributesLevel: A number that will be added to the base value for every race or class level the user obtains
  • dayRaceDataAttribute: The data that will be applied to the attribute

On switch to race commands.

This section covers the executeCommandUponSwitching, where you can execute commands when the player joins/leaves a race.

Execute Command Upon Switching

This executes a console command, with player as the players name.

Example


executeCommandUponSwitching:
  - 'say {'player'} just joined the race!'

Premium version

Execute Command Upon Switching

This executes a console command, with player as the players name.

Adding ==== at the end of the command will execute the command when the user leaves the race.

Example


executeCommandUponSwitching:
  - 'say {'player'} just joined the race!'
  - 'say {'player'} just left the race!===='

Additional Tips

This section covers some miscellaneous tips for using the plugin.

Aligning Races

Using Notepad++, you can align your races for better organization and to prevent plugin breakdown. You'll notice a line between the 'C' and 'o' in 'CommonElf' or any race. Align this line with the first two letters of your races to achieve a neat alignment.

Image showing whats described above

Timer for Checking Potion Effects

The frequency at which the plugin checks for potion effects is determined by the 'timerCheckingPotionEffects' setting. The time is counted in seconds with 20 equaling 1 second. If you wish for the plugin to check every 5 seconds, you would set the following:

timerCheckingPotionEffects: 100

Attribute and Value Correspondence

The values in different attribute lists correspond with each other. For example, the first value in one list corresponds to the first value in another list. This principle applies to all four attribute lists.

An illustration can help clarify this correspondence:

Image showing correspondence between list values

Races Tutorial Creation Examples

Command And Permissions

Free Version Permissions

The following permissions are specific to the Free version of the MythicalRaces plugin:

  • mythicalraces.race.[race]: Grants the ability to choose a specific race. Replace [race] with the name of the desired race. For example, mythicalraces.race.Elf for choosing Elf.
  • mythicalraces.help: Grants access to the help command.
  • mythicalraces.info.races: Grants the ability to view information about races.
  • mythicalraces.gui: Grants access to the graphical user interface.
  • mythicalraces.tree: Grants access to view the race tree.
  • mythicalraces.profile: Grants the ability to view one's own profile.
  • mythicalraces.profile.other: Grants the ability to view other players' profiles.
  • mythicalraces.biome: Grants the ability to view the current biome.
  • mythicalraces.list.races: Grants the ability to list all available races.
  • mythicalraces.lvlset: Grants the ability to set the level of another player.
  • mythicalraces.cooldown.bypass: Allows bypassing race choosing cooldowns.

Free Version Placeholders

These placeholders offer dynamic in-game data for Free users. They are compatible with any plugin that supports PlaceholderAPI:

  • %mythicalraces_race%: Displays the player's race.
  • %mythicalraces_display_race_name%: Displays the display name of the player's race.
  • %mythicalraces_cooldown_time%: Displays the cooldown time.
  • %mythicalraces_has_cooldown%: Displays if the player has a cooldown.
  • %mythicalraces_get_xp%: Displays the player's experience points.
  • %mythicalraces_get_level%: Displays the player's level.
  • %mythicalraces_get_max_xp%: Displays the maximum experience points for the player's level.
  • %mythicalraces_get_xp/max_xp%: Displays the player's current XP as a fraction of their max XP.

Free Version Commands

  • /races choose [race]
  • /races help
  • /races info [race]
  • /races gui
  • /races tree
  • /races profile
  • /races profile [player]
  • /races set race player
  • /races biome
  • /races list
  • /races lvlset [player] [level]

Premium Version Permissions

The following permissions are specific to the Premium version of the MythicalRaces plugin:

  • mythicalraces.race.[race]: Lets a player choose a specific race.
  • mythicalraces.class.[class]: Allows a player to choose a specific class.
  • mythicalraces.help: Grants a player access to the help command.
  • mythicalraces.info.races: Allows a player to view information about races.
  • mythicalraces.gui: Provides a player access to the graphical user interface.
  • mythicalraces.gui.class: Gives a player access to the class-based graphical user interface.
  • mythicalraces.tree: Lets a player view the race tree.
  • mythicalraces.tree.class: Lets a player view the class tree.
  • mythicalraces.profile: Grants a player the ability to view their own profile.
  • mythicalraces.profile.other: Allows a player to view other players' profiles.
  • mythicalraces.race.setrace: Allows setting the race of a specified player. (Don't give to default players)
  • mythicalraces.biome: Lets a player view the current biome.
  • mythicalraces.list.races: Allows a player to list all available races.
  • mythicalraces.lvlset: Enables setting the level of a specified player.
  • mythicalraces.lvlsetclass: Enables setting the level of a specified class for a player.
  • mythicalraces.leaderboard: Grants a player access to the leaderboard.
  • mythicalraces.addxp: Lets adding experience points to a specified player.
  • mythicalraces.rcooldown: Manages cooldown for a specified player.
  • mythicalraces.sub.display: Lets a player display a specific race/class sub.
  • mythicalraces.cooldown.bypass: Allows a player to bypass race choosing cooldowns.
  • mythicalraces.toggle.player: Allows a user to toggle another's abilities/setters (Don't give to default players)
  • mythicalraces.toggle: Allows a user to toggle their own setters/abilities (Depends on if you want to give your players control over this)

Premium Version Placeholders

These placeholders offer dynamic in-game data for Premium users. They are compatible with any plugin that supports PlaceholderAPI:

  • %mythicalraces_race%: Displays the player's race.
  • %mythicalraces_display_race_name%: Displays the display name of the player's race.
  • %mythicalraces_cooldown_time%: Displays the cooldown time.
  • %mythicalraces_has_cooldown%: Displays if the player has a cooldown.
  • %mythicalraces_get_xp%: Displays the player's experience points.
  • %mythicalraces_get_level%: Displays the player's level.
  • %mythicalraces_get_max_xp%: Displays the maximum experience points for the player's level.
  • %mythicalraces_get_xp/max_xp%: Displays the player's current XP as a fraction of their max XP.
  • %mythicalraces_class%: Displays the player's class.
  • %mythicalraces_display_class_name%: Displays the display name of the player's class.
  • %mythicalraces_cooldown_time_class%: Displays the class-specific cooldown time.
  • %mythicalraces_has_cooldown_class%: Displays if the player has a class-specific cooldown.
  • %mythicalraces_get_xp_class%: Displays the class-specific experience points.
  • %mythicalraces_get_level_class%: Displays the player's class level.
  • %mythicalraces_get_max_xp_class%: Displays the maximum class-specific experience points for the player's level.
  • %mythicalraces_get_xp/max_xp_class%: Displays the player's current class XP as a fraction of their max class XP.
  • %mythicalraces_leaderboard_num_[leaderboard position]%: Displays the player's position on the leaderboard.

Premium Version Commands

  • /races choose [race]
  • /races help
  • /races info [race]
  • /races gui
  • /races classgui
  • /races tree
  • /races classtree
  • /races profile
  • /races profile [player]
  • /races set race player
  • /races biome
  • /races list
  • /races lvlset [player] [level]
  • /races lvlsetclass [player] [level]
  • /races leaderboard
  • /races addxp [player] [xp]
  • /races addxpclass [player] [xp]
  • /races rcooldown [player]
  • /races sub [race/class]
  • /races questview [quest]
  • /races questprogress [quest]
  • /races questlist
  • /races reset [player]
  • /races toggle
  • /races toggleplayer [player]

Quests - Premium Only

Here you can define quests for your game.


# This is your quest configuration file, where you define quests for your game.

# Event Types:
# Define the event types and their potential arguments here.
# - 'BLOCK-BREAK:BLOCK_TYPE:AMOUNT' - Player breaks a specific type of block a certain number of times.
# - 'BLOCK-PLACE:BLOCK_TYPE:AMOUNT' - Player places a specific type of block a certain number of times.
# - 'KILL-ENTITY:ENTITY_TYPE:AMOUNT' - Player kills a specific type of entity a certain number of times.
# - 'ITEM-PICKUP:ITEM_NAME:AMOUNT' - Player picks up a specific item a certain number of times.
# - 'ITEM-DROP:ITEM_NAME:AMOUNT' - Player drops a specific item a certain number of times.
# - 'ITEM-CRAFT:ITEM_NAME:AMOUNT' - Player crafts a specific item a certain number of times.
# - 'TRAVEL-WORLD:WORLD_NAME:AMOUNT' - Player travels to a world a certain amount of times.
# - 'KILL-ENTITY-PROJECTILE:ENTITY_TYPE:AMOUNT' - Player kills a specific type of entity with a projectile a certain number of times.

# Placeholders:
# For commands only:
# Use these placeholders in starting and ending commands to provide dynamic information.
# {'x'}, {'y'}, {'z'} - Player's coordinates
# {'player'} - Player's name
# {'world'} - World name

# AssignedTo can be a race or a class name, with 'ALL' meaning all races and all classes
# To add more races or classes assigned to a quest
# Simply add their race/class name to the 'assignedTo' list
# Example
# assignedTo:
#  - 'Elf'
#  - 'Human'

# IMPORTANT #
# if you want to remove quests simply leave the "Beginning" quest, and set the 'assignedTo' to 'NONE'

sql:
  use_uuids: true
  connection_type: "local"  # or "remote"

  # Your remote db string if connection_type is "remote"
  connection_string: "jdbc:mysql://localhost:3306/your_database_name?user=your_username&password=your_password"

  # Enable log filter for quest start/end commands
  enableLogFilter: true

quests:
  Beginning:
    displayName: "Beginning"
    description: "The beginning of your journey"
    lore:
      - "&5The beginning of your journey"
      - "&5Break 10 grass"
      - "&5Break 10 dirt blocks"
      - "&f-------------------------"
      - "&6Rewards:"
      - "&f- 1 diamond"
    events:
      - 'BLOCK-BREAK:GRASS:10'
      - 'BLOCK-BREAK:DIRT:10'
    assignedTo:
      - 'ALL'
    startingQuestCommands:
      - 'execute at {'player'} run playsound minecraft:ui.toast.challenge_complete player {'player'} {'x'} {'y'} {'z'}'
      - 'tellraw {'player'} {'"text":"Started the quest Beginning! To view the quest, use /races questview Beginning","color":"yellow"'}'
    finishedQuestCommands:
      - 'execute at {'player'} run playsound minecraft:entity.player.levelup player {'player'} {'x'} {'y'} {'z'}'
      - 'minecraft:give {'player'} diamond 1'
      - 'tellraw {'player'} {'"text":"You have completed the quest Beginning!","color":"yellow"'}'