Config

Plugin configuration files are split into separate files to organize options. The main config is config.yml for sure.
All the config files are automatically reloaded, please read here.
Config files are not translatable but the language file and all the GUIs are.
Config files don't automatically add new options for outdated configs, they use the default option if an option is missing.

Kingdoms configs don't support advanced YAML features such as explicit tags, directives, explicit document start and ends, and a few others. 99% of the time, people don't even bother which these features when dealing with configuration files, so there's no issue.

All the configs except GUIs (due to the reasons specified in the following link) support auto config updates.

Most of the config options are explained in their config, however here we'll take a look at some basic and advanced features that Kingdoms plugin allows you to use for the config options.

• Setting a message option to ~ or null will not send that message, if you set it to "" it'll still send an empty line.
• 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.
• Sounds are parsed using the [~]<sound>, [volume], [pitch] format. All the Minecraft sounds can be found here. Minecraft volumes start from 0.0 to 1.0 Any number higher than that will just increase the radius the player can hear the sound from, normal is 1.0. Pitch starts from 0.5 to 2.0 normal is 1.0 You can also test this by using the /k admin testSound command. Where ~ is also an optional prefix to play the sound at the player's location rather than to the player only so other nearby players can hear it too.
• 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.
  • 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 see both of them in this image:

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.

---

Math Equations

• Note that these rules apply to all the math equations in any configs.
• Supports all the mathematical operators such as +, -, /, *, %, (), ^, etc...
  • / You should know this one! It's the division operator. Fractional numbers!
  • % in computers mean 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 mean multiply
  • ^ in computers usually refer to bitwise operators, but it exponentiates here. E.g. 2^3 = 2³ = 2 * 2 * 2 = 8
  • 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
• 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.
• You can test your equations with the /k admin evaluate command.
• They support integers, decimals and hexadecimals.
• 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:
  • 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.
  • 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 >>>

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. So how would we write this? 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

if this was on paper, so the important point is that the option name itself is the variable that we're solving. We can rewrite this as:

max-members: %kingdoms_lands% * 2

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

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.

---

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

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 hex color. It'll give you a white color if it's not possible to approximate a solid color from the given hex color.

---

Messages

Plugin supports Complex Messages, Hover Messages, or Raw JSON Text messages are messages that use modern Minecraft messaging features which allows you to do different things when hovering on a text in a message. In addition to hover features, complex messages have a few more useful functions that we will talk about in a moment.
This feature doesn't work on Bukkit servers. It only works on Spigot and forks of Spigot such as Paper.\

You can now use hover:{} anywhere in the message. The default format for hover is hover:{Chat Message;Hover Message (Lore);Action} they all support color codes and placeholders inside them. Note that every space (or any other character) before and after the separators ; are also displayed in the message (except for the Action, read below for more details)!

• Chat Message: The message shown in the chat like the normal messages.
• Hover Message: The message shown when you hover on Chat Message in the chat using your cursor.
• Action: The action performed when you click on Chat Message in the chat.
  • Commands: Execute a command or send a message in chat. Not using a / slash will send a chat message instead as if the player sent this message normally themselves.
  • Suggestions: Put the text in player's chat box. Instead of / you have to use |
  • URL: Open a link in the player's browser (with their consent after they've been prompted by a message on their screen). Instead of / you have to use @

Example: &2Hey hello hover:{&cthis;&2Jeff;Hello Jeff!} &2is my name.\nCome hover:{&emeet;&2Click To Meet\nmaybe not.;/tp Jeff} &2me here. hover:{&lphone number;&2Click to copy;|911} &2my hover:{&9website;&cClick To Open;url:https://www.nasa.gov/}

There's another form of complex messages supported in the language file. If one of the language entries is a section instead of just text, you'll be able to benefit from several features:

# before
message-entry: "Hello I'm a normal complex message"

# after
message-entry:
  # Sound played to the player when the message is sent.
  sound: BLOCK_NOTE_BLOCK_BASS, 1, 1

  # Actionbar shown to the player for a short period of time ~3 seconds
  actionbar: "I support colors and placeholders too."

  # Refer to titles section below to learn how these work.
  titles:
    title: "I support colors and placeholders as well"
    subtitle: "Me too"
    fade-in: 30
    stay: 15
    fade-out: 30

  message: "I'm a complex message, but notice how I don't need the @ anymore to be counted as one"