# 📦 Crates

## Add Crate

Click the stained glass to create a crate.

<figure><img src="../../.gitbook/assets/Screenshot 2025-01-10 181128 (1).png" alt="" width="563"><figcaption><p>Editor > Crates</p></figcaption></figure>

## Placed Crates

Creating a crate only defines it. A crate becomes real in the world once you place it, either with `/crates giveCrate` and putting the block down, or with [Attach Block](#attach-block) on a block that is already there.

<figure><img src="../../.gitbook/assets/editor/crates/placed-crates.png" alt="" width="563"><figcaption><p>Crates (Placed Crates)</p></figcaption></figure>

Every placement is stored in locations.yml, which is the file holding where each crate sits in the world, with its coordinates and the direction it faces. The same crate can be placed as many times as you want, and all of those placements live in that one file. See [File Structure](../../configurations/crate-configuration-file.md#file-structure) for the rest of the plugin's files.

The **Placed Crates** button in the crates menu lists every placement that is currently loaded. From there you can teleport in front of a crate or remove it, which also drops it from `locations.yml`. Crates that are disabled, or sit in a world that is not loaded, are not listed.

> **Warning:**
Deleting `locations.yml` leaves every crate configured but no longer placed anywhere, and moving a setup to another server needs that file copied across together with the worlds it points at.

### Protection

Placed crates can't be blown up by creepers, TNT or beds, moved by pistons, burned, washed away, taken by endermen or changed by any other non-player cause. Only an admin crouching and breaking it removes a crate. If a crate's block disappears anyway, for example after a WorldEdit paste, it is put back with its hologram the next time its chunk loads.

### Test Open ⭐

**Test Open** in the crate editor, or `/crates testOpen <crate>`, plays the opening of the nearest placed crate of that type for you, within 16 blocks. No key or money is used, nothing is given, and stats, win limits, cooldowns, milestones and broadcasts stay as they were. Chat marks it as a test and lists the rewards you would have won.

> **Info:**
This feature is only available with the Premium Plan.

The crate's engine, animations, rewards and rewards mode have their own pages: [Crate Block Engine](../crate-engine-mode/README.md), [Animations](../animations/README.md), [Rewards](../rewards/README.md), [Rewards Mode](../rewards-mode/README.md), [Guaranteed Rewards](../../features/guaranteed-rewards.md) and [Reroll](../../features/reroll.md).

## Edit Crate

### Identifier

With this option, you can set an identifier for the crate. Note that the crate identifier is unique and used internally by the plugin, and its different from the display name. For example, if your crate's name is Elemental Crate the identifier should be set to elemental\_crate.

> **Danger:**
If the identifier is changed, all player progress and keys associated with the crate will no longer work.

<figure><img src="../../.gitbook/assets/editor/crates/identifier.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Display Name

With this option, you can adjust the display name of the crate. The display name is typically shown in the hologram and in messages when you open the chest.

For the display name, you can use the default Minecraft color codes. For hex colors, use the \&#D6D045 format.

<figure><img src="../../.gitbook/assets/editor/crates/item.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Hologram

Every crate can show a hologram floating above it, with its lines, height and style set per crate. It has its own page: [Hologram](hologram.md).

<figure><img src="../../.gitbook/assets/editor/crate/hologram.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Preview Reward

When the preview reward is enabled, users will be able to see all the rewards flickering above the crate.

<figure><img src="../../.gitbook/assets/editor/crates/preview-reward.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

> **Info:**
Turning this on raises the crate's hologram by 0.75 blocks so the two do not overlap. If your hologram jumps when you enable the preview reward, that is why, and the [hologram offset](hologram.md#hologram-offset) can bring it back down.

#### In-Game Preview

The following is an example of using the Preview Reward to a crate.

<figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp91-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>In-Game Preview of Preview Reward</p></figcaption></figure>

### Menus

With the menus, you can assign a different menu to be opened when a user previews rewards, use the rerolls, or select a reward for the selective move. This is a great option if you want to create different layouts for each crate.

<figure><img src="../../.gitbook/assets/editor/crates/menus.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

You can create your own preview menu in the menus folder inside PhoenixCrates\menus. Once you’ve created it, left-click and select that preview menu.

### Preview Actions

From the same menu, a crate can run a list of [actions](../../plugin-information/action-types.md) when a player clicks to preview it, such as sending a message or opening another plugin's menu. They run alongside the rewards preview menu, or replace it entirely when the crate has no preview menu set.

<figure><img src="../../.gitbook/assets/editor/menus/preview-actions.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Menus</p></figcaption></figure>

### Broadcast Message

With the broadcast message option, you can customize the message that is broadcasted to the server when a user wins a reward. Note that for a broadcast message to be sent, the specific reward must have the broadcast option enabled. By default, this feature is disabled. The broadcast message supports multiple lines.

<figure><img src="../../.gitbook/assets/editor/crates/broadcast-message.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

## Link Keys

Choose which keys open this crate. The same link can be made from the key side with [Link Crates](../keys/README.md#link-crates).

<figure><img src="../../.gitbook/assets/editor/crates/link-keys.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Link a Key

Linking a key is a simple process. When you click on the Link Key glass, a menu will appear showing all available keys on your server, allowing you to select the one you want to link to the crate.

<figure><img src="../../.gitbook/assets/editor/link-keys/link-key.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Link Keys</p></figcaption></figure>

### Key Requirement

By default, Key Required is enabled, which means the player must have at least one key to open the crate. If you don't want a key to be required, you can disable this option.

<figure><img src="../../.gitbook/assets/editor/link-keys/key-required.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Link Keys</p></figcaption></figure>

### Key Priority ⭐

When you have two or more keys linked to your crate, you can use the priority setting to determine which keys should be consumed first.

<figure><img src="../../.gitbook/assets/editor/link-keys/priority-reordering.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Link Keys</p></figcaption></figure>

### Key Skips Cost ⭐

> **Info:**
Available in the Premium+ plan of Phoenix Crates.

With this option, a crate can be opened either with one of its linked keys or by paying the open cost. A player who has a key uses it and pays nothing, and no payment confirmation is shown. A player without a key pays the cost instead of being told a key is needed. It only applies while Key Required is enabled and the open cost is above 0.

<figure><img src="../../.gitbook/assets/editor/link-keys/key-skips-cost.png" alt="" width="563"><figcaption><p>Link Keys (Key Skips Cost)</p></figcaption></figure>

## Misc Options

### Simultaneous Openings

With this option, multiple users can open the crate simultaneously. When enabled, only the user opening the crate will see the opening animation. When disabled, everyone nearby will see the crate opening animation. By default, this option is enabled.

<figure><img src="../../.gitbook/assets/editor/crates/simultaneous-openings.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Permission Requirement

With this option, you can assign a permission that restricts crate access to users who have the specified permission.

<figure><img src="../../.gitbook/assets/editor/crates/permission-requirement.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Open Money Cost

The amount a player pays to open the crate. 0 turns it off. Currencies and the payment flow are on [Open Money Cost](open-money-cost.md).

<figure><img src="../../.gitbook/assets/editor/crates/open-cost-engine.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Open Cooldown

With this option, you can set a cooldown for the crate, requiring users to wait a certain amount of time before opening it again. There is no maximum value, but the cooldown must be specified in seconds.

<figure><img src="../../.gitbook/assets/editor/crates/open-cooldown.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Click Behaviour

With this option, you can choose which click on a placed crate opens it and which opens its preview: left, right, both or none. By default, right-click opens and left-click previews. When a click matches both settings, the crate opens. Setting the preview to none stops a missed click from bringing up the preview menu.

<figure><img src="../../.gitbook/assets/editor/crates/click-behaviour.png" alt="" width="563"><figcaption><p>Crate (Click Behaviour)</p></figcaption></figure>

Sneaking admins still remove the crate with left-click, whatever is set here.

### Event Actions

With this option, a crate runs actions at four moments: when an opening starts, when the rewards are given, when the opening ends, and when a player clicks the crate but cannot open it. Any action works, such as a sound, title, message or command, so a crate can play a level-up sound on every win.

<figure><img src="../../.gitbook/assets/editor/crates/event-actions.png" alt="" width="563"><figcaption><p>Crate (Event Actions)</p></figcaption></figure>

Actions set under **Editor > Settings > Event Actions** apply to every crate, and a crate with its own actions for an event uses those instead. Win actions can also be set per reward and, with the Rarity add-on, per rarity. The most specific one wins: reward, then rarity, then crate, then global.

Win actions run once per opening. When one opening gives several rewards, such as a mass opening, the rarest reward decides which actions run. They can use `%reward%`, `%rarity%`, `%crate%`, `%crate_id%` and `%player%`.

Sounds accept a vanilla name like `ENTITY_PLAYER_LEVELUP` or any sound key, including resource-pack sounds such as `myserver:crate.legendary`.

> **Info:**
Per-rarity win actions need the Premium+ plan and the Rarity add-on.

### Attach Block

With this option, you can link the crate to a specific block.

<figure><img src="../../.gitbook/assets/editor/crates/attach-block.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Allow Open Command

With this option, you can choose whether the crate can be opened with the `/crate open <crate_id>` command, so a player can open it virtually instead of walking to it. The crate still needs at least one placed instance in the world for the command to work. By default, this option is disabled.

<figure><img src="../../.gitbook/assets/editor/crates/allow-open-command.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

> **Warning:**
The command opens an existing crate remotely, it does not create one. The crate still needs to be physically placed somewhere in the world, otherwise there is nothing for the command to open.

### Clone Crate ⭐

> **Info:**
Cloning is available in the Premium+ plan of Phoenix Crates.

With this option, you can duplicate a crate with everything it holds: its rewards, animations, hologram, linked keys and every other setting. The copy is given a new identifier automatically, based on the original's, so the two never collide.

A confirmation menu is shown before the copy is made. The clone starts with no placed locations of its own, so you place it in the world like a brand new crate.

This is the fastest way to build a tier of crates, where a Common, Rare and Legendary crate share the same look and differ only in their rewards.

<figure><img src="../../.gitbook/assets/editor/crates/clone-crate.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Enabled

With this option, you can disable the crate. The crate will remain in its location and stay registered, but users will not be able to open or preview it.

<figure><img src="../../.gitbook/assets/editor/crates/enabled.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

### Delete Crate

With this option, you can delete a crate.

<figure><img src="../../.gitbook/assets/editor/crates/delete-crate.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure>

> **Danger:**
This option is permanent, and crates can't be restored.

## Extra Options

Options written in the crate file.

### Display Item Position

With this option, you can adjust the position where the reward item will be displayed. The name of the reward has its own offset, applied on top of the item one, so the text can sit closer or further from the item.

Both are also editable in-game from [Display Settings](../animations/opening-animations/README.md#display-settings), inside the Opening Animation menu.

```yaml
extra-settings:
  animation:
    display-item-position:
      x: 2.0
      y: 1.0
      z: 0.0
    display-item-name-position:
      x: 0.0
      y: 0.3
      z: 0.0
```

<figure><img src="../../.gitbook/assets/image (62).png" alt="" width="563"><figcaption><p>Display Item Position</p></figcaption></figure>

### Item Position

Offsets the floating reward item on each axis, the same values as `display-item-position` above.

<figure><img src="../../.gitbook/assets/editor/display-settings/item-position-z.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations > Display Settings</p></figcaption></figure>

### Name Position

Offsets the reward's name on top of the item one, so the text can sit closer to or further from the item.

<figure><img src="../../.gitbook/assets/editor/display-settings/name-position-z.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations > Display Settings</p></figcaption></figure>

Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates