Placeholders - CryptoMorin/KingdomsX GitHub Wiki

Definition

First let's answer what is a placeholder exactly since the official PlaceholderAPI plugin doesn't even have a technical definition for it. What does it mean?

The word placeholder is a simple English word, however I'll try to explain it in Minecraft context specifically. A placeholder is simply a text that gets replaced by another text in a message.

For example, in this message My kingdom's name is %kingdoms_kingdom_name%. the placeholder %kingdoms_kingdom_name% gets replaced by the name of the player's kingdom. It's like variable x in math that gets replaced by a number. Now you might ask whose kingdom exactly? Well, it really depends, but generally it'd be the kingdom of the person who the message belongs to, and the message usually (but not always) belongs to the person who receives that message.

Context

Placeholders work based on the context that they're used in. This is what determines what the value of the placeholder should be. PlaceholderAPI plugin generally works on player-based context, that means it shows values of placeholders based on which player that placeholder should be evaluated from. In most cases, like mentioned above, the context of the placeholder is the player who views the message, but not always. It can be any player.

For example a simple %kingdoms_kingdom_name% placeholder can be different if used for different players (if they're in different kingdoms). You can test this using the /papi parse <player> <message> command.

Tip

Using the special keyword me for <player> argument is an easy way to evaluate the placeholder as yourself when using the command. This of course means that this won't work in the console. /papi parse me <message>

E.g.

  • /papi parse me My kingdom's name is %kingdoms_kingdom_name%. -> "My kingdom's name is Apothicas."
  • /papi parse pog_fucker69 pog_fucker69 kingdom's name is %kingdoms_kingdom_name%. -> "pog_fucker69 kingdom's name is Ballers."

More advanced plugins such as Kingdoms offer different types of contexts within the plugin itself (not via PlaceholderAPI because it only supports player context) such as a kingdom or a nation as a context. Depending on the type of context used, it can give you information about more placeholders.

Technical Information

If we wanted a more technical definition of a placeholder, in its core placeholders are made out of at least 3 main components.
Format: %<identifier>_<name>%

  • A placeholder is always surrounded by two percent signs. Anything between these percent signs including the percent signs themselves will be replaced by something else.
  • The identifier which is a name to group a list of placeholders together to prevent conflicts. The identifier is always similar to the plugin name. For this plugin, KingdomsX, it's kingdoms
  • The name of the placeholder which is separated by an underscore from the identifier. In our previous example, it was name
    • Sometimes placeholder names are longer than just one word, like %kingdoms_nation_name% which are separated by underscores. Almost all plugins that you use separate names with an underscore too.
    • The only thing all placeholders have in common are these 3 things. Plugins can do whatever they want with the name part. For example, kingdoms has a lot of syntactic features such as placeholder formats, modifiers, functions, etc which I explained further into the wiki.

Note

Certain placeholders don't have underscored separated namespacing (e.g. %mycustomplaceholder%), these placeholders are technically valid by PlaceholderAPI technical definitions but are pretty much discouraged, and there are only a few of them (4 or 5 of them published). Kingdoms currently doesn't support these kinds of placeholders.

What do placeholders do?
Almost 99% percent of the time placeholders only replace text with no side effects, but rarely they'll also have side effects.
Technically placeholders can do things ranging from replacing a simple text to crashing your system.

Who defines placeholders?
Placeholders are defined by plugins, their behavior is also defined by plugins.

What is PlaceholderAPI?
PlaceholderAPI is a Minecraft plugin that allows people to register and use placeholders.
One of the main benefits of this plugin is that it allows you to use placeholders from other plugins in other plugins. This is where the identifier part is important, to avoid placeholder conflicts since there are just so many plugins out there with their own placeholders.

Here's a list of placeholders that you can use.

There are two ways you can use placeholders defined by other plugins with this plugin. Some plugins like Kingdoms don't require any additional setup while other plugins have a separate package that PlaceholderAPI will download for you to use. For more information about downloading packages refer to Expansion Cloud guide.

PlaceholderAPI and most plugins will not yell at you if it finds a placeholder that doesn't know how to translate, it instead leaves it be without replacing it at all. Kingdoms however, will yell at you if it doesn't recognize a placeholder of its own (not the placeholder of other plugins)

I've seen a lot of placeholders with one word before.
If you've seen placeholders like %player%, %amount% %max_amount% before, these are standalone placeholders provided by plugins themselves. PlaceholderAPI doesn't handle these placeholders. For example, KingdomsX has two universal standalone placeholders %player% and %displaynane%. The former just shows the player name and the later shows the player name including any rank (permission plugin) prefix/suffix.


Important

Always remember that if a placeholder is displayed correctly when used in /papi parse me command (e.g. /papi parse me My kingdom is %kingdoms_kingdom_name%) then that means the plugin that you're trying to use the placeholder in has issues, not the plugin that owns the placeholder (unless you're using it within KingdomsX itself). This usually means that you didn't install the placeholder package for the placeholder you're trying to use, or the plugin that you're using placeholders in doesn't support PlaceholderAPI plugin, or the plugin doesn't properly handle placeholders with advanced syntax.
The only exception is the badly formatted placeholders mentioned above.



