> For the complete documentation index, see [llms.txt](https://enchantedmobs.superiormc.cn/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://enchantedmobs.superiormc.cn/for-ultimatequest/configuration/rewards.md).

# Reward Configuration

Each named `rewards` entry needs a supported `type`. Tasks, periods, scrolls, battle-pass tracks, and milestone stages share this format.

| Type                    | Fields / behavior                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `item`                  | `item`: [ItemFormat](/for-ultimatequest/shared-formats/itemformat-tm.md). Inventory overflow drops. |
| `console_command`       | Nonblank `command`, no `/`; supports `{player}`, `{uuid}`, `{quest}`.                               |
| `message`               | String `message`, sent through the action system.                                                   |
| `battlepass-experience` | Existing `battlepass` ID and positive integer `amount`.                                             |
| `random`                | Inline `random` choices or an external `pool`.                                                      |

`display.name`/`display.lore` override generated previews. `reference: <id>` replaces the entire entry using `config.yml -> reward-library.<id>`, without merging overrides.

## Random groups

```yaml
rewards:
  supplies:
    type: random
    count: 2
    repeat: false
    random:
      food:
        rate: 70
        rewards:
          bread:
            type: item
            item: {material: BREAD, amount: 8}
      iron:
        rate: 25
        rewards:
          ingots:
            type: item
            item: {material: IRON_INGOT, amount: 4}
      treasure:
        rate: 5
        rewards:
          gem:
            type: item
            item: {material: DIAMOND, amount: 1}
```

The example draws two groups and grants every reward in each selected group. `count` defaults to 1 (positive integer), `repeat` to false (boolean). Weights are relative finite nonnegative numbers, with finite positive total; zero weights are excluded. Without replacement, count cannot exceed positive-weight choices. `repeat: true` permits repeated grants. Same-named nested rewards in different draws do not overwrite one another.

Random groups can nest up to 8 random levels. Invalid configuration is reported through `ErrorManager` and rejected. Multi-draw previews show weights; single-draw previews may show probabilities.

## External reward pools

A file `reward-pools/<id>.yml` contains `enabled: true` and `rewards.<choice>.rate` / `rewards.<choice>.rewards`. Its `rewards` section is the same choice map as the inline `random` node above. Use:

```yaml
rewards:
  supply:
    type: random
    pool: scroll_novice
    count: 3
    repeat: false
```

`pool` and inline `random` are mutually exclusive. Pool IDs use lowercase letters, digits, `_`, `-`. Referenced pools must exist and be enabled. Nested references are expanded before validation; missing/cyclic/overdeep references reject loading. Objective pools under `pools/` use a different format. `/uq editor reward-pool` edits reward pools.

## Snapshots and claiming

Normal acceptance and periodic assignment creation resolve random rewards into `rewards-snapshot`. Scroll issuance saves its objective/reward definition; its first activation creates the instance and draws the random outcome. Stage rewards resolve at unlock. Existing-instance previews show fixed outcomes; reconnects/reloads do not redraw.

Claims persist an intermediate state before delivery. Failed delivery/final saving may require review. Commands/external effects cannot roll back as one database transaction. Inspect actual delivery before resolving `CLAIMING`/`REVIEW`; marking available can allow another grant.

## 📚 Reference pages

* [Item, command, and message rewards](/for-ultimatequest/configuration/rewards/items-commands.md)
* [Progression rewards](/for-ultimatequest/configuration/rewards/progression.md)
* [Random rewards](/for-ultimatequest/configuration/rewards/random.md)
* [Reward pools and references](/for-ultimatequest/configuration/rewards/pools.md)