Repository navigation
Custom Level Systems (levelsystems.yml)
This section of the wiki will guide you through creating your own custom level systems using Server Levels, specifically using the levelsystems.yml file.
Here you will define how players using your system gain exp, how much exp they gain, the message the player is sent when they level up, the max level, and how exp requirements scale with level.
Here is the default level system that the plugin ships with. It uses every option available to you, and we will start by using it as a base:
default:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New level: %level%</green>'
max-level: 100
exp-gain-multiplier: 0.0
use-milestones: true
exp-gain:
on-chat: 0.2
on-mobkill: 0.4
on-playerkill: 0.6
on-blockbreak: 0.01
on-blockplace: 0.01
exp-requirements:
base-exp-req: 8.0
exp-req-multiplier: 1.1
exp-scalar-type: 'EXPONENTIAL'When creating our own level system, we start by choosing the name of the system. It is best to keep this internal name all lowercase, and it CANNOT contain spaces or any special characters. Letters, numbers, hyphens, and underscores are all allowed here. For the sake of example, lets create a level system called "mining" that will grant the player experience for breaking blocks in the world:
mining:
enabled: trueWe start by adding the enabled: true line to make sure the plugin knows to load this system instead of skipping it entirely. Having disabled systems in your config can help to serve as a reference when creating new level systems.
When the player levels up, its good to let them know that they've leveled up. We do this by adding two sections: send-message-on-levelup and levelup-message. send-message-on-levelup tells the plugin whether or not to send a message, and levelup-message tells the plugin what the message should be:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'The levelup-message uses the MiniMessage format for colors and formatting. Click HERE for a nice generator that should help you create the text in the proper format.
By putting %level% in the string, the message will send the new level that the player has reached instead of %level%.
You can also put %player% to include the player's name in the message.
To set a max level for the level system, you just add the max-level option to your system like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20The max level is stored as a 32 bit integer, and therefore cannot be set above 2.14 billion. If you do not specify a max level, it will default to 100.
ServerLevels allows you to send a message to the player's Action Bar when they gain exp in your systems. If you want your system to tell the player when they gain exp, we simply have to add the show-exp-gain option and set it to true:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
show-exp-gain: trueThis is enough to get it to start sending messages, but if you have several systems you may want to customize the message that the player is sent to differentiate between them. You can do that by adding a exp-gain-message option and adding a String using MiniMessage formatting like this:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
show-exp-gain: true
exp-gain-message: "<green>Gained </green><dark_green>%exp%</dark_green><green> %system% exp</green>"Here, the message will say "Gained [exp amount] mining exp". You can use %exp% in the String to put the amount of exp they're gaining, and %system% for the name of the level system just to make it easier to copy and paste your message between your systems.
By default, the players won't gain any experience in your level system. Either you have to add the player to the system via the /sl addSystem command, using the plugin's API, or have the system automatically add players to the system by adding the auto-add-players option to your levelsystem like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
auto-add-players: trueBy adding this option, when a player joins the server they will automatically be added to the system. This is useful for any systems which always apply to all players, as it saves you the trouble of having to manually add every player yourself.
Sometimes, for example during a special event, you may want to add a multiplier for how fast players gain exp. To set such a multiplier, simply add the exp-gain-multiplier field to your system:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain-multiplier: 0.20In this configuration, players will receive a 20% boost to their exp gains. Think of this field as writing a percentage as a decimal. If you want a 50% increase to all experience gained, you would set this to 0.5.
This field defaults to 0, meaning if unset all exp gains will remain exactly as specified later in the config.
If you want your system to reward players for leveling up, you have to specify that your system is using the plugin's Milestones system. To do this, simply add the use-milestones field to your system:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
use-milestones: trueNow that this is enabled, you can switch to the milestones.yml file and add your customized rewards for each level. Details on this are in a separate, dedicated wiki page.
Now that you have the details of your level system all set up, now you have to tell the plugin how exactly players are meant to gain experience. By default, the plugin supports 5 methods of gaining exp: using chat, killing mobs, killing players, breaking blocks, and placing blocks. Before we can add any of these, we must first add the exp-gain section to your system:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:Do not put anything next to exp-gain, as it serves as a configuration section not a specific option.
If you want players to gain exp when they use the chat, you must add the on-chat option inside your exp-gain section like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-chat: 0.1With the above configuration, players would gain 0.1 exp in this specific level system every time they send a message in chat.
If you want players to gain exp when they kill mobs, you must add the on-mobkill option to your exp-gain section like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-mobkill: 0.6With the above configuration, players would gain 0.6 exp in this specific level system every time they kill a mob.
If you want to give different amounts of exp for different mobs, you must configure the mobs.yml file as shown below. If you want to ONLY grant experience for mobs specified in the mobs.yml file, leave the on-mobkill option empty or omit it entirely.
If you want players to gain exp when they kill players, you must add the on-playerkill option to your exp-gain section like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-playerkill: 0.6With the above configuration, players would gain 0.6 exp in this specific level system every time they kill a player.
If you want players to gain exp when break blocks, you must add the on-blockbreak option to your exp-gain section like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-blockbreak: 0.1With the above configuration, players would gain 0.1 exp in this specific level system every time they break a block.
If you want to give different amounts of exp for different blocks, you must configure the blocks.yml file as shown below. If you want to only grant exp for the specified blocks, leave the on-blockbreak field empty or omit it entirely.
If you want players to gain exp when break blocks, you must add the on-blockplace option to your exp-gain section like so:
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-blockplace: 0.1With the above configuration, players would gain 0.1 exp in this specific level system every time they place a block.
If you want to give different amounts of exp for different blocks, you must configure the blocks.yml file as shown below. If you want to only grant exp for the specified blocks, leave the on-blockplace field empty or omit it entirely.
In most games, the amount of exp required for level 10 is higher than the amount of exp required to simply reach level 1. To configure exactly how the experience requirements increase per level, we must add the exp-gain section to our system and its 3 required options: base-exp-req, exp-req-multiplier, and exp-scalar-type.
mining:
enabled: true
send-message-on-levelup: true
levelup-message: '<green>You leveled up! New mining level: %level%</green>'
max-level: 20
exp-gain:
on-blockbreak: 0.1
exp-requirements:
base-exp-req: 8.0
exp-req-multiplier: 0.5
exp-scalar-type: 'LINEAR'In Server Levels, base-exp-req indicates the amount of exp required to reach level 1, and exp-req-multiplier is the factor by which the amount of required exp increases with each level according to the scalar type specified in exp-scalar-type. Currently, there are 2 supported scalar types, LINEAR and EXPONENTIAL
The linear scalar causes the exp requirement to scale by a set amount each level. Take the following configuration for example:
exp-requirements:
base-exp-req: 8.0
exp-req-multiplier: 0.5
exp-scalar-type: 'LINEAR'The formula for the linear type is player-level * (base-exp-req * exp-req-multiplier) + base-exp-req
Or, in more understandable terms, we first multiply the base-exp-req by our exp-req-multiplier. In our example, this is 8 * 0.5 which gives us 4. Then, for every level after 1, we increase the amount of exp required for that level by the number we just got, in our example 4.
So, to reach level 1, the player must get 8 exp. Then, to reach level 2, the player must get 12 exp (8 + 4). For level 3, 16 exp (12+4), and so on.
Using this scalar type is good for when you want leveling up to feel difficult early on, but don't want the amount of exp required to balloon to incredibly large numbers or otherwise want the amount of required exp to increase by predictable amounts.
The exponential scalar is the most common type of exp scalar out in the world, and functions by multiplying the exp requirement by a set multiplier each level.
exp-requirements:
base-exp-req: 8.0
exp-req-multiplier: 1.1
exp-scalar-type: 'EXPONENTIAL'The formula is previous-exp-cost * exp-required-multiplier
Or, in more understandable terms, we take how much exp the previous level costed, multiply it by our set multiplier, and the result is how much the next level costs.
In the above example, our base requirement is 8, so to reach level 1 the player must get 8 exp. Then, to reach level 2, we take the previous exp cost (8) and multiply it by our multiplier (1.1) to get the exp requirement, in this case that's 8.8 exp. Then, to get to level 3, we take level 2's requirement of 8.8, mutliply THAT by 1.1 to get 9.68, and use 9.68 as the amount of exp required to reach level 3.
This type of Scalar is great for if you want leveling to feel fast and easy early on but ramp up steadily over time. When using this system, exp requirements can reach ridiculous hights if unchecked, so make sure you're granting your players the amount of exp they need to reach those higher levels.
Say, for example, you're creating a traditional RPG leveling system where you kill mobs to level up. In a system like this, it make no sense to have every mob you kill count for the same amount of exp. That's where the mobs.yml file comes in.
In the mobs.yml file, you can configure exactly how much exp any specific mob grants the player for every individual level system.
For plugins that add custom mobs you won't configure those custom enemies here. Instead, you will configure those exp gains for your custom enemies in the plugin's dedicated compatibility file (plugins/ServerLevels/compatibility/plugin-name.yml).
Coming soon!