Kingdoms supports its own placeholders without needing a placeholder plugin. It supports PlaceholderAPI & MVdWPlaceholderAPI. You don't need to download the expansion from Papi ecloud, they're internally implemented into the plugin. The plugin's internal placeholder system is much more optimized than any other placeholder plugin, so it's technically better if you don't install these plugins when you don't need to use them, however the core syntax still remains the same.

Before you get started, as a reminder, you can test all the chat features using the /k admin test command.

Placeholder Modifiers

Kingdoms has a very unique feature for showing numeric placeholders. These features can also be used via PlaceholderAPI.
Placeholder modifiers are a single word used after the placeholder id and before the placeholder name.
Format: %kingdoms_<modifier>_<placeholder>%

Short Placeholders

short A placeholder that is shortened with number suffixes for big numbers to fit in small messages.

Fancy Placeholders

fancy A placeholder that is formatted with the currency format ###.00.

Roman Placeholders

roman A placeholder that is formatted as roman numerals. These are only useful for very small numbers (1 to 4000) if they're used for lower or higher numbers the plugin will error.

Boolean Placeholders

bool Works on placeholders that return either true or false such as %kingdoms_pacifist%. While seeing those words are sufficient to convey the meaning, it's still a little too format, and it's not international. One special language entry is enabled and disabled which is used instead of these values. When the value is true, it uses the enabled language entry and when false, it uses the disabled language entry. By default, enabled is a green ✔ and disabled is a red ❌

Time Placeholders

time Can be used on any number placeholder to turn it into the time formatter as specified inside each language file's time-formatter entry.

Date Placeholders

date Can be used on any number placeholder to turn it into the date formatter as specified inside each language file's date-formatter entry.

Examples:

%kingdoms_short_members% - %kingdoms_fancy_bank% - %kingdoms_roman_rank_priority%

Value Short Fancy Roman
100 100 100 C
12330.34 12.3K 12,330.34 Error
42345234 42.3M 42,345,234 Error

Using these numbers on a time, date or a boolean modifier will give you back nonsensical results because those numbers weren't designed for these modifiers.


Default Placeholders

Most placeholders will depend on a certain context to get their information from. For example %kingdoms_kingdom_name% or %kingdoms_lore% will need you to be in a kingdom to get its name and lore, otherwise there is no kingdom to get its name or lore. For this reason, instead of having the plugin yell at you with a big error, the concept of default placeholders come into play.

If you don't have a kingdom, all the text (string) placeholder will output an empty text (no spaces) and all the number placeholders will give 0 with a few exceptions. These can be changed in config.yml placeholder section.


Placeholder Formats

Normally when you use a placeholder like %kingdoms_kingdom_name% you get the kingdom's name or an empty text if the player doesn't have a kingdom. Now let's say you wanted to decorate this text and do something like [%kingdoms_kingdom_name%] this looks great when the player has a kingdom, but it'll show [] for players with no kingdom.

To solve this issue placeholder formats are defined in config:

formats:
  brackets:
    normal: '[%]'
    default: ''
  parens:
    normal: "(%)"
    default: ''

In order to use these you write %kingdoms_kingdom_name@brackets% (with the format %placeholder@formatname%) In above % is a shorthand for the current placeholder.


Macros

Macros are basically just custom defined placeholders that work only in Kingdoms plugin. They're defined by variables option in config.yml (for historical reasons) and can be used with {$<name>} format, where <name> is the name of the macro which is case-insensitive.

These messages are also translated like normal messages, you can use colors and placeholders in them. This is mostly useful to stop repeating the same thing over and over again and allows you to change its text for multiple places faster by just changing a single option which helps by allowing you to easily follow primary/secondary color theory for your messages.

