一、开启与使用

3.0.0 的神秘箱单独在 box.yml 配置，默认关闭。将 enabled 设为 true，保存后使用 /cpp reload 重载。

/cpp giveItem 玩家名 companionToken 1

1. 玩家主手持神秘箱，右键方块抽取一个精灵并消耗一个箱子。
2. 潜行右键方块打开预览界面，不消耗箱子；界面在 gui/box.yml 配置。
3. 抽到的精灵进入仓库，不会自动替换当前使用的精灵。

开启仓库容量限制后，请先留出空位再开箱；当前版本开箱会先消耗物品，满仓时可能无法获得精灵。

二、配置示例

以下为 box.yml 中的一个箱子，可在 boxes 下增加其他箱子，key 用于发放指令。

enabled: true
boxes:
  companionToken:
    name: "&6精灵神秘箱"
    material: GHAST_TEAR
    custom-model-data: 0
    isEnchant: true
    tooltipStyle: ""
    itemModel: ""
    description:
      - "&7主手持有，右键方块打开"
      - "&7潜行右键方块预览"
    particleAnimation: ""
    soundOnUse: BLOCK_BEACON_POWER_SELECT
    types: {}
    keys: {}
    blacklist: []

• material：物品材质，3.0.0 使用此节点，不再使用旧版物品配置中的 type。
• custom-model-data：自定义模型数据，1.14+ 生效，0 表示不设置。
• isEnchant：是否显示附魔光效。
• tooltipStyle、itemModel：工具提示样式和物品模型，1.21.2+ 生效。
• particleAnimation、soundOnUse：开箱粒子和音效，留空关闭；名称需符合服务器版本。

三、抽取范围与权重

抽取范围按 types、keys、blacklist 依次筛选：

1. types：精灵类型及权重，留空表示不限类型。
2. keys：精灵 key 及权重，留空表示不限精灵；填写后仅列出的精灵进入抽取池。
3. blacklist：精灵 key 黑名单，优先级最高。

精灵类型在 companions/*.yml 顶部通过 type 指定，单个精灵节点中的 type 可以覆盖它，都未配置时为 default。

# 在箱子节点内配置，类型和精灵 key 需与实际精灵配置对应
types:
  default: 80
  event: 20
keys:
  reaper: 60
  fire_dragon: 40
blacklist:
  - slime

同时配置 types 和 keys 时，先按类型权重抽取类型，再在该类型内按精灵权重抽取。权重不需要合计为 100，不是各精灵的最终百分比。没有符合条件的精灵时无法开箱。

旧版 config.yml 的 items 需改为新版 box.yml 配置。迁移或更改箱子外观后，建议用新版指令重新发放物品，避免物品识别差异。