奖励怎么配

这一页讲宝箱里放什么、出现的概率、以及玩家实际能拿到什么。全部写在宝箱文件的 claim 节点下。

先看整体结构

claim:
  key: 1              # 哪个字符是奖励槽位
  amount: 3           # 这次开箱生成几件奖励
  layout: random      # 奖励怎么摆
  generator:          # 奖励池：可能出现哪些奖励
    diamond:
      chance: 20
      material: "diamond"
      amount: 1
    iron:
      chance: 80
      material: "iron_ingot"
      amount: 3~5

理解这几个的关系很重要：

generator 是奖励池，列出所有可能出现的奖励
amount 决定这次从池子里抽几件
key 和 layout 决定抽出来的东西摆在界面哪里

上面这个配置的效果：每次开箱抽 3 件奖励，每件有 20% 概率是钻石、80% 概率是铁锭，随机摆在界面的奖励槽位里。

key：奖励放在哪些格子

key 对应 layout 里的一个字符：

layout:
  - '#########'
  - ' 1111111 '
  - '#########'

claim:
  key: 1

这样第二行中间的 7 个格子就是奖励槽位。

amount：抽几件

claim:
  amount: 3        # 固定 3 件
  amount: 3~8      # 3 到 8 件之间随机

不能超过槽位数量

amount 抽出来的值不能大于布局里奖励槽位的总数。

上面那个布局只有 7 个奖励槽位，如果写 amount: 10，开箱时会失败，控制台输出 claim.amount=10 超过布局中的可用奖励槽位 7，玩家右键宝箱时箱子会变回真实方块。

配之前先数一下布局里有几个奖励字符。

amount: 0 是合法的，效果是界面能打开但里面没有奖励。

layout：怎么摆

值	效果
`random`	随机分布在奖励槽位里，每次位置都不一样
`order`	从第一个槽位开始按顺序摆

random 更有开箱的感觉，order 适合做固定奖励展示。

generator：奖励池

每一个子项就是一种可能的奖励。名字（下面例子里的 diamond、iron）随便起，只是给你自己看的标识。

  generator:
    diamond:
      chance: 20
      material: "diamond"
      amount: 1
      give: source
      name: "&b稀有奖励"
      lore:
        - "&7恭喜你抽到了钻石"

chance：权重

这个数字不是百分比，是相对权重。

    diamond:
      chance: 20
    iron:
      chance: 50
    gold:
      chance: 30

加起来是 100，所以概率刚好是 20%、50%、30%。

但如果你写成 2、5、3，概率完全一样，因为比例没变。所以不需要凑成 100，按相对大小写就行。

chance 必须大于 0

写 chance: 0 会导致开箱失败，控制台输出 claim.generator.xxx.chance 必须大于 0。

想临时禁用某个奖励，把整段注释掉或者删掉，不要写 0。

material：物品从哪来

最简单的情况，写原版物品 ID：

      material: "diamond"
      material: "iron_ingot"
      material: "enchanted_golden_apple"

想用其他插件的物品，写成 前缀: 物品ID：

      material: "mm: my_mythic_item"      # MythicMobs
      material: "ia: namespace:item_id"   # ItemsAdder
      material: "zap: my_item"            # Zaphkiel

完整的前缀列表在奖励系统那一页。

物品源写错会让宝箱打不开

这里的物品是严格检查的。如果出现下面任何一种情况，整个宝箱界面会构建失败：

写了 mm: 但服务器没装 MythicMobs
装了插件但那个物品 ID 不存在
原版材质名拼错了

控制台会输出 构建宝箱 XXX 的 GUI 失败 以及具体原因。它不会悄悄换成别的物品，所以配完记得实际开一次试试。

amount：数量

      amount: 1        # 固定 1 个
      amount: 3~8      # 3 到 8 个随机

必须在 1 到 2304 之间。

超过一组会怎样

界面里显示的数量最多是这个物品的堆叠上限（大部分物品是 64）。但玩家实际领取时会拿到完整数量，插件会自动拆成多组给。

比如配 amount: 100 的铁锭，界面上显示 64 个，实际领到手是 100 个。

give：玩家实际拿到什么

这个选项经常被误解，但它很重要：

值	玩家拿到	什么时候用
`source`	物品源里原始的物品	大部分情况用这个
`display`	界面上显示的那个物品	想让玩家拿到改过名字和描述的版本
`none`	什么都没有	做纯展示、或者靠脚本发奖励

举个例子说明 source 和 display 的区别：

    diamond:
      chance: 100
      material: "diamond"
      amount: 1
      name: "&b神秘钻石"
      lore:
        - "&7来自宝箱"
      give: source     # 玩家拿到普通钻石
      # give: display  # 玩家拿到名字叫"神秘钻石"、带描述的钻石

用 source 时，改名字和描述只影响界面显示，起到"预告"作用，玩家拿到的是干净的原版物品。这通常是你想要的效果。

give: none 的用法

配 none 时物品点击后直接消失，玩家什么都拿不到。它的用途是配合 actions 脚本：让脚本去发钱、给称号、执行命令，物品本身只是个"按钮"。

name 和 lore：显示效果

      name: "&e生成了 {name}"
      lore:
        - "&7这是第一行描述"
        - "&7这是第二行描述"

{name} 会被替换成这个物品在物品源里的 ID。不写 name 就保持原物品的名字。

两者都支持 & 颜色代码和 PlaceholderAPI 变量。

display：描述怎么处理

控制你写的 lore 和原物品自带描述的关系：

值	效果
`overwrite`	用你的 lore 覆盖掉原有的（默认）
`add`	追加在原有描述后面
`clear`	清空所有描述
`insert:3`	插入到第 3 行

      display: add
      lore:
        - "&7—— 来自每日宝箱"

这样配的话，MythicMobs 物品原本的属性描述会保留，只在最后加一行来源说明。

overwrite 的一个细节

overwrite 只在你确实写了 lore 的时候才清空原描述。如果 lore 是空的或者没写，原描述会保留不变。

unique：不重复出现

      unique: true

默认情况下同一个奖励可以在一次开箱里出现多次。设成 true 后，它被抽中一次就从池子里移除，本次开箱最多出现一次。

全部设 unique 时注意数量

如果所有奖励都是 unique: true，那 claim.amount 不能超过奖励的种类数。

比如你有 3 种奖励全部 unique，但 amount: 5，池子会提前抽空，开箱失败并输出 claim.amount=5 无法由 3 个 unique 生成器满足。

flags：隐藏物品信息

      flags:
        - 'hide_attribute'
        - 'hide_enchants'

隐藏物品的属性、附魔之类的信息，让界面干净一些。常用的有 hide_attribute、hide_enchants、hide_unbreakable。

nbt：自定义数据

      nbt:
        my_tag: "my_value"
        nested:
          inner: 123

给物品写入自定义 NBT，通常用来和其他插件配合识别。不需要的话不用管。

actions：点击时执行脚本

      actions:
        left: |-
          tell "&a你左键领取了这件奖励"
        right: |-
          tell "&a你右键领取了这件奖励"
        all: |-
          tell "&7不管左右键都会执行"

&amount 变量能拿到这次领取的数量：

      actions:
        all: |-
          tell inline "&a领取了 {{ &amount }} 个"

自动领取

默认情况下玩家必须逐个点击才能拿到奖励。想让关闭界面时自动领走剩下的：

events:
  close: |-
    tsl-claim

强烈建议加上这一句，否则玩家不小心按 ESC 就白开了一次箱子。

完整示例

一个三档奖励的每日宝箱：

title: "&6&l每日宝箱"

layout:
  - '#########'
  - ' 1111111 '
  - ' 1111111 '
  - '#########'

settings:
  block: "CHEST"
  lock_inventory: true

events:
  close: |-
    tsl-claim

claim:
  key: 1
  amount: 4~6
  layout: random
  generator:
    # 稀有：钻石，唯一
    diamond:
      chance: 10
      unique: true
      give: source
      material: "diamond"
      amount: 1~2
      name: "&b&l稀有奖励"
      display: add
      lore:
        - "&7运气不错"

    # 普通：铁锭
    iron:
      chance: 55
      give: source
      material: "iron_ingot"
      amount: 3~8

    # 中等：金锭
    gold:
      chance: 35
      give: source
      material: "gold_ingot"
      amount: 2~5

icons:
  '#':
    material: "GRAY_STAINED_GLASS_PANE"
    name: " "

这份配置的行为：每次开箱生成 4 到 6 件奖励，钻石只可能出现一次且概率最低，玩家关闭界面时自动领走没点的。

背包满了怎么办

领奖励时如果玩家背包满了，物品会掉在脚下。

config.yml 里的 drop_owner: true（默认开启）能让这些掉落物只有该玩家能捡，避免被旁边的人捡走。建议保持开启。

先看整体结构​

key：奖励放在哪些格子​

amount：抽几件​

layout：怎么摆​

generator：奖励池​

chance：权重​

material：物品从哪来​

amount：数量​

give：玩家实际拿到什么​

name 和 lore：显示效果​

display：描述怎么处理​

unique：不重复出现​

flags：隐藏物品信息​

nbt：自定义数据​

actions：点击时执行脚本​

自动领取​

完整示例​

背包满了怎么办​