> 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/guides/rewards.md).

# Rewards

Who gets rewards, every reward action, chances, groups, the loot chest, offline players and the reward box.

Rewards are lists of **lines** in the KOTH file, under `rewards:`. Every line is one **action**: run a command, give an item, send a title... You can edit the lists in `/koth editor <name>` → **Rewards**, or in the file.

<figure><img src="https://348500357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSlVHklG0EMAOmvfqcizu%2Fuploads%2Fyq08LCXOfQ8OtiH4a8jq%2Frnkoth-en-editor-rewards.png?alt=media" alt="The Rewards page of the editor"><figcaption><p>The Rewards page of the editor</p></figcaption></figure>

```yaml
rewards:
  winner:
    - '[loot]'
    - '[console] give {player} diamond 3'
    - '[firework]'
  second: []
  third: []
  participation:
    - '[console] give {player} iron_ingot 2'
  participation-seconds: 30
  while-holding: []
  while-holding-every: 30
  holder-killed:
    - '[message] {@rewards.holder-killed}'
```

The winners also get the built-in `VICTORY!` title (`event.you-won-title`, turned off with `display.titles: false` in `config.yml`), so there is no `[title]` line by default. Add one only if you want your own title instead of it (and turn `display.titles` off, or players see two titles).

## Who gets each list

| List            | Given to                                                                                                                                           |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| `winner`        | Every player of the winning side who stood in the KOTH (and counted) at some point. In solo, the winner. In teams, every member who took part.     |
| `second`        | Every player of the 2nd best side who stood in the KOTH. Only when there is a winner.                                                              |
| `third`         | Every player of the 3rd best side who stood in the KOTH. Only when there is a winner.                                                              |
| `participation` | Everyone who stood in the KOTH and counted for at least `participation-seconds` (default `30`) in total. Winners too. Given also when nobody wins. |
| `while-holding` | Every `while-holding-every` seconds (default `30`) of holding, to each player of the holding side who is inside and counts.                        |
| `holder-killed` | To whoever kills a player who is holding the KOTH (see below).                                                                                     |

"2nd" and "3rd" are the next sides by progress (capture mode) or points (score mode). A side with no progress or points does not get a place.

### Holder kills

`holder-killed` is given when a player kills someone who is **holding** the KOTH (on the gaining side, inside and counting). To stop farming with friends:

* the killer must be on **another side** than the victim (killing your own teammate gives nothing),
* the same killer gets it **at most once per minute** for the same victim.

The kill also counts for the **Holder kills** stat. `{victim}` is the name of the player who was killed.

The **Kills** stat counts every kill during an event where the killer or the victim was inside the area, except kills of a teammate (same side). A killer who is outside and is not playing the event gets the kill in their stats, but does not become a player of the event (no "events played", no participation rewards).

## Actions

