Wiki Release: 2026.09.8 · UltimateKoth: 2.26.1 · Documentation branch: 2 · UltimateKoth

UltimateKoth placeholders#

UltimateKoth exposes placeholders for player statistics, active and upcoming events, rankings, Koth state, capture progress, loot, schedulers, warps and administration interfaces.

This page separates the placeholders by the context in which they are normally used. The identifier spelling shown here is intentional. For example, formated is the spelling used by the plugin and must not be changed to formatted.

How placeholder context works#

UltimateKoth has two useful ways to resolve Koth-specific data:

Current-context placeholders such as %ukoth_name% are used by UltimateKoth internally in GUI, language and event formats. When PlaceholderAPI supplies a player and that player is currently associated with a Koth region, UltimateKoth can also resolve the Koth from that player context.
Named external placeholders use {KOTH_NAME} to explicitly select a Koth, for example %ukoth_{Castle}_name%. This is the recommended form for PlaceholderAPI scoreboards, holograms, TAB, menus and other external plugins when you need data from a specific Koth.

The name inside {...} is the Koth identifier configured in UltimateKoth, not its colored display name.

%ukoth_{Castle}_name%
%ukoth_{Castle}_status%
%ukoth_{Castle}_timeleft%

If the named Koth does not exist, there is no matching Koth context to resolve.

Player, global and event placeholders#

These placeholders do not require a Koth name in normal use.

Placeholder	What it returns
`%ukoth_player%`	Name of the player supplied to the placeholder request.
`%ukoth_player_group%`	Group/clan/team name returned by the active group integration for the player. If no group is available, UltimateKoth uses its configured no-group text.
`%ukoth_player_single_win_amount%`	Number of individual Koth wins recorded for the player.
`%ukoth_player_group_win_amount%`	Number of group Koth wins recorded for the player.
`%ukoth_player_owner_amount%`	Number of Koths currently owned by the player.
`%ukoth_key%`	The configured default Koth key icon in UltimateKoth's material format.
`%ukoth_usekey%`	Whether the global key-loot system is enabled.
`%ukoth_next_name%`	Name of the next scheduled Koth event.
`%ukoth_next_time%`	Time information for the next scheduled Koth event.
`%ukoth_active_now%`	Current active-event information in the raw/non-formatted form used by the event manager.
`%ukoth_active_now_formated%`	Current active-event information using the plugin's configured formatted output.
`%ukoth_starter_state%`	Whether the Koth starter system is currently enabled.
`%ukoth_mode_amount%`	Number of Koth modes currently registered by UltimateKoth.

Timezone#

Use:

%ukoth_timezone:TYPE%

Supported TYPE values are:

Type	Result
`LOCAL`	Configured scheduler timezone ID.
`ZONE`	Java ZoneId representation of the configured timezone.
`TIME`	Current date/time rendered using the configured scheduler timezone.

Examples:

%ukoth_timezone:LOCAL%
%ukoth_timezone:TIME%
%ukoth_timezone:ZONE%

Ranking placeholders#

UltimateKoth can expose both a preformatted ranking line and individual raw ranking fields.

Formatted top#

%ukoth_top:TYPE:TIME:NUM%

TYPE accepts:

TOPPLAYER — player ranking.
TOPGROUP — group ranking.

TIME accepts:

ALL
DAILY
WEEKLY
MONTHLY
YEARLY

NUM is the ranking position, starting at 1.

Examples:

%ukoth_top:TOPPLAYER:ALL:1%
%ukoth_top:TOPGROUP:MONTHLY:3%

The formatted result uses UltimateKoth's language entry for the top format, so the final text can follow your server language/style configuration.

Raw top fields#

%ukoth_unformated_top:FIND:TYPE:TIME:NUM%

FIND accepts:

NAME — returns the stored ranking name/key.
AMOUNT — returns the recorded win amount.

TYPE, TIME and NUM use the same values as %ukoth_top:...%.

Examples:

%ukoth_unformated_top:NAME:TOPPLAYER:ALL:1%
%ukoth_unformated_top:AMOUNT:TOPGROUP:WEEKLY:2%

Use the raw form when another plugin needs the name and amount in separate placeholders instead of UltimateKoth's already-formatted ranking line.

