Variables

A variable (placeholder) is a message in brackets {} (this now also supports percents %%), which is replaced by the actual data. Example: {player} is replaced with the player name. ChatControl supports thousands of placeholders and you can even create your own ones!

Note: When using LuckPerms, to avoid double prefixes, we suggest you use {luckperms_prefix} from PlaceholderAPI plugin instead of {pl_prefix} from Vault.

For a tutorial on variables in variables/ folder, see JavaScript Variables.

TIP: Use "/chc info variable " to test different variables in a demo message.

Warning: We may lowercase placeholders for performance reasons. If your PlaceholderAPI contains a variable with Uppercased Letters that doesn't work, try writing it in all lower space: Such as {VotingPlugin_alltimetotal} to {votingplugin_alltimetotal}

Proxy Variables

Notice: These variables are taken from player's Bukkit server and work on Proxy.

Variable Name	Description
{player_name}	Dude's name.
{nick} or {player_nick}	Player's nick (or name if not set).
{player_group}	Player's group from permission plugin installed on his server.
{player_prefix}	Player's prefix from the server he is on.
{player_server}	Player's server he is on.
{player_afk}	Returns true or false if player is AFK.
{player_ignoring_pms}	Returns true or false if player is ignoring private messages.
{player_vanished}	Returns true or false if player is vanished.

DiscordSRV variables

Discord variables are limited because we can't get the player instance, but you can use many PlaceholderAPI variables that support it, including:

Variable Name	Description
{username}	Player's name, called from DiscordSRV plugin.
{name}	Player's "effective" name, calling DiscordSRV plugin.
{player_nick}	Player's nick (or name if not set).
{channel}	Channel's name.
{top_role}	Player's highest role.
{top_role_initial}	The initial of player's top role.
{top_role_alias}	The alias of player's top role.
{all_roles}	All roles of the player.
{reply}	The reply player if player is replying to a message, or empty.

Native Variables

By default we support the following variables almost everywhere. If you need more, install PlaceholderAPI or MVdWPlaceholderAPI.

Sometimes we provide more variables than the ones above, such as {message} when there's a message to replace. We can't enumerate them all here because they are different for channels etc., but please see the config files and you'll see them easily.

Variable Name	Description
{player} or {player_name}	Dude's name.
{sender}	The name of the message sender you can use in Receiver_Condition variables in your formats (If you use {player} in that keys it will return the message receiver's name and not the sender's).
{tab_name}	Player's list name.
{display_name}	Player's display name.
{nick} or {player_nick}	Player's nick, or name if no nick.
{player_prefix}	Vault plugin: Player's prefix.
{player_suffix}	Vault plugin: Player's suffix.
{player_group}	Vault plugin: Player's group name from your permissions plugin.
{player_primary_group}	Vault plugin: Player's primary permission group.
{chat_color}	Get player's chat color, if set, or empty. This formats the message.
{chat_color_name}	Get player's color name, such as 'red', if set, or return 'none'.
{chat_color_letter}	Get player's color code, such as '&c' for red, or return ''.
{chat_decoration}	Get player's decoration, if set, or empty. This formats the message.
{chat_decoration_name}	Get player's decoration name, such as 'bold', if set, or return 'none'.
{chat_decoration_letter}	Get player's decoration code, such as '&l' for bold, or return ''.
{channel_range}	Returns the current player channel's chat range (if defined - non-decimal) or none if the channel has no defined range.
{receiver_prefix}	Shows the prefix of the receiver in private messages. Feature is limited on proxy due to the nature of parsing variables cross network.
{town}	Towny plugin: Player's town, if any.
{nation}	Towny plugin: Player's native, if any.
{faction}	Factions, FactionsUUID or FactionsX: Player's faction, if any.
{player_vanished}	Returns true or false if the player is vanished.
{player_newcomer}	Returns true or false if the player is a Newcomer.
{country_code}	MAY BLOCK THE MAIN THREAD: Looks up player's country code from his IP.
{country_name}	MAY BLOCK THE MAIN THREAD: Looks up player's country name from his IP.
{region_name}	MAY BLOCK THE MAIN THREAD: Looks up player's region name from his IP.
{isp}	MAY BLOCK THE MAIN THREAD: Looks up player's isp from his IP.
{world}	Player's world name. Multiverse-Core aliases are supported.
{health}	Player's health.
{location}	Player's full location.
{x}, {y} and {z}	Player's location points.
{ip_address}	Player's IP address.
{sender_is_player}	Return true/false depending if player is not console and not discord.
{sender_is_console}	Return true/false depending if player is console.
{sender_is_discord}	Return true/false depending if player is from Discord.
{player_has_nick}	Return true/false if the player has a custom nick.
{date}	A time formatted according to your Date_Format in settings.yml
{date_short}	A time formatted according to your Date_Format_Short in settings.yml
{date_month}	A time formatted according to your Date_Format_Month in settings.yml
{last_active}	Return the last active player date using Timestamp_Format from settings.yml.
{last_active_elapsed}	Return the time in Xd Xm Xs since player's last join.
{last_active_elapsed_seconds}	Return the time in seconds since player's last join.
{chat_line}	A simple chat line.
{chat_line_smooth}	A smooth chat line.
{server_name}	The "server-name" key from server.properties, or if you use PlaceholderAPI with the server extension, from its file.
{server_version}	The full server version such as 1.21.2
{nms_version}	(Advanced) The NMS package number such as 1_20_R3 (Empty for 1.20.5+ on Paper.)
{label}	Return our main command label.
{prefix_plugin}	Return the Prefix key from your settings.yml
{prefix_info}	Return the info prefix from your localization.
{prefix_success}	Return the success prefix from your localization.
{prefix_warn}	Return the warn prefix from your localization.
{prefix_error}	Return the error prefix from your localization.
{prefix_question}	Return the question prefix from your localization.
{prefix_announce}	Return the announce prefix from your localization.
{data_X}	Returns a custom variable. This is set in rules with data-related operators, see Rules. See rules/chat.rs for example (search for @bot name demo rule).

