> For the complete documentation index, see [llms.txt](https://realisticnode.gitbook.io/rnsetups/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://realisticnode.gitbook.io/rnsetups/rnkoth/configuration/koth-file.md). # KOTH files Every option of a KOTH file (plugins/rnKoth/koths/\.yml). Each KOTH has its own file: `plugins/rnKoth/koths/.yml`. It is created by `/koth create ` (or the editor) from a template with every option and its explanation. Everything here can also be changed with `/koth editor `. The name of the file is the name of the KOTH, used in commands and placeholders. It can only use `a-z`, `0-9`, `-` and `_`, up to 32 characters. Words used by the [placeholders](/rnsetups/rnkoth/reference/placeholders.md#names-you-cant-use) can't be KOTH names: `running`, `current`, `next`, `top`, `hud`, the stat names (`wins`, `captures`, `events`, `time`, `time_formatted`, `kills`, `king`, `king_kills`) and names that start with `top_`, `next_` or `current_`. {% hint style="info" %} You can copy a KOTH file to make a new one: copy `spawn.yml` to `arena.yml` and save. The new KOTH appears a few seconds later (with `auto-reload` on) or after `/koth reload`. {% endhint %} ## Basics | Option | Default | What it does | | -------------- | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `display-name` | `Name` | Name shown to players. Colors work: ``, `<#ff8800>`, `&6`... | | `enabled` | `true` | `false` = it never starts by its schedule. It can still be started with `/koth start`. | | `icon` | `BEACON` | Item that represents this KOTH in the menus. In the editor: hold an item and click **Icon**. | | `mode` | `capture` | `capture`: the first side that holds it alone for `capture.time` seconds wins. `score`: 1 point per second while holding it, first to `score.target` wins (or the most points when time runs out). | ## Areas ```yaml zones: - 'box world 100 64 100 110 66 110' - 'circle world -80 65 30 6 4' ``` One line per area. Set them in game with the wand and `/koth setzone`, or with `/koth setzone circle `. See [Your first KOTH](/rnsetups/rnkoth/guides/first-koth.md). | Line | Meaning | | ---------------------------------------------- | -------------------------------------------------------------------------------------- | | `box ` | A box between two corner blocks, both included. `y1` is the floor where players stand. | | `circle ` | A circle around the block `x y z`, from `y` up, `height` blocks high. | * Areas are **at least 3 blocks high**. A lower area is made 3 blocks high and the console warns you. * A `circle` line without height is 5 blocks high. * With two or more lines the KOTH moves between them (see `roaming`). ## Roaming Only used when there are several areas. | Option | Default | What it does | | -------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | | `roaming.move-every` | `120` | Seconds between moves during an event. `0` = it does not move during the event; each new event uses the next area (remembered across restarts). | | `roaming.order` | `next` | `next` = in the order of the list. `random` = any other area. | ## Capture | Option | Default | What it does | | ---------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `capture.time` | `120` | Seconds to hold the KOTH (capture mode). | | `capture.on-leave` | `reset` | What happens to your progress when you leave or die. `reset`: back to 0. `pause`: it stays, and anyone else must first bring it down to 0 (tug of war). `drain`: it goes down slowly while nobody is inside. | | `capture.drain-speed` | `1.0` | How fast progress goes down with `drain`. `1.0` = 1 second per second. | | `capture.best-wins-when-time-ends` | `true` | When the time runs out, the side with the most progress wins. `false` = nobody wins. | ## Score | Option | Default | What it does | | -------------- | ------- | ---------------------------------------------------- | | `score.target` | `300` | Points to win (1 point per second holding the KOTH). | ## The event | Option | Default | What it does | | ------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `duration` | `900` | Seconds the event lasts (at least 10). `0` = no time limit: it stays open until someone conquers it (capture) or reaches the target (score), or an admin stops it with `/koth stop`. With `0`, `overtime` and `capture.best-wins-when-time-ends` don't apply, and the time left shows `No limit`. | | `overtime` | `60` | Extra seconds when time runs out while the KOTH is contested or someone is capturing. `0` = off. The event ends as soon as the fight is over. | | `contested` | `holder` | When players of different sides (teams, or players on their own) are inside. `freeze`: nobody gains until one side is left. `majority`: the side with more players inside keeps gaining, a tie = nobody (useless with solo teams). `holder`: the side that was already gaining keeps gaining, the others must kill it or push it out. `everyone`: every side inside gains at the same time, the first to finish wins. New KOTHs get `holder`; a file without this line uses `freeze`. | | `min-players` | `2` | Players online on the server needed for a scheduled start. Vanished players and spectators are not counted. `0` = it always starts. | | `teams` | `default` | `default`: teams as `config.yml` says (`teams.mode`). `solo`: in this KOTH every player plays alone. | See [Game modes](/rnsetups/rnkoth/guides/modes.md) for how these work together. ## Schedule | Option | Default | What it does | | ----------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `schedule` | `[]` | When it starts by itself. One line per time: `'daily 20:00'`, `'mon,wed,fri 18:30'`, `'weekdays 19:00'`, `'weekends 16:00'`, `'every 2h'`, `'every 45m'`, `'2026-12-24 21:00'`. | | `announce-before` | `[300, 60, 10]` | Warn players this many seconds before a scheduled start. | | `start-countdown` | `10` | Countdown in seconds before the KOTH opens, also for `/koth start`. `0` = it opens at once. | See [Schedules](/rnsetups/rnkoth/guides/schedules.md) for every format. ## Display | Option | Default | What it does | | ----------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------- | | `display.audience.announcements` | `server` | Who gets the countdown, the "starts in" warnings, opened, moved, overtime, stopped and the results. | | `display.audience.capture-messages` | `world` | Who gets "X is capturing", "X took it", "X lost control" and "contested". | | `display.audience.titles` | `world` | Who sees the start title and the "X won" title (the winners always see their own). | | `display.audience.sounds` | `world` | Who hears the sounds of the event. | | `display.audience.boss-bar` | `150` | Who sees the boss bar with the holder, progress and time left. | | `display.audience.sidebar` | `60` | Who sees the rnKoth sidebar. `%rnkoth_near%` is `yes` for them. | | `display.audience.locator` | `world` | Who gets the arrow and distance in the action bar while outside the area. | | `display.audience.action-bar` | `on` | Progress in the action bar while standing in the area: `on` or `off`. | | `display.audience.discord` | `on` | Post this KOTH to Discord (when Discord is set up in `config.yml`): `on` or `off`. | | `display.boss-bar-color` | `YELLOW` | `PINK`, `BLUE`, `RED`, `GREEN`, `YELLOW`, `PURPLE` or `WHITE`. It turns red while contested. | | `display.hologram` | `true` | Floating text above the KOTH with its state. No other plugin needed. | | `display.hologram-height` | `3.5` | Blocks above the floor of the area. | | `display.border-particles` | `true` | Particles on the edge of the area while it runs: white = free, green = your side, orange = another side, red = contested. | | `display.glow-holder` | `true` | The players holding the KOTH glow so everyone can see them. | | `display.world-name` | `''` | Name shown instead of the world name in messages, like `Spawn` or `/warp pvp`. `''` = the world name, or `world-names` of `config.yml`. | Each `display.audience` part takes `server` (every player), `world` (the world of the KOTH), a number of blocks like `150`, `worlds:pvp,arena`, `region:` or `off`. See [Who sees what](/rnsetups/rnkoth/guides/display.md#who-sees-what). Older files may still have `display.radius`, `display.boss-bar` and `display.locator`: they are only used for the `display.audience` parts the file does not have (see [Older KOTH files](/rnsetups/rnkoth/guides/display.md#older-koth-files)). See [What players see](/rnsetups/rnkoth/guides/display.md). ## Rules | Option | Default | What it does | | ------------------------------- | ----------------------- | ---------------------------------------------------------------------------------------------------------- | | `rules.deny-flight` | `true` | Players inside cannot fly (`/fly`) while the KOTH runs. | | `rules.deny-elytra` | `true` | Players inside cannot glide with elytra. | | `rules.deny-ender-pearls` | `false` | Ender pearls cannot be thrown into the area. | | `rules.invisible-players-count` | `false` | Invisible players count for the capture. | | `rules.afk-seconds` | `60` | Players who do not move for this many seconds stop counting. `0` = off. | | `rules.counted-gamemodes` | `[SURVIVAL, ADVENTURE]` | Game modes that count. | | `rules.blocked-commands` | `[]` | Commands players cannot use inside the area while the KOTH runs, like `['home', 'spawn', 'tpa']`. | | `rules.protect-blocks` | `false` | Nobody can break or place blocks inside the area (and its floor) while it runs. `rnkoth.bypass.rules` can. | See [Rules inside the area](/rnsetups/rnkoth/guides/rules.md). ## Rewards | Option | Default | What it does | | ------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | | `rewards.winner` | loot, 3 diamonds, a firework | Everyone of the winning side who stood in the KOTH. The `VICTORY!` title is built in (`display.titles` in `config.yml`), so it is not a reward line. | | `rewards.second` | `[]` | The 2nd best side. | | `rewards.third` | `[]` | The 3rd best side. | | `rewards.participation` | 2 iron ingots | Everyone who stood in the KOTH at least `participation-seconds`. | | `rewards.participation-seconds` | `30` | Seconds inside (counting) needed for `participation`. | | `rewards.while-holding` | `[]` | Given every few seconds to the players holding the KOTH. | | `rewards.while-holding-every` | `30` | Seconds between `while-holding` rewards. | | `rewards.holder-killed` | a message | Given to whoever kills a player holding the KOTH. | Every line is an action like `'[console] eco give {player} 500'`. See [Rewards](/rnsetups/rnkoth/guides/rewards.md) for every action, chances and groups. ## Commands | Option | Default | What it does | | ------------------- | ------- | -------------------------------------------------------------------- | | `commands.on-start` | `[]` | Console commands run when the KOTH opens. | | `commands.on-end` | `[]` | Console commands run when it ends. `{winner}` is the winner, or `-`. | Placeholders: `{koth}`, `{koth_name}`, `{winner}` and the others of [Rewards](/rnsetups/rnkoth/guides/rewards.md#commands-on-start-and-end). `{@path}` words (in the server language) and PlaceholderAPI placeholders (without a player) work too. ## Loot | Option | Default | What it does | | ------------- | ------- | ----------------------------------------------------------------------------------- | | `loot.mode` | `all` | `all` = every item of the loot chest. `random` = `amount` random items. | | `loot.amount` | `1` | How many items are given with `mode: random`. | | `loot.items` | `[]` | The items given by `[loot]`. Fill them in game: `/koth editor ` → Loot chest. | ## If an option is missing A KOTH file does not need every option. A missing option uses its built-in value, which is the same as the default in the tables above (and in the template). The exception is `display.audience`: a missing part works as before 1.0.1 (`display.radius`, and `sidebar-radius` / `locator-radius` of `config.yml`), so older files keep working the same. Some numbers have a lowest value: `capture.time` and `score.target` at least `1`, `duration` at least `10` (or `0` = no time limit), `drain-speed` at least `0.05`, `while-holding-every` at least `1` and `loot.amount` at least `1`. A wrong word (like `mode: capure`) uses the default. {% hint style="warning" %} If a KOTH file has a YAML mistake, the console shows the line and the KOTH **keeps the last version that was read without errors**: a running event goes on, and `/koth reload` says that some files have errors. Fix the line and save; it is applied a few seconds later. (A file that is already broken when the server starts has no good version yet: it uses the built-in values with no area until you fix it.) {% endhint %}