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

# Rewards

`rewards.yml` decides what winners get. Rewards can be different for each game and for each place (1st, 2nd, 3rd...).

<figure><img src="https://348500357-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FSlVHklG0EMAOmvfqcizu%2Fuploads%2FIZgDsaRVv7es6Yhj3tNE%2Frncg-real-16.png?alt=media" alt="Message of a default reward"><figcaption><p>Message of a default reward</p></figcaption></figure>

## Which list is used

The first one that exists:

1. `games.<game>.<place>` — e.g. `games.math.1`
2. `games.<game>.any`
3. `default.<place>`
4. `default.any`

`<place>` is `1` for the first winner, `2` for the second... (see `winners` of each game). `any` is used for places without their own list.

```yaml
default:
  1:
    - '[console] give {player} diamond {random:1-3}'
    - '[message] {prefix}<gray>You won <aqua>diamonds</aqua>!'
  any:
    - '[console] give {player} iron_ingot {random:2-5}'

games:
  variable:
    1:
      - '[console] give {player} diamond {random:3-5}'
```

## Actions

| Action                             | What it does                                                                                             |
| ---------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `[console] <command>`              | Runs a command from the console (the default when no action is written)                                  |
| `[player] <command>`               | The winner runs the command                                                                              |
| `[message] <text>`                 | Message to the winner                                                                                    |
| `[broadcast] <text>`               | Message to everyone                                                                                      |
| `[actionbar] <text>`               | Action bar to the winner                                                                                 |
| `[title] <title>;<subtitle>`       | Title to the winner                                                                                      |
| `[sound] <sound> [volume] [pitch]` | Sound to the winner                                                                                      |
| `[item] <item> [amount] [name]`    | Gives an item, with an optional name (colors allowed). What does not fit is dropped at the player's feet |

```yaml
- '[item] diamond_sword 1 <gold>Chat Champion'
- '[sound] minecraft:entity.player.levelup 1 1'
- '[title] <gold>Winner!;<gray>Well played'
```

## Conditions

Written **before** the action:

| Condition                |                                       |
| ------------------------ | ------------------------------------- |
| `[chance:25]`            | Only 25% of the times                 |
| `[permission:group.vip]` | Only if the winner has the permission |

```yaml
- '[chance:10] [permission:group.vip] [console] give {player} diamond 5'
```

A chance in a line only applies to **that** line: two lines with `[chance:10]` are rolled separately.

## Groups: several actions with one roll

All of them happen, or none:

```yaml
- chance: 10                    # optional
  permission: group.vip         # optional
  actions:
    - '[console] give {player} emerald 5'
    - '[message] <gold>Lucky! You also got 5 emeralds.'
```

## Pick one: weighted rewards

Exactly **one** of the options happens, chosen by weight (70 + 25 + 5 = 100 → 70%, 25%, 5%):

```yaml
- pick-one:
    - weight: 70
      actions:
        - '[item] iron_ingot 5'
    - weight: 25
      actions:
        - '[item] diamond 2'
    - weight: 5
      permission: group.vip       # optional: only players with it can get this one
      actions:
        - '[item] netherite_ingot 1'
        - '[broadcast] {prefix}<light_purple>{player} got the epic reward!'
```

## Placeholders

`{player}`, `{game}`, `{answer}`, `{time}`, `{place}`, `{place_name}`, `{points}`, `{prefix}` and PlaceholderAPI placeholders.

`{random:1-5}` is a random number between 1 and 5, rolled separately each time it appears.

## Economy example

With an economy plugin (EssentialsX + Vault):

```yaml
games:
  math:
    1:
      - '[console] eco give {player} {random:50-150}'
      - '[message] {prefix}<green>+ money for solving {answer}!'
```

## Players who leave

If the winner leaves before getting the rewards (or right after winning), the commands, items and messages are kept and given the next time they join, with the message `pending-rewards`. They are saved in the database, so a restart does not lose them.

A player who dies right as they win (the death screen still lets them type for a moment) keeps the rewards: items and commands are given and kept after they respawn.

{% hint style="warning" %}
A command that takes the player off the server (`kick`, sending them to another server of the network...) goes **last** in the list. On Folia the commands after it may reach the player while they are leaving, and what they give is lost.
{% endhint %}