I. Enabling and Usage

The 3.0.0 mystery box is configured separately in box.yml and is disabled by default. Set enabled to true, save, then use /cpp reload to reload.

/cpp giveItem playerName companionToken 1

1. With the mystery box in the main hand, right-click a block to draw a companion and consume one box.
2. Sneak right-click a block to open the preview screen without consuming a box; the screen is configured in gui/box.yml.
3. The drawn companion goes into the warehouse and does not automatically replace the currently used companion.

With the warehouse capacity limit enabled, leave an empty slot before opening. In the current version, opening consumes the item first, so you may fail to receive a companion when the warehouse is full.

II. Configuration Example

Below is one box in box.yml. More boxes can be added under boxes, and the key is used for the give command.

enabled: true
boxes:
  companionToken:
    name: "&6Companion Mystery Box"
    material: GHAST_TEAR
    custom-model-data: 0
    isEnchant: true
    tooltipStyle: ""
    itemModel: ""
    description:
      - "&7Hold in main hand, right-click a block to open"
      - "&7Sneak right-click a block to preview"
    particleAnimation: ""
    soundOnUse: BLOCK_BEACON_POWER_SELECT
    types: {}
    keys: {}
    blacklist: []

• material: item material; 3.0.0 uses this node instead of the old item config's type.
• custom-model-data: custom model data, effective on 1.14+, 0 means not set.
• isEnchant: whether to show the enchant glow.
• tooltipStyle, itemModel: tooltip style and item model, effective on 1.21.2+.
• particleAnimation, soundOnUse: opening particles and sound, leave empty to disable; names must match the server version.

III. Draw Range and Weights

The draw range is filtered by types, keys and blacklist in order:

1. types: companion types and their weights; empty means no type restriction.
2. keys: companion keys and their weights; empty means no companion restriction; once filled, only the listed companions enter the draw pool.
3. blacklist: companion key blacklist, with the highest priority.

The companion type is specified at the top of companions/*.yml via type; the type inside a single companion node can override it, and it defaults to default when neither is configured.

# Configured inside the box node; types and companion keys must match the actual companion config
types:
  default: 80
  event: 20
keys:
  reaper: 60
  fire_dragon: 40
blacklist:
  - slime

When both types and keys are configured, a type is drawn by type weight first, then a companion is drawn by companion weight within that type. Weights do not need to sum to 100 and are not each companion's final percentage. When no companion matches the conditions, the box cannot be opened.

The legacy config.yml items must be changed to the new box.yml configuration. After migrating or changing the box appearance, reissue the items with the new command to avoid item recognition differences.