| Action                                | What it does                                                  | Example                                             |
| ------------------------------------- | ------------------------------------------------------------- | --------------------------------------------------- |
| `[console] <command>`                 | Runs a command as the console.                                | `[console] eco give {player} 500`                   |
| `[player] <command>`                  | Runs a command as the player.                                 | `[player] warp spawn`                               |
| `[message] <text>`                    | Sends a chat message to the player. `[msg]` works too.        | `[message] <green>Well done!`                       |
| `[broadcast] <text>`                  | Sends a chat message to every player and the console.         | `[broadcast] <gold>{player} conquered {koth_name}!` |
| `[title] <title>;<subtitle>`          | Shows a title. The subtitle (after `;`) is optional.          | `[title] <gold>Winner;<gray>GG`                     |
| `[actionbar] <text>`                  | Shows a text above the hotbar.                                | `[actionbar] <yellow>+500 coins`                    |
| `[sound] <sound> [volume] [pitch]`    | Plays a sound to the player. Volume and pitch default to `1`. | `[sound] entity.player.levelup 1 1`                 |
| `[item] <item> [amount] [name]`       | Gives an item. The name can have colors and spaces.           | `[item] diamond 5 <aqua>KOTH Diamond`               |
| `[effect] <effect> [seconds] [level]` | Gives a potion effect. Defaults: 10 seconds, level 1.         | `[effect] speed 30 2`                               |
| `[firework]`                          | Launches a firework at the player. It never hurts anyone.     | `[firework]`                                        |
| `[loot]`                              | Gives the items of the [loot chest](#loot-chest).             | `[loot]`                                            |

A line **without** `[...]` at the start is run as a console command: `eco give {player} 500` is the same as `[console] eco give {player} 500`. A leading `/` in commands is removed.

<figure><img src="https://348500357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSlVHklG0EMAOmvfqcizu%2Fuploads%2Fcf7JGHIjGmuVsAqjlbGk%2Frnkoth-en-editor-rewardlist.png?alt=media" alt="A reward list: left click a line to edit it, right click to remove it"><figcaption><p>A reward list: left click a line to edit it, right click to remove it</p></figcaption></figure>

* **Sounds** use the Minecraft key, with dots: `entity.player.levelup`, `ui.toast.challenge_complete`, or with a namespace (`minecraft:block.bell.use`, or a resource pack sound).
* **Items** use the item id: `diamond`, `golden_apple`, `netherite_ingot`.
* **Effects** use the effect id: `speed`, `strength`, `regeneration`, `resistance`.

{% hint style="warning" %}
A line with a mistake (an unknown item, effect or action) is skipped and the console tells you which line. The other lines are still given.
{% endhint %}

## Chances and permissions

Put these in front of any action:

| Prefix                      | Meaning                                                       | Example                                                     |
| --------------------------- | ------------------------------------------------------------- | ----------------------------------------------------------- |
| `[chance:<percent>]`        | Only runs that percent of the time.                           | `[chance:25] [console] crate key give {player} legendary 1` |
| `[permission:<permission>]` | Only for players with the permission. `[perm:...]` works too. | `[permission:vip.koth] [console] eco give {player} 500`     |

They can be combined: `[permission:vip] [chance:50] [item] diamond 2`.

## Groups

A group runs several actions together. Groups are written in the file (the editor shows them as a bundle; you can remove them there with a right click, but not edit them).

**Chance group**: all the actions, or none.

```yaml
rewards:
  winner:
    - '[console] eco give {player} 1000'
    - chance: 10
      actions:
        - '[item] diamond_block 1 <aqua>Lucky block'
        - '[broadcast] <gold>{player} got the lucky reward!'
```

**Pick one**: exactly one option is chosen. `weight` is how likely each option is (default `1`). Here the first option is chosen 3 times out of 4.

```yaml
rewards:
  winner:
    - pick-one:
        - weight: 3
          actions:
            - '[item] iron_ingot 16'
        - weight: 1
          actions:
            - '[item] diamond 4'
            - '[message] <aqua>Lucky you!'
```

Groups can hold lines with `[chance:...]` and `[permission:...]`, and other groups.

## Placeholders in rewards

| Placeholder                                                        | Value                                                                 |
| ------------------------------------------------------------------ | --------------------------------------------------------------------- |
| `{player}`                                                         | The player who gets the reward                                        |
| `{team}`                                                           | Their team name (the player name in solo)                             |
| `{koth}` / `{koth_name}`                                           | Name / display name of the KOTH                                       |
| `{place}`                                                          | `1` for winners, `2` and `3` for 2nd and 3rd, `0` for the other lists |
| `{time}`                                                           | Seconds the player stood inside and counted                           |
| `{held}`                                                           | Seconds the player held the KOTH                                      |
| `{points}`                                                         | Points of their side (score mode)                                     |
| `{kills}`                                                          | Kills of the player in this event                                     |
| `{victim}`                                                         | Only in `holder-killed`: the holder who was killed                    |
| `{mode}`, `{duration}`, `{target}`, `{world}`, `{x}`, `{y}`, `{z}` | The KOTH's mode, length, target and location                          |

In texts shown to the player (`[message]`, `[broadcast]`, `[title]`, `[actionbar]` and item names) you can also use:

* **Language words**: `{@path}` is replaced by the text at that path of the language file, in the language of the player. `{@rewards.victory-title}` is `<gold><bold>VICTORY` in English and the Spanish text for Spanish players. See [Languages](/rnsetups/rnkoth/configuration/languages.md#language-words).
* **PlaceholderAPI** placeholders of the player, like `%player_name%`, when PlaceholderAPI is installed.

{% hint style="info" %}
Commands (`[console]`, `[player]` and lines without an action) also accept `{@path}` words, in the **server** language (`language` in `config.yml`, since a command has no reader), and PlaceholderAPI placeholders of the player who gets the reward. For example `'[console] say {player} has %vault_eco_balance% coins'`.
{% endhint %}

## Loot chest

The loot chest holds real items: with enchantments, names, lore and custom data from other plugins.

1. `/koth editor <name>` → **Loot chest**.
2. Put the items in the chest.
3. Close it. The chat says `Loot saved (5 stack(s)).`

The items you put in are kept as the loot (they are not given back to you). Open the chest again to change them.

The `[loot]` action gives these items to **one** winner: the player of the winning side who stood the longest in the KOTH. In solo, that is the winner. In the other lists, `[loot]` gives nothing.

```yaml
loot:
  mode: all     # all = every item, random = 'amount' random items
  amount: 1
  items: []     # filled by the editor
```

With `mode: random`, `amount` random stacks of the chest are given each time.

## Commands on start and end

```yaml
commands:
  on-start: []
  on-end: []
```

Console commands run when the KOTH opens and when it ends (with or without a winner). Write plain commands, **without** `[console]`. Placeholders: `{koth}`, `{koth_name}`, `{world}`, `{x}`, `{y}`, `{z}`, the values of a running KOTH (`{holder}`, `{leader}`, `{players}`, `{elapsed}`...), and in `on-end` also `{winner}` (`-` when nobody won) and `{winner_score}`. `{@path}` words are replaced in the server language (so `{holder}` with nobody holding it gives `Nobody`), and PlaceholderAPI placeholders that need no player work too (like `%server_online%`).

```yaml
commands:
  on-start:
    - 'broadcast The KOTH {koth} is open!'
  on-end:
    - 'eco give {winner} 100'
```

{% hint style="info" %}
In team mode `{winner}` is the team name. Use the `winner` reward list to give something to each player.
{% endhint %}

## Players who are offline

Players who left the server before the end still get their rewards. The lines are saved with their values and run the next time the player joins (a couple of seconds after joining), with the message `You got rewards you won while you were offline.` Nothing is lost.

## The reward box

Items that do not fit in the inventory go to the player's **reward box**, never to the floor. The player is told: `Your inventory is full: 3 items went to your reward box. [/koth claim]` (one message for everything a reward gives at once, with the total).

<figure><img src="https://348500357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSlVHklG0EMAOmvfqcizu%2Fuploads%2FD4748ZVSolbUnUGhg7Vu%2Frnkoth-en-menu-claim.png?alt=media" alt="The reward box: click an item, or Take everything"><figcaption><p>The reward box: click an item, or Take everything</p></figcaption></figure>

* `/koth claim` opens the box. Click an item to take it, or **Take everything**.
* At least one free slot is needed.
* On join, players with items in the box get a reminder with an `[Open]` button.
* Each item is removed from the box before it is given, so it can never be taken twice. Items that still do not fit go back to the box.

Turn the command off with `rewards.claim-command: false` in `config.yml`. Then:

* `/koth claim` only answers `The reward box can't be opened with a command on this server.` (`claim.command-disabled`).
* The "inventory full" message and the reminder on join have no clickable button (`claim.stored-no-command` and `claim.waiting-no-command` in the language file).
* The box button is hidden in the `/koth` menu.
* `/koth open claim <player>` still opens the box for that player. Use it from an NPC (Citizens), a menu plugin or a sign, which run commands as the console.

{% hint style="warning" %}
With `claim-command: false`, items that do not fit still go to the box. Give players another way to open it (`/koth open claim <player>`), or keep the command on.
{% endhint %}