Koth-specific placeholders#

The following placeholders describe one Koth. They are used extensively by UltimateKoth's GUI and language files. For PlaceholderAPI, use the named form described later when you want to target a specific Koth reliably.

Identity, position and basic state#

Placeholder	What it returns
`%ukoth_direction_relative%`	Relative direction from the requesting player to the Koth coordinate. If the player and Koth are in different worlds, UltimateKoth uses its configured different-world message.
`%ukoth_icon%`	Koth icon in UltimateKoth's serialized/material format. Uses the default icon when the Koth has no custom icon.
`%ukoth_name%`	Koth display name, including its configured color formatting.
`%ukoth_id%`	Internal/plain Koth identifier.
`%ukoth_cuboid_area%`	Volume of the Koth cuboid region.
`%ukoth_world%`	World containing the Koth region.
`%ukoth_coord_x%`	Resolved Koth coordinate X.
`%ukoth_coord_y%`	Resolved Koth coordinate Y.
`%ukoth_coord_z%`	Resolved Koth coordinate Z.
`%ukoth_status%`	Current event status using the configured language text. If no event is running, the result is the configured `STOPPED` status.
`%ukoth_has_owner%`	`true` or `false` depending on whether the Koth currently has an owner.
`%ukoth_event_counter%`	Current event counter stored by the Koth.
`%ukoth_is_self_destructing%`	Whether the Koth's auto-destroy/self-destruct setting is enabled.

Capture and control#

Placeholder	What it returns
`%ukoth_capture_time%`	Configured capture time value.
`%ukoth_capture_time_formated%`	Capture time converted to UltimateKoth's human-readable duration format.
`%ukoth_capture_mode%`	Raw capture mode identifier.
`%ukoth_capture_mode_formated%`	Capture mode using the configured language text.
`%ukoth_timeleft%`	Remaining capture time while a player is controlling the Koth.
`%ukoth_control_player%`	Name of the player currently controlling the Koth, or the configured fallback text when nobody is controlling it.
`%ukoth_control_group%`	Group of the current controlling player, when a group integration is available.

UltimateKoth also exposes the accumulated-control ranking of the current event:

%ukoth_control_longesttime:POSITION:TYPE%

POSITION starts at 1. TYPE accepts player, group or time.

Examples:

%ukoth_control_longesttime:1:player%
%ukoth_control_longesttime:1:group%
%ukoth_control_longesttime:1:time%

This ranking is based on the event's tracked controllers and is especially useful with capture modes that care about accumulated control time.

Maximum event time#

Placeholder	What it returns
`%ukoth_maxtimeleft%`	Remaining maximum-event time using UltimateKoth's duration formatting.
`%ukoth_maxtime_enabled%`	Whether maximum event time is enabled for the Koth.
`%ukoth_maxtime_size%`	Configured maximum time value, or `0` when disabled.
`%ukoth_maxtime_size_formated%`	Maximum time converted to a human-readable duration, or `0` when disabled.
`%ukoth_maxtime_endaction%`	Configured action when max time is reached, such as the active `EndAction` value.
`%ukoth_maxtime_endaction_bordercolor%`	Configured border color associated with the max-time end action.

Progress bar placeholders#

The progress-bar placeholders are dynamic. The text after barleft_ or barmax_ is parsed as a progress-bar definition.

Capture progress bar#

%ukoth_barleft_{amount}_length:15_remaining:<gray>■_progress:<#e1b128>■_complete:<#d15f21>■_fullbar:<red>Ending%

{amount} is replaced internally with the current capture percentage. When nobody is controlling the Koth, UltimateKoth feeds the bar a full remaining value.

Maximum-time progress bar#

%ukoth_barmax_{amount}_length:15_remaining:<gray>■_progress:<#e1b128>■_complete:<#d15f21>■_fullbar:<red>Ending%

{amount} is replaced internally with the percentage calculated from the event's remaining maximum time. If max time is disabled, UltimateKoth uses the full/default bar state.

These placeholders are intended for UltimateKoth formats that support the plugin's MiniMessage/progress-bar syntax. When embedding them into another plugin, confirm that the destination preserves the placeholder string and supports the resulting color format.

Loot and key rewards#