PlaceholderAPI-Compatible Variables

The variables below can be used with the PlaceholderAPI plugin anywhere, or, remove "chatcontrolred" from them to use them in our plugin.

Variable Name	Description
{chatcontrolred_label_channel}	The first command alias that triggers channel command, such as "/channel". This is set in settings.yml.
{chatcontrolred_label_ignore}	The first command alias that triggers ignore command.
{chatcontrolred_label_mail}	The first command alias that triggers mail command.
{chatcontrolred_label_me}	The first command alias that triggers me command.
{chatcontrolred_label_mute}	The first command alias that triggers mute command.
{chatcontrolred_label_motd}	The first command alias that triggers motd command.
{chatcontrolred_label_tag}	The first command alias that triggers tag command.
{chatcontrolred_label_reply}	The first command alias that triggers reply command.
{chatcontrolred_label_spy}	The first command alias that triggers spy command.
{chatcontrolred_label_tell}	The first command alias that triggers tell command.
{chatcontrolred_label_toggle}	The first command alias that triggers toggle command.
{chatcontrolred_player_is_spying_<channel>}	Returns "true" or "false" if the player is spying the given channel.
{chatcontrolred_player_is_spying_<mode>}	Returns "true" or "false" if the player is spying the given mode. Modes available: chat, command, private_message, mail, sign, book and anvil.
{chatcontrolred_player_in_channel_<channel>}	Returns "true" or "false" if the player is in the given channel.
{chatcontrolred_channel}	Returns the player's current channel he's writing into.
{chatcontrolred_player_channel_mode_<channel>}	Returns the channel mode ("read" or "write") or "none" if player has no such channel.
{chatcontrolred_nick}	Return player's nick, or player's name if not set.
{chatcontrolred_prefix_tag}	Return player's prefix set with /tag, or "" if not set.
{chatcontrolred_suffix_tag}	Return player's suffix set with /tag, or "" if not set.
{chatcontrolred_reply_target}	Returns "none" or the /reply player if any.
{chatcontrolred_player_newcomer}	Returns "true" or "false" whether or not the player is newcomer. Newcomer limits are set in settings.yml.
{chatcontrolred_is_ignoring_<mode>}	Returns "true" or "false" if the player is ignoring the given mode via /toggle command. Modes available: mail, announcement, me, pm, chat, soundnotify.
{chatcontrolred_data_<key>}	Returns a custom variable. This is set in rules with data-related operators, see Rules. See rules/chat.rs for example (search for @bot name demo rule).

The [#flpc-i] and [#flpc-1] variables

Those special variables help you catch the color of the message and the restore it back. This is useful such as in rules, where you might want to create a rule which colorizes one word only, and then restore back to the original color of your message:

match house
then replace [#flpc-i]&chouse[#flpc-1]

In this rule we find the word "house" in chat and replace it with &chouse to make it red. If the chat message was in green, we catch the old color automatically using [#flpc-i] and set it back into [#flpc-1] so that you don't end up having all words after "house" being red, but they get restored to being green automatically.

The '+' Plus Letter And Trailing Space Removal

Everyone knows how frustrating is to end up with trailing spaces if you want to show a factions prefix but a player doesn't have any faction [VIP] ⠀kangarko: Hi!.

That's why we made all variables support the "+" operators in front, or at the end of them. Even PlaceholderAPI variables are supported.

By adding the + at the end or the start of a variable, such as "{player_group+}", we only add an extra space after it if there's an actual variable set. If there is no variable, you will not end up with a trailing space.

Adding New Variables Via API

You can just hook into PlaceholderAPI and use their API to add placeholders, including relational placeholders: https://github.com/PlaceholderAPI/PlaceholderAPI/wiki/PlaceholderExpansion

We will support them automatically in the plugin, such as in formats/: