> 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/ultimatequest-zhong-wen-wen-dang/pei-zhi/rewards.md).

# 奖励配置

`rewards` 下每个具名条目需要支持的 type。普通任务、周期、卷轴、战令轨道和里程碑阶段共用此格式。

| 类型                      | 字段/行为                                                                                              |
| ----------------------- | -------------------------------------------------------------------------------------------------- |
| `item`                  | `item`：[ItemFormat](/ultimatequest-zhong-wen-wen-dang/gong-gong-ge-shi/itemformat-tm.md)，背包放不下时掉落。 |
| `console_command`       | 非空 command，不带 `/`，支持 `{player}`、`{uuid}`、`{quest}`。                                                |
| `message`               | 字符串 message，通过动作系统发送。                                                                              |
| `battlepass-experience` | 现有 battlepass ID 与正整数 amount。                                                                      |
| `random`                | 内联 random 选项或外部 pool。                                                                              |

`display.name`/`display.lore` 覆盖自动预览。`reference: <id>` 使用 `config.yml -> reward-library.<id>` 替换整个条目，不合并覆盖。

## 随机组

```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}
```

示例抽两组，发放每个抽中组的全部奖励。count 默认 1（正整数），repeat 默认 false（布尔值）。权重为有限非负数，总和为有限正数；0 权重排除。不重复时 count 不超过正权重选项数；repeat: true 允许重复发放。不同轮次的同名嵌套奖励不覆盖。

随机组最多嵌套 8 层，非法配置通过 ErrorManager 报错并拒绝加载。多项预览显示权重，单项可显示概率。

## 外部奖励池

`reward-pools/<id>.yml` 包含 enabled: true 和 `rewards.<选项>.rate` / `rewards.<选项>.rewards`，其 rewards 与上例内联 random 的选项映射相同。引用方式：

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

pool 与内联 random 互斥。ID 使用小写字母、数字、下划线、短横线。引用池必须存在且启用。嵌套引用先展开再校验，缺失/循环/过深引用会拒绝加载。`pools/` 下的目标池格式不同。用 `/uq editor reward-pool` 编辑奖励池。

## 快照与领奖

普通任务接取、周期实例创建时将随机结果写入 rewards-snapshot；卷轴发放保存目标/奖励定义，首次激活创建实例时抽取随机结果。阶段奖励在解锁时解析。实例预览显示固定结果，重登/重载不重抽。

领奖先保存中间状态，再发放。发放/最终保存失败可能需复核。命令和外部效果不能作为同一数据库事务回滚；解决 CLAIMING/REVIEW 前先核对实际发放，设回可领取可能再次发奖。

## 📚 参考页面

* [物品、命令与消息奖励](/ultimatequest-zhong-wen-wen-dang/pei-zhi/rewards/items-commands.md)
* [成长奖励](/ultimatequest-zhong-wen-wen-dang/pei-zhi/rewards/progression.md)
* [随机奖励](/ultimatequest-zhong-wen-wen-dang/pei-zhi/rewards/random.md)
* [奖励池与引用](/ultimatequest-zhong-wen-wen-dang/pei-zhi/rewards/pools.md)