Config

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.
• 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.
• 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.
• 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 >>>

---

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
  Note: Hex colors aren't supported for Windows terminal. Only Spigot can fix this.

---

Complex Messages

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.
To send a complex message, you must add COMPLEX: at the beginning of that message. This is required so the plugin can know this message must be parsed using an advanced parser, which means if it's not specified, the plugin can handle the message normally for more performance.
After specifying the tag, 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 url:

Example: COMPLEX:&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/}

Complex messages also have a feature called color backreferences.
Imagine you have a message like this

&2Added %rank% &2to player &6%player%

Possible values for %rank% are: %rank% = [&6Admin] &c %rank% = [&eModerator] &e

What if you wanted to change %player% color according to the last color captured by %rank%? In this case, it'd be either &c or &e. You can't simply do %rank%%player% because %rank% would be replaced by the enter rank text, we only want the last color.

That's where color backreferences will be useful.

&2Added %rank% &2to player {%rank% & -1}%player%

{%rank% & -1} will be translated to the last color captured by the %rank% placeholder.
E.g. if %rank% is &8[&cAdmin&8] &6 using this special format gives you &6

The syntax for a color backreference declaration is {%placeholder% [& index]} - Where %placeholder% is simply the placeholder name, you should not put any space between { and the placeholder. - Where index is an optional position that the color should be retrieved from. Omitting this option (e.g. {%rank%}) is the equivalent of {%rank% & -1} which gives you the last color.
The position can be either positive or negative. Positive positions means that the search should start from the beginning of the placeholder while negative positions mean that the color search should start from the end of the string.

Note that a color in this case is considered a group of color codes that when used together can change how the message is displayed. color here also includes formatting codes (&l, &n, &k and etc)
So for example in a message like if %msg% placeholder value is &2&lHello &c&3world doing {%msg% & 1} will give you &2&l not &l
This is because when &2 is mixed with &l it preserves the previous code (&2) and make a new format out of it. In this case a bold green text, but doing {%msg% & 2} on the same message gives you &c and not &c&3 this is because &3 does not preserve &c and it completely changes the color of the text, thus making the previous code unnecessary, although it's questionable why someone would format their messages in this way...

You can test all the chat features using the /k admin test command.

---

Main

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.

Language File

The default language file is en.yml which is not saved in the plugin, it's generated automatically.
Language files automatically add new entries to their list, however they don't remove any old ones. If a translated language file is missing an entry, it'll copy one from the original (English) version into the file instead. Language entries don't have any explanation, they're mostly easy to understand. If you couldn't find the usage for an entry, you can always ask.

The language entry format for all the commands are commands -> [groups...] -> <name> where [groups...] are the main command names of that command and <name> is the main command name of that command. The group and names are explained in the permissions section.

All the language entries support:

• Chat Colors and 1.16 Hex Colors
• Line Breaks \n (It also keeps the color for the next line.)
• Complex Messages (90% of the non-GUI messages)
• Internal & External Placeholders (for external placeholders you need PlaceholderAPI)
• Complete Removal (by setting it to an empty text string: '' or "")
• If prefix option is enabled in config, you can use NOPREFIX| at the beginning of a message to exclude it, or if the option is disabled, you can use PREFIX| to use the prefix for that specific message.

All community translations are welcomed. You can also improve existing translations. You can translate the language file and all the GUIs located in the guis folder, but plugin configs are not translatable.
Here are some rules when translating the plugin. These rules apply to GUI translations as well.

• Obviously don't just drop them in Google Translate and paste them back to the file. Translate them manually.
• You shouldn't change how the sentences are phrased and add or remove a part of the description unless it makes it easier to understand in that particular language.
• You can change the colors, but do not use 1.16 hex color codes.
• You shouldn't change the plugin prefix. Anywhere that the name Kingdoms is used that is referring to the plugin and not the name itself, shouldn't be translated.
• Make sure to validate your files.
• You can change the GUI design as long as it has all the functional options used.
• You can give credits, but only at the beginning of the file. No IPs are allowed unless you have a domain that redirects to an appropriate website with SSL certificate (HTTPS).
• You can add explanations anywhere in the file if you want.

After translating your language file, place your translated file in the plugin's folder. The file's name should be the same as the option below without the .yml file extension. Some of these language files are outdated. Standard way of naming this is to follow IETF language tags from IETF use ISO-639-1 codes. If you can't find it, or don't feel like it, don't bother.
If you translated the plugin, you can contact me and I'll add it to the plugin.

All the language files are translated by the community. They're not guaranteed to be 100% accurate or complete. Developers and translators are not responsible to update the language files. Latest available translations can be found here.

---

GUIs

Each GUI uses an entire YAML file to parse its settings from the guis -> <lang> folder.
Unlike language files, they don't automatically add new options since their 100% customizable.
If your conditional GUI options are not changing that means your Java version is JRE instead of JDK.

Main Options

• title: The title of the GUI.
• rows: The rows of the GUI, it can be from 1 to 9
• type: If no rows is specified, a type will be used. You can see all the types here.
• sound: Sound when the GUI opens. Format is sound: <type>, [volume], [pitch] You can also use default to use the default sound specified in config.
• message: Message when the GUI opens.
• commands: Commands executed when the GUI opens.
• interactable: Interactable slots of this GUI. If it only contains one slot and that number is lower than zero, then the list will act as a blacklist.
• disallow-creative: true or false. Whether this GUI can be opened in creative mode or not.

Item Options

These options are used under the item names which are under options entry of GUIs. Option names are really important for some GUIs. They define what an option does from the code. If an option name doesn't have any actions attached to it, it'll not do anything when clicked on. This is where conditional GUIs come to use.
All the text options in items support color codes and placeholders.
Some people might find the following information hard to understand. If you have a question for any options below, ask me.

• name: The name of the item.
• lore: The lore of the item. You can use this differently. Either by using yaml lists or using strings and \n. You can also use \n if you're using a list.
• material: The material of the item.
• amount: The item amount.
• damage: The item's damage (durability).
• skull: The item's skull texture. This can be a player's name, UUID, a textures.minecraft.com link or a Base64. The recommended value is always Base64 as it doesn't require encoding and connections. A good website to get skull textures from that also supports Base64 is minecraft-heads.com. The value preference for this option from best to worst is as follows: base64 -> textures link -> UUID -> Name Note that you need to set the material to PLAYER_HEAD for this to work. You can use %player% to use the skull of the current player who opened the GUI.
• unbreakable: true or false. Whether this item should have an unbreakable attribute.
• model-data: The 1.14 custom data models feature.
• enchants: Item's enchantments. It's a yaml entry with the entry keys as the enchantment name and the entry values as the enchantment level. Example:

enchants:
  ARROW_FIRE: 2
  DURABILITY: 3

• flags: The item flags. Item flags in Minecraft are badly named, so it might not do the exact thing you're looking for. In this case, you might want to try other flags. Example:

flags: [HIDE_ATTRIBUTES, HIDE_POTION_EFFECTS]

• attributes: Item attributes are the numbers shown in the bottom of the item's description under the item's lore. You can hide these with item flags but you can also change them with attributes.
  Format:

attributes:
  Attribute: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/Attribute.html
    name: https://minecraft.gamepedia.com/Attribute
    amount: The modifier's number.
    operation: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/attribute/AttributeModifier.Operation.html
    slot: HEAD - CHEST - LEGS - FEET - HAND - OFF_HAND

• sound: The sound played when this item is clicked.
• commands: The commands executed when this item is clicked.
• message: The message sent to the player when this item is clicked.
• can-take: true or false. If this item can be taken out of the GUI by the player.
• slots/posx,posy/slot: The position(s) of the item. When using slot, you need to count the slots of the GUI from top to bottom and left to right and then subtract that number by one. When using posx and posy You just need to know the exact position in the GUI. When using slots it's the same as slot, but you can put the item in multiple slots with the same properties and actions. slots: [34, 35, 36, 37]
• patterns: Only works if the item is a banner. It's a section list with format: Pattern as the key and Dye Color as the value.
• color RGB color used for leather armor colors. Format: r, g, b
• spawner Entity type used for spawner blocks.
• projectiles A list of items for charged projectiles of a crossbow. The serialization for these items follow the same rules as these.
• effects The effects used for suspicious stew. A config list.
• color and pattern-color Dye Color used for tropical fish and pattern used for the pattern.
• power The power of a firework.
• firework
  • flicker true or false of the firework should have flicker.
  • trial true or false of the firework should have trial.
  • colors The RGB colors that this firework can have.
  • fade-colors The fading colors of this firework.
  • type The firework type.

Conditional

GUI items use a simple logical-relational evaluator to change item appearance depending on a condition. You can change the entire item property by using condition option and putting each under a custom condition name. You can also use conditions for sounds, slots and messages.

Currently this evaluator only supports numbers.
Supported operations:

Symbol	Description
==	Checks if two numbers are equal. (You could also use =, but == is conventional.
!=	Checks if two numbers are not equal.
>	Checks if a number is greater than a number.
<	Checks if a number is less than a number.
>=	Checks if a number is greater than or equals to a number.
<=	Checks if a number is less than or equal to a number.
&&	Checks if both conditions are true.
||	Checks if either conditions are true.

Example:

options:
  hello:
    # Note that "activated" and "else" are just normal names that have no effects.
    # The last condition which is always used if none of the conditions above it were met, is named "else" most of the times.
    activated:
      condition: "%kingdoms_members% > 10 && %kingdoms_members% < 20"
      name: "&2Activated"
      material: GREEN_WOOL
    else:
      # We use true here because if the previous condition wasn't met,
      # there is no need for us to use "%kingdoms_members% <= 10" here.
      condition: true
      name: "&4Disabled"
      material: RED_WOOL
      sound:
        "%kingdoms_members% <= 5": BLOCK_ANVIL_FALL
        "true": BLOCK_ANVIL_BREAK