Placeholder	What it returns
`%ukoth_loot_type%`	Configured loot type.
`%ukoth_loots_amount%`	Number of non-empty loot items stored for the Koth.
`%ukoth_loot_chance%`	Configured loot chance including `%`.
`%ukoth_loot_max_amount%`	Configured maximum loot amount.
`%ukoth_loot_whole_group%`	Raw `true`/`false` state for whole-group loot.
`%ukoth_loot_whole_group_formated%`	Whole-group loot state using UltimateKoth's configured true/false language text.
`%ukoth_keyreceive_enabled%`	Whether this Koth awards keys.
`%ukoth_keyreceive_amount%`	Number of keys awarded. Returns `0` when key rewards are disabled.

Proximity#

Placeholder	What it returns
`%ukoth_proximity_type%`	Configured proximity type using UltimateKoth's language text, or `0` when disabled.
`%ukoth_proximity_enabled%`	Uses the same resolver as `proximity_type` in the current source.
`%ukoth_proximity_size%`	Configured proximity size. For `WORLD` and `ALLWORLDS`, UltimateKoth returns the corresponding configured language text instead of a numeric radius. Returns `0` when disabled.

Koth commands#

%ukoth_commands_amount% returns the number of commands assigned to the Koth.

Individual command entries are addressed by the command entry UUID:

%ukoth_command:<UUID>%
%ukoth_command_type:<UUID>%

%ukoth_command:<UUID>% returns the stored command text. %ukoth_command_type:<UUID>% returns its command execution type.

The value is a command-entry UUID, not a simple 0, 1, 2 list position.

Scheduler placeholders#

Placeholder	What it returns
`%ukoth_scheduler_next_time%`	Next scheduled event time for the selected Koth.
`%ukoth_scheduler_next_name%`	Next scheduled event name for the selected Koth.
`%ukoth_scheduler_amount%`	Number of schedulers attached to the selected Koth.
`%ukoth_scheduler:<num>%`	Scheduler rendered with UltimateKoth's configured scheduler format.
`%ukoth_scheduler:<num>:<type>%`	One field from a scheduler entry.

For %ukoth_scheduler:<num>:<type>%, the supported fields are:

frequency
month_day
week_day
hour
minute
min_players

The scheduler list is accessed by Java list index in the current implementation, so <num> starts at 0.

Examples:

%ukoth_scheduler:0%
%ukoth_scheduler:0:frequency%
%ukoth_scheduler:0:hour%
%ukoth_scheduler:0:min_players%

Warp placeholders#

Placeholder	What it returns
`%ukoth_has_warp%`	Raw `true`/`false` depending on whether the Koth has a warp.
`%ukoth_has_warp_formated%`	Warp availability using UltimateKoth's configured true/false language text.
`%ukoth_warp:WORLD%`	Warp world.
`%ukoth_warp:X%`	Warp X coordinate.
`%ukoth_warp:Y%`	Warp Y coordinate.
`%ukoth_warp:Z%`	Warp Z coordinate.
`%ukoth_custom_warp_message%`	Configured custom warp message. UltimateKoth chooses the enabled or disabled message according to whether the Koth has a usable player warp and parses Koth placeholders inside that message.

If the Koth has no warp, the coordinate/world resolver uses the plugin's configured NONE text.

Koth settings placeholders#

Use:

%ukoth_settings_state:TYPE%
%ukoth_settings_state_formated:TYPE%

The raw version returns the boolean state. The formated version uses UltimateKoth's configured enabled/disabled language text.

Supported TYPE values in the current source are:

Type	Setting
`ALLOWWITHOUTGROUP`	Players without a group may participate according to this Koth setting.
`ALLOWPLAYERWARP`	Player warp to the Koth is enabled.
`VISIBLETOPLAYERS`	Koth is visible to players through the relevant interfaces.
`STOPTIMEINDISPUTE`	Capture timing behavior while the Koth is disputed.
`USECENTRALHOLOGRAM`	Central hologram usage for the Koth.
`WARPONLYSTARTED`	Warp is restricted to the started/running event state.
`USESCOREBOARD`	Koth scoreboard is enabled.

Examples:

%ukoth_settings_state:ALLOWPLAYERWARP%
%ukoth_settings_state_formated:ALLOWPLAYERWARP%
%ukoth_settings_state_formated:USESCOREBOARD%

Older placeholder lists may show %settings_state_formated:TYPE% without the ukoth_ prefix. The actual UltimateKoth placeholder identifier is %ukoth_settings_state_formated:TYPE%.

External PlaceholderAPI placeholders for a specific Koth#

To query a specific Koth from PlaceholderAPI, put the Koth ID between curly braces immediately after ukoth_:

%ukoth_{KOTH_NAME}_PLACEHOLDER%

For a Koth called Castle, for example:

%ukoth_{Castle}_name%
%ukoth_{Castle}_status%
%ukoth_{Castle}_control_player%
%ukoth_{Castle}_capture_time_formated%
%ukoth_{Castle}_scheduler_next_time%

The following named forms correspond to the Koth-specific placeholders documented above:

%ukoth_{KOTH_NAME}_direction_relative%
%ukoth_{KOTH_NAME}_icon%
%ukoth_{KOTH_NAME}_name%
%ukoth_{KOTH_NAME}_id%
%ukoth_{KOTH_NAME}_cuboid_area%
%ukoth_{KOTH_NAME}_commands_amount%
%ukoth_{KOTH_NAME}_maxtimeleft%
%ukoth_{KOTH_NAME}_maxtime_enabled%
%ukoth_{KOTH_NAME}_maxtime_size%
%ukoth_{KOTH_NAME}_maxtime_endaction%
%ukoth_{KOTH_NAME}_maxtime_endaction_bordercolor%
%ukoth_{KOTH_NAME}_maxtime_size_formated%
%ukoth_{KOTH_NAME}_timeleft%
%ukoth_{KOTH_NAME}_control_player%
%ukoth_{KOTH_NAME}_control_group%
%ukoth_{KOTH_NAME}_control_longesttime:POSITION:TYPE%
%ukoth_{KOTH_NAME}_capture_time%
%ukoth_{KOTH_NAME}_capture_time_formated%
%ukoth_{KOTH_NAME}_capture_mode%
%ukoth_{KOTH_NAME}_capture_mode_formated%
%ukoth_{KOTH_NAME}_world%
%ukoth_{KOTH_NAME}_coord_x%
%ukoth_{KOTH_NAME}_coord_y%
%ukoth_{KOTH_NAME}_coord_z%
%ukoth_{KOTH_NAME}_status%
%ukoth_{KOTH_NAME}_loot_type%
%ukoth_{KOTH_NAME}_loots_amount%
%ukoth_{KOTH_NAME}_loot_chance%
%ukoth_{KOTH_NAME}_loot_max_amount%
%ukoth_{KOTH_NAME}_loot_whole_group%
%ukoth_{KOTH_NAME}_loot_whole_group_formated%
%ukoth_{KOTH_NAME}_keyreceive_enabled%
%ukoth_{KOTH_NAME}_keyreceive_amount%
%ukoth_{KOTH_NAME}_proximity_type%
%ukoth_{KOTH_NAME}_proximity_enabled%
%ukoth_{KOTH_NAME}_proximity_size%
%ukoth_{KOTH_NAME}_command:<UUID>%
%ukoth_{KOTH_NAME}_command_type:<UUID>%
%ukoth_{KOTH_NAME}_scheduler_next_time%
%ukoth_{KOTH_NAME}_scheduler_next_name%
%ukoth_{KOTH_NAME}_scheduler_amount%
%ukoth_{KOTH_NAME}_scheduler:<num>%
%ukoth_{KOTH_NAME}_scheduler:<num>:<type>%
%ukoth_{KOTH_NAME}_has_owner%
%ukoth_{KOTH_NAME}_event_counter%
%ukoth_{KOTH_NAME}_is_self_destructing%
%ukoth_{KOTH_NAME}_has_warp_formated%
%ukoth_{KOTH_NAME}_has_warp%
%ukoth_{KOTH_NAME}_warp:WORLD%
%ukoth_{KOTH_NAME}_warp:X%
%ukoth_{KOTH_NAME}_warp:Y%
%ukoth_{KOTH_NAME}_warp:Z%
%ukoth_{KOTH_NAME}_settings_state:TYPE%
%ukoth_{KOTH_NAME}_settings_state_formated:TYPE%
%ukoth_{KOTH_NAME}_custom_warp_message%

