奖励系统

概述

奖励配置在宝箱文件的 claim 节点下。插件使用权重随机从 generator 中抽取物品，放入 GUI 的指定槽位供玩家领取。

基本结构

claim:
  # 布局内可领取的物品编号（对应 layout 中的字符）
  key: 1

  # 生成的物品数量，支持范围写法
  amount: 3~8

  # 物品布局方式
  # random    随机分布
  # order     顺序分布
  layout: random

  generator:
    # 自定义编号（可以有多个）
    custom:
      chance: 30
      display: overwrite
      give: none
      unique: true
      material: "mm: treasure"
      amount: 1~3
      name: "生成了 {name}"
      flags:
        - 'hide_attribute'
      nbt:
        c1:
          c2: 'xxx'
      lore:
        - "被覆盖的lore"
      actions:
        left: |-
          tell "获取了"

generator 配置详解

每个 generator 条目代表一种可能的奖励物品：

配置项	说明
`chance`	权重值（整数），值越大被抽中的概率越高。必须大于 0
`material`	物品来源，格式为 `来源: 物品ID`，详见下方物品源表
`amount`	物品数量，支持 `最小~最大` 范围写法，如 `1~3`。必须落在 `1~2304` 之间
`name`	显示名称，留空则不修改。`{name}` 会替换为该物品在物品源里的 ID
`lore`	显示 Lore 列表
`flags`	ItemFlag 列表，如 `hide_attribute`
`nbt`	自定义 NBT 数据
`unique`	是否唯一生成（默认 false），设为 true 则该奖励在一次开箱中最多出现一次
`display`	显示规则，控制 Lore 如何处理
`give`	给予规则，控制玩家实际获得什么物品
`actions`	点击动作，支持按点击类型绑定 Kether 脚本

display 显示规则

值	说明
`overwrite`	覆盖源物品的 Lore
`add`	在源物品 Lore 末尾追加
`clear`	清空 Lore
`insert:N`	在第 N 行插入 Lore。N 必须是非负整数；超过现有行数时追加到末尾

overwrite 只在你确实写了 lore 时才会清空原有 Lore；lore 为空时保留源物品 Lore 不变。

give 给予规则

值	说明
`none`	点击后物品消失，不给予任何物品
`source`	给予 material 生成的原始物品
`display`	给予 GUI 中显示的物品（经过 name/lore 修改后的）

actions 点击动作

支持按点击类型绑定不同的 Kether 脚本：

actions:
  left: |-
    tell "左键获取了"
  right: |-
    tell "右键获取了"
  all: |-
    tell "任意点击都会执行"

all 键表示任意点击类型都会执行。Kether 脚本中可使用 &amount 变量获取物品数量。

物品源

通过 material 字段指定物品来源，格式为 来源前缀: 物品ID。不写前缀则默认为原版物品。

来源	前缀	别名	格式示例
Minecraft 原版	`minecraft`	`mc`	`stone` 或 `minecraft: stone`
MythicMobs	`mythicmobs`	`mm`, `mythic`	`mm: treasure`
Zaphkiel	`zaphkiel`	`zap`, `zl`	`zap: itemID`
ItemsAdder	`itemsadder`	`ia`	`ia: namespace:itemID`
MMOItems	`mmoitems`	`mi`, `mmo`	`mi: SWORD,itemID`
NeigeItems	`neigeitems`	`ni`	`ni: itemID`
Oraxen	`oraxen`	`ox`	`ox: itemID`
SX-Item	`sxitem`	`sx`, `si`	`sx: itemID:key1:value1`
CraftEngine	`craftengine`	`ce`	`ce: namespace:itemID`
PxRpg	`pxrpg`	`pr`	`pr: item:itemID` 或 `pr: equip:itemID` 或 `pr: gem:itemID`
AzureFlow	`azureflow`	`af`	`af: itemID`

物品源为软依赖，只有服务器安装了对应插件才会自动挂钩。启动时控制台会打印 已挂钩软依赖 XXX 作为物品源，据此可以确认哪些源可用。

物品源缺失会导致整个宝箱打不开

claim.generator 和 icons 里的物品采用严格解析：如果写的前缀对应插件没装（未挂钩），或该 ID 在物品库里不存在，插件会直接抛出异常，导致这个宝箱的界面构建失败，虚拟方块被还原为真实方块，控制台输出 构建宝箱 <ID> 的 GUI 失败。

它不会静默退回成原版物品或基岩。配置奖励前请先确认对应物品插件已安装且 ID 正确。

权重计算

权重是相对值。例如有三个奖励，权重分别为 30、50、20，则：

奖励 A 概率 = 30 / (30+50+20) = 30%
奖励 B 概率 = 50 / (30+50+20) = 50%
奖励 C 概率 = 20 / (30+50+20) = 20%

抽取是有放回的：默认同一个奖励可以在一次开箱中被抽中多次。设置 unique: true 的奖励被抽中后会从候选池移除，本次开箱最多出现一次。

数量与槽位的关系

claim.amount 决定这次开箱生成几个奖励，每个奖励各占一个槽位：

claim.amount 抽出的值不能超过 layout 里 claim.key 字符的总数，超了会导致宝箱界面构建失败
如果所有 generator 都是 unique: true，claim.amount 还不能超过 generator 的个数，否则候选池会提前耗尽
claim.amount 为 0 时不生成任何奖励，界面仍会正常打开

单个 generator 的 amount 是该物品的堆叠数量。界面里显示的数量会被压到该物品的最大堆叠上限，但实际发给玩家时按配置的完整数量拆成多组给出。

物品掉落

当玩家背包满时，领取的物品会掉落到地面。如果 config.yml 中 drop_owner 设为 true，掉落的物品只有该玩家能拾取。

概述​

基本结构​

generator 配置详解​

display 显示规则​

give 给予规则​

actions 点击动作​

物品源​

权重计算​

数量与槽位的关系​

物品掉落​

概述