Skip to content
BattleStudio

Information

OptimalKoth features, the capture rules, commands, permissions, placeholders and tokens in one reference.

BattleStudio plugin

OptimalKoth

Wand-selected capture zones where one player must hold the hill to win, with holograms, boss bars, weekly schedules and command rewards.

Requires
Paper / FoliaMC 1.21.11+Java 21+OptimalLibraryPlaceholderAPI
Buy on BuiltByBitInstallation guideGet support

OptimalKoth runs King of the Hill events. You select a zone with the KOTH wand and turn it into a KOTH with one command. When the KOTH starts (by command or from a schedule), the first player standing in the zone starts capturing it, and wins by holding it for the KOTH’s Capture-Time without leaving. The winner gets the KOTH’s rewards.

There is no menu and no player command. Players follow a KOTH through chat announcements, titles, a floating hologram above the zone, a boss bar and PlaceholderAPI placeholders. Everything is managed with /kothadmin.

How a capture works

Section titled “How a capture works”

A running KOTH checks its zone once per second.

  • Only the capturer counts. One player holds the hill at a time. There is no score mode and no team capture: teammates of the capturer in the zone neither help nor contest, they wait in line like everyone else.
  • The queue. Players inside the zone are queued in the order they entered. Leaving the zone drops a player from the queue, so walking back in puts them at the end.
  • Taking the hill. When nobody holds the hill, the first player in the queue becomes the capturer and HILL-TAKEN is announced.
  • Dropping the hill. A capturer who leaves the zone (or dies) loses it and HILL-DROPPED is announced. With Reset-On-Leave: true the held time goes back to zero; with false the next capturer continues from where the last one stopped. The next player in the queue takes over in the same second.
  • Progress. Every Progress-Announcement-Interval held seconds, HILL-PROGRESS is announced.
  • Winning. Each second the capturer stays adds one second. Reaching Capture-Time captures the KOTH: KOTH-WON is announced and the rewards run for the winner. Only the capturer is rewarded.
  • Time limit. Max-Duration seconds after the start, a KOTH nobody captured ends without a winner (KOTH-TIMED-OUT). 0 means it runs until someone captures it. A capture on the last second still wins.

Dead players and spectators are never counted as inside the zone.

Features

Section titled “Features”
  • Cuboid capture zones selected in-game with a wand, with live particle outlines
  • One file per KOTH in koths/, created for you by /kothadmin create
  • Single-capturer King of the Hill with a fair entry queue
  • Optional held-time reset when the capturer leaves
  • Optional time limit and periodic progress announcements
  • A packet hologram above every KOTH, with separate lines while running and while idle
  • A boss bar that fills with the held time, shown to everyone or only to nearby players
  • Rewards as action lines: console and player commands, messages, broadcasts, action bars, titles, sounds
  • Weekly schedules by day and time, with an optional random pick and a minimum online player count
  • Chat announcements with optional screen titles and sounds
  • Capture history and per-player win counts in SQLite or MySQL
  • PlaceholderAPI expansion with global, per KOTH and per player values
  • Team points for the winner’s team when OptimalTeams is installed
  • Folia-ready

Commands

Section titled “Commands”

OptimalKoth has one command, /kothadmin (aliases /kadmin, /kothsadmin, /optimalkothadmin). Every subcommand needs optimalkoth.admin. The command is hidden from tab completion for players without that permission. /kothadmin with no arguments shows the help panel.

Command Description Console
/kothadmin list List every KOTH with its status, current capturer and next scheduled start. yes
/kothadmin wand Get the KOTH wand. A full inventory drops it at your feet. no
/kothadmin create <koth> Create a KOTH from your wand selection. no
/kothadmin delete <koth> Stop the KOTH if it is running and delete its file. yes
/kothadmin start <koth> Start a KOTH right now. yes
/kothadmin stop <koth> Stop a running KOTH without a winner. yes
/kothadmin tp <koth> Teleport to the top centre of the KOTH zone. no
/kothadmin outline <koth> Show or hide the particle outline of a KOTH zone. no
/kothadmin reload Reload config.yml, messages.yml, every KOTH file and schedules.yml. yes

A KOTH id is 1 to 32 lower-case letters, digits or dashes (spawn, nether-koth, koth-2). Ids are lower-cased for you.

start refuses a KOTH that is disabled in its file, one whose world is not loaded and one that is already running, each with its own message.

Permissions

Section titled “Permissions”
  • optimalkoth.admin - every /kothadmin command and using the KOTH wand (default: op)

Players need no permission to capture a KOTH, see its hologram or boss bar, or receive rewards.

Placeholders

Section titled “Placeholders”

With PlaceholderAPI installed, OptimalKoth registers the optimalkoth expansion. Replace <koth> with a KOTH id.

Placeholder Value
%optimalkoth_active% Number of KOTHs running right now.
%optimalkoth_next% Countdown to the next scheduled KOTH (any KOTH).
%optimalkoth_next_date% Date and time of the next scheduled KOTH, in Settings.Date-Format.
%optimalkoth_next_name% Display name of the next scheduled KOTH.
%optimalkoth_status_<koth>% Koth-Format.Status.Active or Idle.
%optimalkoth_capturer_<koth>% Current capturer, or Koth-Format.No-Capturer.
%optimalkoth_time_left_<koth>% Capture time still needed.
%optimalkoth_ends_in_<koth>% Time until the KOTH times out, or Koth-Format.Unlimited.
%optimalkoth_next_<koth>% Countdown to this KOTH’s next scheduled start.
%optimalkoth_next_date_<koth>% Date and time of this KOTH’s next scheduled start.
%optimalkoth_last_winner_<koth>% Name of the player who captured it last, or Koth-Format.No-Winner.
%optimalkoth_name_<koth>% The KOTH’s Display-Name.
%optimalkoth_wins% How many KOTHs the viewing player has captured in total.

Per KOTH placeholders return an empty string for an unknown id. When nothing is scheduled, the next placeholders show Koth-Format.No-Schedule.

PlaceholderAPI also resolves %...% placeholders from other plugins in messages, titles and rewards.

Tokens

Section titled “Tokens”

These {...} tokens resolve in messages, hologram lines, the boss bar title and rewards.

Token Value
{koth} The KOTH’s Display-Name.
{koth-id} The KOTH id (its file name).
{world} The zone’s world.
{x}, {y}, {z} The block at the centre of the zone.
{status} Koth-Format.Status.Active while running, Idle otherwise.
{capture-time} The KOTH’s Capture-Time, formatted.
{time-left} Capture time still needed (Capture-Time minus the held time). Equals {capture-time} while the KOTH is not running.
{progress} Held time as a percentage of Capture-Time (0 to 100, no % sign).
{elapsed} Time since the KOTH started.
{ends-in} Time until it times out, or Koth-Format.Unlimited when Max-Duration is 0.
{capturer} The current capturer, or Koth-Format.No-Capturer.
{last-winner} The last player who captured it, or Koth-Format.No-Winner.
{next} Countdown to its next scheduled start, or Koth-Format.No-Schedule.
{next-date} Date of its next scheduled start in Settings.Date-Format, or Koth-Format.No-Schedule.
{player} The winner. Rewards and KOTH-WON only.

Durations are printed compactly, for example 2m, 30s or 1h, 5m.

Some messages add their own tokens ({blocks}, {required}, {online}, {ms} and others), see messages.yml.

Formatting

Section titled “Formatting”

Every text field supports legacy & codes, &#RRGGBB hex, MiniMessage (<gradient:a,b,c>, <rainbow>, <bold>, <#RRGGBB>, …) and, with PlaceholderAPI installed, %...% placeholders.

OptimalTeams

Section titled “OptimalTeams”

When OptimalTeams is installed, the winner’s team earns team points for every KOTH capture. The amount and the on/off switch live in OptimalTeams’ own config.yml under Point-Sources.Koth-Capture (see Points & Team Top), not in OptimalKoth. A winner without a team earns no team points.

Reference

Section titled “Reference”