Another set of macros can be defined per language. Which is under their variables section. Unlike the config.yml macros, these macros do not support conditional options, however both of these macro types can have other macros defined in them. So if you want a conditional macro for each language, define the condition in your config.yml then define the translatable message as separate macros in each language file and use the macro name in the the config.yml macro.

# config.yml
variables:
  enabled:
    enabled: '&8[&2{$enabled_lang}&8]'
  # ^^^^^^^ Note that the condition here used is a variable named "enabled" this is usually the variable defined inside GUIs
  # per option when they're toggled or not. Another way to better demonstrate this would be to define the condition like this instead:
  # 'enabled == true': '&8[&2{$enabled_lang}&8]'
    else: '&8[&4{$disabled_lang}&8]'
  # ^^^^^ this is a keyword that can be used for all conditions in the plugin, which basically
  # means "do this if other conditions failed" Note that the order of conditions are important.
# languages/en.yml
variables:
  enabled_lang: 'Enabled'
  disabled_lang: 'Disabled'

Note that you should give macros defined in config.yml and language files different names as they will override each other.


Color Back Reference

Imagine you have a message like this

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

And let's assume that the possible values for %rank% are [&6Admin] &c and [&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 entire rank text, however 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

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


Placeholder Functions

If you wanted to get the count of a specific type of structures in a land, normally you'd think that the placeholder would look something like %kingdoms_structures_powercell_count%, well that looks like a good guess, but the problem is that placeholders are predefined by the plugin itself. You can't make a new placeholder yourself and since you can make new structure styles yourself, it'd be very inefficient for the plugin to automatically create placeholders for each of these structures.

To solve this issue placeholder functions take some parameters and operate on that parameter instead.
Following our previous example %kingdoms_structures_powercell_count% is actually pretty close to the actual placeholder which is %kingdoms_structures:count style=powercell%

This format might look very weird at first, but it's really easy to understand, so let's take a look at each part.

  • structures is simply the placeholder name, just like all the other placeholders.
  • :count is saying that perform the count function (indicated by the colon :) for this placeholder. Note that the count function is unique to this placeholder and you can't use it with all other placeholders. For example you can't say %kingdoms_members:count% because there's nothing to calculate. %kingdoms_members% placeholder itself returns the calculated result.
  • style=powercell Here style is a parameter of count function and its value is powercell (indicated by the equals sign =)

So the general format for placeholder functions is: %kingdoms_<placeholder>:<function> [parameters]%
Where parameters are zero or more <parameter name>=<parameter value> separated by commas.

Additionally instead of explicitly writing the parameter name, you can separate their values in the position they appear without commas. You can also omit the function name only if the placeholder has one function.
Format: %kingdoms_<placeholder> <parameters>% = zero or more <parameter value> separated by commas. E.g. %kingdoms_structures powercell% - %kingdoms_top 1 max_members%

How do I know the position these arguments appear in? Check the parameters in this guide!



Placeholders

Players

                             Placeholder                              Description
