> **Can't find what you're looking for?** Use `search_docs` on the docs MCP server at `https://aetherskywarswiki.netlify.app/api/mcp` to find what you need.

# Mystery box

A block players walk up to, pay coins at, and open for something random. It is a real block you
place, not a menu that appears out of nowhere, so it can be built into your lobby.

<img src="/box-open-flow.svg" alt="An open pays coins, spins the reels, and lands a reward or coins for a duplicate" />

There are no keys. A box costs coins, the same coins everything else costs, so a player who has been
playing can always open one. If you would rather sell access, give a rank a permission and set the
cost to 0.

Two files are involved. `mysterybox.yml` is what is inside the box, and you edit that.
`mysteryboxes.yml` is where the boxes you placed are standing, and the plugin writes that for you.

## Putting one down

| Command | What it does | Permission |
| --- | --- | --- |
| `/mysterybox` | Opens a box. Also `/box` and `/mbox`. | `asw.play` |
| `/asw mysterybox give` | Puts the placeable item in your inventory. | `asw.admin` |
| `/asw mysterybox remove` | Takes down the box you are looking at and gives the item back. | `asw.admin` |
| `/asw mysterybox list` | Every box you have placed, with its coordinates. | `asw.admin` |
| `/asw mysterybox reload` | Rereads `mysterybox.yml`. | `asw.admin` |

Run the give command, place the item where you want it, and it becomes a box: three lines of writing
float above it and purple particles ring the block. Players right click it to open one.

To take one down, look at it from within about six blocks and run the remove command. The block
goes, the writing goes, and the item comes back to your inventory, so putting one in the wrong spot
costs nothing.

:::tip
A placed box cannot be broken by hand, in creative, by an explosion or by a piston. Nothing in your
lobby can knock one over by accident, and the only way to take one down is the command.
:::

The item is marked in its own hidden data rather than by its name, so an ordinary ender chest is
still an ordinary ender chest, and renaming ours in an anvil changes nothing either way.

## What is inside it

```yaml
Cost: 500
Bulk-Amounts: [1, 5, 10]
Duplicate-Coins: 250
Opening-Effect: ENDER_SIGNAL
Opening-Ticks: 50
```

| Key | What it means |
| --- | --- |
| `Cost` | What one open costs, in coins or your Vault economy. |
| `Bulk-Amounts` | The buttons in the menu. Each costs its number times the cost. |
| `Duplicate-Coins` | Paid instead when a cosmetic comes up that the player already owns. |
| `Opening-Effect` | The show around the player while the box opens. |
| `Opening-Ticks` | How long it spins before it settles. Twenty ticks is one second. |

### Rarities

You choose how many there are and what they are called. A rarity decides the colour a reward reads
in, the show that plays when it comes up, and whether the whole server is told.

```yaml
Rarities:
  LEGENDARY:
    Displayname: 'Legendary'
    Colour: '&#FFC857'
    Effect: 'FIREWORK_SHOW'
    Broadcast: true
    Order: 4
```

Leave `Effect` blank for a quiet band, or a common reward sets off fireworks. `Broadcast` is meant
for the top band only, or it stops being special. `Order` is only used to show the odds in order.

### Rewards

```yaml
Rewards:
  dance_dragon:
    Rarity: LEGENDARY
    Type: COSMETIC
    Weight: 8
    Displayname: 'Dragon Flyby'
    Material: DRAGON_HEAD
    Category: Victory-Dances
    Item: item136
```

| Type | What it needs |
| --- | --- |
| `COINS` | `Amount`, paid straight into their balance. |
| `COSMETIC` | `Category` and `Item`, naming a section and an entry in `shops.yml`. |
| `ITEM` | `Material` and `Amount`, put in their inventory or dropped at their feet if it is full. |
| `COMMAND` | `Commands`, run from the console with `%player%` replaced. |

### How the odds work

Every reward has a `Weight`, not a percentage. A weight of 10 in a pool adding up to 100 comes up one
time in ten. Add another reward with weight 100 and the first is now one in twenty, and you did not
have to touch any other number.

Set a weight to 0 to keep a reward in the file but stop it ever coming up. If every weight is 0 the
box switches itself off and says so in the console, since otherwise it could never give anything.

The odds for each band are shown in the menu, worked out from the weights, so they are always what
the file actually says rather than a number somebody typed.

## What a player sees

The menu shows the odds, what one costs, and their own balance. Clicking a button takes the coins,
spins a row of reels that slows down, and settles on what they won.

A bulk open plays one show rather than one per box. Five rewards land side by side at the end and
five lines appear in chat. The rolling happens the moment the coins are taken, so what comes up
cannot change while the reels are spinning, but nobody watching can tell the difference.

Pulling something they already own pays `Duplicate-Coins` instead and says so, so a box is never a
wasted open.

If they cannot afford it, nothing is taken and nothing is rolled.