> For the complete documentation index, see [llms.txt](https://darkstarworks.gitbook.io/plugins/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://darkstarworks.gitbook.io/plugins/mc/mt-documentation/rewards-yml.md).

# rewards.yml

Four independent reward channels fire when a chamber is cleared, once per participant. Each is toggleable and scales with the tier the player cleared at (their tier *before* the bump — the difficulty they actually beat).

## Format

```yaml
on-chamber-cleared:

  xp-orbs:
    enabled: true
    base: 50
    per-tier-bonus: 25            # total = base + tier_rank × per-tier-bonus

  vault-currency:
    enabled: true
    base: 100.0
    per-tier-bonus: 50.0

  legendary-key:
    enabled: true
    min-tier: "T5"               # T1..T20 or M1..M5
    crate: "platinum"            # crate id from TCP-VaultCrates
    tier: "ominous"              # "normal" | "ominous"
    chance-per-tier: 0.05

  leaderboard:
    enabled: true
```

## Tier rank

Rewards scale by **tier rank** — a single number across both ranges:

* T1 = 1, T2 = 2, … T20 = 20
* M1 = 21, M2 = 22, … M5 = 25

So `base + rank × per-tier-bonus` grows smoothly from Standard into Mythic.

## The channels

### XP orbs

Gives `base + rank × per-tier-bonus` experience to the player. With the defaults, a T5 clear pays 50 + 5×25 = **175 XP**; an M5 clear pays 50 + 25×25 = **675 XP**.

### Vault currency

Deposits `base + rank × per-tier-bonus` via Vault. **Requires Vault + an economy plugin** — no-ops silently otherwise. Same formula as XP.

### Legendary key

On a successful roll, drops one crate key at the player's feet. **Requires TCP-VaultCrates.**

* **`min-tier`** — below this tier, the key never drops.
* **`chance-per-tier`** — the roll chance is `(rank − min_tier_rank + 1) × chance-per-tier`, capped at 100%. With `min-tier: T5` and `chance-per-tier: 0.05`: a T5 clear is 5%, T20 is 80%, M5 is capped at 100%.
* **`crate` / `tier`** — which VaultCrates crate + key tier to drop.

### Leaderboard

Writes a row to the season completion log (used by `/tcpmt leaderboard` and the GUI). **Only records while a season is active.** Unlike the other three, this credits offline participants too — someone who cleared then logged off still gets the entry.

## Threading & safety

Rewards that touch the world (XP, currency, key drop) are applied on the player's region thread, so they're Folia-safe. The leaderboard write goes through the plugin's own database off the main thread. Every channel checks its backing plugin is present before doing anything.

***

Next: [**Commands & permissions →**](/plugins/mc/mt-documentation/commands-and-permissions.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://darkstarworks.gitbook.io/plugins/mc/mt-documentation/rewards-yml.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.