Skip to main content

Config

Plugin configuration files are split into separate files to organize options. All the config files are automatically reloaded.
Config files are not translatable but the language file and all the GUIs are.
Kingdoms uses YAML as its main config system.
For information specific to language files, refer to Languages section.

tip

All the configs including language files except GUIs, support auto config updates. However this feature is disabled by default. When the auto updater is disabled, the plugin tries to use the default value.

Most config options are explained in their own config files. This page covers some basic and advanced features that the Kingdoms plugin supports in config options.

  • Most numeric options can be disabled by setting their value to 0 (or lower) unless specified otherwise. This disables any side effects that the option might have (such as sending messages)
  • You can use \n line break to break lines for messages.
  • All the Minecraft materials can be found here.
  • Potion effects are defined using the <potion>, <duration>, <level> [%chance] where is one of these and the duration is in seconds. Also the level doesn't start from 0 unlike the standards. The chance (the percent sign is required before it, but notice there's no comma) is from 0 to 100
  • Sounds use the [~][category@]<sound>, [volume], [pitch], [seed] format. All Minecraft sounds can be found here. Minecraft volume ranges from 0.0 to 1.0, with 1.0 as the normal value. Any higher number only increases the radius in which players can hear the sound. Pitch ranges from 0.5 to 2.0, with 1.0 as the normal value. You can test sounds with the /k admin sound command. The optional ~ prefix plays the sound at the player's location instead of only for that player, allowing nearby players to hear it too. The <sound> can also come from a resource pack and usually looks like rpname:my.custom.sound.
  • Options that you can specify commands for always take one or multiple commands.
    • Singular like commands: "k admin rp %kingdoms_name% add 100" or commands: [ "k admin rp %kingdoms_name% add 100" ]
    • Multiple like commands: [ "give %player% diamond 10", "give %player% grass 4" ]
    • The slash at the beginning of the commands are optional, but if you ever had to use a plugin which uses 2 slashes (such as //wand) you have to use 3 slashes instead commands: "///wand"
    • There are two command directive prefixes that change the executor of the command:
      • OP: By default commands are executed as if the player executed them. Using this directive will make the player execute the commands as op.
      • CONSOLE: This tells the server to execute the command from console. This is preferred over OP directive.
      • E.g. commands: [ "CONSOLE:give %player% diamond 10", "OP:give %player% diamond 10" ]
  • Surprisingly one thing that some people don't know, is that you can use Ctrl + F to search for something in a file. This is useful for searching for config options or language entries. If you didn't know this, Google Ctrl + Z and Ctrl + R as well.
  • Most of the config options in the config that represent a time, support time suffixes. The default time suffix is seconds. Please also note that most of the cooldown options in the config are temporary, meaning that the timer will reset after server restarts. Some time suffixes:
    • You might see some config options that only support ticks. In Minecraft each second is 20 ticks.
    • ms, millisec, millisecs, millisecond, milliseconds (Note: Due to the tick-based nature of Minecraft, not all options use this accurately)
    • s, sec, secs, second, seconds
    • m, min, mins, minutes, minutes
    • h, hr, hrs, hour, hours
    • d, day, days
    • Example: time-limit: 10days

Boss Bars​

Boss bars are the progress bars that you usually see on the top of your screen when fighting withers and the ender dragon. You can test different values using the /bossbar vanilla command.
You can see both of them in this image:

BossBar

Options:

  • enabled Usually this option is present to determine whether the bar should be shown at all or not.
  • title The title of the bar which supports colors (including hex colors) and placeholders, but they do not support line breaks.
  • color The color of the bar. You can find all the colors here.
  • style The style of the bar. Bars can be either a solid line just like the ones shown in the image above, or segmented with indicators that divide the bar with small vertical lines. You can find all the styles here.
  • flags A list of cool visual side-effects. You can find all the flags here.

Styles:
Solid Segmented

Math​

These rules apply to all the math equations in any configs.
After reading the basics, you can head to the practical section for a better understanding.

Simple Operations​

Supports all the mathematical operators such as +, -, /, *, %, (), ^, etc...

  • / You should know this one! It's the division operator. Fractional numbers!
  • % in computers, this is called modulo which is basically the remainder of a division. For example, 4 / 3 has a remainder of 1 so 4 % 3 is 1 and 4 / 2 has a remainder of 0 so 4 % 2 is 0
  • * in computers means multiply
  • ^ in computers usually refers to bitwise operators, but it exponentiates here. E.g. 2^3 = 2³ = 2 * 2 * 2 = 8
note

Sometimes you might encounter an error regarding the symbols that you used in a math equation being unknown. These issues mostly happen when you're editing the config on a phone (for some reasons...) which can sometimes make you confuse symbols. For example, on iPhone, there is a symbol − technically named minus sign (U+2212), but on PC or android, the symbol is - named hyphen-minus (U+002D). While both are correct, there may be other symbols that look similar and may cause math compiler issues.

They support Order of operations (Operator Precedence). Bitwise operator precedence are the same as Java's. E.g. 2 + 2 * 100 is 2 + 200 and not 4 * 100

tip

You can test your equations with the /k admin evaluate command.

Placeholders​

Placeholder support depending on the context. For example, in some cases only the kingdom is present with no player. That means you can use %kingdoms_name%, but not %kingdoms_rank_name% because there are no players present. Some equations provide custom placeholders that should be explained above the equation in configs. For example, lvl is a custom placeholder commonly used in equations. For more info, visit the linked wiki.

  • The compiler also interprets boolean placeholders. Returning 1 for true and 0 for false. This can be used with conditional functions.
  • They support integers, decimals and hexadecimals.

Functions​

They also support all the Java Math functions (other than the functions with exact in their name which are useless anyway). You're definitely familiar with functions f(x), but here we will use meaningful names other than f to use functions. In order to understand this document, simply ignore the header description, just scroll down to read the method names. You'll see stuff like int, long, float and double next to the parameter names, they're all basically representing a number. int and long are numbers without decimals, and float and double are numbers with or without decimals. If a function requires an integer, it'll automatically convert into an integer if the passed parameter is a decimal by rounding it.

Some options rarely support equations for time formats. In these equations you can represent the time by surrounding it with square brackets. E.g. lvl * [1 day]

  • Special Functions:

    • time() Gets the current time in milliseconds (since unix epoch).
    • max(a, b, c, ...) Returns the greatest number from all the given arguments.
    • min(a, b, c, ...) Returns the smallest number from all the given arguments.
    • random(min, max) Get a random decimal number between the given minimum and the maximum numbers.
    • randInt(min, max) Get a random integer number between the given minimum and the maximum numbers.
    • whatPercentOf(x, y) Finds X is What % of Y which is equivalent to (x / y) * 100
    • percentOf(x, y) Gets X percent of Y which is equivalent to (x / 100) * y
    • naturalSum(n) Calculates the natural sum from 1 to the given number.
    • reverse(n) Returns the value obtained by reversing the order of the bits in the two's complement binary representation of the specified number.
    • reverseBytes(n) Returns the value obtained by reversing the order of the bytes in the two's complement representation of the specified number.
    • hash(n) Returns the hashcode of the argument.
    • identityHash(n) Returns the identity hashcode of the argument.
    • Conditional functions:
      • eq(var1, var2, var3, var4) Gives var3 if var1 is equal to var2, otherwise it'll give var4
      • ne(var1, var2, var3, var4) Gives var3 if var1 is not equal to var2, otherwise it'll give var4
      • gt(var1, var2, var3, var4) Gives var3 if var1 is greater than var2, otherwise it'll give var4
      • lt(var1, var2, var3, var4) Gives var3 if var1 is less than var2, otherwise it'll give var4
      • ge(var1, var2, var3, var4) Gives var3 if var1 is greater than or equal to var2, otherwise it'll give var4
      • le(var1, var2, var3, var4) Gives var3 if var1 is less than or equal to var2, otherwise it'll give var4

  • They support Bitwise Operations too. This is a more simplified version specifically for Java. However, some of them use a different operator since the operator system in the math evaluator works per a character. They might conflict if used in conditional GUIs.

    • & Bitwise AND operator
    • | Bitwise OR operator
    • ! Bitwise XOR operator ^
    • ~ Bitwise Compliment Operator
    • > Bitwise Binary Right Shift Operator >>
    • < Bitwise Binary Left Shift Operator <<
    • $ Bitwise Shift Right Zero Fill Operator >>>

Practical Math​

When we say a math equation you'll normally expect to see something like the common Quadratic equation or a simpler Polynomial equation such as x + 3 = 10 (which would be x = 10 - 3), but in configs, the core concept is represented a little differently.

Let's say there's an option for the max number of members that can join your kingdom.

max-members: 10

Obviously this doesn't look really fun because a kingdom can only have 10 members no matter how big it is, so for this option, we're going to spice things up a little and use a math expression. We can use the %kingdoms_max_members% placeholder as our variable that the equation is going to be solved for and %kingdoms_lands% as a factor for the equation. Let's say we want kingdoms to have 2 members for every one land that they claimed.

max-members: %kingdoms_max_members% = %kingdoms_lands% * 2

While this looks logical, it's just redundant. If you look at the option name, it's already named max-members, so it's like you're writing

maxMembers = maxMembers = lands * 2

The point is that the option name itself is the variable that we're solving. We can rewrite this as:

max-members: %kingdoms_lands% * 2

There's one issue left, in equations the percent signs % are useless and even cause errors. Because instead they're interpreted as modulus operator ("operators" are things like plus + and multiply *) so you'll have to write:

max-members: kingdoms_lands * 2
Functions​

Now if we wanted to get a little more advanced and say we want to cap this value at 50 members, we can use the function feature.

max-members: min(kingdoms_lands * 2, 50)

Now even if a kingdom claimed 100 lands (100 * 2 = 200) they'll only have 50 max members, because that's what the min() function is doing.
Functions are just like normal math functions f(x) the only difference is that their name is a little more obvious.

min(x, y) function is really simple. It says I'll take both x and y inputs and give you the minimum of the two values as the output. So for example min(3, 1) gives you 1 obviously because 1 < 3
For you math students out there, the equivalent mathematical definition would look like:

min(x, y)={x;x≤y;x>      ymin(x, \: y) = \begin{cases} x & ;\quad x \le \\ y & ;\quad x > \;\;\; y \end{cases}

This is where things get juicier. You could also choose different numbers based on different conditions. Let's say you wanted max-members to be 10 if the kingdom has less than 10 lands, 35 if it has less than 20 lands, 50 if it has less than 30 lands and if none of those conditions match, just give them 100 lands (here we know that they definitely have more than 30 lands based on the previously failed conditions)
The solution to this isn't really pretty, but it is what it is:

max-members: lt(kingdoms_lands, 10, 10, lt(kingdoms_lands, 20, 30, lt(kingdoms_lands, 30, 50, 100))

The math definition for lt function:

lt(x, y, z, u)={z;x<      u;x≥ylt(x, \: y, \: z, \: u) = \begin{cases} z & ;\quad x < \;\;\; \\ u & ;\quad x \ge y \end{cases}



And just like mentioned above, placeholders that return a boolean value (either true or false) will be automatically turned into numbers.

true = 1
false = 0

So for example, if you wanted to use different values depending on whether masswar is running or not, you could use the %kingdoms_masswar_is_running% boolean placeholder and eq() function (which is like lt() but checks if values are equal or not)

eq(kingdoms_masswar_is_running, 1, 10, 20)

This gives 10 if MassWar is running, otherwise if its not running, it gives 20. Notice that the 1 you could also revert this and use 0 (for false)

These functions are conditional functions which you can read more about them above. There's nothing new about them except their functionality of course. In this example, the function just happen to take another function as its parameter. Because they still return a number as their output which can be used as an input for another function and that's all it matters. If you remember, this is an example of function composition. (Holy shit, Math just got useful!)

The plugin provides a lot more operators and functions that you can use, but most of the time you don't need to use them all.

Conditions​

Conditions are used across the plugin to perform an action when a condition is true. Conditions tend to follow the basic syntax for conditionals in most programming languages, specially Java.

An example of what a condition looks like: kingdoms_kingdom_is_pacifist && kingdoms_members > 30
Conditions use placeholders and special operators called logical operators (just like arithmetic operators such as +, -, etc.)

Logical Operator SymbolDescription
!aNegation, meaning !a will be false if a itself is true and vice versa.
a == bChecks if two numbers are equal.
a != bChecks if two numbers are not equal.
a > bChecks if number a is greater than number b.
a < bChecks if number a is less than number b.
a >= bChecks if number a is greater than or equals to number b.
a <= bChecks if number a is less than or equal to number b.
a && bChecks if both conditions are true.
a || bChecks if either conditions are true.

Condition options support placeholders of course, but just like math equations, you have to omit the %s when writing them.
And just like math, you can group conditions together inside parenthesis. (a && b) || c Means that this entire condition will be true only if a and b are true or if c is true.

For example, if you want to check if number x is between 50 and 100, you can write: x >= 50 && x <= 100

note

Usually the keyword else corresponds to the value true in config files. Meaning that if this condition is ever reached, it will always evaluate to their given value, so this condition should be always added as the last branch. You can usually find this in GUI files where an option's appearance changes based on several conditions.

Permission Conditions​

All conditional options also support a special placeholder that checks whether the player has a permission. The format is perm_<permission> where <permission> is the same as the permission text that you use in permission plugins, but instead of being separated by dots, they're separated by underscores. E.g. kingdoms.command.show would be perm_kingdoms_command_show and just like all the other placeholders in condition options, this one doesn't need to be surrounded by %s either.

1.16 Hex Colors​

You can use the new 1.16 custom hex colors. There are various formats to use hex colors. We'll go through them all. Note that all the formats below are case-insensitive.

  • &#<hex> where <hex> is a 6-digit hexadecimal color in the form of RRGGBB e.g. &#658b9e - &#62231A
  • {#<hex>} where <hex> can either be a 3 or 6 digit hexadecimal color in the form of RGB or RRGGBB e.g. {#68e} - {#62231a}
  • {#<color>} where <color> is a predefined color name in chat.yml e.g. {#Navy} - {#Maroon}
  • {#<r>, <g>, <b>} it's the simple RGB format. E.g. {#255, 0, 0} - {#120, 0, 120} The format to do this is &#<hex> the <hex> is a hex 6-character code for RGB colors. You can pick one from here
    Example: &2The &#6bffa5quick {#754646}&lbrown {#c82}&ofox {#255, 0, 0}&mjumped {#Navy}&nover &r&#531b52the &#62231alazy &#404040&kdog
tip

This plugin also offers backwards compatible hex colors with pre-1.16 version. It has a simple built-in system which tries to find the closest color to the given hex color. The result is almost always accurate. This feature works everywhere in Kingdoms plugin that colors are supported.

Item Matchers​

Some options in configs require an item to be matched in order for the item to be used. This includes accepting certain special items for resource points, siege cannon and warp pad fuels, etc.

While their syntax is very similar to the original item options, they don't support all of their options, however they have a few new special values.

Once an option is defined for an item matcher, the item must have that property, otherwise the matching will fail. Other properties that are not defined here will be ignored. Which means if you only define a "name" option, even if the item has lore, enchants, etc, it will only check if the name of the item matches correctly.

How to read this documentation?

name: StringMatcher # The name of the item.
lore: StringMatcher # The lore of the item.
material: StringMatcher # https://hub.spigotmc.org/javadocs/spigot/org/bukkit/Material.html
custom-model-data: Number or Text or Color # The 1.14 custom data models feature.

enchants: [Enchant]
class Enchant
  EnchantmentName: EnchantmentLevelCondition # The level of the enchantment.
end

# NBTName is a dot separated name of the path to the NBT value. The names are something that most plugins will not document
# since they're not used by server admins most of the time. Although you shouldn't be using them either when other options
# are available, they're the most reliable options as it relies on hidden internal data.
nbt: NBTName -> StringMatchers

alias StringMatchers: for Text
  "https://github.com/CryptoMorin/KingdomsX/wiki/Config/#string-matchers"

alias EnchantmentLevelCondition: for Text 
  Condition # With the placeholder "lvl" -> https://github.com/CryptoMorin/KingdomsX/wiki/GUIs#conditional
  or *      # Meaning any level is acceptable as long as the item has the enchantment.
  or Number # The exact number (same as "lvl == number" condition)

Example:

cool-thing:
  name: "REGEX:Awesome Sword \(\d+\)"
  lore: "CONTAINS:best sword"
  material: NETHERITE_SWORD
  custom-model-data: 40065
  enchants:
    SHARPNESS: '*' # You need to surround it with quotes.
    UNBREAKING: 3
    FIRE_ASPECT: 2 <= lvl < 6
  nbt:
    "Kingdoms.Structure": 'siege-cannon'
    "Kingdoms.Mail.Subject": 'CONTAINS:war'

String Matchers​

Used for creating conditions based on a text pattern. If the text (string) matches the pattern, it'll be chosen.

"..."          -> Checks if the text exactly matches the given text. E.g. "Hello" only matches with "Hello" and not "hello"
"CI:..."       -> Checks if the text exactly matches the given text, but in a case-insensitive way. So "Hello" matches "hello" as well
"CONTAINS:..." -> Checks if the text contains the given text. E.g. "CONTAINS:cel" will be matched for "Eggcelent"
"STARTS:..."   -> Checks if the text starts with the given text. E.g. "STARTS:Egg" will be matched for "Eggcelent"
"ENDS:..."     -> Checks if the text ends with the given text. E.g. "ENDS:lent" will be matched for "Eggcelent"
"REGEX:..."    -> You can learn more about RegEx patterns by Googling them.
"REGEX@CI:..." -> RegEx pattern with case-insensitive flag.

Technically RegEx can do anything the other options can do, however they're provided for easier configuration and also performance improvements. You should use the others unless your pattern is complex.

Number Matchers​

Used for creating conditions based on a number range. If the number matches the range, it'll be chosen. (Here ? represents any number)

?         -> Matches a number exactly. So 1 would only match 1.0 and not 1.1
?, ?, ... -> Matches any of the numbers in this list exactly.
<?        -> Matches any number that is less than the given number. "<3" matches -5, -1, 0, 2, but not 3 or 4
=<?       -> Matches any number that is less than or equal to the given number. "<3" matches -5, -1, 0, 2, 3
>?        -> Matches any number that is greater than the given number. ">3" matches 4, 5, 6, but not 3
>=?       -> Matches any number that is greater than the given number. ">=3" matches 3, 4, 5, 6
? < x < ? -> Matches any number thats between the given range. You could use any symbol instead. "x" here is just a literal text. It will be replaced with the number that the pattern will match later. "5 < x < 10" means any number that's between 5 (exclusive) and 10 (exclusive)

Skin Textures​

Some config options expect a player skin texture. For example, turret skulls or GUI options that use a head. Most of these options are recognizable because they're simply named skull. Kingdoms uses a highly advanced system to fetch skulls and you can take advantage of it.

There are several methods that you can choose for acquiring the same skin texture:

  • Username: Simply write the username of the player down. E.g. Notch
  • UUID: Either the online UUID of the player or offline UUID (if your server is cracked) E.g. 069a79f4-44e9-4726-a5be-fca90e38aaf5
  • Textures URL: E.g. http://textures.minecraft.net/texture/e5461a215b325fbdf892db67b7bfb60ad2bf1580dc968a15dfb304ccd5e74db
  • Textures Hash: Same as textures URL without the URL prefix. E.g. e5461a215b325fbdf892db67b7bfb60ad2bf1580dc968a15dfb304ccd5e74db
  • Base64: E.g. eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMTRkY2E5MTE5NjE5ZjEzY2MyZmM3YjZjNjI2Yjk4YWE4Nzk0ODMwN2I1ZDY3MzA1ZWNlNWY5MTA3ODljNTAyIn19fQ==
tip

Use textures URL, textures hash or base64 values when possible as they will improve performance a lot.
You can find them from online websites such as minecraft-heads.com.

E.g. here's a texture that I found on the website:

An image showing custom-heads.com page for one of the heads called 'missing texture'
tip

You can use /k admin skull command to create items and blocks with various values and also get the texture data of specific heads placed in your world.

warning

Reasons that can cause textures to not work:

  • Some clients or mods cause the plugin to not display the textures correctly. You should try running a Vanilla client.
  • When using texture URL/hash or base64 values, there are times when these values expire due to various reasons, and you'd have to update their values manually or find a new texture that's similar.
  • Your server might be getting rate-limited by Mojang API (only happens for usernames/uuid values). This usually happens in shared hosting and also specifically when your server is cracked (as more data needs to be requested). Kingdoms already takes advantage of Mojang's bulk API and the internal server cache and if you reach this limit, there's nothing really you can do about this.
  • You or the server is running without internet connection. This is obviously required to fetch the texture data.
© 2026 KingdomsX. A plugin by Crypto Morin. KingdomsX-Wiki @ a96a96f(Docusaurus)