%kingdoms_lang% Gives back the native name of the language that the player is using.
%kingdoms_joined% The time that you joined your kingdom.
%kingdoms_last_donation_time% Last time you donated resource points to your kingdom. This is changed by the option in config.yml -> resource-points -> last-donation-duration
%kingdoms_last_donation_amount% The total donations you made during your last donation time.
%kingdoms_total_donations% Your total resource points donations to your kingdom.
%kingdoms_tax% The amount of money you have to pay to your kingdom.
%kingdoms_land:info name=<placeholder>% Gets the kingdom's information of the current land that the player is standing on. For example to get the resource points of the kingdom which owns the current land, %kingdoms_land:info name=resource_points%. If you wanted to get their name, it would be %kingdoms_land:info name=kingdom_name%, etc.
%kingdoms_claims% Amount of claims the kingdom has. This number can be higher than %kingdoms_claims% in various situations.
%kingdoms_max_claims% Maximum amount of claims a kingdom can have.
%kingdoms_power% Player's power amount.
%kingdoms_has_kingdom% A boolean placeholder if the player is in a kingdom or not.
%kingdoms_is_spy% A boolean placeholder if the player is /k admin spy
%kingdoms_is_sneak_mode% A boolean placeholder if the player is /k sneak
%kingdoms_is_admin% A boolean placeholder if the player is in admin mode.
%kingdoms_is_flying% A boolean placeholder if the player is using /k admin fly
%kingdoms_is_pvp% A boolean placeholder if the player has /k pvp enabled.
%kingdoms_is_invading% A boolean placeholder if the player is /k invade
%kingdoms_rank_node% Your kingdom's rank node.
%kingdoms_rank_name% Your kingdom's rank name.
%kingdoms_rank_color% Your kingdom's rank color.
%kingdoms_rank_symbol% Your kingdom's rank symbol.
%kingdoms_rank_priority% Your kingdom's rank priority. 0 is king and the maximum number is the member rank.
%kingdoms_rank_max_claims% Maximum amount of lands your rank can claim in your kingdom.
%kingdoms_nation_rank_node% Your nation's rank node.
%kingdoms_nation_rank_name% Your nation's rank name.
%kingdoms_nation_rank_color% Your nation's rank color.
%kingdoms_nation_rank_symbol% Your nation's rank symbol.
%kingdoms_nation_rank_priority% Your nation's rank priority. 0 is king and the maximum number is the member rank.
%kingdoms_map_width% Your /k map width which is customizable.
%kingdoms_map_height% Your /k map height which is customizable.
%kingdoms_chat_channel% Your chat channel's node. The chat channel node are the key entry names inside chat.yml
%kingdoms_chat_channel_name% Your chat channel's displayname.
%kingdoms_chat_channel_short% Your chat channel's short (usually a one-lettered) name.
%kingdoms_chat_channel_color% Your chat channel's color.
%kingdoms_distance_from_core% The player's distance (in blocks) from their kingdom's core. The core is either nexus if set, or home otherwise (or the default value if none is set) If the player is in another world, distance-from-core-other-world equation is used instead. This is mostly useful for regulating claiming costs while allowing disconnected claims.
%kingdoms_land_relation% The relationship between the land's owner kingdom and the player's kingdom. WILDERNESS if unclaimed, or SELF, NEUTRAL, TRUCE, ALLY or ENEMY otherwise. This is not intended to be directly shown to players, but to be used inside conditions.

Kingdoms

                               Placeholder                                Description
