> ## Documentation Index
> Fetch the complete documentation index at: https://www.kitemc.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 奖励配置

<span id="奖励配置" />

奖励是玩家完成任务和达成等级后获得的回报，ArcPass 支持多种奖励类型。

<h2 id="文件位置">
  文件位置
</h2>

```
plugins/ArcPass/rewards/
├── default.yml     # 默认奖励定义
├── items.yml       # 物品奖励
├── economy.yml     # 经济奖励
├── titles.yml      # 称号奖励
└── ...
```

<h2 id="奖励类型">
  奖励类型
</h2>

| 类型 | 说明 | 依赖插件 |
| - | - | - |
| `ITEM` | 物品奖励 | 无 |
| `ECONOMY` | 金币/点券 | Vault / CMI |
| `COMMAND` | 执行命令 | 无 |
| `PERMISSION` | 权限节点 | LuckPerms |
| `TITLE` | 称号/前缀 | DeluxeTags / TAB |
| `COSMETIC` | 装饰品 | 自定义 |
| `EXPERIENCE` | 原版经验 | 无 |

<h2 id="基本结构">
  基本结构
</h2>

```yaml theme={null}
# rewards/items.yml

# 物品奖励示例
item_diamond_10:
  type: ITEM
  display-name: "&b钻石 x10"
  description: "获得 10 颗钻石"
  icon: DIAMOND
  value: "DIAMOND"
  amount: 10

# 经济奖励示例
economy_1000:
  type: ECONOMY
  display-name: "&6金币 x1000"
  description: "获得 1000 金币"
  icon: GOLD_BLOCK
  value: "1000"

# 称号奖励示例
title_champion:
  type: TITLE
  display-name: "&b冠军称号"
  description: "解锁「冠军」称号前缀"
  icon: NAME_TAG
  value: "&b[冠军] "
  data:
    priority: 60
```

<h2 id="物品奖励">
  物品奖励
</h2>

<h3 id="原版物品">
  原版物品
</h3>

```yaml theme={null}
reward_diamond_sword:
  type: ITEM
  display-name: "&b钻石剑"
  icon: DIAMOND_SWORD
  value: "DIAMOND_SWORD"
  amount: 1
```

<h3 id="oraxen-物品">
  Oraxen 物品
</h3>

```yaml theme={null}
reward_custom_sword:
  type: ITEM
  display-name: "&6传说之剑"
  icon: DIAMOND_SWORD
  value: "oraxen:legendary_sword"  # Oraxen 物品 ID
  amount: 1
```

<h3 id="itemsadder-物品">
  ItemsAdder 物品
</h3>

```yaml theme={null}
reward_magic_gem:
  type: ITEM
  display-name: "&d魔法宝石"
  icon: EMERALD
  value: "itemsadder:myitems:magic_gem"  # ItemsAdder 物品 ID
  amount: 5
```

<h3 id="自定义-nbt-物品">
  自定义 NBT 物品
</h3>

```yaml theme={null}
reward_custom_item:
  type: ITEM
  display-name: "&6特制工具"
  icon: DIAMOND_PICKAXE
  # 使用 give 命令格式
  value: "minecraft:diamond_pickaxe{Enchantments:[{id:efficiency,lvl:5}]}"
  amount: 1
```

<h2 id="自定义图标">
  自定义图标 v1.1.5
</h2>

默认情况下，`icon` 字段接受原版材料名（如 `DIAMOND`）。从 v1.1.5 起，你可以使用 **CustomModelData**、**ItemsAdder** 或 **Oraxen** 物品作为 GUI 图标。

<h3 id="custommodeldata">
  CustomModelData
</h3>

```yaml theme={null}
reward_exchange_card:
  type: ITEM
  display-name: "&e兑换卡"
  icon: PAPER
  custom-model-data: 10001    # CustomModelData 值
  value: "PAPER"
  amount: 5
```

<h3 id="itemsadder-图标">
  ItemsAdder 图标