The dynamic progress bars use the same named-Koth rule:

%ukoth_{KOTH_NAME}_barleft_{amount}_length:15_remaining:<gray>■_progress:<#e1b128>■_complete:<#d15f21>■_fullbar:<red>Ending%

%ukoth_{KOTH_NAME}_barmax_{amount}_length:15_remaining:<gray>■_progress:<#e1b128>■_complete:<#d15f21>■_fullbar:<red>Ending%

The correct named settings form is %ukoth_{KOTH_NAME}_settings_state_formated:TYPE%. A form such as %settings_{KOTH_NAME}_state_formated:TYPE% does not match the current PlaceholderAPI resolver.

Practical examples#

Hologram for one Koth#

Castle Koth
Status: %ukoth_{Castle}_status%
Controller: %ukoth_{Castle}_control_player%
Group: %ukoth_{Castle}_control_group%
Capture: %ukoth_{Castle}_timeleft%
Next event: %ukoth_{Castle}_scheduler_next_time%

Global statistics scoreboard#

Your group: %ukoth_player_group%
Solo wins: %ukoth_player_single_win_amount%
Group wins: %ukoth_player_group_win_amount%
Top player: %ukoth_top:TOPPLAYER:ALL:1%
Top group: %ukoth_top:TOPGROUP:ALL:1%
Next Koth: %ukoth_next_name%

Raw leaderboard fields#

If you want to format the ranking yourself in another plugin:

#1 %ukoth_unformated_top:NAME:TOPPLAYER:ALL:1% - %ukoth_unformated_top:AMOUNT:TOPPLAYER:ALL:1% wins
#2 %ukoth_unformated_top:NAME:TOPPLAYER:ALL:2% - %ukoth_unformated_top:AMOUNT:TOPPLAYER:ALL:2% wins

Troubleshooting placeholders#

The placeholder is shown literally#

Check that PlaceholderAPI is installed and that the destination plugin actually parses PlaceholderAPI placeholders. UltimateKoth registers the ukoth expansion directly and marks it as persistent, so a separate eCloud download is not required for the built-in expansion.

For Koth-specific data in an external plugin, prefer the explicit named syntax:

%ukoth_{KOTH_NAME}_status%

instead of relying on the player's current Koth context.

A named placeholder does not resolve#

Confirm that the text inside {KOTH_NAME} is the actual Koth identifier. The parser searches UltimateKoth's Koth manager by that name before resolving the remaining identifier.

A scheduler placeholder is empty or unchanged#

Make sure the Koth has scheduler entries. %ukoth_scheduler:<num>% uses a zero-based list index in the current implementation, so the first entry is 0.

A command placeholder does not resolve#

%ukoth_command:<UUID>% and %ukoth_command_type:<UUID>% expect the UUID of the stored command entry. They do not use the command's visual position in a GUI.

`formated` looks misspelled#

It is intentionally documented exactly as implemented. Use:

%ukoth_active_now_formated%
%ukoth_capture_time_formated%
%ukoth_loot_whole_group_formated%
%ukoth_has_warp_formated%
%ukoth_settings_state_formated:TYPE%

Do not change formated to formatted in the placeholder identifier.

UltimateKoth placeholders#

How placeholder context works#

Player, global and event placeholders#

Timezone#

Ranking placeholders#

Formatted top#

Raw top fields#

Koth-specific placeholders#

Identity, position and basic state#

Capture and control#

Maximum event time#

Progress bar placeholders#

Capture progress bar#

Maximum-time progress bar#

Loot and key rewards#

Proximity#

Koth commands#

Scheduler placeholders#

Warp placeholders#

Koth settings placeholders#

External PlaceholderAPI placeholders for a specific Koth#

Practical examples#

Hologram for one Koth#

Global statistics scoreboard#

Raw leaderboard fields#

Troubleshooting placeholders#

The placeholder is shown literally#

A named placeholder does not resolve#

A scheduler placeholder is empty or unchanged#

A command placeholder does not resolve#

formated looks misspelled#

`formated` looks misspelled#