%kingdoms_kingdom_name% Your kingdom name.
%kingdoms_lore% Your kingdom lore that can be set and removed using /k lore
%kingdoms_kingdom_tag% Your kingdom tag that can be set and removed using /k tag
%kingdoms_top_position% Your kingdom's position in /k top leaderboard.
%kingdoms_members% Your kingdom members count.
%kingdoms_max_members% Your kingdom max members count.
%kingdoms_online_members% Your kingdom online members count.
%kingdoms_offline_members% Your kingdom offline members count.
%kingdoms_member:sum of=math% Gives back the sum of the math operation which supports placeholders applied to each member in the kingdom. (functions aren't supported here)
%kingdoms_kingdom_flag% Kingdom flag URL for Dynmap.
%kingdoms_kingdom_color% Kingdom HTML hex color code.
%kingdoms_king% Your kingdom king name.
%kingdoms_might% Your kingdom might count.
%kingdoms_since% The date your kingdom was created in year-month-day format.
%kingdoms_home% Your kingdom home location.
%kingdoms_nexus% Your kingdom nexus location.
%kingdoms_lands% Your kingdom land count.
%kingdoms_avg_lands_distance% The average distance of your lands from your nexus or home (in order or 0 if none is set) This placeholder is measured in chunk distance (not block distance) and is mostly useful for taxes.
%kingdoms_kingdom_power% Your kingdom's total power amount.
%kingdoms_max_lands% Kingdom max land count.
%kingdoms_shield_since% Time that you activated your kingdom shield.
%kingdoms_shield_time% Your kingdom shield duration.
%kingdoms_shield_time_left% Kingdom shield time left.
%kingdoms_resource_points% Your kingdom's resource points.
%kingdoms_bank% Kingdom bank money.
%kingdoms_ranks% Kingdom rank count.
%kingdoms_kingdom_is_pacifist% A boolean placeholder, true if pacifism mode is enabled for this kingdom, otherwise false.
%kingdoms_kingdom_is_permanent% A boolean placeholder if the kingdom is permanent.
%kingdoms_kingdom_is_hidden% A boolean placeholder if the kingdom is hidden.
%kingdoms_kingdom_home_is_public% A boolean placeholder if the kingdom's home is publicly available to everyone.
%kingdoms_kingdom_requires_invite% A boolean placeholder if the kingdom requires an invitation from the players in order to join.
%kingdoms_mails_total% The total number of mails that your kingdom has received and sent.
%kingdoms_max_lands_modifier% Extra lands that are given to the kingdom by admins from the /k admin maxLandModifier command.
%kingdoms_server_kingdom_tax% The amount of money your kingdom has to pay to server for taxes.
%kingdoms_nation_tax% The amount of money your kingdom has to pay to your nation for taxes.
%kingdoms_kingdom_tax% The amount of money your kingdom has to pay for taxes. This is the same as %kingdoms_server_kingdom_tax% if the kingdom is not in a nation, or %kingdoms_nation_tax% if the kingdom is in a nation.
%kingdoms_structures_total% Total number of structures in kingdom.
%kingdoms_turrets_total% Total number of turrets in kingdom.
%kingdoms_structures:count style=<name>% Total number of of a specific structure in the kingdom. E.g. %kingdoms_structures powercell%
%kingdoms_turrets:count style=<name>% Total number of of a specific structure in the kingdom. E.g. %kingdoms_turrets arrow%
%kingdoms_total_war_points% Peace Treaties Addon The sum of all the war points a kingdom has for other kingdoms.
%kingdoms_kingdom_upgrade:level type=name, of=name% Gets the upgrade level of one of the kingdom's upgrade. The type parameter can be misc, powerup or champion and the of parameter is the name of the upgrade such as DAMAGE_BOOST or ANTI_EXPLOSION. A general rule of thumb is that whatever name you see in the config, uppercase all the characters and use _ instead of -.

Nations

                               Placeholder                                Description
%kingdoms_nation_name% Your kingdom's nation name.
%kingdoms_nation_kingdoms% The amount of kingdoms that are in your nation.
%kingdoms_nation_spawn% Your kingdom's nation spawn location.
%kingdoms_nation_bank% Kingdom bank money balance.
%kingdoms_nation_since% The date your nation was created in year-month-day format.
%kingdoms_nation_resource_points% Nation resource points.
%kingdoms_nation_might% Nation might rank.
%kingdoms_nation:capital get=<placeholder>% Gets information about the capital kingdom of the nation. E.g. to get the capital kingdom's name %kingdoms_nation:capital get=name%
%kingdoms_nation_tax% Nation's tax for kingdoms.
%kingdoms_server_nation_tax% The amount of money your nation has to pay to server for taxes.
%kingdoms_nation_shield_since% Time that you activated your nation shield.
%kingdoms_nation_shield_time% Your nation shield duration.
%kingdoms_nation_shield_time_left% Nation shield time left.
%kingdoms_nation:sum of=<placeholder>% Used to sum any number property of the nation's kingdom members. For example to sum all the resource points that are in this nation, (not including the resource points of the nation itself) %kingdoms_nation:sum of=resource_points%
%kingdoms_nation_zone:info name=ph% Gets information about the nation zone that the player is standing on. E.g. %kingdoms_nation_zone:info name=kingdom_name% This information is sometimes ambiguous, because multiple nation zones can overlap.

Relational Placeholders

Not many plugins support relational placeholders. They can only be used in other plugins if you have PlaceholderAPI plugin installed, however like normal placeholders, they'll work internally in Kingdoms plugin without PAPI installed. Relational placeholders are placeholders that require two players. This will check the kingdom relation between them to make new special placeholders.
If you're using these placeholders from PlaceholderAPI you need to add rel_ at the beginning, so the format would be %rel_<placeholder>%

Placeholder Description
%kingdoms_relation% The relationship between two players/kingdoms. SELF, NEUTRAL, ALLY, TRUCE or ENEMY
%kingdoms_relation_name% The relation name defined in your language file (relations -> <name> -> name path).
%kingdoms_relation_color% The relation color defined in relations.yml between your kingdoms.
%kingdoms_war_points% Peace Treaties Addon The War Points a kingdom has against the other kingdom.

Server-wide Placeholders

These placeholders can be used with no context. They don't require a player, kingdom, nation and etc.

                                      Placeholder                                       Description
%kingdoms_masswar_is_running% This is a boolean placeholder
%kingdoms_masswar_time% If Mass War is running, this gives the time left until the event ends and if it's not running, it gives the time before the event begins.
%kingdoms_top:at pos=<position>, of=<placeholder>% The placeholder used to retrieve one of the kingdoms that corresponds to what /k top returns. <position> starts from 1 and <placeholder> is simply the placeholder's name as you'd normally use excluding percents and kingdoms prefix. For example, %kingdoms_top:at pos=5, of=name% (or %kingdoms_top 5 name%) would show %kingdoms_name% as if it was used for the 5th kingdom. Use this placeholder sparingly as it can impact performance when used a lot.
⚠️ **GitHub.com Fallback** ⚠️