</h3>

```yaml theme={null}
reward_magic_wand:
  type: ITEM
  display-name: "&d魔法杖"
  icon: "itemsadder:命名空间:物品ID"   # 使用 ItemsAdder 物品作为图标
  value: "itemsadder:命名空间:物品ID"
  amount: 1
```

<h3 id="oraxen-图标">
  Oraxen 图标
</h3>

```yaml theme={null}
reward_oraxen_gem:
  type: ITEM
  display-name: "&b水晶宝石"
  icon: "oraxen:crystal_gem"   # 使用 Oraxen 物品作为图标
  value: "oraxen:crystal_gem"
  amount: 1
```

<Tip>
  `icon` 字段控制 GUI 中的显示图标，`value` 字段控制玩家实际获得的内容，两者可以不同。
</Tip>

<h3 id="捕获任意物品作为图标">
  捕获任意物品作为图标 v1.9.2
</h3>

奖励编辑 GUI 可以将玩家主手中的任意物品捕获为奖励图标：

1. 在主手持有要作为图标的物品。
2. 左键点击奖励编辑器中的“图标”槽位。
3. 保存奖励。

捕获的图标会保留物品名称、Lore、附魔、CustomModelData 和其他自定义数据。右键点击图标槽位可以恢复该奖励类型的默认图标。图标只影响 GUI 显示，不会改变玩家实际获得的奖励。

<h2 id="物品预览槽位">
  物品预览槽位 v1.8.2
</h2>

在管理 GUI（`/arcpass admin rewards`）中编辑物品奖励时，你可以通过将物品点击到预览槽位来设置奖励的展示物品：

1. 打开奖励编辑 GUI，找到物品预览槽位（红色玻璃框内的空槽位）
2. 在你自己背包中**左键点击**任意物品 — 物品会粘在光标上
3. 将光标移动到预览槽位上方，再次**左键点击** — 物品即被捕获为奖励的展示物品

<Info>
  * 预览槽位始终显示**单个物品**，无论你放入的物品堆叠数量是多少
  * 实际发放**数量**由数量设置单独控制
  * 支持自定义 NBT、CustomModelData、附魔等物品
</Info>

<h2 id="经济奖励">
  经济奖励
</h2>

```yaml theme={null}
# 给予游戏币
reward_gold_1000:
  type: ECONOMY
  display-name: "&6金币 x1000"
  description: "获得 1000 金币"
  icon: GOLD_INGOT
  value: "1000"

# 给予点券（需要配置点券经济）
reward_points_100:
  type: ECONOMY
  display-name: "&e点券 x100"
  icon: SUNFLOWER
  value: "100"
  data:
    currency: "points"  # 自定义货币名称
```

<h2 id="命令奖励">
  命令奖励
</h2>

```yaml theme={null}
reward_announce:
  type: COMMAND
  display-name: "&e全服公告"
  icon: BOOK
  # %player% 会被替换为玩家名
  value: "broadcast &6恭喜 &e%player% &6达成成就！"

# 多条命令
reward_vip_package:
  type: COMMAND
  display-name: "&dVIP 礼包"
  icon: CHEST
  value: |
    give %player% diamond 64
    eco give %player% 10000
    lp user %player% permission set vip.access true
```

<h2 id="权限奖励">
  权限奖励
</h2>

需要 LuckPerms 插件：

```yaml theme={null}
# 永久权限
reward_fly_permission:
  type: PERMISSION
  display-name: "&b飞行权限"
  description: "解锁飞行能力"
  icon: FEATHER
  value: "essentials.fly"

# 临时权限
reward_temp_vip:
  type: PERMISSION
  display-name: "&eVIP 体验卡"
  description: "7 天 VIP 体验"
  icon: PAPER
  value: "group.vip"
  data:
    duration: 604800  # 秒（7天）

# 权限组
reward_rank_up:
  type: PERMISSION
  display-name: "&6晋升精英"
  icon: GOLDEN_HELMET
  value: "group.elite"
  data:
    type: group
```

<h2 id="称号奖励">
  称号奖励
</h2>

<h3 id="deluxetags-称号">
  DeluxeTags 称号
</h3>

```yaml theme={null}
reward_title_champion:
  type: TITLE
  display-name: "&6冠军称号"
  description: "解锁 [冠军] 称号"
  icon: NAME_TAG
  value: "&e[&6冠军&e] "
  data:
    tag-id: "champion"
    description: "战斗通行证最终奖励"
    priority: 100
    auto-equip: true
```

<h3 id="tab-称号-folia-兼容">
  TAB 称号（Folia 兼容）
</h3>

```yaml theme={null}
reward_title_legend:
  type: TITLE
  display-name: "&d传奇称号"
  icon: NAME_TAG
  value: "&5[&d传奇&5] "
  data:
    position: prefix  # prefix 或 suffix
    persistent: true
```

<h2 id="装饰品奖励">
  装饰品奖励
</h2>

```yaml theme={null}
reward_particle_flame:
  type: COSMETIC
  display-name: "&c火焰粒子"
  description: "身边环绕火焰粒子效果"
  icon: BLAZE_POWDER
  value: "particle_flame"
  data:
    cosmetic-type: particle
```

<h2 id="经验奖励">
  经验奖励
</h2>

给予原版 Minecraft 经验：

```yaml theme={null}
reward_mc_exp_100:
  type: EXPERIENCE
  display-name: "&a经验值 x100"
  icon: EXPERIENCE_BOTTLE
  value: "100"  # 经验点数
  # 或使用等级
  # data:
  #   type: levels
  #   value: 5
```

<h2 id="条件奖励">
  条件奖励
</h2>

设置奖励的领取条件：

```yaml theme={null}
reward_special:
  type: ITEM
  display-name: "&6特殊奖励"
  icon: NETHER_STAR
  value: "NETHER_STAR"
  amount: 1

  # 领取条件
  conditions:
    # 需要某个权限
    - type: permission
      permission: arcpass.reward.special

    # 背包有空位
    - type: inventory_space
      slots: 1
```

<h2 id="奖励组">
  奖励组
</h2>

将多个奖励打包：

```yaml theme={null}
reward_starter_pack:
  type: GROUP
  display-name: "&a新手礼包"
  description:
    - "&7包含以下物品:"
    - "&7- 钻石剑 x1"
    - "&7- 金币 x500"
  icon: CHEST
  rewards:
    - reward_diamond_sword
    - reward_gold_500
```

<h2 id="完整示例">
  完整示例
</h2>

```yaml theme={null}
# rewards/items.yml

# 新手物品
reward_starter_sword:
  type: ITEM
  display-name: "&f新手之剑"
  description: "踏上冒险之路的第一把武器"
  icon: IRON_SWORD
  value: "IRON_SWORD"
  amount: 1

# 中期奖励
reward_diamond_set:
  type: GROUP
  display-name: "&b钻石套装"
  description:
    - "&7完整的钻石装备"
  icon: DIAMOND_CHESTPLATE
  rewards:
    - reward_diamond_helmet
    - reward_diamond_chestplate
    - reward_diamond_leggings
    - reward_diamond_boots

# 最终奖励
reward_legendary_weapon:
  type: ITEM
  display-name: "&6传说武器"
  description:
    - "&7赛季最终奖励"
    - "&7独一无二的传说装备"
  icon: NETHERITE_SWORD
  value: "oraxen:legendary_blade"
  amount: 1
```

<h2 id="下一步">
  下一步
</h2>

<Columns cols={2}>
  <Card title="配置通行证" icon="ticket" href="/arcpass/config/passes">
    设置等级和档位
  </Card>

  <Card title="配置 GUI" icon="palette" href="/arcpass/config/gui">
    设置界面布局
  </Card>
</Columns>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.