# Phoenix Crates documentation > Premium crates plugin for Spigot, Paper and Folia with animated 3D crates, a full in-game editor and random or selective rewards. Docs: https://www.phoenixplugins.com/docs/phoenix-crates Supported Minecraft versions: 1.20.4 – 26.3 (Spigot, Paper, Folia) --- # 💎 Premium Add-ons ## Crate Claim Stores rewards and keys for players who are offline or have a full inventory, so nothing is ever lost. Players collect them with `/crate claim`. ## Mass Opening Lets players open several keys at once instead of one at a time, with configurable opening amounts per crate. ## Rarities Adds rarities that you can assign to rewards, each with its own display name, colour, and effects. ## Lootboxes Lets a crate be opened directly from a held item, without placing a crate block in the world. ## Last Winner Tracks the most recent winner of each crate and exposes them through placeholders. ## Redis Caches player data in Redis and keeps it in sync across a network of servers. ## Animations Extra opening animations that you can mix with the built-in ones. Available as the Deluxe, Halloween, and Christmas animation packs. # 🪨 Free Add-ons ## Leaderboard Adds placeholders for a top 10 ranking of players by how many crates they have opened. ## Reward Loop Gives a reward to every online player on a fixed timer, independent from crates and keys. ## IP Limit Limits mass key and reward giveaways to one player per IP address, so alt accounts cannot multiply them. Source: https://www.phoenixplugins.com/docs/phoenix-crates/addons --- # 🌠 Animations ## Animations Animation add-ons add extra opening animations on top of the ones built into the plugin. Each animation registers as an independent Pre Open (Phase 1), Post Open (Phase 2), or Reward Display (Phase 3) animation, so you can mix and match them freely with the built-in ones. They are installed like any other add-on, by dropping the JAR into the **PhoenixCrates/addons** folder. Once installed, the new animations show up in the editor under the crate's animations. ## Available Add-ons | Add-on | Animations | | ------ | ---------- | | [Deluxe Animations](deluxe-animations.md) | CSGO (Vertical), Black Hole, Orbit Roulette, Astro Burst | | [Halloween Crate Animations](halloween-crate-animations.md) | Bat, Witch, Skeleton, and Demon animations | | [Christmas Crate Animations](christmas-crate-animations.md) | Santa Claus, Bouncing Present, Tree, and matching phases | > **Info:** The Lootbox add-on also ships its own animations. You can find them on the [Lootbox](../lootbox/README.md#animations) page. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/animations --- # 🎅 Christmas Crate Animations > **Warning:** This is an addon for PhoenixCrates, not a plugin. ### Purchase Christmas Crate Animations from our [Website](https://www.myphoenixstore.com/en/items/christmas-crate-animations-v1) ## Installation To install the Christmas Crate animations, make sure to drag and drop the JAR file into the **PhoenixCrates/addons** folder. Be sure to install it there; otherwise, the file won't work.
Once you have installed the JAR successfully, head over to the editor and then to the animations. From there, you will be able to configure the animations for each crate. ### Customize: Every Christmas animation can be customized per crate. In the crate's opening animations, right-click the selected animation to open its settings. Depending on the animation you can change the items and head textures it uses, Santa's and the elf's outfit, sizes, colors, the melody and how many presents, ornaments or snowflakes it spawns. **Reset to Defaults** restores every setting of that animation. ### Animation List: Just like the plugin's built-in animations, each Christmas animation registers as an independent Pre Open (Phase 1), Post Open (Phase 2), or Reward Display (Phase 3) animation, so you can freely mix and match any phase 1 with any phase 2 and phase 3, not only the suggested combinations below. The following list shows the combinations they were designed around: ### Combination 1: **Phase 1**: Christmas Santa Claus **Phase 2:** Christmas Present Cannon **Phase 3:** Christmas Merry Cyclone ### Combination 2: **Phase 1**: Christmas Bouncing Present **Phase 2:** Christmas Magic Elf **Phase 3:** Christmas Snowfall ### Combination 3: **Phase 1**: Christmas Tree **Phase 2:** Christmas Flying Ornaments **Phase 3:** Christmas Essence Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/animations/christmas-crate-animations --- # 🪙 Deluxe Animations ## CSGO (Vertical) The **Vertical CSGO** animation will display a physical CSGO animation vertically, cycling through a few of the rewards in the crate until it stops on a single one. **Required Version:** 1.17+ **Customizable:** No **Material:** Gunpowder https://youtu.be/Zd6WLzsU7kI CSGO (Verical) Animation - In Game ## Black Hole The **Black Hole** animation summons a black hole when a crate is opened, which causes all nearby players to be pulled toward it, making it difficult for them to move away. Additionally, players within range will be affected by **potion effects** and **sounds** during the animation. **Required Version:** 1.17+ **Customizable:** No **Material:** Black Dye https://www.youtube.com/watch?v=vaUe-90dgkM Black Hole Animation - In Game > **Danger:** The Animation above doesn't support Bedrock users, since Bedrock doesn't support Player Heads. ## Orbit Roulette The **Orbit Roulette** animation summons items from the rewards table that rise from the ground and orbit around the crate. **Required Version:** 1.17+ **Customizable:** No **Material:** Gold Ingot https://www.youtube.com/watch?v=Isii-nTwKuM Orbit Roulette Animation - In Game ## Astro Burst The **Astro Burst** animation launches a burst of reward items from the crate into the air, similar to fireworks, before ending in an explosion effect that reveals the winning reward. **Required Version:** 1.17+ **Customizable:** No **Material:** Wind Charge https://www.youtube.com/watch?v=EQOkmosenQ0 Astro Burst Animation - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/animations/deluxe-animations --- # 🎃 Halloween Crate Animations > **Warning:** This is an addon for PhoenixCrates, not a plugin. ## Installation To install the **Halloween Crate Animations**, make sure to drag and drop the JAR file into the **PhoenixCrates/addons** folder. Be sure to install it there. Otherwise, the jar won't load. Once you have installed the JAR successfully, head over to the editor and then to the animations. From there, you will be able to configure the animations for each crate. Just like the plugin's built-in animations, each Halloween animation registers as an independent Pre Open (Phase 1), Post Open (Phase 2), or Reward Display (Phase 3) animation, so you can freely mix and match any phase 1 with any phase 2 and phase 3, not only the suggested combinations below. ## Customize Every Halloween animation can be customized per crate. In the crate's opening animations, right-click the selected animation to open its settings. Depending on the animation you can change the items and head textures it uses, its size, its colors and how many treats, bats, ghosts or orbs it spawns. **Reset to Defaults** restores every setting of that animation. ## Bat Crate: **Phase 1**: Bouncing Jack **Phase 2:** Bat Exodus **Phase 3:** Eerie Unveiling https://youtu.be/WQrTRHUKGSw Bat Animation Combination - In Game *** ## Witch Crate: **Phase 1**: Witch Brew Boom **Phase 2:** Pumpkin Glow **Phase 3:** Pumpkin Essence https://youtu.be/7lyaB7ereOY Witch Animation Combination - In Game *** ## Skeleton Crate: **Phase 1:** Haunting Vortex **Phase 2:** Spooky Ascension **Phase 3:** Dark Emanation https://youtu.be/mxq6IwD0ngs Skeleton Animation Combination - In Game *** ## Demon Crate: **Phase 1**: Cauldron Madness **Phase 2:** Ghost Rise **Phase 3:** Spectral Surge https://youtu.be/dPG7AUlWlHs Demon Animation Combination - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/animations/halloween-crate-animations --- # 🌐 API > **Danger:** The API is only available for the premium version of the plugin. ## API Below, you’ll find information about our API. If you have any questions, feel free to contact our team. * **Create Custom Animations** - [Click Here](custom-animations.md) Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/api --- # 🔧 Custom Animations > **Danger:** The API is only available for the premium version of the plugin. ``` public class YourPhaseAnimation extends OpeningPhaseAnimation { public YourPhaseAnimation(OpeningCrateAnimation animation, OpeningPhaseType type, EmptyOpeningPhaseData data) { super(animation, type, data); } @Override public void load() { } @Override public void tick() { } @Override public void unload() { } } ``` ``` public void onEnable() { registerPhase( new OpeningPhaseType(PhaseType.FIRST, "YOUR_PHASE_IDENTIFIER", "Your Display Name", XMaterial.STONE, ServerVersion.v1_16_R1, new XMaterial[] {}, EmptyOpeningPhaseData.class, (animation, type, data) -> new YourPhaseAnimationAnimation(animation, type, (EmptyOpeningPhaseData) data), () -> new EmptyOpeningPhaseData())); } public void onDisable() { for (final OpeningPhaseType type : this.registeredPhases) { OpeningPhaseType.unregisterPhase(type); } } private void registerPhase(OpeningPhaseType phase) { // Registering first phase animations OpeningPhaseType.registerPhase(phase); // Caching to unload later on this.registeredPhases.add(phase); } ``` Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/api/custom-animations --- # 📬 Crate Claim ## Information The Crate Claim add-on gives every player a personal claim storage, so rewards, keys and crates handed to them while they are offline or with a full inventory are never lost.

Crate Claim - Add-On

👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/crate-claim-addon) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Claiming Every player gets their own storage that holds rewards, keys and lootboxes given to them while they were offline or out of inventory space. It holds an unlimited number of items, needs no permission, and players reach it with `/crate claim`.

/crate claim command

### What Changes Without It Crate Claim is what makes a full inventory harmless. Without the add-on installed: * A player whose inventory is full **cannot open a crate at all**. The interaction is refused with an "inventory is full" message and no key is taken. * Keys, crates and rewards given by command are dropped at the player's feet instead, with a message telling them so. * A physical key given to an offline player is not delivered, since there is nowhere to hold it. With the add-on installed, all of these are stored for the player to collect later. The win commands of a reward won with a full inventory are stored too, as one entry showing the reward's display item. Claiming it runs the commands. ### Claim All With the claim-all feature, you can instantly claim all available rewards from the menu.

/crate claim command

### Bedrock Bedrock players get the claim menu as a [Bedrock form](../../configurations/geysermc-bedrock.md#bedrock-forms): Claim All first, then a button per stored item. Tapping one claims it. `/crate inspectClaim` always opens the chest menu. ## Settings The add-on adds its own entry to the editor settings, holding the three options below.

Editor

### Prioritize Inventory Hands items straight to the player and only falls back to the claim storage when there is not enough room, so an online player with space never has to run a command to collect anything. Turning it off routes everything through the claim menu instead. On by default.

Editor > Settings > Crate Claim

### Join Reminder Tells a player they have something waiting the moment they log in, which is what makes an offline delivery discoverable. On by default.

Editor > Settings > Crate Claim

### Automated Reminder How long between the repeat reminders sent to players who still have unclaimed items. Only players holding something are reminded, so raising it quietens the message on a busy server without switching it off.

Editor > Settings > Crate Claim

### Admin Commands * `/crate inspectClaim ` - Inspect another player's pending crate claims. Requires `phoenixcrates.command.inspectclaim`. * `/crate resetClaimsAll confirm` - Permanently clears every player's pending crate claims, online and offline. This action cannot be undone. Requires `phoenixcrates.command.resetclaims`. Without `confirm`, the command only shows a warning. The reset runs in the background with a progress bar in the action bar, or every 10% in the console, and it will not start while another task over every player's data is running. With the [Redis](../redis.md) add-on, it also clears the claims cached on the other servers of the network. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/crate-claim --- # 📥 Claiming ## Crate Claim Every player gets their own storage that holds rewards, keys and lootboxes given to them while they were offline or out of inventory space. It holds an unlimited number of items, needs no permission, and players reach it with `/crate claim`.

/crate claim command

## What Changes Without It Crate Claim is what makes a full inventory harmless. Without the add-on installed: * A player whose inventory is full **cannot open a crate at all**. The interaction is refused with an "inventory is full" message and no key is taken. * Keys, crates and rewards given by command are dropped at the player's feet instead, with a message telling them so. * A physical key given to an offline player is not delivered, since there is nowhere to hold it. With the add-on installed, all of these are stored for the player to collect later. The win commands of a reward won with a full inventory are stored too, as one entry showing the reward's display item. Claiming it runs the commands. ## Claim All With the claim-all feature, you can instantly claim all available rewards from the menu.

/crate claim command

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/crate-claim/claiming --- # ⚙️ Settings ## Settings The add-on adds its own entry to the editor settings, holding the three options below.

Editor

### Prioritize Inventory Hands items straight to the player and only falls back to the claim storage when there is not enough room, so an online player with space never has to run a command to collect anything. Turning it off routes everything through the claim menu instead. On by default.

Editor > Settings > Crate Claim

### Join Reminder Tells a player they have something waiting the moment they log in, which is what makes an offline delivery discoverable. On by default.

Editor > Settings > Crate Claim

### Automated Reminder How long between the repeat reminders sent to players who still have unclaimed items. Only players holding something are reminded, so raising it quietens the message on a busy server without switching it off.

Editor > Settings > Crate Claim

## Admin Commands * `/crate inspectClaim ` - Inspect another player's pending crate claims. Requires `phoenixcrates.command.inspectclaim`. * `/crate resetClaimsAll confirm` - Permanently clears every player's pending crate claims, online and offline. This action cannot be undone. Requires `phoenixcrates.command.resetclaims`. Without `confirm`, the command only shows a warning. The reset runs in the background with a progress bar in the action bar, or every 10% in the console, and it will not start while another task over every player's data is running. With the [Redis](../redis.md) add-on, it also clears the claims cached on the other servers of the network. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/crate-claim/settings --- # 🆕 Custom Addons ## Custom Addons Custom Addons are extensions that allow users to extend, modify, or enhance the functionality of our plugin. Think of them as building blocks that enable you to tailor the behavior of the plugin, making it uniquely yours. ## Maven Dependency ```xml nexus https://repo.myphoenixstore.com/repository/maven-public/ ``` ```xml com.phoenixplugins.sdk api 1.0-SNAPSHOT ``` ### **Addon.yml File**: * To begin customizing your plugin experience, ensure you have an "addon.yml" file in the resources of your Java project. * Open the "addon.yml" file and configure it according to your addon's specifications. ``` name: AddonName main: your.path.AddonExample author: [YourName] version: 1.0 description: Small Description (Optional) website: Website (Optional) ``` The "addon.yml" file serves as the configuration hub for your Custom Addon, providing essential metadata such as the addon's name, main class path, author details, version, and optional description and website information. ### **Main Class**: * Ensure that the specified `main` class in the "addon.yml" file corresponds to the path of your addon class within your project. ```java package your.path; import java.io.IOException; import com.phoenixplugins.sdk.addons.Addon; public class AddonExample extends Addon { public AddonExample() { // Your code here } @Override public void onLoad() { // Your code here } @Override public void onEnable() { // Your code here } @Override public void onDisable() { // Your code here } @Override public String getRequiredPluginVersion() { return "2.1.4"; // Define the main required version } } ``` ### **Compile your Addon**: * Compile your Custom Addon following your Java project's build instructions. ### **Install your Addon**: * Move the compiled JAR file to the "addons" folder within the "PhoenixCrates" directory in your server plugins. * Restart the server to apply changes and activate your Custom Addon. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/custom-addons --- # 🌐 IP Limit ## Information The IP Limit add-on caps how many accounts sharing the same IP address can receive keys, crates and rewards that are handed out to everyone online at once, so alt accounts cannot multiply a giveaway.

IP Limit - Add-On

👉 [You can claim this add-on for free on Phoenix Plugins](https://www.phoenixplugins.com/product/iplimit) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Limits Everything the add-on does is reached from the IP Limit button in the main editor. Only actions that reward several players in one go are affected, so commands aimed at a single player are never filtered. A limit of `0` is shown as Unlimited and turns the cap off for that action alone.

Editor

### Enabled Switches the whole add-on off without uninstalling it. While it is off, every action reaches all online players regardless of the limits set below.

Editor > IP Limit

### Global Limits The default cap for each of the four actions that can reward everyone online. Keys and crates without an override of their own use these values.

Editor > IP Limit

#### Give Key All Caps how many accounts per IP receive a key from `/crates giveKeyAll`.

Editor > IP Limit > Global

#### Give Crate All Caps how many accounts per IP receive a crate from `/crates giveCrateAll`.

Editor > IP Limit > Global

#### Share With Players Online Caps how many accounts per IP receive a reward that has Share With Players Online turned on. The player who opened the crate is filtered like everyone else, so with a limit of `1` and two of their accounts online, the reward can land on the other account instead of theirs.

Editor > IP Limit > Global

#### Reward On Loop Caps how many accounts per IP receive a recurring reward from the [Reward On Loop](../reward-on-loop/) add-on. This one cannot be overridden per key or crate, since a loop reward belongs to neither.

Editor > IP Limit > Global

### Limit Per Key Lists every registered key so a single one can carry its own cap instead of the Give Key All value. Keys with no override of their own are listed as inherited.

Editor > IP Limit

### Limit Per Crate The same list for crates. A crate override replaces the Give Crate All value **and** the Share With Players Online value for that crate, so it covers both the giveaway command and rewards shared from inside it.

Editor > IP Limit

#### Limit The cap for this key or crate on its own. It opens showing the global value it currently inherits, and setting it here creates the override.

Editor > IP Limit > Crate

#### Use Global Limit Removes the override so the key or crate follows the global value again. This is not the same as setting the limit to `0`, which would make that one key or crate unlimited while the global cap stays in place.

Editor > IP Limit > Crate

> **Info:** Players whose IP address cannot be read are never filtered out, so a proxy setup that hides the real address leaves the limits with nothing to match on. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/ip-limit --- # 🚦 Limits ## IP Limit Everything the add-on does is reached from the IP Limit button in the main editor. Only actions that reward several players in one go are affected, so commands aimed at a single player are never filtered. A limit of `0` is shown as Unlimited and turns the cap off for that action alone.

Editor

## Enabled Switches the whole add-on off without uninstalling it. While it is off, every action reaches all online players regardless of the limits set below.

Editor > IP Limit

## Global Limits The default cap for each of the four actions that can reward everyone online. Keys and crates without an override of their own use these values.

Editor > IP Limit

### Give Key All Caps how many accounts per IP receive a key from `/crates giveKeyAll`.

Editor > IP Limit > Global

### Give Crate All Caps how many accounts per IP receive a crate from `/crates giveCrateAll`.

Editor > IP Limit > Global

### Share With Players Online Caps how many accounts per IP receive a reward that has Share With Players Online turned on. The player who opened the crate is filtered like everyone else, so with a limit of `1` and two of their accounts online, the reward can land on the other account instead of theirs.

Editor > IP Limit > Global

### Reward On Loop Caps how many accounts per IP receive a recurring reward from the [Reward On Loop](../reward-on-loop/) add-on. This one cannot be overridden per key or crate, since a loop reward belongs to neither.

Editor > IP Limit > Global

## Limit Per Key Lists every registered key so a single one can carry its own cap instead of the Give Key All value. Keys with no override of their own are listed as inherited.

Editor > IP Limit

## Limit Per Crate The same list for crates. A crate override replaces the Give Crate All value **and** the Share With Players Online value for that crate, so it covers both the giveaway command and rewards shared from inside it.

Editor > IP Limit

### Limit The cap for this key or crate on its own. It opens showing the global value it currently inherits, and setting it here creates the override.

Editor > IP Limit > Crate

### Use Global Limit Removes the override so the key or crate follows the global value again. This is not the same as setting the limit to `0`, which would make that one key or crate unlimited while the global cap stays in place.

Editor > IP Limit > Crate

> **Info:** Players whose IP address cannot be read are never filtered out, so a proxy setup that hides the real address leaves the limits with nothing to match on. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/ip-limit/limits --- # 🛒 Key Shop ## Information The Key Shop add-on lets players buy crate keys with a currency, and trade keys they already hold for a different kind of key. It gives a server a way to sell keys in game rather than only through a web store, and gives players something to do with the pile of common keys they never open. Prices are charged through the same cost engines a crate uses for its open cost, so an entry can be priced in Vault money, experience levels, PlayerPoints, VotingPlugin points, ExcellentEconomy or PhoenixCurrencies without any extra setup. ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. The currency plugin an entry is priced in has to be installed for that entry to be purchasable, but an entry priced at `0` needs nothing. ## Files | File | What it holds | | ---- | ------------- | | `PhoenixCrates/key-shop.yml` | The shop entries, the exchanges and the add-on setting. | | `PhoenixCrates/menus/default_key_shop.yml` | The layout of the shop menu. | | `PhoenixCrates/menus/default_key_exchange.yml` | The layout of the exchange menu. | | `PhoenixCrates/translations/keyshop.translations..yml` | The add-on messages. | Purchase counts are stored per player in the database, in the `player_keyshop_table` table. ## Commands * `/crate shop [player]` - Opens the key shop. Without an argument it opens for the sender. * `/crate exchange [player]` - Opens the key exchange. * `/crate resetKeyShop ` - Clears a player's purchase and trade counters, freeing every limit again. Requires `phoenixcrates.command.resetkeyshop`. ## Bedrock Bedrock players get the shop and the exchange as [Bedrock forms](../../configurations/geysermc-bedrock.md#bedrock-forms): a button per entry with its price, or what it trades. Tapping an entry buys or trades it right away, or asks first when purchase confirmation is on. An entry the player cannot use shows why. ## Permissions | Permission | What it allows | | ---------- | -------------- | | `phoenixcrates.command.resetkeyshop` | Resetting a player's shop limits. | Individual entries are gated with their own `permission` option rather than a permission node. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/key-shop --- # 🔄 Exchanges ## Exchanges An exchange trades a number of one key for a number of another. They live under `exchanges` in key-shop.yml and are shown in their own menu. ```yaml exchanges: '0': identifier: vote_to_legendary display-item: material: TRIPWIRE_HOOK display-name: '&6Upgrade to Legendary' amount: 1 from-key: vote from-amount: 10 to-key: legendary to-amount: 1 permission: '' daily-limit: -1 total-limit: -1 exchange-message: - '&aYou traded &fx%from_amount% %from_key% &afor &fx%to_amount% %to_key%&a.' ``` ## Options | Option | What it does | | ------ | ------------ | | `identifier` | The name the trade counters are stored under. | | `display-item` | The item shown in the exchange menu. | | `from-key` | The identifier of the key being spent. | | `from-amount` | How many of it one trade consumes. | | `to-key` | The identifier of the key being received. | | `to-amount` | How many of it one trade gives. | | `permission` | The player needs this to use the trade. Leave empty for everyone. | | `daily-limit` | Trades allowed per player per day, `-1` for unlimited. | | `total-limit` | Trades allowed per player for the lifetime of the exchange, `-1` for unlimited. | | `exchange-message` | Sent to the player after the trade. | ## Virtual and physical keys Both sides work with either kind of key. A virtual key is taken from the player's stored key count, and a physical key is taken from their inventory, including the off-hand slot. The key received is delivered the same way any other key is, so a physical key with a full inventory follows whatever the Crate Claim add-on is set to do. The menu only offers a trade the player can actually complete, so an entry greys out when they are short of the key it consumes. > **Warning:** An exchange pointing at a key identifier that no longer exists shows as unavailable and can never be used. Renaming a key means updating every exchange that references it. ## Message placeholders `exchange-message` accepts `%player%`, `%from_amount%`, `%from_key%`, `%to_amount%` and `%to_key%`. ## Menu placeholders The `exchange-item` and `unavailable-item` entries in menus/default\_key\_exchange.yml accept: | Placeholder | Value | | ----------- | ----- | | `%entry%` | The display name of the exchange. | | `%item_name%` | The name of the configured display item. | | `%from_key%` / `%from_amount%` | The key spent and how many. | | `%to_key%` / `%to_amount%` | The key received and how many. | | `%owned%` | How many of the spent key the player holds. | | `%remaining%` | Trades the player has left, or the "Unlimited" label. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/key-shop/exchanges --- # 📜 Placeholders ## PlaceholderAPI Placeholders | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_keyshop_price_\% | The price of a shop entry, formatted by its cost engine. | | %phoenixcrates_keyshop_remaining_\% | Purchases the player has left on that entry. | | %phoenixcrates_keyshop_exchanges_\% | Trades the player has left on that exchange. | ``` %phoenixcrates_keyshop_price_vote_key_single% %phoenixcrates_keyshop_remaining_vote_key_single% %phoenixcrates_keyshop_exchanges_vote_to_legendary% ``` An entry with no limit reports `∞`. An identifier that does not exist reports `N/A`, which is the usual sign of a typo. > **Info:** The price placeholder works from the console and in contexts with no player, since a price does not depend on who is asking. The other two need an online player and report `N/A` otherwise. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/key-shop/placeholders --- # 💰 Shop Entries ## Entries Every offer lives under `entries` in key-shop.yml. ```yaml confirm-purchases: false entries: '0': identifier: vote_key_single display-item: material: TRIPWIRE_HOOK display-name: '&aVote Key' amount: 1 key: vote amount: 1 cost-engine: VAULT currency: '' price: 2500.0 permission: '' daily-limit: 5 total-limit: -1 purchase-commands: [] purchase-message: - '&aYou bought &fx%amount% %key% &afor &f%price%&a.' ``` > **Info:** Entries are stored as a numbered section rather than a YAML list, the same shape the crate rewards use. The numbers are positions only and have to stay unique inside the section. ## Options | Option | What it does | | ------ | ------------ | | `identifier` | The name the purchase counters are stored under. Renaming it resets every player's limit on that entry. | | `display-item` | The item shown in the shop menu. | | `key` | The identifier of the key being sold. | | `amount` | How many keys one purchase gives. | | `cost-engine` | Which currency the price is charged in. | | `currency` | The currency id, used only by `EXCELLENTECONOMY` and `PHOENIXCURRENCIES`. Leave empty otherwise. | | `price` | What one purchase costs. A price of `0` is free and skips the currency check entirely. | | `permission` | The player needs this to buy the entry. Leave empty for everyone. | | `daily-limit` | Purchases allowed per player per day, `-1` for unlimited. | | `total-limit` | Purchases allowed per player for the lifetime of the entry, `-1` for unlimited. | | `purchase-commands` | Commands run by the console after a purchase. | | `purchase-message` | Sent to the buyer. | ## Cost engines | Engine | Requires | Notes | | ------ | -------- | ----- | | `NONE` | Nothing | The entry is free whatever `price` says. | | `LEVEL` | Nothing | Charges experience levels, whole numbers only. | | `VAULT` | Vault and an economy plugin | | | `PLAYERPOINTS` | PlayerPoints | Whole numbers only. | | `VOTINGPLUGIN` | VotingPlugin | Charges vote points, whole numbers only. | | `EXCELLENTECONOMY` | ExcellentEconomy | Set `currency` to the currency id. | | `PHOENIXCURRENCIES` | PhoenixCurrencies | Set `currency` to the currency id. | An entry whose engine is not installed shows as unavailable in the menu rather than failing on click. ## Limits The daily counter resets at midnight UTC, and it resets for a player who stays online across the boundary as well as one who logs in after it. Both limits apply at once, so an entry with a daily limit of `2` and a total limit of `10` allows two per day up to ten in total. `/crate resetKeyShop ` clears both counters for that player. ## Confirmation `confirm-purchases` at the top of the file turns every purchase into two clicks. The first click arms the entry and swaps its icon to the `confirm-item` layout, and a second click within five seconds completes the purchase. Anything else — waiting out the five seconds, or closing the menu — cancels it. > **Info:** The armed state lives with the open menu, so it is per player and disappears when they close the shop. ## Message placeholders `purchase-message` accepts `%player%`, `%amount%`, `%key%`, `%entry%` and `%price%`. `purchase-commands` accept `%player%` along with any PlaceholderAPI placeholder. ## Menu placeholders The `entry-item`, `confirm-item` and `unavailable-item` entries in menus/default\_key\_shop.yml accept: | Placeholder | Value | | ----------- | ----- | | `%entry%` | The display name of the entry. | | `%item_name%` | The name of the configured display item. | | `%key%` | The display name of the key being sold. | | `%amount%` | How many keys the purchase gives. | | `%price%` | The price, formatted by the cost engine. | | `%remaining%` | Purchases the player has left, or the "Unlimited" label. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/key-shop/shop-entries --- # 🏆 Last Winner ## Information The Last Winner add-on adds placeholders to PhoenixCrates. This add-on allows you to display the last winner of a crate in various places.

Last Winner - Add-On

👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/last-winner-addon) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition, and PlaceholderAPI for the placeholders to resolve. ## Placeholders `` is `1` for the most recent winner, `2` for the second most recent, and so on. Up to the last **20** winners are kept per crate; requesting a position beyond that (or beyond the number of winners recorded so far) returns an empty value, as does a crate with no winners at all. `N/A` only shows for a moment while the winners of a crate are first being loaded. Crate identifiers containing underscores, such as `fire_crate`, work as written. | Placeholders | Description | |-------------------------------------------------------------|-----------------------------------------------------------| | %phoenixcrates_lastwinner_player\_\\_\% | Returns the player name on a specific position per crate. | | %phoenixcrates_lastwinner_reward\_\\_\% | Returns the reward on a specific position per crate. | | %phoenixcrates_lastwinner_rewardid\_\\_\% | Returns the reward's identifier on a specific position per crate. | | %phoenixcrates_lastwinner_hour\_\\_\% | Returns the hour that the player opened the crate. | | %phoenixcrates_lastwinner_minute\_\\_\% | Returns the minute that the player opened the crate. | | %phoenixcrates_lastwinner_second\_\\_\% | Returns the second that the player opened the crate. | | %phoenixcrates_lastwinner_day\_\\_\% | Returns the day that the player opened the crate. | | %phoenixcrates_lastwinner_month\_\\_\% | Returns the month that the player opened the crate. | | %phoenixcrates_lastwinner_year\_\\_\% | Returns the year that the player opened the crate. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/last-winner --- # Untitled ## PlaceholderAPI Placeholders The following is the list of the available placeholders that Last Winner has. `` is `1` for the most recent winner, `2` for the second most recent, and so on. Up to the last **20** winners are kept per crate; requesting a position beyond that (or beyond the number of winners recorded so far) returns an empty value. A crate with no winners recorded at all returns `N/A`. Crate identifiers containing underscores, such as `fire_crate`, work as written. | Placeholders | Description | |-------------------------------------------------------------|-----------------------------------------------------------| | %phoenixcrates_lastwinner_player\_\\_\% | Returns the player name on a specific position per crate. | | %phoenixcrates_lastwinner_reward\_\\_\% | Returns the reward on a specific position per crate. | | %phoenixcrates_lastwinner_rewardid\_\\_\% | Returns the reward's identifier on a specific position per crate. | | %phoenixcrates_lastwinner_hour\_\\_\% | Returns the hour that the player opened the crate. | | %phoenixcrates_lastwinner_minute\_\\_\% | Returns the minute that the player opened the crate. | | %phoenixcrates_lastwinner_second\_\\_\% | Returns the second that the player opened the crate. | | %phoenixcrates_lastwinner_day\_\\_\% | Returns the day that the player opened the crate. | | %phoenixcrates_lastwinner_month\_\\_\% | Returns the month that the player opened the crate. | | %phoenixcrates_lastwinner_year\_\\_\% | Returns the year that the player opened the crate. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/last-winner/placeholders --- # 🏆 Leaderboard ## Information The Leaderboard add-on adds placeholders to PhoenixCrates, ranking players by how many crates they have opened, per crate or across every crate.

Leaderboard - Add-On

👉 [You can claim this add-on for free on Phoenix Plugins](https://www.phoenixplugins.com/product/leaderboard) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition, and PlaceholderAPI for the placeholders to resolve. ## Placeholders The add-on ranks players by the number of crates they have opened, either for one crate or across every crate. It is entirely placeholder-driven, so there is no in-game menu. Only the top **10** are kept, and players who have never opened that crate are left out of the ranking entirely. A ranking is cached for 2 minutes, and opening a crate immediately invalidates both that crate's ranking and the global one, so a win is reflected on the next lookup rather than up to two minutes later. ### PlaceholderAPI Placeholders | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_leaderboard_\_\% | The name of the player at that rank. | | %phoenixcrates_leaderboard_\_\_value% | The number of crates that player has opened. | Use `global` as the identifier to rank across every crate, or a crate's identifier to rank for that crate only. `` starts at 1. Crate identifiers containing underscores, such as `fire_crate`, work as written. **Example:** `%phoenixcrates_leaderboard_global_1%` returns the name of the player who has opened the most crates on your server. `N/A` is returned by a rank nobody occupies yet, by a crate identifier that does not exist, and by the first lookup of a ranking that is not cached yet, since it is built in the background. Ask again once it has been computed. > **Info:** `global` is reserved. A crate whose identifier is literally `global` cannot be queried through these placeholders, because the whole-server leaderboard is matched first. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/leaderboard --- # 📜 Placeholders ## Leaderboard The add-on ranks players by the number of crates they have opened, either for one crate or across every crate. It is entirely placeholder-driven, so there is no in-game menu. Only the top **10** are kept, and players who have never opened that crate are left out of the ranking entirely. A ranking is cached for 2 minutes, and opening a crate immediately invalidates both that crate's ranking and the global one, so a win is reflected on the next lookup rather than up to two minutes later. ## PlaceholderAPI Placeholders | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_leaderboard_\_\% | The name of the player at that rank. | | %phoenixcrates_leaderboard_\_\_value% | The number of crates that player has opened. | Use `global` as the identifier to rank across every crate, or a crate's identifier to rank for that crate only. `` starts at 1. Crate identifiers containing underscores, such as `fire_crate`, work as written. **Example:** `%phoenixcrates_leaderboard_global_1%` returns the name of the player who has opened the most crates on your server. `N/A` is returned by a rank nobody occupies yet, by a crate identifier that does not exist, and by the first lookup of a ranking that is not cached yet, since it is built in the background. Ask again once it has been computed. > **Info:** `global` is reserved. A crate whose identifier is literally `global` cannot be queried through these placeholders, because the whole-server leaderboard is matched first. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/leaderboard/placeholders --- # 🎁 Lootbox ## Information The Lootbox add-on lets a crate be opened straight from a held item, without placing a crate block in the world, and comes with its own set of animations.

Lootbox - Add-On

👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/lootboxes) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Opening Formerly known as Pouches, a lootbox is a crate carried as an item and opened where the player stands. It is turned on per crate, so a server can mix lootbox crates and placed crates freely.

Editor > Crates > Crate

> **Info:** Turning Lootbox on for a crate also turns off that crate's Key Required setting, since a lootbox is paid for with the item itself rather than a key. ### Opening Behavior What a right-click does depends on the crate's rewards mode. * **Random** opens the crate on the spot and takes one item from the hand straight away. * **Selective (non RNG)** opens the reward menu first and only takes the item once a reward is confirmed. The item is looked for anywhere in the inventory at that moment, not just in the hand, and if none is left the claim is cancelled. A configured confirmation menu is shown before any of this, exactly as it would be for a placed crate. ### Placing a Lootbox A crate with a world animation phase needs a block for that animation to play on, so it cannot open in mid-air. The player right-clicks the ground to set the crate down, and it opens there on its own before disappearing again, which is what makes the world animation possible on a crate carried as an item. Right-clicking the air with one of these instead tells the player to place it on the ground. > **Info:** Without a world animation phase, none of this applies. The crate opens directly from the hand wherever the player is standing. > **Info:** Holders of `phoenixcrates.admin` can sneak while placing a lootbox item to place it as an ordinary crate instead of opening it, which is how a lootbox crate is set up in the world without spending items. ### MythicItems Support With MythicItems installed, `pcrates:crate` gives a lootbox item as a mob drop, taking the crate identifier as its argument. `pcrates:pouch` is kept as an alias so older configurations keep working. The drop resolves to nothing at all if the crate does not exist, is disabled, or is not a lootbox, so a mistyped identifier is silently skipped rather than dropping a broken item. ## Animations Installing the add-on adds six animations to the lists every crate picks from. They are listed with a Lootbox Addon suffix so they are easy to spot, and they work on any crate, not only lootbox ones. | Animation | Phase | | --------- | ----- | | Eruption | Pre Open | | Pulse | Pre Open | | Arcane | Pre Open | | Vortex | Post Open | | Tornado | Post Open | | Treasure Cascade | Reward Display | Where each phase sits in an opening is covered on the [Opening Animations](../../main-features/animations/opening-animations/README.md) page. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/lootbox --- # 🎇 Animations ## Exclusive Animations Installing the add-on adds six animations to the lists every crate picks from. They are listed with a Lootbox Addon suffix so they are easy to spot, and they work on any crate, not only lootbox ones. | Animation | Phase | | --------- | ----- | | Eruption | Pre Open | | Pulse | Pre Open | | Arcane | Pre Open | | Vortex | Post Open | | Tornado | Post Open | | Treasure Cascade | Reward Display | Where each phase sits in an opening is covered on the [Opening Animations](../../main-features/animations/opening-animations/README.md) page. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/lootbox/animations --- # 🚢 Migrating from Pouches ## Migrating from Pouches Pouches were replaced by lootboxes. Any pouches left over from that version are converted on the first server start after the add-on is installed, with no command to run, and the number converted is written to the console. Each converted crate comes out configured the way a lootbox normally is, so Key Required and any linked keys are cleared rather than carried over. The migration runs once. The old folder is renamed afterwards so a later restart does not convert the same crates again, which also means putting files back into a fresh pouches folder is enough to migrate more of them later. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/lootbox/migration --- # 🖱️ Opening ## Lootbox Formerly known as Pouches, a lootbox is a crate carried as an item and opened where the player stands. It is turned on per crate, so a server can mix lootbox crates and placed crates freely.

Editor > Crates > Crate

> **Info:** Turning Lootbox on for a crate also turns off that crate's Key Required setting, since a lootbox is paid for with the item itself rather than a key. ## Opening Behavior What a right-click does depends on the crate's rewards mode. * **Random** opens the crate on the spot and takes one item from the hand straight away. * **Selective (non RNG)** opens the reward menu first and only takes the item once a reward is confirmed. The item is looked for anywhere in the inventory at that moment, not just in the hand, and if none is left the claim is cancelled. A configured confirmation menu is shown before any of this, exactly as it would be for a placed crate. ## Placing a Lootbox A crate with a world animation phase needs a block for that animation to play on, so it cannot open in mid-air. The player right-clicks the ground to set the crate down, and it opens there on its own before disappearing again, which is what makes the world animation possible on a crate carried as an item. Right-clicking the air with one of these instead tells the player to place it on the ground. > **Info:** Without a world animation phase, none of this applies. The crate opens directly from the hand wherever the player is standing. > **Info:** Holders of `phoenixcrates.admin` can sneak while placing a lootbox item to place it as an ordinary crate instead of opening it, which is how a lootbox crate is set up in the world without spending items. ## MythicItems Support With MythicItems installed, `pcrates:crate` gives a lootbox item as a mob drop, taking the crate identifier as its argument. `pcrates:pouch` is kept as an alias so older configurations keep working. The drop resolves to nothing at all if the crate does not exist, is disabled, or is not a lootbox, so a mistyped identifier is silently skipped rather than dropping a broken item. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/lootbox/opening --- # 🔐 Mass Opening ## Information The Mass Opening add-on lets players open many keys at once on a crate, instead of one opening at a time. On a keyless crate with an open cost, players pay for many openings at once instead.

Mass Opening - Add-On

👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/mass-opening) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Crate Interaction When the player right-clicks to open the crate, they will see a menu displaying all available mass opening options. The red glass below an option indicates that the player either doesn't have permission to use that opening or doesn't have enough keys. **Menu:** `default_crate_mass_opening`

Crate Interaction

### Available Keys The available keys item will display the total number of keys you have for that crate, along with a list showing the amount of each individual key.

Crate Interaction

### Paying with Money A crate that needs no key and has an [Open Money Cost](../../main-features/crates/open-money-cost.md) uses the same menu, paid with money instead of keys. Every option shows its total cost, and an option turns red when the player cannot afford it. Choosing one opens a confirmation with the total before anything is charged, so ten openings of a $250 crate ask for $2,500 once and roll rewards ten times. The available keys item is hidden for these crates. Shift-right-click open-all opens as many as the player can afford, up to the open-all limit, or 100 when the limit is set to all. Only the Random rewards mode supports paid mass opening. ### Selective Mode On a crate using the Selective (non RNG) rewards mode, a player holding more than one key gets the [Mass Selection](#mass-selection) menu instead, where several rewards are picked and opened together. ### Reroll If the reroll feature is enabled along with mass opening, a different behavior occurs when using any opening option other than the single-key opening. Instead of receiving rewards individually, the player will see a menu displaying all the rewards they’ve won. They can click on any item to reroll it. Additionally, there's a Claim All Rewards option to collect everything at once. **Menu:** `default_crate_mass_reroll`

Crate Interaction

### Bedrock Bedrock players get the opening options and the reroll menu as [Bedrock forms](../../configurations/geysermc-bedrock.md#bedrock-forms). An option the player cannot use shows why under its button. In the reroll form, tapping a reward rerolls it, and closing the form claims everything. ## Mass Selection Mass selection is the Selective (non RNG) counterpart of the mass opening menu. Instead of spending one key on one reward at a time, the player picks several rewards, and how many of each, then receives all of them in a single opening. It takes over the normal select reward menu when the crate uses Selective mode, requires a key, has mass opening enabled, and the player owns more than one key. With a single key, the regular select reward menu is used instead. **Menu:** `default_crate_mass_selective` > **Info:** The opening amounts (x1, x6, x12...), the Open All option, the mass opening permissions and the global mass opening options only apply to crates in Random mode. On a selective crate the player's whole key balance is the selection limit. ### Selecting Rewards Left-clicking a reward adds one copy to the selection, right-clicking removes one. A selected reward is swapped for the selection material and stacked to the amount picked, so the count of every choice stays visible while browsing. The total number of selections is capped by the keys the player currently owns. Once the cap is reached, the remaining rewards gain an extra lore line and clicking them sends a message instead of selecting. Rewards the player cannot obtain at that moment, because of a missing permission, a reached win limit or a win cooldown, are shown as locked and cannot be selected. Disabled rewards and rewards past their time limit are not listed at all. ### Rarity Groups Rewards belonging to a rarity with [Group Rewards](../rarity/reward-rarity.md#reward-groups) enabled are collapsed into a single category icon. Clicking it opens the same menu filtered to that rarity, where the player selects normally, and closing it returns to the full list. Selections made inside a category are kept, so the cap and the confirm item always count every choice across all categories. ### Confirming The confirm item shows how many rewards are selected against the keys available. Confirming consumes one key per selected reward and opens all of them in one crate opening. The Required Keys value of a reward, or of its rarity, is not applied here: every selection costs exactly one key. Rerolling is always skipped for a mass selection opening, even when reroll is enabled on the crate. Bedrock players pick their rewards with one slider per reward, rarity groups included, and submit to open them. Locked rewards are listed without a slider. ### Customization The menu has its own items and options on top of the usual settings, pagination and items: | Option | Description | | ----------------------- | --------------------------------------------------------------------------------- | | Confirm | The item that validates the selection and opens the crate. | | Reward Item | Name and lore applied on top of each selectable reward. | | Locked Reward Item | Name and lore used for rewards the player cannot obtain. | | Selected Material | The material a reward is replaced with once selected. | | Sounds | The sounds played when selecting, unselecting, and when an action is not allowed. | | Max Selections Lore | Extra lore added to the rewards that can no longer be selected. | | Max Selections Message | The message sent when clicking a reward past the selection cap. | The following placeholders are available in this menu: | Placeholder | Description | | -------------------- | -------------------------------------------------- | | `%total_selections%` | Total amount of rewards currently selected. | | `%available_keys%` | Amount of keys the player owns for that crate. | | `%selected_amount%` | Amount selected of that specific reward. | | `%reward_name%` | Display name of the reward. | | `%reward_lore%` | Lore of the reward. | ## Settings With mass opening, players are able to open many keys simultaneously and obtain rewards. It is turned on per crate through its own menu, and starts out disabled.

Editor > Crates > Crate

### Opening Settings There are six opening options, all configurable except the single-key one, defaulting to x1, x6, x12, x32, x64 and x100. The largest can also be set to consume every key the player holds. Each option can be turned off on its own, and the amounts have to stay in ascending order, so an option can never be raised past the next one. Disabling every option turns mass opening off for that crate. > **Info:** The Open All maximum cannot be set below the highest opening option. Lowering it past that value snaps it back up, which can look like the setting is not saving. Lower the option above it first. The opening options apply to crates in Random mode. A selective crate uses the [Mass Selection](#mass-selection) menu instead, where the key balance is the only limit.

Editor > Crates > Crate > Mass Opening

### Global Settings These apply to every crate at once rather than to one crate, and all three only affect crates in Random mode. They sit under the add-on's own entry in the editor settings.

Editor

#### Skip Single Key Menu Sends a player straight into the opening when they only hold one key, since a menu offering a single choice has nothing to decide. On by default.

Editor > Settings > Mass Opening

#### Shift Right-Click Open All Gives players a shortcut past the menu entirely, spending every key they hold in one interaction. On a [paid crate](#paying-with-money) it opens as many as the player can afford instead, after a confirmation. Off by default, and it still respects the Open All permission.

Editor > Settings > Mass Opening

#### Toggle Mass Opening Menu Suppresses the mass opening menu on every crate in Random mode, including crates paid with money, so interacting opens one at a time as though the add-on were not installed. Useful for turning mass opening off server-wide without touching each crate. > **Info:** This toggle does not reach crates in Selective mode. A player holding more than one key still gets the [Mass Selection](#mass-selection) menu there.

Editor > Settings > Mass Opening

## Permissions Each opening option above the first is gated separately, so a server can sell larger openings by rank. An option the player has no permission for is shown greyed out rather than hidden. | Permission | Description | | -------------------------- | ----------------------------------------------- | | phoenixcrates.massopen.1 | Gives access to the 2nd opening of a crate | | phoenixcrates.massopen.2 | Gives access to the 3rd opening of a crate | | phoenixcrates.massopen.3 | Gives access to the 4th opening of a crate | | phoenixcrates.massopen.4 | Gives access to the 5th opening of a crate | | phoenixcrates.massopen.all | Gives access to the Open All opening of a crate | | phoenixcrates.massopen.\* | Gives access to all the openings | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/mass-opening --- # 👆 Crate Interaction ## Crate Interaction When the player right-clicks to open the crate, they will see a menu displaying all available mass opening options. The red glass below an option indicates that the player either doesn't have permission to use that opening or doesn't have enough keys. **Menu:** `default_crate_mass_opening`

Crate Interaction

## Available Keys The available keys item will display the total number of keys you have for that crate, along with a list showing the amount of each individual key.

Crate Interaction

## Paying with Money A crate that needs no key and has an [Open Money Cost](../../main-features/crates/open-money-cost.md) uses the same menu, paid with money instead of keys. Every option shows its total cost, and an option turns red when the player cannot afford it. Choosing one opens a confirmation with the total before anything is charged, so ten openings of a $250 crate ask for $2,500 once and roll rewards ten times. The available keys item is hidden for these crates. Shift-right-click open-all opens as many as the player can afford, up to the open-all limit, or 100 when the limit is set to all. Only the Random rewards mode supports paid mass opening. ## Selective Mode On a crate using the Selective (non RNG) rewards mode, a player holding more than one key gets the [Mass Selection](mass-selection.md) menu instead, where several rewards are picked and opened together. ## Reroll If the reroll feature is enabled along with mass opening, a different behavior occurs when using any opening option other than the single-key opening. Instead of receiving rewards individually, the player will see a menu displaying all the rewards they’ve won. They can click on any item to reroll it. Additionally, there's a Claim All Rewards option to collect everything at once. **Menu:** `default_crate_mass_reroll`

Crate Interaction

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/mass-opening/crate-interaction --- # 🧺 Mass Selection ## Mass Selection Mass selection is the Selective (non RNG) counterpart of the mass opening menu. Instead of spending one key on one reward at a time, the player picks several rewards, and how many of each, then receives all of them in a single opening. It takes over the normal select reward menu when the crate uses Selective mode, requires a key, has mass opening enabled, and the player owns more than one key. With a single key, the regular select reward menu is used instead. **Menu:** `default_crate_mass_selective` > **Info:** The opening amounts (x1, x6, x12...), the Open All option, the mass opening permissions and the global mass opening options only apply to crates in Random mode. On a selective crate the player's whole key balance is the selection limit. ## Selecting Rewards Left-clicking a reward adds one copy to the selection, right-clicking removes one. A selected reward is swapped for the selection material and stacked to the amount picked, so the count of every choice stays visible while browsing. The total number of selections is capped by the keys the player currently owns. Once the cap is reached, the remaining rewards gain an extra lore line and clicking them sends a message instead of selecting. Rewards the player cannot obtain at that moment, because of a missing permission, a reached win limit or a win cooldown, are shown as locked and cannot be selected. Disabled rewards and rewards past their time limit are not listed at all. ## Rarity Groups Rewards belonging to a rarity with [Group Rewards](../rarity/reward-groups.md) enabled are collapsed into a single category icon. Clicking it opens the same menu filtered to that rarity, where the player selects normally, and closing it returns to the full list. Selections made inside a category are kept, so the cap and the confirm item always count every choice across all categories. ## Confirming The confirm item shows how many rewards are selected against the keys available. Confirming consumes one key per selected reward and opens all of them in one crate opening. The Required Keys value of a reward, or of its rarity, is not applied here: every selection costs exactly one key. Rerolling is always skipped for a mass selection opening, even when reroll is enabled on the crate. ## Customization The menu has its own items and options on top of the usual settings, pagination and items: | Option | Description | | ----------------------- | --------------------------------------------------------------------------------- | | Confirm | The item that validates the selection and opens the crate. | | Reward Item | Name and lore applied on top of each selectable reward. | | Locked Reward Item | Name and lore used for rewards the player cannot obtain. | | Selected Material | The material a reward is replaced with once selected. | | Sounds | The sounds played when selecting, unselecting, and when an action is not allowed. | | Max Selections Lore | Extra lore added to the rewards that can no longer be selected. | | Max Selections Message | The message sent when clicking a reward past the selection cap. | The following placeholders are available in this menu: | Placeholder | Description | | -------------------- | -------------------------------------------------- | | `%total_selections%` | Total amount of rewards currently selected. | | `%available_keys%` | Amount of keys the player owns for that crate. | | `%selected_amount%` | Amount selected of that specific reward. | | `%reward_name%` | Display name of the reward. | | `%reward_lore%` | Lore of the reward. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/mass-opening/mass-selection --- # 🔒 Permissions ## Permissions Each opening option above the first is gated separately, so a server can sell larger openings by rank. An option the player has no permission for is shown greyed out rather than hidden. | Permission | Description | | -------------------------- | ----------------------------------------------- | | phoenixcrates.massopen.1 | Gives access to the 2nd opening of a crate | | phoenixcrates.massopen.2 | Gives access to the 3rd opening of a crate | | phoenixcrates.massopen.3 | Gives access to the 4th opening of a crate | | phoenixcrates.massopen.4 | Gives access to the 5th opening of a crate | | phoenixcrates.massopen.all | Gives access to the Open All opening of a crate | | phoenixcrates.massopen.\* | Gives access to all the openings | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/mass-opening/permissions --- # ⚙️ Settings ## Mass Opening With mass opening, players are able to open many keys simultaneously and obtain rewards. It is turned on per crate through its own menu, and starts out disabled.

Editor > Crates > Crate

## Opening Settings There are six opening options, all configurable except the single-key one, defaulting to x1, x6, x12, x32, x64 and x100. The largest can also be set to consume every key the player holds. Each option can be turned off on its own, and the amounts have to stay in ascending order, so an option can never be raised past the next one. Disabling every option turns mass opening off for that crate. > **Info:** The Open All maximum cannot be set below the highest opening option. Lowering it past that value snaps it back up, which can look like the setting is not saving. Lower the option above it first. The opening options apply to crates in Random mode. A selective crate uses the [Mass Selection](mass-selection.md) menu instead, where the key balance is the only limit.

Editor > Crates > Crate > Mass Opening

## Global Settings These apply to every crate at once rather than to one crate, and all three only affect crates in Random mode. They sit under the add-on's own entry in the editor settings.

Editor

### Skip Single Key Menu Sends a player straight into the opening when they only hold one key, since a menu offering a single choice has nothing to decide. On by default.

Editor > Settings > Mass Opening

### Shift Right-Click Open All Gives players a shortcut past the menu entirely, spending every key they hold in one interaction. On a [paid crate](crate-interaction.md#paying-with-money) it opens as many as the player can afford instead, after a confirmation. Off by default, and it still respects the Open All permission.

Editor > Settings > Mass Opening

### Toggle Mass Opening Menu Suppresses the menu for every crate, so interacting opens one key at a time as though the add-on were not installed. Useful for turning mass opening off server-wide without touching each crate.

Editor > Settings > Mass Opening

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/mass-opening/settings --- # 🏅 Milestones ## Information The Milestones add-on rewards a player for the number of crates they have opened, turning a long grind into a set of visible goals. A milestone can watch one crate or every crate at once, and its reward can be handed over automatically or left in a menu for the player to claim. Progress is read from the openings the plugin already records on each player, so installing the add-on does not reset or re-count anything. A player who has already opened 400 crates arrives with that progress intact. ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. PlaceholderAPI is only needed for the progress placeholders, the milestones themselves work without it. ## Files | File | What it holds | | ---- | ------------- | | `PhoenixCrates/milestones.yml` | The milestone tiers and the two add-on settings. | | `PhoenixCrates/menus/default_crate_milestones.yml` | The layout of the milestones menu. | | `PhoenixCrates/translations/milestones.translations..yml` | The add-on messages. | The claimed tiers are stored per player in the database, in the `player_milestones_table` table, so they follow the player across every server sharing that database. ## Bedrock Bedrock players get the milestones menu as a [Bedrock form](../../configurations/geysermc-bedrock.md#bedrock-forms): a button per tier with its progress. Tapping an unlocked tier claims it, any other tier shows its description. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/milestones --- # 🎯 Milestones ## Tiers Every tier lives under `milestones` in milestones.yml. A tier is unlocked once the player's opening count on its track reaches `required-openings`. ```yaml milestones: '0': identifier: first_steps display-item: material: DIAMOND display-name: '&aFirst Steps' amount: 1 crate: '*' required-openings: 10 win-items: {} win-commands: - 'crate giveKey vote %player% 3' win-message: - '&aYou reached the &f%milestone%&a milestone!' broadcast-message: - '&e%player% &areached the &f%milestone%&a milestone!' required-permissions: [] auto-claim: false broadcast: false max-win-item-amount: -1 max-win-command-amount: -1 ``` > **Info:** Tiers are stored as a numbered section rather than a YAML list, which is the same shape the crate rewards use. The numbers are positions only, so they have to stay unique inside the section, and reordering them changes the order shown in the menu but nothing else. ## Options | Option | What it does | | ------ | ------------ | | `identifier` | The name the tier is stored under. Renaming it makes every player able to claim the tier again, so treat it as permanent. | | `display-item` | The item shown in the milestones menu. | | `crate` | Which openings are counted. A crate identifier counts only that crate; `*` counts every crate together. | | `required-openings` | How many openings unlock the tier. | | `win-items` | Items handed to the player. | | `win-commands` | Commands run when the tier is claimed. Prefix a command with `*` to run it as the player instead of the console. | | `win-message` | Sent to the player who claimed the tier. | | `broadcast-message` | Sent to every online player, only when `broadcast` is on. | | `required-permissions` | The player needs at least one of these to see or claim the tier. Leave empty for everyone. | | `auto-claim` | Hands the reward over the moment the tier unlocks instead of waiting for a click. | | `broadcast` | Announces the tier to the whole server. | | `max-win-item-amount` | How many of the win items are given, `-1` for all of them. | | `max-win-command-amount` | How many of the win commands are run, `-1` for all of them. | ## Tracks Tiers are grouped by the crate they watch, and each group runs its own ladder. A tier on `vote` and a tier on `*` are on separate ladders, so a player can be part way through both at once. The menu lists every tier in ascending order of `required-openings`, whichever track it belongs to. > **Info:** `crate` is matched against the crate identifier, not its display name. A tier pointing at a crate that no longer exists simply never unlocks. ## Message placeholders `win-message` and `broadcast-message` accept: | Placeholder | Value | | ----------- | ----- | | `%player%` | The player who claimed the tier. | | `%milestone%` | The display name of the tier. | | `%openings%` | The tier's `required-openings`. | ## Menu placeholders The `locked-milestone`, `claimable-milestone` and `claimed-milestone` entries in menus/default\_crate\_milestones.yml accept: | Placeholder | Value | | ----------- | ----- | | `%milestone%` | The display name of the tier. | | `%item_name%` | The name of the configured display item. | | `%progress%` | Openings on this track, capped at the requirement. | | `%total_progress%` | Openings on this track, uncapped. | | `%required%` | Openings needed to unlock the tier. | | `%percent%` | Progress as a whole number out of 100. | | `%crate%` | The crate identifier, or the "Any Crate" label for a `*` tier. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/milestones/milestones --- # 📜 Placeholders ## PlaceholderAPI Placeholders | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_milestones_claimed% | How many tiers the player has claimed. | | %phoenixcrates_milestones_pending% | How many unlocked tiers are waiting to be claimed. | | %phoenixcrates_milestones_progress_\% | The player's openings on that track. | | %phoenixcrates_milestones_next_\% | The display name of the next unclaimed tier on that track. | | %phoenixcrates_milestones_remaining_\% | Openings still needed to unlock that tier. | The three track placeholders take a crate identifier. Use `*` to read the "any crate" track. ``` %phoenixcrates_milestones_next_vote% %phoenixcrates_milestones_remaining_*% ``` A track whose tiers have all been claimed reports `-` for `next` and `0` for `remaining`, so a scoreboard line can be left in place once a player finishes the ladder. > **Info:** A player whose crate data has not finished loading reports `N/A` rather than a wrong number. Seeing it briefly on login is expected. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/milestones/placeholders --- # ⚙️ Settings ## Settings Both settings sit at the top of milestones.yml. ### claim-retroactively Decides what happens to the tiers a player had already passed before the add-on was installed. On by default, those tiers are offered as normal, which is what you want on a new setup. Turned off, the tiers a player has already passed are written off once, silently, the first time their milestones are evaluated. Only the tiers they cross from that point on pay out. This is the setting to use when adding milestones to an established server, where the default would hand a veteran player every tier at once. > **Warning:** The write-off happens per player and cannot be undone by turning the setting back on. Decide before the add-on goes live on a server with existing players. ### notify-on-join Tells a player shortly after they log in how many rewards are waiting to be claimed. Only players with something pending are messaged. On by default. ## Commands * `/crate milestones [player]` - Opens the milestones menu. Without an argument it opens for the sender. * `/crate resetMilestones ` - Clears the tiers a player has claimed, letting them claim every unlocked tier again. Requires `phoenixcrates.command.resetmilestones`. ## Permissions | Permission | What it allows | | ---------- | -------------- | | `phoenixcrates.command.resetmilestones` | Resetting a player's claimed milestones. | Individual tiers are gated with their own `required-permissions` list rather than a permission node, so a rank-only milestone is configured on the tier itself. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/milestones/settings --- # 💍 Rarity ## Information The Rarity add-on adds categories to PhoenixCrates. Rarities are attached to rewards to synchronize their drop rates, or to keys to guarantee a reward of a specific rarity.

Rarities - Add-On

👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/rarities-addon) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Rarities ### Create a Rarity Rarities have their own category in the editor, where they are created and managed. Clicking the stained glass adds a new one.

Editor > Rarities

Every rarity already created is listed there with its identifier, and opening one leads to its own settings.

Editor > Rarities

A rarity is attached to rewards on [Reward Rarity](reward-rarity.md) and to keys with [Guarantee Rarity Reward](../../main-features/keys/README.md#guarantee-rarity-reward). ## Edit Rarity ### Identifier With this option, you can set an identifier for the rarity. Note that the rarity identifier is unique and used internally by the plugin, and its different from the display name.

Editor > Rarities > Rarity

> **Danger:** If the identifier is changed, all rarities associated with the rewards/keys will no longer work. ### Display Name With this option, you can adjust the display name of the rarity. The display name is typically shown in the reward/key lore. For the display name, you can use the default Minecraft color codes. For hex colors, use the \&#D6D045 format.

Editor > Rarities > Rarity

### Enabled With this option, you can disable the rarity. It stays attached to its rewards and keys, but those rewards can no longer be won and their lore shows Not set in place of the rarity name.

Editor > Rarities > Rarity

### Group Rewards With this option, every reward carrying this rarity is collapsed into a single category icon in the rewards preview, the select reward menu and the mass selection menu, instead of being listed one by one. The category and the item representing it are covered in [Reward Groups](reward-rarity.md#reward-groups).

Editor > Rarities > Rarity

### Delete Rarity This option allows you to permanently delete a rarity. Note that selecting it will first open a confirmation menu before the rarity is deleted. Additionally, the rarity will still be attached to a reward/key.

Editor > Rarities > Rarity

> **Danger:** This option is permanent, and rewards can't be restored. ## Misc Options ### Rarity Weight With this, you can set a weight value for the rarity (default `100`). Every reward attached to that rarity has its own individual chance weight multiplied by `rarity weight / 100` before the crate's normal chance calculation runs, so a higher rarity weight makes every reward under it proportionally more likely to be picked, and a lower weight makes them rarer, without having to edit each reward's chance individually. It is not a percentage and does not reserve a share of the draw.

Editor > Rarities > Rarity

> **Info:** If a rarity is disabled, every reward attached to it becomes impossible to win (effective weight `0`) until the rarity is re-enabled. ### Required Keys With this, you can set how many keys are required to redeem a reward of this rarity when the crate uses the Selective (non RNG) rewards mode (default `1`). Once a rarity is assigned to a reward, this value overrides that reward's own individual Required Keys setting.

Editor > Rarities > Rarity

### Opening Animation With this, you can pick a second phase animation for the rarity. When the reward drawn from a crate has this rarity, its animation plays instead of the crate's own second phase. Leaving it on Crate Default keeps the crate's animation.

Rarity (Opening Animation)

The override only applies when the rarity's animation runs in the same place as the crate's: a GUI animation can replace a GUI one and a world animation a world one. Otherwise the crate's animation plays. When one opening draws several rewards, the first one decides. Only GUI animations and world animations without settings of their own can be picked. ### Win Actions With this, you can set actions that run when a reward of this rarity is won, such as a sound or a broadcast for a legendary drop. They replace the crate's and the global On Win actions, and a reward with its own win actions still uses those instead. The placeholders and how one opening with several rewards is handled are covered in [Event Actions](../../main-features/crates/README.md#event-actions).

Rarity (Win Actions)

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity --- # 🎟️ Edit Rarity ## Identifier With this option, you can set an identifier for the rarity. Note that the rarity identifier is unique and used internally by the plugin, and its different from the display name.

Editor > Rarities > Rarity

> **Danger:** If the identifier is changed, all rarities associated with the rewards/keys will no longer work. ## Display Name With this option, you can adjust the display name of the rarity. The display name is typically shown in the reward/key lore. For the display name, you can use the default Minecraft color codes. For hex colors, use the \&#D6D045 format.

Editor > Rarities > Rarity

## Enabled With this option, you can disable the rarity. The rarity will remain to the key and rewards, but only as a display name for their lore.

Editor > Rarities > Rarity

## Group Rewards With this option, every reward carrying this rarity is collapsed into a single category icon in the rewards preview, the select reward menu and the mass selection menu, instead of being listed one by one. The category and the item representing it are covered in [Reward Groups](reward-groups.md).

Editor > Rarities > Rarity

## Delete Rarity This option allows you to permanently delete a rarity. Note that selecting it will first open a confirmation menu before the key is deleted. Additionally, the rarity will still be attached to a reward/key.

Editor > Rarities > Rarity

> **Danger:** This option is permanent, and rewards can't be restored. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity/edit-rarity --- # 📈 Misc Options ## Rarity Weight With this, you can set a weight value for the rarity (default `100`). Every reward attached to that rarity has its own individual chance weight multiplied by `rarity weight / 100` before the crate's normal chance calculation runs, so a higher rarity weight makes every reward under it proportionally more likely to be picked, and a lower weight makes them rarer, without having to edit each reward's chance individually. It is not a percentage and does not reserve a share of the draw.

Editor > Rarities > Rarity

> **Info:** If a rarity is disabled, every reward attached to it becomes impossible to win (effective weight `0`) until the rarity is re-enabled. ## Required Keys With this, you can set how many keys are required to redeem a reward of this rarity when the crate uses the Selective (non RNG) rewards mode (default `1`). Once a rarity is assigned to a reward, this value overrides that reward's own individual Required Keys setting.

Editor > Rarities > Rarity

## Opening Animation With this, you can pick a second phase animation for the rarity. When the reward drawn from a crate has this rarity, its animation plays instead of the crate's own second phase. Leaving it on Crate Default keeps the crate's animation.

Rarity (Opening Animation)

The override only applies when the rarity's animation runs in the same place as the crate's: a GUI animation can replace a GUI one and a world animation a world one. Otherwise the crate's animation plays. When one opening draws several rewards, the first one decides. Only GUI animations and world animations without settings of their own can be picked. ## Win Actions With this, you can set actions that run when a reward of this rarity is won, such as a sound or a broadcast for a legendary drop. They replace the crate's and the global On Win actions, and a reward with its own win actions still uses those instead. The placeholders and how one opening with several rewards is handled are covered in [Event Actions](../../main-features/crates/misc-options.md#event-actions).

Rarity (Win Actions)

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity/misc-options --- # 💍 Rarities ## Create a Rarity Rarities have their own category in the editor, where they are created and managed. Clicking the stained glass adds a new one.

Editor > Rarities

Every rarity already created is listed there with its identifier, and opening one leads to its own settings.

Editor > Rarities

## Navigation From here, you can quickly navigate to a specific feature related to rarities. | Feature | Description | | ------------------------------------------------------------------------------------- | --------------------------------------- | | [Identifier](edit-rarity.md#identifier) | Set a unique ID for your rarity. | | [Display Name](edit-rarity.md#display-name) | Change the display name for the rarity. | | [Weight](misc-options.md#rarity-weight) | Set the chance weight for the rarity. | | [Required Keys](misc-options.md#required-keys) | Set how many keys are needed to redeem a reward of this rarity in Selective mode. | | [Opening Animation](misc-options.md#opening-animation) | Play a different second phase animation for this rarity. | | [Win Actions](misc-options.md#win-actions) | Run actions when a reward of this rarity is won. | | [Enabled](edit-rarity.md#enabled) | Swap the status of the rarity. | | [Group Rewards](edit-rarity.md#group-rewards) | Collapse every reward of this rarity into one category. | | [Display Item](reward-groups.md#display-item) | Customize the item representing the category. | | [Preview Menu](reward-groups.md#preview-menu) | Override the menu used when previewing a category. | | [Delete Rarity](edit-rarity.md#delete-rarity) | Quick delete the rarity. | | [Reward Rarity](reward-rarity.md) | Assign a Rarity to a Reward. | | [Key Rarity](../../main-features/keys/edit-key.md#guarantee-rarity-reward) | Assign a Rarity to a Key. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity/rarities --- # 🗂️ Reward Groups ## Reward Groups A rarity with [Group Rewards](edit-rarity.md#group-rewards) enabled collapses every reward carrying it into one category icon instead of listing them one by one. Players open the category to browse or pick from it, which keeps crates with a long reward list readable. Rewards without a grouped rarity keep their own slot and are listed after the categories. A rarity that is disabled never groups, its rewards go back to being listed individually.

Editor > Crates > Crate > Rewards

Opening a category lists the rewards it holds, each one editable from there like any other reward.

Editor > Crates > Crate > Rewards > Category

## Where Groups Appear | Menu | Behaviour | | ------------------------------------------------------------------- | ------------------------------------------------------------------ | | Rewards Preview | The category opens a preview filtered to that rarity. | | Select Reward | The category opens the rewards of that rarity to choose from. | | [Mass Selection](../mass-opening/mass-selection.md) | The category opens a filtered selection shared with the main menu. | | Editor > Crates > Crate > Rewards | The category opens its settings and the rewards it contains. | ## Display Item By default a category is shown as a chest named after the rarity, with the number of rewards it contains in the lore. Opening the category from the crate reward list in the editor gives access to its settings, where the icon can be replaced with any item and given a custom display name and lore, both supporting MiniMessage. An Item Properties sub-menu goes further: RGB color, item flags, banner patterns, enchantments, model data and item model, enchantment glint override, potion effects, armor trim, and tooltip style.

Editor > Crates > Crate > Rewards > Category

## Preview Menu Clicking a category in the rewards preview opens the crate's own preview menu, filtered to that rarity. With this option you can point a category at a different preview menu instead, which is useful to give a rarity its own title, size or decoration. Leaving it unset keeps the crate's preview menu.

Editor > Crates > Crate > Rewards > Category

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity/reward-groups --- # 🥇 Reward Rarity By assigning a rarity to your rewards, you can easily organize them across different crates.

Editor > Crates > Crate > Rewards > Reward

## Rarity Display When you select a rarity for your reward, its rarity is used to compute the reward's actual win chance (via the rarity's [Weight](README.md#rarity-weight)), and the rarity's display name becomes available in the reward's lore through the `%rarity_name%` placeholder. Since the chance calculation already accounts for the rarity's weight, the reward's displayed percentage always reflects the rarity automatically, without needing a separate sync toggle. If the rarity has [Required Keys](README.md#required-keys) set, it also overrides the reward's own Required Keys value when the crate uses Selective (non RNG) mode.

Editor > Crates > Crate > Rewards

Editor > Crates > Crate > Rewards > Reward

## Reward Groups A rarity with [Group Rewards](README.md#group-rewards) enabled collapses every reward carrying it into one category icon instead of listing them one by one. Players open the category to browse or pick from it, which keeps crates with a long reward list readable. Rewards without a grouped rarity keep their own slot and are listed after the categories. A rarity that is disabled never groups, its rewards go back to being listed individually.

Editor > Crates > Crate > Rewards

Opening a category lists the rewards it holds, each one editable from there like any other reward.

Editor > Crates > Crate > Rewards > Category

### Where Groups Appear | Menu | Behaviour | | ------------------------------------------------------------------- | ------------------------------------------------------------------ | | Rewards Preview | The category opens a preview filtered to that rarity. | | Select Reward | The category opens the rewards of that rarity to choose from. | | [Mass Selection](../mass-opening/README.md#mass-selection) | The category opens a filtered selection shared with the main menu. | | Editor > Crates > Crate > Rewards | The category opens its settings and the rewards it contains. | ### Display Item By default a category is shown as a chest named after the rarity, with the number of rewards it contains in the lore. Opening the category from the crate reward list in the editor gives access to its settings, where the icon can be replaced with any item and given a custom display name and lore, both supporting MiniMessage. An Item Properties sub-menu goes further: RGB color, item flags, banner patterns, enchantments, model data and item model, enchantment glint override, potion effects, armor trim, and tooltip style.

Editor > Crates > Crate > Rewards > Category

### Preview Menu Clicking a category in the rewards preview opens the crate's own preview menu, filtered to that rarity. With this option you can point a category at a different preview menu instead, which is useful to give a rarity its own title, size or decoration. Leaving it unset keeps the crate's preview menu.

Editor > Crates > Crate > Rewards > Category

Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/rarity/reward-rarity --- # 🗄️ Redis ## Information The Redis add-on caches player data in Redis and keeps it in sync across a network of servers, so keys, cooldowns and win limits stay consistent as players move between them. 👉 [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. ## Redis Redis sits in front of your database, it does not replace it. On the first start it generates a `redis.yml` file in the plugin's folder, where you set your connection details. > **Warning:** You still need MySQL configured. Redis is only the cache and locking layer, all data is still written to the database. ## Player Locking While a server is handling a player, it holds a lock on that player in Redis so no other server can write their data at the same time. The lock is refreshed for as long as the player is online, and released when they leave or when the server shuts down. If a lock cannot be obtained in time, the change is written straight to the database instead, so no rewards or keys are lost. ## Cross-Server Messaging Servers connected to the same Redis with the same key prefix send each other messages, so an action taken on one server reaches the rest of the network. Resetting every [Crate Claim](crate-claim/README.md#admin-commands), for example, also clears the claims cached on the other servers. Messaging is enabled by default. If the messaging connection drops, the server keeps retrying on its own until it is restored. ## Settings | Setting | Description | | ------- | ----------- | | Host / Port / Password / Database | The connection details of your Redis server. | | Connection Pool | The maximum, idle, and minimum number of connections kept open. Default is `8`, `8`, and `0`. | | Key Prefix | The prefix used for every key the add-on writes and for its messaging channel. Networks sharing one Redis server stay apart, with separate player data, locks and messages, as long as each uses its own prefix. Default is `phoenixcrates`. | | Data TTL | How long, in seconds, cached player data is kept. Default is `3600`. | | Lock TTL | How long, in seconds, a player lock stays valid without a refresh. Default is `15`. | | Heartbeat Interval | How often, in seconds, held locks are refreshed. Default is `5`. | | Lock Poll Interval | How often, in milliseconds, a server retries while waiting for a lock. Default is `200`. | | Max Lock Wait | How long, in milliseconds, to keep waiting for a lock before giving up and writing straight to the database. Default is `15000`. | | Messaging | Turns cross-server messaging on or off. Enabled by default. | | Messaging Channel | The channel servers talk over, placed after the key prefix. Default is `messages`. | | Reconnect Delay | How long, in seconds, to wait before retrying a lost messaging connection. Default is `5`, and the minimum is `1`. | | Debug | Logs every cache and lock operation to the console. Disabled by default. | ```yaml lock: heartbeat-interval-seconds: 5 ttl-seconds: 15 poll-interval-ms: 200 max-wait-ms: 15000 ``` > **Info:** The two lock timing options are not written into `redis.yml` when the file is first created. Add them yourself if you need to change them from the defaults above. > **Info:** If the connection to Redis fails on startup, the add-on logs a warning and the plugin keeps running on the database alone, without cross-server messaging. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/redis --- # 🔁 Reward On Loop ## Information The Reward On Loop add-on gives a reward to every online player on a fixed timer, independently from crates and keys.

Reward On Loop - Add-On

👉 [You can claim this add-on for free on Phoenix Plugins](https://www.phoenixplugins.com/product/reward-on-loop) ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. PlaceholderAPI is only needed for the countdown placeholders, the rewards themselves fire without it. ## Loop Rewards Loop rewards are reached from the Reward On Loop button in the main editor. Each one runs on its own timer, so several can fire on completely different schedules.

Editor

### Add Loop Reward Creates a new loop reward and opens it for editing. There is no limit on how many you can have, and a new one starts on its interval right away.

Editor > Loop Rewards

### Display Item The icon and name the reward is listed under in the editor. It is never given to anyone, but its name is what `%reward%` prints in the win message.

Editor > Loop Reward

### Win Items The physical items handed to each player when the reward fires.

Editor > Loop Reward

### Win Commands The commands run when the reward fires, once per receiving player.

Editor > Loop Reward

### Win Message The message each receiving player is sent. Leaving it empty sends nothing at all, which is the way to make a reward arrive silently.

Editor > Loop Reward

### Interval (seconds) How long between two firings of this reward. Changing it restarts the countdown, so the next reward is a full interval away rather than carrying over what had already elapsed. An interval of `0` stops the reward from ever firing, which is how a loop reward is paused without deleting it.

Editor > Loop Reward

### Timer Mode Whether the countdown is shared or personal. Changing it restarts the countdown the same way the interval does. | Mode | Behaviour | | ---- | --------- | | Global | One countdown for the whole server, so everyone is rewarded at the same moment. This is the default. | | Per Player | Each player has their own countdown, starting the moment they join. |

Editor > Loop Reward

> **Warning:** A Per Player countdown is dropped when the player disconnects, so they begin a fresh interval on their next join instead of resuming where they left off. A player who reconnects often enough never reaches the reward. ### Required Permissions Restricts the reward to players holding at least one of the listed permissions. An empty list, which is the default, gives it to everyone.

Editor > Loop Reward

### Max Win Item Amount Caps how many of the win items are actually delivered per firing. Unlimited hands over the whole list.

Editor > Loop Reward

### Max Win Command Amount The same cap for the win commands.

Editor > Loop Reward

### Max Wins Per Player How many times one player may receive this reward before being skipped for good.

Editor > Loop Reward

> **Info:** Win counts are held in memory only, so a server restart lets everyone win up to the cap again. Renaming the reward's identifier clears them the same way. ### Identifier The internal name the countdown placeholders address the reward by. It cannot contain spaces, and renaming it restarts the countdown.

Editor > Loop Reward

### Delete Permanently removes the loop reward after a confirmation prompt.

Editor > Loop Reward

> **Info:** With the [IP Limit](../ip-limit/) add-on installed, a loop reward reaches only a limited number of accounts per IP address each time it fires. That cap is set under Global Limits and cannot be overridden per key or crate. ## Placeholders Every placeholder reports the time left until a loop reward fires again. With Per Player timer mode they show the viewing player's own countdown, and with Global they show the one shared countdown. | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_rewardonloop_nextReward_\% | Time remaining, formatted as `1h 20m 5s`. | | %phoenixcrates_rewardonloop_nextReward_\_hours% | Whole hours remaining. | | %phoenixcrates_rewardonloop_nextReward_\_minutes% | Minutes remaining within the current hour. | | %phoenixcrates_rewardonloop_nextReward_\_seconds% | Seconds remaining within the current minute. | The three unit variants are parts of one countdown rather than three separate totals, so they are meant to be combined into a single line. A reward identifier that does not exist reports zero rather than an error, so a countdown stuck at `0s` usually means the identifier is misspelled. > **Info:** `hours`, `minutes`, `seconds` and `formatted` are read as unit suffixes, so a reward whose identifier ends in one of them cannot be queried. Rename it if a countdown refuses to resolve. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/reward-on-loop --- # 🎁 Loop Rewards ## Reward On Loop Loop rewards are reached from the Reward On Loop button in the main editor. Each one runs on its own timer, so several can fire on completely different schedules.

Editor

## Add Loop Reward Creates a new loop reward and opens it for editing. There is no limit on how many you can have, and a new one starts on its interval right away.

Editor > Loop Rewards

## Display Item The icon and name the reward is listed under in the editor. It is never given to anyone, but its name is what `%reward%` prints in the win message.

Editor > Loop Reward

## Win Items The physical items handed to each player when the reward fires.

Editor > Loop Reward

## Win Commands The commands run when the reward fires, once per receiving player.

Editor > Loop Reward

## Win Message The message each receiving player is sent. Leaving it empty sends nothing at all, which is the way to make a reward arrive silently.

Editor > Loop Reward

## Interval (seconds) How long between two firings of this reward. Changing it restarts the countdown, so the next reward is a full interval away rather than carrying over what had already elapsed. An interval of `0` stops the reward from ever firing, which is how a loop reward is paused without deleting it.

Editor > Loop Reward

## Timer Mode Whether the countdown is shared or personal. Changing it restarts the countdown the same way the interval does. | Mode | Behaviour | | ---- | --------- | | Global | One countdown for the whole server, so everyone is rewarded at the same moment. This is the default. | | Per Player | Each player has their own countdown, starting the moment they join. |

Editor > Loop Reward

> **Warning:** A Per Player countdown is dropped when the player disconnects, so they begin a fresh interval on their next join instead of resuming where they left off. A player who reconnects often enough never reaches the reward. ## Required Permissions Restricts the reward to players holding at least one of the listed permissions. An empty list, which is the default, gives it to everyone.

Editor > Loop Reward

## Max Win Item Amount Caps how many of the win items are actually delivered per firing. Unlimited hands over the whole list.

Editor > Loop Reward

## Max Win Command Amount The same cap for the win commands.

Editor > Loop Reward

## Max Wins Per Player How many times one player may receive this reward before being skipped for good.

Editor > Loop Reward

> **Info:** Win counts are held in memory only, so a server restart lets everyone win up to the cap again. Renaming the reward's identifier clears them the same way. ## Identifier The internal name the countdown placeholders address the reward by. It cannot contain spaces, and renaming it restarts the countdown.

Editor > Loop Reward

## Delete Permanently removes the loop reward after a confirmation prompt.

Editor > Loop Reward

> **Info:** With the [IP Limit](../ip-limit/) add-on installed, a loop reward reaches only a limited number of accounts per IP address each time it fires. That cap is set under Global Limits and cannot be overridden per key or crate. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/reward-on-loop/loop-rewards --- # 📜 Placeholders ## PlaceholderAPI Placeholders Every placeholder reports the time left until a loop reward fires again. With Per Player timer mode they show the viewing player's own countdown, and with Global they show the one shared countdown. | Placeholder | Description | | ----------- | ----------- | | %phoenixcrates_rewardonloop_nextReward_\% | Time remaining, formatted as `1h 20m 5s`. | | %phoenixcrates_rewardonloop_nextReward_\_hours% | Whole hours remaining. | | %phoenixcrates_rewardonloop_nextReward_\_minutes% | Minutes remaining within the current hour. | | %phoenixcrates_rewardonloop_nextReward_\_seconds% | Seconds remaining within the current minute. | The three unit variants are parts of one countdown rather than three separate totals, so they are meant to be combined into a single line. A reward identifier that does not exist reports zero rather than an error, so a countdown stuck at `0s` usually means the identifier is misspelled. > **Info:** `hours`, `minutes`, `seconds` and `formatted` are read as unit suffixes, so a reward whose identifier ends in one of them cannot be queried. Rename it if a countdown refuses to resolve. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/reward-on-loop/placeholders --- # 🎟️ Vouchers ## Information The Vouchers add-on adds redeemable codes. A code can hand out crate keys, items and commands, and can be limited by how many times it is used in total, how many times one player may use it, and when it stops working. It is the piece a giveaway needs: a code posted in Discord, a code bundled with a store purchase, or a one-off code for a single player, all created in game without editing a file. ## Installation To install this add-on, you can either: - Drag and drop the jar file into the PhoenixCrates/addons folder, then restart your server. - Download the plugin with the add-on selected during the downloading. > **Warning:** The add-on requires the Premium edition. ## Files | File | What it holds | | ---- | ------------- | | `PhoenixCrates/vouchers.yml` | The codes, their rewards and the code generator settings. | | `PhoenixCrates/translations/vouchers.translations..yml` | The add-on messages. | Which codes a player has redeemed is stored per player in the database, in the `player_vouchers_table` table. The number of times a code has been used across the whole server is stored on the code itself in `vouchers.yml`, so it survives a restart. Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/vouchers --- # 🏷️ Codes ## Codes Every code lives under `vouchers` in vouchers.yml. ```yaml generated-code-alphabet: ABCDEFGHJKLMNPQRSTUVWXYZ23456789 generated-code-length: 8 vouchers: '0': code: SUMMER25 enabled: true display-name: '&6Summer Giveaway' display-item: material: PAPER display-name: '&aVoucher' amount: 1 key-rewards: '0': key: vote amount: 5 win-items: {} win-commands: [] redeem-message: - '&aYou redeemed the code &f%code%&a!' broadcast-message: - '&e%player% &aredeemed the code &f%code%&a!' broadcast: false max-uses: 100 max-uses-per-player: 1 expires-at: -1 permission: '' uses: 0 max-win-item-amount: -1 max-win-command-amount: -1 ``` > **Info:** Codes and their key rewards are stored as numbered sections rather than YAML lists, the same shape the crate rewards use. The numbers are positions only and have to stay unique inside their section. ## Options | Option | What it does | | ------ | ------------ | | `code` | What the player types. Matched without regard to casing, so `summer25` and `SUMMER25` are the same code. | | `enabled` | Switches the code off without deleting it or losing its usage count. | | `display-name` | A friendly name used in messages. Falls back to the code itself when empty. | | `display-item` | The icon the reward pipeline uses when the items are handed over. | | `key-rewards` | The keys the code gives, as a list of `key` and `amount` pairs. | | `win-items` | Items the code gives. | | `win-commands` | Commands run when the code is redeemed. Prefix a command with `*` to run it as the player instead of the console. | | `redeem-message` | Sent to the player who redeemed the code. | | `broadcast-message` | Sent to every online player, only when `broadcast` is on. | | `broadcast` | Announces the redemption to the whole server. | | `max-uses` | Redemptions allowed across the whole server, `-1` for unlimited. | | `max-uses-per-player` | Redemptions allowed per player, `-1` for unlimited. Defaults to `1`. | | `expires-at` | Epoch milliseconds after which the code stops working, `-1` for never. | | `permission` | The player needs this to redeem the code. Leave empty for everyone. | | `uses` | How many times the code has been redeemed. Maintained by the plugin. | | `max-win-item-amount` | How many of the win items are given, `-1` for all of them. | | `max-win-command-amount` | How many of the win commands are run, `-1` for all of them. | > **Warning:** `uses` is written by the plugin. Editing it by hand changes how many redemptions are left on a code with a `max-uses` cap, and setting it back to `0` reopens a code that had run out. ## Limits The two caps do different jobs and are usually combined. `max-uses-per-player` stops one player redeeming the same code repeatedly, and `max-uses` caps the giveaway as a whole. Both are enforced at the moment of redemption rather than on a timer, so two players redeeming the last remaining use at the same instant cannot both get through — one of them is told the code is exhausted. ## Generated codes `generated-code-alphabet` and `generated-code-length` control the codes produced by `/crate createVoucher` when it is asked to generate one. The default alphabet leaves out `I`, `O`, `0` and `1`, so a code read off a screenshot or a Discord message cannot be mistyped into a different valid code. Generated codes are always checked against the existing ones before being used. ## Message placeholders `redeem-message` and `broadcast-message` accept: | Placeholder | Value | | ----------- | ----- | | `%player%` | The player who redeemed the code. | | `%code%` | The code itself. | | `%voucher%` | The display name, falling back to the code. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/vouchers/codes --- # 🤖 Commands ## Player Commands * `/crate redeem ` - Redeems a code. Needs no permission, though an individual code can require one through its own `permission` option. ## Admin Commands * `/crate createVoucher [amount] [uses]` - Creates a code granting a number of one key. Pass `-` as the code to generate one instead of choosing it. `uses` is the total across the server, `-1` for unlimited. Requires `phoenixcrates.command.createvoucher`. * `/crate deleteVoucher ` - Deletes a code. Requires `phoenixcrates.command.deletevoucher`. * `/crate vouchers` - Lists every code with its usage count and status. Requires `phoenixcrates.command.vouchers`. * `/crate resetVouchers ` - Clears which codes a player has redeemed, letting them redeem them all again. Requires `phoenixcrates.command.resetvouchers`. ## Permissions | Permission | What it allows | | ---------- | -------------- | | `phoenixcrates.command.createvoucher` | Creating codes. | | `phoenixcrates.command.deletevoucher` | Deleting codes. | | `phoenixcrates.command.vouchers` | Listing codes. | | `phoenixcrates.command.resetvouchers` | Resetting a player's redeemed codes. | ## Creating a code in game ``` /crate createVoucher SUMMER25 vote 5 100 ``` Creates `SUMMER25`, granting five `vote` keys, redeemable a hundred times across the server and once per player. ``` /crate createVoucher - legendary 1 1 ``` Generates a code granting a single `legendary` key that only one player can ever use, which is the shape a personal reward or a single-winner giveaway takes. A code made this way is written straight into vouchers.yml and works immediately, with no reload. Anything the command does not cover — items, commands, an expiry date, a permission — is edited into the file afterwards. > **Info:** The command refuses a code that already exists rather than overwriting it, so an accidental repeat cannot wipe the usage count of a live giveaway. ## Status in the list `/crate vouchers` marks each code as one of: | Status | Meaning | | ------ | ------- | | `active` | Redeemable. | | `disabled` | `enabled` is off. | | `expired` | Past its `expires-at`. | | `exhausted` | Has reached `max-uses`. | Source: https://www.phoenixplugins.com/docs/phoenix-crates/add-ons/vouchers/commands --- # 🌐 API > **Danger:** The API is only available for the premium version of the plugin. Build your own extensions for Phoenix Crates with our public API. [Events](events.md) and [Examples](examples.md) have their own pages. ## Maven Repository ```xml phoenixplugins https://repo.phoenixplugins.com/ ``` ## Dependency ```xml com.phoenixplugins.phoenixcrates api 1.0.0-SNAPSHOT ``` ## Advanced Access (Internal Classes) Our public API covers the recommended integration points for addons. If you need deeper access to internal classes and systems, we recommend using a direct `systemPath` dependency to your local Phoenix Crates plugin JAR. ```xml com.phoenixplugins.phoenixcrates internal 1.0.0-SNAPSHOT system ${project.basedir}/libs/PhoenixCrates-1.0.0-SNAPSHOT.jar ``` Place the plugin JAR in your project's `libs` folder before building. ## JavaDocs * [Open Phoenix Crates JavaDocs](https://www.phoenixplugins.com/javadocs/phoenix-crates) ## Custom Addons Custom Addons are extensions that allow you to extend, modify, or enhance Phoenix Crates behavior with your own Java code. ### Before You Start 1. Add the [Maven Repository](#maven-repository) and the [Dependency](#dependency) above. 2. Create your addon project (Maven or Gradle). 3. Make sure your final artifact is a shaded or standalone JAR when needed. ### addon.yml Create an `addon.yml` file in your project's resources folder. ```yaml name: AddonName main: your.path.AddonExample author: [YourName] version: 1.0.0 description: Small description (optional) website: https://your-website.com (optional) ``` Required fields: * `name`: Display name of your addon. * `main`: Fully qualified path to your addon main class. * `author`: One or more addon authors. * `version`: Addon version. ### Main Class Example The `main` value in `addon.yml` must point to your class that extends `Addon`. ```java package your.path; import com.phoenixplugins.phoenixcrates.api.sdk.plugin.addons.Addon; public class AddonExample extends Addon { @Override public void onLoad() { // Called when the addon is loaded. } @Override public void onEnable() { // Register listeners, commands, tasks, etc. } @Override public void onDisable() { // Cleanup logic. } @Override public String getRequiredPluginVersion() { return "5.0.0"; } } ``` ### Build and Install 1. Build your addon JAR with your normal project build command. 2. Move the compiled JAR into `plugins/PhoenixCrates/addons`. 3. Restart the server. 4. Check console logs to confirm the addon was loaded successfully. ## Custom Animations Create your own opening phase animations and register them at runtime through the API. ### 1. Create Your Phase Class Extend `OpeningPhaseAnimation` and implement the lifecycle methods: ```java public class YourPhaseAnimation extends OpeningPhaseAnimation { public YourPhaseAnimation(OpeningCrateAnimation animation, OpeningPhaseType type, EmptyOpeningPhaseData data) { super(animation, type, data); } @Override public void load() { } @Override public void tick() { } @Override public void unload() { } } ``` ### 2. Register on Enable Register your phase during addon startup and unregister it on shutdown: ```java public void onEnable() { registerPhase( new OpeningPhaseType(PhaseType.FIRST, "YOUR_PHASE_IDENTIFIER", "Your Display Name", XMaterial.STONE, ServerVersion.v1_16_R1, new XMaterial[] {}, EmptyOpeningPhaseData.class, (animation, type, data) -> new YourPhaseAnimation(animation, type, (EmptyOpeningPhaseData) data), () -> new EmptyOpeningPhaseData())); } public void onDisable() { for (final OpeningPhaseType type : this.registeredPhases) { OpeningPhaseType.unregisterPhase(type); } } private void registerPhase(OpeningPhaseType phase) { // Registering first phase animations OpeningPhaseType.registerPhase(phase); // Caching to unload later on this.registeredPhases.add(phase); } ``` ### Good Practices * Use unique identifiers for each custom phase. * Keep heavy logic out of `tick()` when possible. * Always unregister phases in `onDisable()`. * Test phases on the same Minecraft version as production. Source: https://www.phoenixplugins.com/docs/phoenix-crates/api --- # 🔧 Custom Addons > **Danger:** The API is only available for the premium version of the plugin. Custom Addons are extensions that allow you to extend, modify, or enhance Phoenix Crates behavior with your own Java code. ## Before You Start 1. Add the API dependency from the [API page](README.md). 2. Create your addon project (Maven or Gradle). 3. Make sure your final artifact is a shaded or standalone JAR when needed. ## addon.yml Create an `addon.yml` file in your project's resources folder. ```yaml name: AddonName main: your.path.AddonExample author: [YourName] version: 1.0.0 description: Small description (optional) website: https://your-website.com (optional) ``` Required fields: * `name`: Display name of your addon. * `main`: Fully qualified path to your addon main class. * `author`: One or more addon authors. * `version`: Addon version. ## Main Class Example The `main` value in `addon.yml` must point to your class that extends `Addon`. ```java package your.path; import com.phoenixplugins.phoenixcrates.api.sdk.plugin.addons.Addon; public class AddonExample extends Addon { @Override public void onLoad() { // Called when the addon is loaded. } @Override public void onEnable() { // Register listeners, commands, tasks, etc. } @Override public void onDisable() { // Cleanup logic. } @Override public String getRequiredPluginVersion() { return "5.0.0"; } } ``` ## Build and Install 1. Build your addon JAR with your normal project build command. 2. Move the compiled JAR into `plugins/PhoenixCrates/addons`. 3. Restart the server. 4. Check console logs to confirm the addon was loaded successfully. ## Next Step After your addon loads correctly, continue with [🎞️ Custom Animations](custom-animations.md) to register your own crate animation phases. Source: https://www.phoenixplugins.com/docs/phoenix-crates/api/custom-addons --- # 🎞️ Custom Animations > **Danger:** The API is only available for the premium version of the plugin. Create your own opening phase animations and register them at runtime through the API. ## 1. Create Your Phase Class Extend `OpeningPhaseAnimation` and implement the lifecycle methods: ```java public class YourPhaseAnimation extends OpeningPhaseAnimation { public YourPhaseAnimation(OpeningCrateAnimation animation, OpeningPhaseType type, EmptyOpeningPhaseData data) { super(animation, type, data); } @Override public void load() { } @Override public void tick() { } @Override public void unload() { } } ``` ## 2. Register on Enable Register your phase during addon startup and unregister it on shutdown: ```java public void onEnable() { registerPhase( new OpeningPhaseType(PhaseType.FIRST, "YOUR_PHASE_IDENTIFIER", "Your Display Name", XMaterial.STONE, ServerVersion.v1_16_R1, new XMaterial[] {}, EmptyOpeningPhaseData.class, (animation, type, data) -> new YourPhaseAnimation(animation, type, (EmptyOpeningPhaseData) data), () -> new EmptyOpeningPhaseData())); } public void onDisable() { for (final OpeningPhaseType type : this.registeredPhases) { OpeningPhaseType.unregisterPhase(type); } } private void registerPhase(OpeningPhaseType phase) { // Registering first phase animations OpeningPhaseType.registerPhase(phase); // Caching to unload later on this.registeredPhases.add(phase); } ``` ## Good Practices * Use unique identifiers for each custom phase. * Keep heavy logic out of `tick()` when possible. * Always unregister phases in `onDisable()`. * Test phases on the same Minecraft version as production. ## Need Addon Setup First? If you have not created your addon bootstrap yet, start with [🔧 Custom Addons](custom-addons.md). Source: https://www.phoenixplugins.com/docs/phoenix-crates/api/custom-animations --- # 📡 Events > **Danger:** The API is only available for the premium version of the plugin. All events are standard Bukkit events, registered the usual way with `@EventHandler`. Crate events live in `com.phoenixplugins.phoenixcrates.api.crate.events`, item delivery in `com.phoenixplugins.phoenixcrates.api.events.items`. ## Event List | Event | Fires when | Cancellable | | ---------------------------- | --------------------------------------------------------------- | ----------- | | `CratePlaceEvent` | A player places a crate item in the world | Yes | | `CratePreviewOpenEvent` | The rewards preview menu is about to open | Yes | | `CratePreOpenEvent` | An opening has been requested, before any check runs | Yes | | `CrateOpenEvent` | The opening has started | No | | `CrateRewardSelectionEvent` | A random crate is choosing which reward to award | No | | `CrateSelectiveConfirmEvent` | A player confirms a reward in Selective mode | Yes | | `CratePreRerollEvent` | A reroll has been requested | Yes | | `CrateRerollEvent` | A reroll has produced a new reward | No | | `CrateRewardWinItemsEvent` | The item list for a win has been built, before it is given | No | | `CrateRewardPlayerEvent` | A player has been awarded a reward | No | | `ItemDeliveryEvent` | Items are about to be delivered to a player | No | Several of these are not cancellable but still let a listener change the outcome, which is covered per event below. ## CratePlaceEvent Fired when a player places a crate item. Exposes `getCrate()` (the `CrateType`), `getWhoPlaced()` and `getLocation()`. > **Warning:** This event fires **before** the `phoenixcrates.admin` check. A listener that only wants to veto placements in protected regions should not assume the placement would otherwise have succeeded. ## CratePreviewOpenEvent Fired before the rewards preview opens. Exposes `getCrateType()`, `getPlayer()` and `getPreviewMenu()`, the name of the menu that is about to be used. Cancel it to block the preview. ## CratePreOpenEvent Fired as soon as an opening is requested and before the plugin checks keys, permission, cooldown or cost. Cancel it to stop the opening with no key consumed. Exposes `getCrate()`, `getPlayer()` and `getType()`. This is the event to use for your own access rules. See [Examples](examples.md). ## CrateOpenEvent Fired once an opening has passed every check and has started. Not cancellable, since the key has already been taken. Use it for logging and metrics, which is exactly what the built-in logger does. ## CrateRewardSelectionEvent Fired while a crate in Random mode is picking a reward. Exposes `getCrate()`, `getPlayer()`, `getKey()` and `getCandidates()`, the rewards that are currently eligible for this player. To choose the reward yourself, call `setSelectedReward()` **and** `setHandled(true)`. Setting the reward without marking the event handled lets the normal selection run and replace your choice. ## CrateSelectiveConfirmEvent Fired when a player confirms a reward on a crate in Selective (non RNG) mode. Exposes `getCrate()`, `getPlayer()` and `getSelectedReward()`. Cancel it to refuse the selection. ## CratePreRerollEvent Fired when a player requests a reroll. Exposes `getSession()`, the active `OpeningSession`. Cancel it to refuse the reroll, or call `setHandled(true)` to tell the plugin your listener has taken over the reroll itself. ## CrateRerollEvent Fired once a reroll has run and produced a new reward, so it is the counterpart to `CratePreRerollEvent`. Exposes `getCrate()`, `getPlayer()` and `getReward()`, the reward the reroll landed on. A reroll in a normal opening replaces every reward, so the event fires once per new reward. A reroll from the Mass Opening menu targets one reward, so it fires once. Use it for logging and metrics. To actually block or take over a reroll, use `CratePreRerollEvent`. ## CrateRewardWinItemsEvent Fired after the final item list for a win has been built and before those items reach the player. Exposes `getCrate()`, `getReward()`, `getPlayer()` and a mutable `getWinItems()`, which `setWinItems()` can replace outright. This is the place to add a bonus item, apply your own NBT, or swap items per player. ## CrateRewardPlayerEvent Fired when a player is awarded a reward. Exposes `getCrate()`, `getPlayer()` and `getReward()`, which is settable. ## ItemDeliveryEvent Fired whenever the plugin hands items to a player, whether from an opening or from a command. Exposes `getPlayer()`, `getPlayerData()`, `getRemainingItems()` and `getSource()`, which is one of `KEY_GRANT`, `CRATE_GRANT` or `REWARD_GRANT`. Edit `getRemainingItems()` or call `setRemainingItems()` to change what is delivered, and `consumeAll()` to take responsibility for every item yourself, which is how the Crate Claim add-on stores items for offline players. Use `getRemainingItemsSnapshot()` if you need a copy that is safe to hold onto. Source: https://www.phoenixplugins.com/docs/phoenix-crates/api/events --- # 🧪 Examples > **Danger:** These examples target the public API module and are written to avoid depending on internal classes. ## 1) Listen and override reward selection Use `CrateRewardSelectionEvent` to choose a reward yourself. ```java import com.phoenixplugins.phoenixcrates.api.crate.events.CrateRewardSelectionEvent; import com.phoenixplugins.phoenixcrates.api.reward.BaseReward; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; import java.util.Comparator; public final class RewardSelectionListener implements Listener { @EventHandler public void onRewardSelection(CrateRewardSelectionEvent event) { BaseReward best = event.getCandidates().stream() .max(Comparator.comparingDouble(BaseReward::getWeight)) .orElse(null); if (best != null) { event.setSelectedReward(best); event.setHandled(true); } } } ``` Do not set only `selectedReward` and forget `handled`, otherwise the default flow can still replace your choice. ## 2) Validate opening attempts before they start Use `CratePreOpenEvent` when you want to block a crate opening with your own checks. ```java import com.phoenixplugins.phoenixcrates.api.crate.events.CratePreOpenEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; public final class OpenGuardListener implements Listener { @EventHandler public void onPreOpen(CratePreOpenEvent event) { if (!event.getPlayer().hasPermission("myaddon.open")) { event.setCancelled(true); event.getPlayer().sendMessage("You cannot open this crate right now."); } } } ``` ## 3) Query crates from the manager Access the manager through `PhoenixCratesAPI`. ```java import com.phoenixplugins.phoenixcrates.api.PhoenixCratesAPI; import com.phoenixplugins.phoenixcrates.api.crate.CrateType; import java.util.List; public final class CratesDebugService { public List getEnabledTypes() { return PhoenixCratesAPI.getCratesManager().getCrateTypes(); } public int getRegisteredCount() { return PhoenixCratesAPI.getCratesManager().countRegisteredTypes(); } } ``` ## 4) Inject a custom player data layer The player data layer supports chain-of-responsibility style custom caching. ```java import com.phoenixplugins.phoenixcrates.api.PhoenixCratesAPI; import com.phoenixplugins.phoenixcrates.api.player.PlayerDataLayer; import com.phoenixplugins.phoenixcrates.api.player.PlayerDbModel; import java.util.UUID; import java.util.concurrent.CompletableFuture; public final class MyDataLayer implements PlayerDataLayer { private PlayerDataLayer next; @Override public CompletableFuture fetchByUniqueId(UUID uniqueId) { return next == null ? CompletableFuture.completedFuture(null) : next.fetchByUniqueId(uniqueId); } @Override public CompletableFuture insert(T model) { return next.insert(model); } @Override public CompletableFuture update(T model) { return next.update(model); } @Override public void setNextLayer(PlayerDataLayer nextLayer) { this.next = nextLayer; } @Override public PlayerDataLayer getNextLayer() { return this.next; } } // During addon load: // PhoenixCratesAPI.getPlayersManager().setPlayerDataLayer(new MyDataLayer()); ``` Do not block the main thread waiting for `CompletableFuture` results. ## 5) Read player crate data safely Use the async fetch API for offline/online players. ```java import com.phoenixplugins.phoenixcrates.api.PhoenixCratesAPI; import org.bukkit.OfflinePlayer; public final class PlayerDataService { public void loadData(OfflinePlayer player) { PhoenixCratesAPI.getPlayersManager() .fetchPlayerDataAsync(player) .thenAccept(data -> { if (data != null) { // Read fields/modules from your callback. } }); } } ``` ## 6) Track openings and rerolls for analytics Listen to open and reroll events for metrics or logs. ```java import com.phoenixplugins.phoenixcrates.api.crate.events.CrateOpenEvent; import com.phoenixplugins.phoenixcrates.api.crate.events.CrateRerollEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; public final class AnalyticsListener implements Listener { @EventHandler public void onOpen(CrateOpenEvent event) { // Store event.getPlayer().getUniqueId() + event.getType().getIdentifier() } @EventHandler public void onReroll(CrateRerollEvent event) { // Store event.getPlayer().getUniqueId() + event.getReward().getIdentifier() } } ``` > **Info:** A reroll in a normal opening replaces every reward, so `CrateRerollEvent` fires once per new reward. To block or take over a reroll instead of recording it, use `CratePreRerollEvent`. Every event is listed on the [Events](events.md) page. ## 7) Customize final item delivery Use `ItemDeliveryEvent` to edit or consume the list of items before they are delivered. ```java import com.phoenixplugins.phoenixcrates.api.events.items.ItemDeliveryEvent; import org.bukkit.event.EventHandler; import org.bukkit.event.Listener; import org.bukkit.inventory.ItemStack; import java.util.ArrayList; import java.util.List; public final class ItemDeliveryListener implements Listener { @EventHandler public void onDelivery(ItemDeliveryEvent event) { List filtered = new ArrayList<>(event.getRemainingItemsSnapshot()); filtered.removeIf(item -> item.getAmount() <= 0); event.setRemainingItems(filtered); } } ``` ## 8) Inspect and manage animation phases Use the animation registry to discover or register phases. ```java import com.phoenixplugins.phoenixcrates.api.PhoenixCratesAPI; import com.phoenixplugins.phoenixcrates.api.crate.animation.AnimationPhase; import com.phoenixplugins.phoenixcrates.api.crate.animation.PhaseType; import java.util.Collection; import java.util.Optional; public final class AnimationRegistryService { public Collection getOpeningPhases() { return PhoenixCratesAPI.getAnimationsRegistry().getPhases(PhaseType.OPENING); } public Optional findById(String id) { return PhoenixCratesAPI.getAnimationsRegistry().getPhaseById(PhaseType.OPENING, id); } } ``` ## What is not supported by API-only integrations * Do not depend on internal classes from plugin modules outside `com.phoenixplugins.phoenixcrates.api.*`. * Do not call methods marked internal/unsafe unless you are maintaining plugin internals. * Do not assume constructor availability for concrete runtime implementations. * Do not override the full opening flow by reflection; use events and managers instead. Source: https://www.phoenixplugins.com/docs/phoenix-crates/api/examples --- # 📂 Crate Configuration File ## Example Crate Each crate has its file inside the crates folder. Check the default structure of a crate: ```yml enabled: true identifier: example1 item: material: custom:example_crate amount: 1 display-name: '&eExample #1' block-material: BROWN_WOOL engine: VANILLA_BLOCK open-cost: engine: NONE amount: 0.0 currency: '' key-skips-cost: false open-cooldown: 0 simultaneous-openings: true preview-item: false permission: required: false permission: phoenixcrates.crate.example1 idle-effects: - CIRCLE;{REDSTONE;#ff0000;0.0;1.0;2.0;0.0;0.0;1} opening-animation: pre-open: DEFAULT open: SPOTLIGHT_GUI display: NONE hologram: type: BUILTIN offset: 0.0 lines: - '&e&l%name%' - '' - '&aRight &7Click to open' - '&cLeft &7Click to preview' menus: rewards: default_rewards_preview select-reward: default_select_reward rerolls: default_crate_reroll preview-actions: [] key-required: true linked-keys-ids: - example1 allow-open-command: true broadcast: message: '&ePlayer &a%player% &ejust got &6"%reward%" &ereward from the crate &6%crate%&e!' max-win-rewards: 0 rewards-mode: RANDOM rewards: '0': enabled: true identifier: reward_1783907600221 display-item: material: custom:example_crate amount: 4 win-items: '0': material: custom:grass_block amount: 1 win-commands: [] broadcast: false weight: 100.0 win-limits: -1 global-win-limit: -1 cooldowns: win-limit-cooldown: 0 global-win-limit-cooldown: 0 time-limited-cooldown: 0 time-limited-expiry: 0 guaranteed-win: -1 required-keys: 1 allow-win-message: false notification-type: CHAT share-players-online: false restricted-permissions: [] required-permissions: [] max-win: item-amount: 1 command-amount: -1 alternative-reward: enabled: false reward: item: material: DIAMOND_PICKAXE display-name: '&aAlternative Item' amount: 1 virtual: false broadcast: false allow-win-message: true share-players-online: false commands: [] guaranteed-reward-type: DISABLED reroll: enabled: false free-rolls: 0 groups: '0': namespace: common rerolls: 3 replay-animation: false skip-same-reward: false extra-settings: animation: display-item-position: x: 0.0 y: 2.0 z: 0.0 display-item-name-position: x: 0.0 y: 0.3 z: 0.0 skip-on-esc: false clicks: open: RIGHT preview: LEFT event-actions: open: [] win: [] close: [] denied: [] ``` ## Clicks `clicks` takes `LEFT`, `RIGHT`, `BOTH` or `NONE`, as set from [Click Behaviour](../main-features/crates/README.md#click-behaviour). ## Event Actions `event-actions` overrides the global lists from `config.yml` for this crate, event by event. A reward can also carry a `win-actions` list of its own, which takes over from both. See [Event Actions](../main-features/crates/README.md#event-actions). ## Idle Effects The `idle-effects` lines pack a whole particle effect into one string, in the form `TYPE;{PARTICLE;COLOR;offsetX;offsetY;offsetZ;spread;velocity;amount}`. Each field is explained on the [Idle Animations](../main-features/animations/README.md#in-the-config-file) page. ## Item Storage Every crate file starts with an `internal-storage` section holding the raw items the crate uses, each under a name that the rest of the file points at with `custom:`. It is written by the plugin, so a crate item, a reward item or a display item edited from the editor ends up there instead of being repeated inline. Editing an item by hand means editing its entry in that section. Removing an entry that something still points at leaves that part of the crate without an item. ## Add-on Sections Installed add-ons append their own section to every crate file, and Mass Opening also adds its two menu names into the existing `menus` section. A file only grows once the add-on has run for the first time, and deleting a section makes it come back with its defaults. ```yml mass-opening: enabled: false presets: first: enabled: true amount: 6 open-all: enabled: true max-amount: 100 lootbox: enabled: false menus: mass-reroll: default_crate_mass_reroll mass-selective: default_crate_mass_selective ``` ## File Structure Everything the plugin writes lives in plugins/PhoenixCrates. ``` plugins/PhoenixCrates/ ├── addons/ ├── crates/ ├── keys/ ├── menus/ ├── translations/ ├── internal/ ├── logs/ ├── config.yml ├── locations.yml ├── internal_storage.yml ├── messages.yml └── rarities.yml ``` ### Folders | Folder | Contents | | ---------------- | ------------------------------------------------------------------------------------------------- | | **crates** | One file per crate. See [Example Crate](#example-crate). | | **keys** | One file per key. | | **menus** | The menu layouts. See [Customize Menus](customize-menus.md). | | **addons** | Add-on jars. Drop a new add-on here and restart. | | **translations** | The language files. See [Languages & Translations](languages.md). | | **internal** | Plugin-managed working data. Never edit this by hand. | | **logs** | Written by the logger. See [Log the Actions](../features/log-the-actions.md). | ### Files | File | Contents | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | **config.yml** | The main settings, the database connection and the license. See [Main Configuration](main-configuration.md). | | **locations.yml** | Every crate placed in the world, with its coordinates and facing. See the note below. | | **internal_storage.yml** | Items saved from the editor that are not tied to a single crate. | | **messages.yml** | Legacy message file, kept for configurations made before translations were introduced. | | **rarities.yml** | The rarities, when the Rarity add-on is installed. | Installed add-ons add one file each: `crate-claim.yml`, `mass-opening.yml`, `ip-limit.yml`, `reward-on-loop.yml`, `redis.yml`, and `logger.yml` for the logger. > **Warning:** locations.yml is what makes a placed crate exist. Deleting it leaves every crate configured but no longer placed anywhere in the world. ### What Lives in the Database Player progress is **not** in these files. Virtual keys, open cooldowns, opened counts, win limits and rerolls are all stored in the database configured in `config.yml`, which is SQLite (a file inside the plugin folder) by default and MySQL if you set it up. ### Moving to Another Server To carry your setup across: * **Configuration** - copy `crates/`, `keys/`, `menus/`, `translations/`, `config.yml`, `internal_storage.yml`, `rarities.yml` and the add-on files. * **Placed crates** - copy `locations.yml`, but only if the worlds come across too. A location pointing at a world that does not exist is skipped. * **Player progress** - point the new server at the same MySQL database, or copy the SQLite file across. > **Danger:** If you copy `config.yml` to a second server, remember that a license only allows a limited number of concurrent sessions. See [Licensing](../plugin-information/licensing.md). ### What to Back Up The whole plugins/PhoenixCrates folder, plus your database if you use MySQL. The editor writes changes to these files as you make them, so a backup taken while the server runs is a valid one. ### Reporting a Problem Turning on `debug` in `config.yml` adds verbose console logging and creates a debug\_output folder with extra diagnostics. Both are useful to attach when you report an issue to us. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/crate-configuration-file --- # 🎑 Customize Menus ## Crate Menus All the crate menus you can customize for the plugin are located in the menus folder of Phoenix Crates. These menus are: * The rewards preview menu - REWARDS\_PREVIEW * The select reward menu - SELECT\_REWARD * The confirmation menu - CONFIRMATION * The reroll menu - CRATE\_REROLL * The virtual keys menu - VIRTUAL\_KEYS Add-ons register menus of their own, which only exist once the add-on is installed: * The mass opening menu - CRATE\_MASS\_OPENING * The mass reroll menu - CRATE\_MASS\_REROLL * The mass selection menu - CRATE\_MASS\_SELECTIVE * The claim menu - CRATE\_CLAIM

Menus Folder

If you want to have a different preview menu for a crate, you can simply create your own custom menu and attach it to the crate's [Preview Menu](../main-features/crates/README.md#menus) instead of changing the default one. The layout of every menu can also be changed in-game with the [In-Game Menu Editor](in-game-menu-editor.md) ⭐. ## Menu Settings Menu settings can be found in any type of menu. From there, you can specify the type of menu you want, the title of the menu, the number of rows it will have, the refresh rate, and the actions that will run when the user clicks to preview it. ```yaml settings: type: # REWARDS_PREVIEW, SELECT_REWARD, CONFIRMATION, CRATE_REROLL, VIRTUAL_KEYS title: '%crate% Rewards' rows: # 1, 2, 3, 4, 5, 6 refresh: enabled: false rate: 20 on-open-actions: [] ``` You can change the rows number if you want to adjust the rows that the menu will have. ## Confirmation Menu The confirmation menu is shown to players before an action is carried out, such as opening a crate with an Open Money Cost or picking a reward in Selective mode. It has its own `confirm` and `cancel` items alongside the usual `item-slot`, which shows the item the player is about to receive/select. This menu can be skipped entirely with the Disable Confirmation Menus option, found in the editor's Settings menu. ## Pagination Pagination is another main option that menus have. With this, you can create multiple pages, set your preview page item, the next page item, and a material that will fill specific slots. ## Items With the items, you can create custom entries to be included in your menu. These could be items to close the menu or items that display where players can purchase keys. ```yaml items: close-menu: slot: '49' material: ARROW amount: 1 custom-model-data: 0 glow: false hide-attributes: false display-name: '&aClose Menu' lore: - '&7Click here to close this menu.' - '' - '&6Left-Click: &eClose menu.' actions: - '[CLOSE_INVENTORY]' ``` Two more options are available on any item and are not in the example above: * **item-model** - The item model identifier to use, on server versions that support it. * **hide-tooltip** - Hides the item's tooltip completely. This is what the filler panes in the default menus use. The `slot` accepts a single slot (`'49'`), a range (`'45-53'`), or a comma separated mix of both (`'0, 8, 45-53'`), so one entry can fill several slots at once. ## Item Material Every item in a menu takes a `material`, the pagination arrows, the decorative fillers and the available keys item included. Alongside vanilla materials it accepts the same [hooked values](reward-config-editing.md#hooked-materials) as a reward, so any of them can be a custom item from ItemsAdder, Nexo, CraftEngine, MMOItems, ExecutableItems, Mythic Items or HeadDatabase. ```yaml pagination: next-item: slot: '26' material: itemsadder:medieval_crates:next_arrow custom-model-data: 0 item-model: '' display-name: '&6Next page - Page %page%' ``` > **Danger:** The parts of a hooked material are separated by colons, never dashes, and an ItemsAdder value keeps its namespace, so it has three parts. `itemsadder-medieval_crates-next_arrow` and `itemsadder:next_arrow` both fail. Keep `custom-model-data` at 0 and `item-model` empty on a hooked material. Both are applied on top of whatever the hook returns and would override the model the custom item already carries. A 0 and an empty value are skipped, leaving the hook's own model alone. An item rendering as a barrier means the material was accepted as a hooked value but nothing came back, either because the id is wrong or because the hooking plugin had not finished loading its items when the menu was built. A material rejected outright is logged as an unknown material on startup instead. ## Reward The rewards are the items you offer in your crate. You can adjust their names, lore, and configure them as you wish. The selective reward option also includes a setting for a locked item, in case the reward has already been claimed. The reward slots will be based on the slots: that were set in the pagination ```yaml reward: name: '&7%reward_name%' lore: - '%reward_lore%' - '' - '&eYour percentage: &6%percentage%%' - '&eYour chance: &6%chance%%' - '' - '&7Check our &6&lWIKI &7to understand the difference' - '&7between percentage and chance.' - '' - '&7(This lore is configured at the menus folder)' ``` ## Review & Reroll These two items are found in the reroll menu. The review option allows you to claim the reward you won, while the reroll option lets you get another reward instead. ## Virtual Keys Menu The menu behind `/crates virtualKeys` lives in menus/virtual\_keys.yml and is customized like any other, with its own settings, pagination and items. On top of those it has a `key-item` block, which is the entry rendered for each of the player's keys. ```yaml key-item: display-name: '&e%key_name%' lore: - '%item_lore%' - '' - '&fAmount: &e%amount%' ``` | Placeholder | Description | | ------------ | -------------------------------------------- | | %key\_name% | The key's display name. | | %amount% | How many of that key the player has. | | %item\_lore% | The lore of the key item itself. | The item's material comes from the key, so it always looks like the real key. > **Info:** The menu only lists keys that are set to Virtual, are enabled, and that the player currently owns at least one of. A physical key never shows up here, and a key the player has none of is left out rather than shown as zero. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/customize-menus --- # 🗂️ File Structure ## Overview Everything the plugin writes lives in plugins/PhoenixCrates. ``` plugins/PhoenixCrates/ ├── addons/ ├── crates/ ├── keys/ ├── menus/ ├── translations/ ├── internal/ ├── logs/ ├── config.yml ├── locations.yml ├── internal_storage.yml ├── messages.yml └── rarities.yml ``` ## Folders | Folder | Contents | | ---------------- | ------------------------------------------------------------------------------------------------- | | **crates** | One file per crate. See [Crate Configuration File](crate-configuration-file.md). | | **keys** | One file per key. | | **menus** | The menu layouts. See [Customize Menus](customize-menus.md). | | **addons** | Add-on jars. Drop a new add-on here and restart. | | **translations** | The language files. See [Languages & Translations](languages.md). | | **internal** | Plugin-managed working data. Never edit this by hand. | | **logs** | Written by the logger. See [Log the Actions](../features/log-the-actions.md). | ## Files | File | Contents | | ------------------------ | ---------------------------------------------------------------------------------------------------------- | | **config.yml** | The main settings, the database connection and the license. See [Main Configuration](main-configuration.md). | | **locations.yml** | Every crate placed in the world, with its coordinates and facing. See the note below. | | **internal_storage.yml** | Items saved from the editor that are not tied to a single crate. | | **messages.yml** | Legacy message file, kept for configurations made before translations were introduced. | | **rarities.yml** | The rarities, when the Rarity add-on is installed. | Installed add-ons add one file each: `crate-claim.yml`, `mass-opening.yml`, `ip-limit.yml`, `reward-on-loop.yml`, `redis.yml`, and `logger.yml` for the logger. > **Warning:** locations.yml is what makes a placed crate exist. Deleting it leaves every crate configured but no longer placed anywhere in the world. ## What Lives in the Database Player progress is **not** in these files. Virtual keys, open cooldowns, opened counts, win limits and rerolls are all stored in the database configured in `config.yml`, which is SQLite (a file inside the plugin folder) by default and MySQL if you set it up. ## Moving to Another Server To carry your setup across: * **Configuration** - copy `crates/`, `keys/`, `menus/`, `translations/`, `config.yml`, `internal_storage.yml`, `rarities.yml` and the add-on files. * **Placed crates** - copy `locations.yml`, but only if the worlds come across too. A location pointing at a world that does not exist is skipped. * **Player progress** - point the new server at the same MySQL database, or copy the SQLite file across. > **Danger:** If you copy `config.yml` to a second server, remember that a license only allows a limited number of concurrent sessions. See [Licensing](../plugin-information/licensing.md). ## What to Back Up The whole plugins/PhoenixCrates folder, plus your database if you use MySQL. The editor writes changes to these files as you make them, so a backup taken while the server runs is a valid one. ## Reporting a Problem Turning on `debug` in `config.yml` adds verbose console logging and creates a debug\_output folder with extra diagnostics. Both are useful to attach when you report an issue to us. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/file-structure --- # 🛠️ GeyserMC (Bedrock) ## Overview For Bedrock to work, the most common practice is to have a Java version with Geyser that allows Bedrock clients. **Please note:** This guide will not cover the installation process of Geyser itself. Refer to the Geyser wiki for comprehensive installation instructions: [Geyser Wiki Setup](https://wiki.geysermc.org/geyser/setup/) ## Bedrock Forms > **Info:** These options are in the bedrock section of config.yml. They have no editor option. Bedrock players can use the player menus as native Bedrock forms instead of chest menus. Forms need Floodgate or Geyser to be installed on the same server as the plugin. Without either, everyone gets the chest menus. ```yaml bedrock: forms: true input-modes: [] allow-opt-out: true resize-chest-menus: true icons: enabled: true fallback-url: "" head-url: "https://mc-heads.net/head/%texture%" ``` | Menu | Bedrock form | | --- | --- | | Rewards preview | A button per reward with its chance, or the keys it needs in selective crates. Tapping a reward shows its full description. Reward groups open their own list. | | Reward selection | A button per reward with the keys it needs. Tapping an unlocked reward redeems it, a locked one shows why it is locked. | | Confirmation | A confirm and a cancel button. | | Reroll | A claim and a reroll button, or only claim when no rerolls are left. Closing the form claims the reward. | | Virtual keys | A button per key with the amount owned. | The preview and selection forms list the keys the player owns for that crate at the top. Buttons use the menu titles and the reward, key and button names of the menu files, with colors kept and hex colors removed, since forms cannot show them. The rest of the form text comes from the bedrock section of the translations file. Opening animations are not forms and look the same as on Java. The [Key Shop](../add-ons/key-shop/README.md), [Crate Claim](../add-ons/crate-claim/README.md), [Milestones](../add-ons/milestones/README.md) and [Mass Opening](../add-ons/mass-opening/README.md) add-ons have forms for their player menus too, described on their pages. Every other menu, the editor included, stays a chest menu. A button with several click actions asks Bedrock players which one to run, since Bedrock cannot Shift or right-click, and text input opens as a form. If a form cannot be sent, the player gets the chest menu instead and the console says so. ### Forms Turns Bedrock forms on or off for the whole server. When off, Bedrock players get the chest menus like everyone else. ### Input Modes Limits forms to Bedrock players on certain devices, by their input mode: `TOUCH`, `CONTROLLER`, `KEYBOARD_MOUSE` or `VR`. Players on any other input get chest menus. Leave the list empty to give forms to every Bedrock player. ### Allow Opt Out Lets Bedrock players choose chest menus for themselves. The preview, selection and virtual keys forms get a button to switch to chest menus, and `/crates forms` switches between the two. The choice is remembered per player. When this is off, every Bedrock player gets forms and the command is refused. ### Resize Chest Menus Bedrock only draws chest menus of 3 or 6 rows cleanly. With this on, a player menu of 1 or 2 rows is opened with 3 rows and a menu of 4 or 5 rows with 6, for Bedrock players who get chest menus. Java players always see the rows the menu is set to. ### Icons Adds an icon to form buttons. * **enabled** - Turns icons on or off. * **fallback-url** - An image URL for materials the built-in icon table does not know. `%material%` is replaced by the material name in lower case. Leave it empty for no icon. * **head-url** - An image URL for player heads. `%texture%` is replaced by the head's texture id, or the owner's name when it has no texture. Leave it empty for no head icons. Vanilla items use the Bedrock texture of the same item. Items with custom model data or an item model get no icon, since their texture only exists in a resource pack. ## Step by Step Guide ### Step 1: Install Geyser Optional Pack The GeyserOptionalPack is a resource pack specifically designed for Bedrock Edition clients playing on Geyser servers. It adds features and bug fixes to bring the Bedrock experience closer to Java Edition, including improvements in model rendering. A resource pack allows for additional features and bug fixes to be implemented within the limitations of Bedrock Edition. You can download the GeyserOptionalPack from the official GitHub repository: [GeyserOptionalPack GitHub](https://github.com/GeyserMC/GeyserOptionalPack). ### Step 2: Convert Your Java Resource Pack to Bedrock While some complex Java textures require manual conversion, this guide will focus on converting simpler models. There are two main approaches depending on your source for the Java models: #### 2.1 Using Kastle Java to Bedrock Converter: We will be using Kas-tle's java2bedrock conversion tool available at this link: Kas-tle java2bedrock conversion. **Here's how to convert your Java resource pack to Bedrock using java2bedrock.sh:** **2.1.1 Convert the Java Model Engine Resource Pack (Optional):** * Extract the `resource_pack.zip` file from `plugins/ModelEngine/resource_pack.zip`. * Merge the extracted files with your other java resource packs (if needed) and proceed to the next step. **2.1.2 Uploading Your Java Resource Pack:** Unfortunately, in most cases, you won't have a direct URL for your Java resource pack. Here's a workaround using Dropbox: 1. Upload your Java resource pack to Dropbox. 2. Get a direct download link for the file. To do this, access the file in Dropbox and click the "..." menu. Then, select "Share" and copy the link. 3. **Important:** Append "\&dl=1" to the end of the copied URL. This enables direct downloading. **2.1.3 Generate Bedrock Resource Pack:** * Visit the java2bedrock.sh conversion link ([Kas-tle java2bedrock conversion](https://github.com/Kas-tle/java2bedrock.sh/issues/new?assignees=\&labels=conversion\&template=pack-conversion.yml\&title=%5BPack%5D%3A+)). * Paste your modified Dropbox download URL (with "\&dl=1") into the "Java Pack Direct Download URL" option. * Follow the converter's instructions to complete the conversion process. * Click on "Submit new issue" to initiate the conversion. * Wait for the conversion to be over **2.1.4 Using the Converted Resource Pack:** * Once the conversion is complete, download the generated Bedrock resource pack. * Place the converted Bedrock resource pack in the `Geyser > packs` folder on your server. * Place the file `geyser_mappings.json` file in the `Geyser > custom_mappings` folder on your server. ## Bedrock Skull Textures Bedrock cannot load player head textures on its own, so opening animations that use heads need every head registered in Geyser's `skin-hashes` option, following the [Geyser custom skulls guide](https://geysermc.org/wiki/geyser/custom-skulls/). Add the part of each link after `http://textures.minecraft.net/texture/`.
Christmas Crate Animations add-on | Animation | Heads | | --- | --- | | Santa Claus | [Santa](http://textures.minecraft.net/texture/14e424b1676feec3a3f8ebade9e7d6a6f71f7756a869f36f7df0fc182d436e), [Kid](http://textures.minecraft.net/texture/5c8d3e33cb1ca1aacf9dad322f4f7519cd7dfa509c33b7dd87b5398ee0ac17a8) | | Elf | [Present](http://textures.minecraft.net/texture/45368f5635ff6c3407f0f356c5b6e0947bcd5e38490c9aa8b8b582a4f21ae3cb), [TV](http://textures.minecraft.net/texture/7bbe8fd1aa39f15076e884dfe6ddb9a3f3761db31e2b1f9940b5dfd34d1c4d), [Elf](http://textures.minecraft.net/texture/4ec5455f43426ca1874b5c7b4a492ec3722a502f8b9599e758e133fed8b3c1e4) | | Christmas Tree | [Ornament](http://textures.minecraft.net/texture/2db24dc262631663ba1e3e3398645013dc5cd2331ec9b9f3eb26855a0b104baa) | | Presents, every animation | [White](http://textures.minecraft.net/texture/e47b37e67a89159bf4acc4a44d4328f4efc0181605142288e5eed1ab8aed913c), [Green](http://textures.minecraft.net/texture/28dc3c84491c4ff103de6ea01880e2d83432cd4878b84d6b43253cc51fd978e7), [Blue](http://textures.minecraft.net/texture/5b85e29f29ec9a90e482ea5b8391bcb4560bbae0dcd15d7ce1d86016b4356e98), [Purple](http://textures.minecraft.net/texture/e9e39d91c04c30cc1f530fee798eed279dde60f95c2e1d155c0fdd361d0962ed), [Yellow](http://textures.minecraft.net/texture/abd98792dd92d9719894341ac9012a584c4428558fd2c712f78e5f0d4da85470), [Red](http://textures.minecraft.net/texture/45368f5635ff6c3407f0f356c5b6e0947bcd5e38490c9aa8b8b582a4f21ae3cb) | | Ornaments, every animation | [Red](http://textures.minecraft.net/texture/c6f518cdcc30da6e21833f3d90366c3703c27a0170b928fb15b5e51816f4e15e), [Orange](http://textures.minecraft.net/texture/ad53ec557eca3c5a08be794164b2e9b6a7fb703a33388f0a9c02c3b16c2945e4), [Yellow](http://textures.minecraft.net/texture/c0dac2501c9e756767f6943323ad5955b5a975bb09be12364ef80ea3f1ca7b06), [Lime](http://textures.minecraft.net/texture/9b68ca27a304d21e2e8a99a748093f95ae5b148c59d7af0b5670f1d15202502e), [Green](http://textures.minecraft.net/texture/41e7340dd4c009c43c398bc40d9aed147014057a7f43722c6cdc9b45837015f5), [Dark Green](http://textures.minecraft.net/texture/b605c66347f327c5eed27672d7a0e347f4e36c006353c91b78935ba28116504), [Dark Aqua](http://textures.minecraft.net/texture/623323728e9df5c38053176465da1f4c855cd6a3a5f3928a223150e680441a8f), [Dark Blue](http://textures.minecraft.net/texture/86f901bbde8cd67520fa0c7ae461ee7ca66ce3c4c481cd5c12fb43712eea6b63), [Aqua](http://textures.minecraft.net/texture/29273cb3c79ecd53c13b4d71e9afd919d1dcba1410c2538b8fe099ecd61a6cb4), [Very Dark Blue](http://textures.minecraft.net/texture/17f85d2edc530c4f33a35c7cccefea9528812137ae13e040e1169032b4f39c53), [Purple](http://textures.minecraft.net/texture/431d901ceeb38d0f9c63ae66cd5a46e33a09c0349d383f5a5c7c3726e0e0e371), [Magenta](http://textures.minecraft.net/texture/94b3aed343afb22d536ca60cf95e56cf334c68bc41b1369ec9b06f4dd050e6cb), [Pink](http://textures.minecraft.net/texture/87f5c30a117ee8ae80c7858ac42c67b2bbe5e600a60ceeaa2817f862dd89333d) |
Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/geysermc-bedrock --- # 🖼️ In-Game Menu Editor > **Info:** Available in the Premium+ plan of Phoenix Crates. The editor changes the same menu files described in [Customize Menus](customize-menus.md). A menu saved in-game is live straight away, with no reload. ## Opening the Editor There are two ways in, both needing phoenixcrates.command.editor:

Editor (Menu Layouts)

Menu Layouts (Default Rewards Preview)

* **Editor > Menu Layouts** lists every menu file by its name. Left-click one to edit it. * /crates editLayout \ opens one menu directly, by its file name without `.yml`, such as `default_rewards_preview`. Your own menu files, such as a second preview menu for one crate, are listed too. Add-on menus are listed once their add-on is installed. The menu opens as it looks to players, with every button in place. The slots where the menu shows its own content, such as the rewards or the keys, appear as lime panes. > **Warning:** While you edit, your hotbar holds the editor tools. Your own hotbar items are saved to a backup file first, and the editor does not open if that backup fails. They come back when you close the menu. ## Editing a Button With no tool turned on, click any button to open its editor. Every field there changes that one button: | Field | Description | | --- | --- | | Look | Drop an item here to copy its material, custom model data, item model and head texture. | | Display Name | The name of the button. | | Lore | The lore of the button. | | Amount | How many are shown, 1 to 64. | | Glow | Makes the button glow. | | Hide Attributes | Hides attack damage and similar lines. | | Custom Model Data | The custom model data of the button. | | Click Actions | The [actions](../plugin-information/action-types.md) run when the button is clicked. | | Hide Tooltip | Hides the tooltip entirely. | | Tooltip Style | The tooltip style, such as `minecraft:blue`. | | Delete | Removes the button. | A field only appears when the button has that option, and Delete only appears on decoration. The plugin's own buttons, such as the page arrows, can be moved and restyled but not deleted. ## Drag and Drop Pick up any item from your inventory and drop it: * **On a button** to give the button that item's look. The name, lore and actions stay. * **On an empty slot** to add the item as new decoration, with its look, name and lore. This is the quickest way to put a custom item from a resource pack or a textured head into a menu. ## Hotbar Tools Right-click a tool while holding it, or click it in your inventory. The first three are modes: one is on at a time, it glows while on, and using it again turns it off. | Slot | Tool | Description | | --- | --- | --- | | 1 | Reordering | Click a button, then click where it should go. If that slot is taken, the two buttons swap places. | | 2 | Item Slots | Click an empty slot to add it to the menu's item slots, or click a lime slot to remove it. Also repeats decoration: click it to select it, then click empty slots to put it there too. | | 3 | New Button | Click an empty slot to place a new button there. Its editor opens straight away. | | 4 | Add a Row | Makes the menu one row taller, up to 6. | | 5 | Remove a Row | Makes the menu one row shorter, down to 1. | | 8 | Menu Title | Type the new title, in a dialog where the server supports one, otherwise in chat. | | 9 | Templates & Text | Opens the parts of the menu that have no slot of their own. | A slot group always keeps at least one slot, and a button locked to a single slot cannot be repeated. Removing a row does not delete what was on it. Anything left below the last row is hidden, you are told how many slots, and adding the row back shows it again. ## Templates & Text Templates are buttons the menu draws by itself, once per entry, rather than placing them on a slot. Editing one restyles every copy of it. Text entries are the lines the menu adds by itself rather than a button you place. ## Saving Close the menu to save. The file is written, the menu is live for players at once, and your hotbar is given back. If you opened it from the Menu Layouts list, the list opens again. The menu is also saved when you leave the server, when you die, and when the server stops. Dying ends the session, and your own hotbar items drop with the rest of your inventory. If the server crashes mid-edit, your hotbar is given back the next time you join. While editing, the tools cannot be dropped, placed or moved, and you cannot swap hands. > **Info:** Two admins can open the same menu at the same time. The second is warned, and whoever closes last overwrites the other's changes. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/in-game-menu-editor --- # 🌍 Languages & Translations ## Translations Every line the plugin can print lives in one file: ``` PhoenixCrates/translations/translations.en.yml ``` Messages to players, command replies, the holograms, the menus and the whole in-game editor are all in there. Edit it, run /crates reload, and the new text is live. To stop a message from appearing at all, set it to `''` (empty quotes). Every add-on brings its own file into the same folder, named after itself, so the Rarity messages are in `rarity.translations.en.yml` and the Lootbox ones in `lootbox.translations.en.yml`. They work exactly like the main file. > **Info:** Older versions kept this in **messages.yml**. On the first start after upgrading, the plugin copies your text across into the translation file on its own and renames the old one to **old_messages.yml**. Editor text is not carried over, since the old file never had it. ## Language The language the plugin loads is set in config.yml, or from **Editor > Settings > Language**. ```yaml language: UNDEFINED ```

Editor > Settings

UNDEFINED is the value a fresh install starts on, and it behaves as English. It is also the one value the editor will not let you pick again once you have chosen a real language. The picker lists every language the plugin knows about:
CodeLanguageFile
EN_USEnglish (United States)translations.en.yml
AR_SAArabic (Saudi Arabia)translations.ar.yml
PT_BRPortuguese (Brazil)translations.br.yml
PT_PTPortuguese (Portugal)translations.pt.yml
ES_ESSpanish (Spain)translations.es.yml
FR_FRFrench (France)translations.fr.yml
DE_DEGerman (Germany)translations.de.yml
IT_ITItalian (Italy)translations.it.yml
NL_NLDutch (Netherlands)translations.nl.yml
SV_SESwedish (Sweden)translations.sv.yml
PL_PLPolish (Poland)translations.pl.yml
CS_CZCzech (Czechia)translations.cs.yml
RU_RURussian (Russia)translations.ru.yml
TR_TRTurkish (Turkey)translations.tr.yml
EL_GRGreek (Greece)translations.el.yml
HI_INHindi (India)translations.hi.yml
ID_IDIndonesian (Indonesia)translations.id.yml
VI_VNVietnamese (Vietnam)translations.vi.yml
JA_JPJapanese (Japan)translations.ja.yml
KO_KRKorean (South Korea)translations.ko.yml
ZH_CNChinese (Simplified)translations.zh.yml
The file name uses the short form rather than the code, which is worth knowing before you go looking for it — PT_BR writes `translations.br.yml`, not `translations.pt_br.yml`. > **Warning:** Only the languages included in the build you are running can be picked. The rest are dark grey in the editor and clicking skips straight past them. At the moment the plugin ships with English, so the way to run it in another language is to translate the file yourself. ## Setting it from a command /crates setLanguage \ switches language without a full reload. It only accepts a language the build actually ships, and answers `No translation is bundled for language ...` for anything else. While `language` is still UNDEFINED, anyone joining with phoenixcrates.admin is offered a suggestion in chat, picked from where the server appears to be, with the command ready to click. Setting a language yourself stops it. ## Translating the plugin Everything sits under the short language code at the top of the file, and the value is either a line or a list of lines. Translate the right-hand side and leave the keys and the placeholders alone. ```yaml en: unknown-argument: "&cUnknown Argument!" no-permission: "&cYou are not allowed to do this! (Need %permission%)" ``` ```yaml en: error-processing: - "&cAn error occurred while processing this action (Check console):" - "&7%message%" ``` Anything wrapped in `%` is filled in by the plugin, so `%player%`, `%permission%` and `%message%` have to survive the translation to keep working. Colour codes can be moved around freely. > **Info:** English is always loaded first, and the chosen language is laid over the top of it. A key you have not translated yet falls back to its English line rather than printing blank, so a file can be translated a piece at a time. > **Info:** Keep a copy of your translated file before updating the plugin. New keys are added to it automatically — the console prints `Missing value for key "..."` and writes the English default straight into your file — but it is the file your work lives in. ## The editor is translated too Everything under the `editor` keys is the text of the in-game editor — the name and description of every option. Translating those is optional, and skipping them leaves the editor in English while your players see your language. ## Rich Text (MiniMessage) Phoenix Crates understands [MiniMessage](https://docs.advntr.dev/minimessage/format.html) tags, like ``, `` or ``, on top of the classic `&` colour codes. This lets you use gradients, hover text and clickable links, none of which `&` codes can do. ### Format | Example | Result | | -------------------------------------------------------- | -------------------------------------- | | `Hello` | Red text | | `<#ff8800>Hello` | Any hex colour | | `Phoenix Crates` | Text fading from one colour to another | | `Warning` | Bold and underlined | | `Legendary!` | Each letter a different colour | | `Hover` | Text with a tooltip | | `Our site` | Text that opens a link | A closing tag is optional. `Hello` colours the rest of the line, while `Hello there` colours only the first word. ### Where it works | Place | Notes | | ----------------------------- | ------------------------------------------------- | | Chat messages | Everything in the language file that reaches chat | | Crate holograms | The floating text above a crate | | Reward names and lore | Including the rarity group display item | | Menu titles, item names, lore | Anywhere the editor lets you write text | ### Where it doesn't work Titles, subtitles, the action bar and boss bars only understand `&` codes. Those are sent as raw legacy text, so a tag in one of them is shown to the player exactly as you typed it. ### Usage notes * Legacy `&` codes, including `&#RRGGBB` hex, keep working everywhere exactly as before. * In **chat messages**, use one style per line. A chat line is only sent as MiniMessage when it contains no legacy colour codes at all, so mixing `&c` and `` in the same line falls back to legacy and prints the tag. * Everywhere else the two can be mixed freely. A hologram line or an item name is read as MiniMessage as soon as it contains a tag, and any `&` codes in it are converted along with it. * A tag the server does not recognise is left in the text as written rather than being dropped, which is what keeps resource pack glyph tags working. > **Warning:** MiniMessage needs [Paper](https://papermc.io/) or a fork of it. On plain Spigot the tags are printed exactly as you typed them, so stay on `&` codes there. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/languages --- # 📁 Main Configuration ## General Configuration Below is a list of options that are in the config.yml and a description of what they do. * **Knockback** - This option allows you to change the knockback that the player takes when trying to open a crate with the wrong key * **Quick-Open** - This option will enable players to quick open when holding the crate key and shifting right-clicking it. * **Render-Radius** - This option allows you to define the distance that effects will need to stop showing to the player. * **Disable Confirmation Menus** - This option allows you to skip confirmation menus (open money cost, selective reward mode) so players go straight to the action. * **Key Mainhand Requirement** - This option allows you to define whether players will need to have a key in their main hand to open crates. Enabled by default. * **Event Actions** - The actions every crate runs on open, win, close and denied, unless the crate has its own. See [Event Actions](../main-features/crates/README.md#event-actions). All of these options can also be changed in-game from the editor's Settings menu.

Editor > Settings

The following ones exist only in the file: * **Hologram Refresh Rate** - How many ticks pass between two refreshes of the built-in crate holograms. A higher value updates placeholders in the hologram less often and costs less. Values below 10 are raised to 10. * **Internal Pool Size** - `performance.internal-pool-size`, the number of threads the plugin uses for its own background work such as database reads and animation preparation. The default of `5` suits almost every server. Raise it only if you run a very large network and see the plugin queueing work. * **Notify If New Version** - Whether players with the admin permission are told on join that a newer version of the plugin is out. * **Join Reminder** - Lite only, sends players with `phoenixcrates.admin` a message on join about the premium version. * **Debug** - Adds verbose logging to the console, useful when reporting an issue. * **Product License** - Premium only, your license key. See [Licensing](../plugin-information/licensing.md). ## Broadcast Message (Lite) The Lite version has a single broadcast message shared by every crate, set in `config.yml`. The Premium version does not use this option, because there the broadcast message is configured per crate from the editor. ```yaml crates: broadcast-message: - '&ePlayer &a%player% &ejust got &6"%reward%" &ereward from the crate &6%crate%&e!' ``` ## Event Actions Each event is a list of [actions](../plugin-information/action-types.md). An empty list runs nothing. ```yaml event-actions: open: [] win: - '[SOUND] minecraft:entity.player.levelup; 1; 1' close: [] denied: [] ``` ## Placeholder Cost Engine The currency used by every crate whose open cost runs on the Placeholder engine. It is also editable from the crate's open cost, and each field is explained on [Open Money Cost](../main-features/crates/open-money-cost.md#placeholder-currency). ```yaml cost-engines: placeholder: display-name: Tokens balance: '' withdraw-command: '' whole-number: false ``` ## Commands The virtual keys and the pay key commands can each be turned off, and given an alternative name that is registered next to the default one, which is useful when another plugin already claims the same command. Pay key is disabled by default, so `/crates payKey` only exists after enabling it here. Changes apply on `/crates reload`, without a restart. An alternative name another plugin already uses is not registered, and the console says so. The command still works under `/crates`. ```yaml commands: virtual-keys: enabled: true alternative: virtualkeys pay-key: enabled: false alternative: paykey ``` ## Bedrock How Bedrock players joining through Geyser see the player menus: native forms, chest menu sizes and form icons. Every option is explained on the [GeyserMC (Bedrock)](geysermc-bedrock.md#bedrock-forms) page. ## Database The plugin also supports databases. The available options are mysql and sqlite. ```yaml database: type: sqlite address: localhost name: phoenixcrates_db port: 3306 username: phoenixuser password: phoenixpassword table-prefix: pc ``` ### Connection Pool When using MySQL, the connection pool can be tuned under `database.hikari`. The defaults are good for a normal server, and are worth revisiting only if you run a large network or your database is on a different machine. ```yaml database: hikari: maximumPoolSize: 10 minimumIdle: 5 idleTimeout: 300000 maxLifetime: 1700000 connectionTimeout: 30000 fetch-timeout: 5000 ``` | Option | Description | | ----------------- | ------------------------------------------------------------------------------------------------- | | maximumPoolSize | The most connections the plugin will open at once. | | minimumIdle | How many connections are kept open while idle. | | idleTimeout | How long, in milliseconds, an idle connection is kept before being closed. | | maxLifetime | How long, in milliseconds, a connection lives before being replaced. Keep it under your MySQL `wait_timeout`. | | connectionTimeout | How long, in milliseconds, to wait for a free connection before giving up. | | fetch-timeout | How long, in milliseconds, to wait for a player's data before treating it as unavailable. | > **Info:** If players are told to wait while their data loads when they open a crate, raising `fetch-timeout` or `maximumPoolSize` is usually the fix. Save the file and reload the plugin to apply the changes. ## Messages & Translations Every message the plugin sends lives in the translation file rather than in config.yml, and `language` decides which one is loaded. Editing the wording, silencing a message, and running the plugin in another language are all on [Languages & Translations](languages.md). ## MiniMessage On top of the usual `&` colour codes, text accepts MiniMessage tags for gradients, hover text and clickable links. It has its own page: [Rich Text (MiniMessage)](languages.md#rich-text-minimessage). Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/main-configuration --- # 📰 Reward Config Editing > **Danger:** If you copy and paste a reward, make sure to change its identifier, as it must be unique. ## Edit Rewards You can also edit the rewards through the configuration file if you prefer to manage everything manually. ## Reward Options Each entry under `rewards` carries the reward's own settings alongside its items. Every one of them is also editable from [Edit Reward](../main-features/rewards/edit-reward.md), so the table below is mostly useful when generating crates outside the game or editing many rewards at once. | Option | Description | | ------------------------ | ---------------------------------------------------------------------------------------------- | | identifier | Unique id of the reward. Changing it loses the player progress tied to it. | | enabled | Whether the reward can be won at all. | | display-item | The item shown in the preview, never given to the player. | | win-items | The items the player receives, numbered from `'0'`. | | win-commands | Commands run when the reward is won. | | weight | Chance share in Random mode. Higher means more often. | | win-limits | How many times one player can win it. `-1` is unlimited. | | global-win-limit | How many times everyone combined can win it. `-1` is unlimited. | | guaranteed-win | Openings after which the reward is guaranteed. `-1` disables it. | | required-keys | Keys the reward costs in Selective mode. | | required-permissions | Permissions a player must have for the reward to be available. | | restricted-permissions | Permissions that prevent a player from winning the reward. | | broadcast | Whether winning it announces the crate's broadcast message. | | allow-win-message | Whether the winner gets a message. | | notification-type | Where that message goes, `CHAT` or `ACTION_BAR`. | | share-players-online | Whether every online player also receives the reward. | `max-win` caps how much of each list is handed out per win, picked at random, with `-1` meaning the whole list: ```yaml max-win: item-amount: 1 command-amount: -1 ``` `cooldowns` holds the three reward cooldowns, in seconds. `time-limited-expiry` is written by the plugin to remember when the time limited window ends, and is not meant to be set by hand: ```yaml cooldowns: win-limit-cooldown: 0 global-win-limit-cooldown: 0 time-limited-cooldown: 0 time-limited-expiry: 0 ``` `alternative-reward` is the reward given once a limit is reached, with its own item, commands and toggles: ```yaml alternative-reward: enabled: false reward: item: material: DIAMOND_PICKAXE display-name: '&aAlternative Item' amount: 1 virtual: false broadcast: false allow-win-message: true share-players-online: false commands: [] ``` Setting `virtual` to `true` keeps the alternative item as a display only, so the player receives nothing but the commands still run. ## Format: The following option is the method you can use for vanilla items. \ **Note:** This option cannot be configured through the in-game editor, as the editor uses the bukkit format to also support custom properties and modded Items. ```yaml display-item: material: PAPER win-items: '0': material: PAPER ``` ## Material: Allows you to set a material on your item. > ```yaml > material: TEXT > ``` > > > **Supported material values:** > > > > * Vanilla (`DIAMOND`). > > * [HeadDatabase ](https://www.spigotmc.org/resources/head-database.14280)(`hdb:id`) > > * [ItemsAdder](https://www.spigotmc.org/resources/%E2%9C%A8itemsadder%E2%AD%90emotes-mobs-items-armors-hud-gui-emojis-blocks-wings-hats-liquids.73355) (`itemsadder:namespace:id`) > > * [Nexo](https://mcmodels.net/products/13172/nexo?srsltid=AfmBOoocUPY8FdXiOkDqM4Rml1Gs449TBz0x_FoKwJBgG8IYvkvMNJ2H) (`nexo:id`) > > * [Mythic Items](https://mythiccraft.io/index.php?ewr-porta) (`mythicitem:id`) > > * [MMOItems](https://www.spigotmc.org/resources/%EF%B8%8F%E2%9A%94%EF%B8%8F-mmoitems-%E2%9A%94%EF%B8%8F-items-weapons-armor-sets-tiers-editor-gui-skills.39267) (`mmoitem:type:id` ) > > * [ExecutableItems](https://www.spigotmc.org/resources/%E2%9A%94%EF%B8%8Fexecutableitems-%E2%AD%90-customize-all-items-add-abilities-%E2%AD%90-ai-items-generation-on-the-discord-%E2%9C%85.83070) (`executableitem:id`) > > * [CraftEngine](https://modrinth.com/plugin/craftengine) (`craftengine:id`) > > > > > - [Materials Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) > **Info:** For hooked items (ItemsAdder, Nexo, MMOItems, ExecutableItems, CraftEngine, etc.), the `id` is the custom item's own identifier as registered in that plugin. ## Hooked Materials A hooked material is the hook name, a colon, then the id the other plugin knows the item by. Only the first colon separates the two, so everything after it reaches that plugin exactly as written. > **Danger:** The separator is a colon, never a dash. `itemsadder-medieval_crates-crate_key` is read as a plain material name, matches none, and is reported as an unknown material in the console. The hook is never reached. The same value written with colons resolves. | Hook | Value | Example | | --------------- | ------------------------ | ------------------------------------ | | ItemsAdder | `itemsadder:namespace:id`| `itemsadder:medieval_crates:crate_key` | | MMOItems | `mmoitem:type:id` | `mmoitem:SWORD:cutlass` | | Nexo | `nexo:id` | `nexo:ruby_sword` | | CraftEngine | `craftengine:id` | `craftengine:default:ruby_sword` | | Mythic Items | `mythicitem:id` | `mythicitem:excalibur` | | ExecutableItems | `executableitem:id` | `executableitem:magic_wand` | | HeadDatabase | `hdb:id` | `hdb:1234` | ItemsAdder and MMOItems ids are built from two parts of their own, so those values have three parts in total. `itemsadder:crate_key` sends only `crate_key` to ItemsAdder and resolves to nothing, and an MMOItems value with no type is rejected. For the rest, pass the id exactly as the plugin registers it, namespace included where it has one. > ```yaml > material: itemsadder:medieval_crates:crate_key > ``` The same values work in every `material` field of the plugin, the [menus](customize-menus.md#item-material) included. > **Info:** When the hook name is valid but the plugin is not installed, or the id resolves to nothing, the item becomes a placeholder rather than the crate failing to load. On a reward it names the hook in its lore, in a menu it is a barrier. ## Display Name Allows you to set a display name on your item. > ```yaml > display-name: '&eExample Reward' > ``` > **Success:** This option also supports [MiniMessage](https://docs.advntr.dev/minimessage/format) Format. ## Lore: Allows you to set a custom lore on your item. > ```yaml > lore: > - '&cLine 1' > - '&eLine 2' > - '&aLine 3' > ``` > **Success:** This option also supports [MiniMessage](https://docs.advntr.dev/minimessage/format) Format. ## Model Data: Allows you to set custom model data on your item. > ```yaml > model-data: 1000 > ``` ## Item Model: Allows you to set a custom [Item Model](https://minecraft.wiki/w/Items_model_definition) (the modern resource-pack item model component) on your item. > ```yaml > item-model: 'minecraft:custom_paper' > ``` > **Warning:** This option requires the resource pack to actually define the referenced item model. If the model doesn't exist, the item will simply render with its base material's texture. ## Amount: Allows you to set a fixed stack size on your item. > ```yaml > amount: 1 > ``` ## Enchants: Allows you to set enchants on your item. > ```yaml > enchants: > - 'PROTECTION:1' > - 'UNBREAKING:1' > ``` > > > * [Enchantsments Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html) ## Item Flags: Allows you to set item flags on your item, to hide certain tooltip sections (enchants, attributes, "unbreakable", etc). > ```yaml > flags: > - 'HIDE_ENCHANTS' > ``` > > > * `item-flags` is accepted as an alias, used when `flags` is absent. > > * [Item Flags Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html) ## Tooltip Style: Allows you to set a custom tooltip style/texture (resource-pack defined) for the item's tooltip box. > ```yaml > tooltip-style: 'minecraft:gui/sprites/widget/inventory_tooltip' > ``` > **Warning:** Requires server version **1.21.2+**. On older server versions this option is ignored. ## Enchantment Glint Override: Allows you to force the enchantment glint (the shimmering/glowing effect) on or off, independently of whether the item is actually enchanted. > ```yaml > enchantment-glint-override: true # Boolean (`true`/`false`) > ``` > **Warning:** Requires server version **1.20.5+**. On older server versions this option is ignored. ## Banner Meta: Allows you to add banner patterns to your item. Works on banners, and on shields (and other blocks that carry banner data). > ```yaml > banner-meta: > - 'RED;STRIPE_BOTTOM' > - 'WHITE;CROSS' > ``` > > > * Each entry follows the format `;`. > > * [DyeColor Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/DyeColor.html) / [PatternType Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/block/banner/PatternType.html) ## Armor Trim (Material & Pattern): Allows you to apply an armor trim to your item, by setting both the trim material and the trim pattern. > ```yaml > trim-material: IRON > trim-pattern: DUNE > ``` > > > * Both options must be set together. > > * [Armor Trim Materials](https://minecraft.wiki/w/Smithing#Trim_materials) / [Armor Trim Patterns](https://minecraft.wiki/w/Smithing#Trim_patterns) > **Warning:** Requires server version **1.20+**. On older server versions this option is ignored. ## Potion Effects: Allows you to add custom potion effects to a potion item. > ```yaml > potion-effects: > - 'speed;1200;1' > - 'regeneration;600;0' > ``` > > > * Each entry follows the format `;;`. > > * [Potion Effect Types Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html) ## RGB: Allows you to set a custom color on your item, using raw RGB values. > ```yaml > rgb: '38, 192, 210' > ``` > > > * Format: `R, G, B` (each `0`-`255`). Applies to leather armor, potions, maps and firework effects. ### Item Config Example The following is an example of a reward with its display item and the actual reward. ```yaml '2': identifier: reward_1759509999284 display-item: material: PAPER # Legacy colors support display-name: '&#C00BD6Paper' lore: - '&cCustom Paper Item' model-data: 1000 enchants: - 'PROTECTION:1' flags: - 'HIDE_ENCHANTS' win-items: '0': material: PAPER # Mini Message Support display-name: 'Paper' lore: - 'Custom Paper Item' model-data: 1000 enchants: - 'PROTECTION:1' flags: - 'HIDE_ENCHANTS' ``` Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/reward-config-editing --- # 🎨 Rich Text (MiniMessage) ## Information Phoenix Crates understands [MiniMessage](https://docs.advntr.dev/minimessage/format.html) tags, like ``, `` or ``, on top of the classic `&` colour codes. This lets you use gradients, hover text and clickable links, none of which `&` codes can do. ## Format | Example | Result | | -------------------------------------------------------- | -------------------------------------- | | `Hello` | Red text | | `<#ff8800>Hello` | Any hex colour | | `Phoenix Crates` | Text fading from one colour to another | | `Warning` | Bold and underlined | | `Legendary!` | Each letter a different colour | | `Hover` | Text with a tooltip | | `Our site` | Text that opens a link | A closing tag is optional. `Hello` colours the rest of the line, while `Hello there` colours only the first word. ## Where it works | Place | Notes | | ----------------------------- | ------------------------------------------------- | | Chat messages | Everything in the language file that reaches chat | | Crate holograms | The floating text above a crate | | Reward names and lore | Including the rarity group display item | | Menu titles, item names, lore | Anywhere the editor lets you write text | ## Where it doesn't work Titles, subtitles, the action bar and boss bars only understand `&` codes. Those are sent as raw legacy text, so a tag in one of them is shown to the player exactly as you typed it. ## Usage notes * Legacy `&` codes, including `&#RRGGBB` hex, keep working everywhere exactly as before. * In **chat messages**, use one style per line. A chat line is only sent as MiniMessage when it contains no legacy colour codes at all, so mixing `&c` and `` in the same line falls back to legacy and prints the tag. * Everywhere else the two can be mixed freely. A hologram line or an item name is read as MiniMessage as soon as it contains a tag, and any `&` codes in it are converted along with it. * A tag the server does not recognise is left in the text as written rather than being dropped, which is what keeps resource pack glyph tags working. > **Warning:** MiniMessage needs [Paper](https://papermc.io/) or a fork of it. On plain Spigot the tags are printed exactly as you typed them, so stay on `&` codes there. Source: https://www.phoenixplugins.com/docs/phoenix-crates/configurations/rich-text --- # 💎 Features
CratesRewardsAnimations
Customize via the In-Game Editor.Customize via the In-Game Editor.Customize via In-Game Editor.
Multiple locations per crate.Win rewards that the user selects.120+ Animation combinations to choose from.
One configuration file per crate.Win rewards that are given randomly.Use premade combinations as animations.
Crate Block can be any material.Selective (non RNG) rewards mode.Create your own unique animations.
Vanilla Block and Vanilla Model engines.Support for any custom item.Code your own animations with our API.
ModelEngine 3&4 for Animated Models.Support for modded items.Packet Based to not cause performance issues.
Better Model support, with scaling.Rewards executed by the user or the console.Multiple stages of animations.
Custom hologram per crate.Run commands as rewards.Idle animation state.
Preview rewards for each crate.PlaceholderAPI Support for commands.Close animation state.
Customize Rewards Preview menu.Customize the display name for the reward.First, Second, and Third animation state.
Preview the Reward above the crate.Multiple items given from a single reward.Pre Open and Post Open animations.
Require permission to open a crate.Add multiple items as rewards at once.Reward Display animations.
Require balance to open a crate (vault)Reorder the rewards from the editor.Delay the timing of an animation.
Option to not require a key.Quick delete for the reward.Animation that contain custom sounds.
Open cooldown per crate.An option for virtual rewards.Synchronizing the animation stages with the model.
Knockback when the user doesn't have a key.Percentage to win an item.Animations for all the users at the same time.
Broadcast message per crate.Adjust the win limit.
Simultaneous openings by multiple players.Maximum amount of wins per reward.
Clone a crate.Alternative reward when the user won the default one.
Virtual and Physical Keys.Reward that will be given to all online users.
Guaranteed Rewards.Broadcast the reward when its given to the user.
Rerolls.Blacklist permissions from receiving the reward.
Log the actions.Edit the rewards straight from the config file.
Migrate from other crate plugins.Win actions per reward.
MySQL and SQlite Database.
Folia supported.
Bedrock supported through GeyserMC.
MiniMessage and hex color support.
Plugin Messages 100% configurable.
Event actions on open, win, close and denied.
Choose which click opens and which previews.
Pay with any PlaceholderAPI currency.
Manage every placed crate from the editor.
## Add-ons
Add-onWhat it adds
Last WinnerShow who last won from a crate, with its own placeholders.
RarityGive the rewards a rarity tier with its own display.
Mass OpeningOpen many keys at once from a single interaction.
Crate ClaimHold rewards and physical keys for users who are offline.
Reward On LoopRepeat a reward on a timer, with permission and win caps.
LeaderboardRank the users by their openings and their wins.
IP LimitLimit how many openings come from the same IP address.
RedisKeep the crate data in sync across multiple servers.
LootboxOpen a crate from a placed block that plays the animations.
Deluxe AnimationsExtra animation pack.
Halloween Crate AnimationsSeasonal animation pack.
Christmas Crate AnimationsSeasonal animation pack.
## Suggestions If you notice something missing from our plugin, please let us know. Additionally, we are always open to suggestions from our users to add more content and improve the plugin. Source: https://www.phoenixplugins.com/docs/phoenix-crates/features --- # 🤖 Action Types In our system's configuration files, you can utilize various action types to perform different actions. These actions enable you to interact with players, broadcast messages, play sounds, set gamemodes, and much more. ## Action Types | Action List | Description | | ------------------- | -------------------------------------------- | | \[MESSAGE] | Display a custom message to the player | | \[TITLE] | Display a custom title message to the player | | \[ACTION\_BAR] | This is a custom action bar | | \[CLOSE\_INVENTORY] | Close the player's current inventory | | \[COMMAND] | Execute a command (console or player) | | \[GAMEMODE] | Set the player's gamemode | | \[POTION\_EFFECT] | Apply a potion effect to the player | | \[SOUND] | Play a sound for the player | | \[MENU] | Open a custom menu | | \[DELAY] | A way to delay some actions | | \[OPEN] | Opens the crate | Explore each action type to learn more about its syntax and usage. Examples are provided to illustrate how to use these actions effectively in your system or application. ### **Send Chat Message** This action sends a custom message to the player. * **Syntax:** `[MESSAGE] ` * **Example:** `[MESSAGE] &aThis is a custom message` ### **Send Title Message** This action displays a custom title message to the player. * **Syntax:** `[TITLE] ; <subtitle>; <fadein>; <stay>; <fadeout>` * **Example:** `[TITLE] &aCustom title;&7Custom Subtitle; 20; 40; 20` ### **Send Action Bar Message** This action displays a custom action bar message to the player. * **Syntax:** `[ACTION_BAR] <message>` * **Example:** `[ACTION_BAR] This is a custom action bar` ### **Close Inventory** This action closes the inventory the player has open. * **Syntax:** `[CLOSE_INVENTORY]` * **Example:** `[CLOSE_INVENTORY]` ### **Execute Command** This action executes a command either from the console or as a player. * **Syntax:** `[COMMAND] <target>; <command>` * **Example:** `[COMMAND] console; mvtp %player% world` * **Example**: `[COMMAND] player; warp spawn` ### **Change Gamemode** This action sets the gamemode for the player. * **Syntax:** `[GAMEMODE] <gamemode>` * **Example:** `[GAMEMODE] adventure` ### **Give Potion Effect** This action gives the player a potion effect. * **Syntax:** `[POTION_EFFECT] <effect>; <duration>; <amplifier>` * **Example:** `[POTION_EFFECT] speed; 5; 2` ### **Play Sound** This action plays a sound for the player. * **Syntax:** `[SOUND] <sound>; <volume>; <pitch>` * **Example:** `[SOUND] entity_arrow_hit_player; 1; 1` ### **Open Menu** This action opens a custom graphical user interface (GUI) menu. * **Syntax:** `[MENU] <menu_name>` * **Example:** `[MENU] main_menu` ### **Delay** This action will make a short pause until it continues executing actions. * **Syntax:** `[DELAY] <seconds>` * **Example:** `[DELAY] 3` Source: https://www.phoenixplugins.com/docs/phoenix-crates/features/action-types --- # 🪙 Guaranteed Rewards > **Info:** This feature is only available in the random rewards mode ## Guaranteed Mode Guaranteed Rewards are a great way to ensure a player receives a specific reward after reaching a set number of openings. Guaranteed Mode has two types, but it is disabled by default. The available options are: * **Sequential** * **Repetitive** <figure><img src="../.gitbook/assets/Screenshot 2025-05-24 201733.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate > Rewards</p></figcaption></figure> ## Sequential The guaranteed reward will work in a sequence, meaning players will receive the reward only once upon reaching a specific number of openings. Once that number is reached, they will "unlock" the next guaranteed reward in the sequence. **Example:** * Reward : Requires 5 Openings The player will receive that reward only once on the 5th opening. ## Repetitive The guaranteed reward will work on repeat, meaning players will receive the reward every **X** crate openings. Once that number is reached, they will receive the reward again. **Example:** * Reward : Requires 5 Openings The player will receive that reward on repeat on every 5th opening. ## Create a Guarantee Reward Creating a Guaranteed Reward is very simple and straightforward. You only need to specify the number of openings required for the player to receive the reward. <figure><img src="../.gitbook/assets/editor/reward/guaranteed-win.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Unique Coloring If you decide to use a guaranteed reward for a specific reward, its display will change in the editor to help you identify it more easily. <div><figure><img src="../.gitbook/assets/Screenshot 2025-05-24 204733.png" alt="" width="560"><figcaption><p>Editor > Crates > Crate > Rewards</p></figcaption></figure> <figure><img src="../.gitbook/assets/Screenshot 2025-05-24 204750.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate > Rewards</p></figcaption></figure></div> **Red:** When the reward is based only on a specific number of openings.\ **Yellow****:** When the reward requires both a specific number of openings and a percentage chance.\ **Green:** When the reward is based only on a percentage (default). Source: https://www.phoenixplugins.com/docs/phoenix-crates/features/guaranteed-rewards --- # 🔎 Log the Actions ## Logger The logger records two things: when a player opens a crate, and when a player receives a reward. Both are written to a log file on your server, and can also be sent to a Discord channel through a webhook. Everything on this page is configured in logger.yml. ## Log Files Logging to file is always on and needs no setup. The current log is plugins/PhoenixCrates/logs/latest.log, with one timestamped line per action: ``` [2025-08-24_19-42-07][INFO] Steve opened a crate Vote Crate (vote) at world, 128, 64, -310. ``` Every time the server starts, the previous `latest.log` is compressed and kept alongside it as `<date>_<time>.log.gz`, so history is never overwritten. Old archives are kept until you delete them. ## Discord Webhook To also send these to Discord, set `discord-webhook.enabled` to `true` in `logger.yml`. By default this is set to false. ## Create a Webhook First, go to the settings of the Discord channel where you want to log crate actions. Then, navigate to the Integrations tab and click Create Webhook. <figure><img src="../.gitbook/assets/web.png" alt=""><figcaption></figcaption></figure> ## Setup the Logger The webhook will now have a URL. Make sure to click the copy button to save it. <figure><img src="../.gitbook/assets/web2.png" alt=""><figcaption></figcaption></figure> After copying the link, paste it into the `url: ''` field in the discord-webhook settings. ## Customization Now that the logger is set up, you can customize it by modifying the messages and the embed sent to the channel. <figure><img src="../.gitbook/assets/image (70).png" alt=""><figcaption></figcaption></figure> ### Log Format The two `log-format` entries decide what each line says. The same text is used for the file and for Discord. ```yaml log-format: open-crate: '%player% opened a crate %crate_name% (%crate_id%) at %location%.' won-reward: '%player% got the reward %reward_name% (%reward_id%) on crate %crate_name% (%crate_id%).' ``` | Placeholder | Available in | Description | | ---------------- | ------------ | ---------------------------------------------- | | %player% | both | The player's name. | | %crate\_name% | both | The crate's display name, without colours. | | %crate\_id% | both | The crate's identifier. | | %location% | open-crate | The crate's position, as `world, x, y, z`. | | %reward\_name% | won-reward | The reward's display name, without colours. | | %reward\_id% | won-reward | The reward's identifier. | | %reward\_amount% | won-reward | The amount on the reward's display item. | > **Info:** Setting a format to `''` (empty quotes) switches that action off completely. It stops being written to the file and stops being sent to Discord. This is the way to log only rewards, or only openings. ### Webhook Appearance The name and avatar the webhook posts under, and the embed it posts, are all configurable. ```yaml discord-webhook: enabled: true url: '' avatar-url: '' username: Phoenix Crates - Logger embed: title: Action Log description: '%message%' color: '#4a20ff' ``` | Option | Description | | ----------------- | ------------------------------------------------------------------------------ | | url | The webhook URL you copied from Discord. | | username | The name the message is posted under. | | avatar-url | A direct image URL to use as the avatar. Leave empty for the webhook's own. | | embed.title | The embed's heading. | | embed.description | The embed's body. `%message%` is the formatted log line. | | embed.color | The stripe colour down the side of the embed, as a hex value. | Now, make sure to save the changes and restart the plugin to apply the changes. Source: https://www.phoenixplugins.com/docs/phoenix-crates/features/log-the-actions --- # 🎲 Reroll > **Info:** The Reroll feature is available in the Premium+ plan of Phoenix Crates. When a user is dissatisfied with the reward they received, they have the option to reroll it. There are three ways a player ends up with rerolls: ## Reroll Types * **Create a Group**: You can create a group with a specific permission that grants a designated number of rerolls to users who have that permission. * **Free Rerolls**: You can set a "Free Rerolls" option, which determines the number of rerolls available to all players when opening a crate. * **Granted Rerolls**: Rerolls given with `/crates giveReroll` are stored on the player and last until they are used or taken back with `/crates takeReroll`. ## Rerolls Everything below lives in the crate's Rerolls menu, reached from the crate itself. <figure><img src="../.gitbook/assets/editor/crate/rerolls.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Enabled Whether the crate offers rerolls at all. By default this feature is disabled, so it has to be switched on per crate. <figure><img src="../.gitbook/assets/editor/rerolling/enabled.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls</p></figcaption></figure> ## Free Rerolls The number of rerolls every player gets on this crate, without needing a permission or a granted reroll. <figure><img src="../.gitbook/assets/editor/rerolling/free-rerolls.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls</p></figcaption></figure> ## Replay Animation When enabled, rerolling replays the crate's opening animation, and the reroll menu re-opens once it finishes. <figure><img src="../.gitbook/assets/editor/rerolling/replay-animation.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls</p></figcaption></figure> ## Skip Same Reward When enabled, a player will never receive the same reward they already won while rerolling on that opening. <figure><img src="../.gitbook/assets/editor/rerolling/skip-same-reward.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls</p></figcaption></figure> ## Reroll Groups A group grants a number of rerolls to everyone holding its permission. Each group in the list shows the permission it uses and what it is worth, and is edited or removed from there. <figure><img src="../.gitbook/assets/editor/rerolling/group-legendary.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls</p></figcaption></figure> ### Namespace The name of the group, which is also the last part of its permission, `phoenixcrates.reroll.<namespace>`. <figure><img src="../.gitbook/assets/editor/rerolling/namespace.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls > Group</p></figcaption></figure> ### Rerolls How many rerolls a player in this group has on the crate. <figure><img src="../.gitbook/assets/editor/rerolling/rerolls.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rerolls > Group</p></figcaption></figure> ## How the Total Is Calculated The three sources are added together: ``` free rerolls + best matching group + granted rerolls ``` So a player with 5 free rerolls, a group worth 10 and 2 granted rerolls opens with 17. > **Warning:** Groups do **not** stack with each other. If a player matches several groups, only the one with the highest reroll count is used. Give a VIP the group worth 10 and they get 10, not 10 plus whatever their default group grants. When the [Mass Opening](../add-ons/mass-opening/) add-on opens several keys at once, the total is multiplied by the number of keys used, so opening 12 keys with 3 rerolls each gives 36 rerolls for that session. ## Group Permissions A group grants its rerolls to any player holding `phoenixcrates.reroll.<group name>`, where the group name is the namespace you typed when creating it. The exact permission is shown in the editor on the group's own item, so you can copy it from there. > **Info:** Avoid spaces in group names. The permission uses the name as written, and a permission containing a space cannot be granted by most permission plugins. ## In-Game Preview The following is the menu users see when the reroll option is enabled. They can choose to either reroll the item or claim it. This menu can also be customized from the menus folder. <figure><img src="../.gitbook/assets/Untitledvideo-MadewithClipchamp88-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Reroll Preview In-Game</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/features/reroll --- # 🔌 First Installation ## Installation 1. Download the jar from our website 2. Install PhoenixCrates-?.jar into your "Plugins" folder. 3. Start your server 4. Configure the plugin by yml file or by in-game editor `/phoenixcrates editor` <figure><img src=".gitbook/assets/editor/editor.gif" alt="" width="563"><figcaption><p>The in-game editor</p></figcaption></figure> ## Add-on Installation 1. Select the add-ons you wish to install. 2. The add-ons will be included in the same jar. 3. Drag and drop the jar in the plugins folder 4. The PhoenixCrates jar will generate the add-ons in the `PhoenixCrates\addons` folder 5. [Optional] If you wish to download the add-ons separately, you can put them manually to that folder. <figure><img src=".gitbook/assets/misc/phoenixcrates_download.png" alt=""><figcaption><p>Download PhoenixCrates Popup</p></figcaption></figure> > **Info:** We strongly advise using the latest STABLE build of the plugin, as it includes the most recent bug fixes. ## Version Support The plugin supports Spigot, any Spigot forks, Paper, any Paper forks, and Folia. It should also work on any custom modded servers. <table><thead><tr><th>Minecraft Version</th><th data-type="checkbox"></th></tr></thead><tbody><tr><td>26.x</td><td>true</td></tr><tr><td>1.21.x</td><td>true</td></tr><tr><td>1.20.4+</td><td>true</td></tr></tbody></table> Version 6.0 dropped support for versions older than 1.20.4. Source: https://www.phoenixplugins.com/docs/phoenix-crates/first-installation --- # 🎉 Animations A crate plays two kinds of animation, both set from its Animations menu: an idle animation while nobody is opening it, and an opening animation when a player does. <figure><img src="../../.gitbook/assets/editor/crates/animations.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Opening Animation Plays when a player opens the crate, through its three phases, up to the reward being revealed. Every phase and animation is on [Opening Animations](opening-animations/README.md); the animation add-ons add more on [Animations](../../add-ons/animations/README.md). <figure><img src="../../.gitbook/assets/editor/engine/opening-animation.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations</p></figcaption></figure> ## Idle Animations Plays while nobody is opening the crate, and is built from particle effects. There are 120+ effect combinations available. <figure><img src="../../.gitbook/assets/editor/engine/idle-animation.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations</p></figcaption></figure> <figure><img src="../../.gitbook/assets/editor/idle-animation/add-effect.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation</p></figcaption></figure> ### Effect Type In the drop down below, you’ll find all the available effect types we currently offer. <details> <summary>Effect Types</summary> | Effect | Shape | Plan | | -------------- | -------------------------------- | ------- | | Default | Simple particle spawn at offset | Lite | | Circle | Particles orbit in a flat circle | Lite | | Star | Five-pointed star pattern | Lite | | Square | Square frame around the crate | Lite | | Deltoid | Triangular curved shape | Premium | | Astroid | Four-cusped hypocycloid | Premium | | Flower | Petal-like flower pattern | Premium | | Quatrefoil | Four-lobed clover shape | Premium | | Diamond | Diamond-shaped outline | Premium | | Ninja Star | Spinning shuriken pattern | Premium | | Spiral | Ascending helix spiral | Premium | | Conical Spiral | Cone-shaped rising spiral | Premium | | Pulse | Expanding ring pulse | Premium | </details> <figure><img src="../../.gitbook/assets/editor/select-effect-shape/diamond.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation > Select Effect Shape</p></figcaption></figure> ### Particle Type There are 100 different particle options available for you to choose from for your crate. * **None** - This type of particle can't have any special behavior. * **Directional - This type of particles can have a velocity.** * **Colorable - This type of particles can have a color.** ### **Additional Options** * **Color -** Not all particles support color. Redstone is a well-known particle that can change color, but others may not. If a particle doesn’t support color, this field will be ignore**d.** * **Offset -** Defines the position of the effect relative to the crate. * **Radius -** Controls the randomness of the effect’s position. * **Amount -** Sets the number of particles to display. For example, with a circle pattern and an amount of 2, you’ll see a 2-particle effect. (Recommended to test in-game.) * **Velocity** - There are some particles that allow speed. This field allows you to change the speed of each spawned particle. ### Edit an Effect Once an effect is created, it will appear in the main effects list, where you can Left-Click to edit it. The maximum number of effects you can add is 12. <figure><img src="../../.gitbook/assets/editor/idle-animation/star-3.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation</p></figcaption></figure> ### In the Config File Each effect is stored on a single line in the crate file, under `idle-effects`: ```yaml idle-effects: - CIRCLE;{REDSTONE;#ff0000;0.0;1.0;2.0;0.0;0.0;1} ``` The format is: ``` TYPE;{PARTICLE;COLOR;offsetX;offsetY;offsetZ;spread;velocity;amount} ``` | Field | Description | | -------- | ------------------------------------------------------------------ | | TYPE | The effect type, such as `CIRCLE` or `SPIRAL`. | | PARTICLE | The particle to use, such as `REDSTONE`. | | COLOR | The particle colour as hex, ignored by particles that cannot be coloured. | | offsetX | Position relative to the crate, sideways. | | offsetY | Position relative to the crate, height. | | offsetZ | Position relative to the crate, depth. | | spread | Randomness applied to each particle's position. | | velocity | Speed given to each particle, on particles that support it. | | amount | How many particles to spawn. | Editing from the editor is easier and safer, but knowing the format helps if you generate crates outside the game. Example of the Idle Animation In-Game <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp91-ezgif.com-video-to-gif-converter (1).gif" alt="" width="563"><figcaption><p>Example of the Default Idle Animation</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations --- # 🧍‍♂️ Idle Animations ## Idle Animations With idle animations, you can use particles to create custom animations. There are 120+ effect combinations available, allowing you to make your crate as unique as you like. <figure><img src="../../.gitbook/assets/editor/idle-animation/add-effect.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation</p></figcaption></figure> ## Effect Type In the drop down below, you’ll find all the available effect types we currently offer. <details> <summary>Effect Types</summary> | Effect | Shape | Plan | | -------------- | -------------------------------- | ------- | | Default | Simple particle spawn at offset | Lite | | Circle | Particles orbit in a flat circle | Lite | | Star | Five-pointed star pattern | Lite | | Square | Square frame around the crate | Lite | | Deltoid | Triangular curved shape | Premium | | Astroid | Four-cusped hypocycloid | Premium | | Flower | Petal-like flower pattern | Premium | | Quatrefoil | Four-lobed clover shape | Premium | | Diamond | Diamond-shaped outline | Premium | | Ninja Star | Spinning shuriken pattern | Premium | | Spiral | Ascending helix spiral | Premium | | Conical Spiral | Cone-shaped rising spiral | Premium | | Pulse | Expanding ring pulse | Premium | </details> <figure><img src="../../.gitbook/assets/editor/select-effect-shape/diamond.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation > Select Effect Shape</p></figcaption></figure> ## Particle Type There are 100 different particle options available for you to choose from for your crate. * **None** - This type of particle can't have any special behavior. * **Directional - This type of particles can have a velocity.** * **Colorable - This type of particles can have a color.** ## **Additional Options** * **Color -** Not all particles support color. Redstone is a well-known particle that can change color, but others may not. If a particle doesn’t support color, this field will be ignore**d.** * **Offset -** Defines the position of the effect relative to the crate. * **Radius -** Controls the randomness of the effect’s position. * **Amount -** Sets the number of particles to display. For example, with a circle pattern and an amount of 2, you’ll see a 2-particle effect. (Recommended to test in-game.) * **Velocity** - There are some particles that allow speed. This field allows you to change the speed of each spawned particle. ## Edit an Effect Once an effect is created, it will appear in the main effects list, where you can Left-Click to edit it. The maximum number of effects you can add is 12. <figure><img src="../../.gitbook/assets/editor/idle-animation/star-3.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Idle Animation</p></figcaption></figure> ## In the Config File Each effect is stored on a single line in the crate file, under `idle-effects`: ```yaml idle-effects: - CIRCLE;{REDSTONE;#ff0000;0.0;1.0;2.0;0.0;0.0;1} ``` The format is: ``` TYPE;{PARTICLE;COLOR;offsetX;offsetY;offsetZ;spread;velocity;amount} ``` | Field | Description | | -------- | ------------------------------------------------------------------ | | TYPE | The effect type, such as `CIRCLE` or `SPIRAL`. | | PARTICLE | The particle to use, such as `REDSTONE`. | | COLOR | The particle colour as hex, ignored by particles that cannot be coloured. | | offsetX | Position relative to the crate, sideways. | | offsetY | Position relative to the crate, height. | | offsetZ | Position relative to the crate, depth. | | spread | Randomness applied to each particle's position. | | velocity | Speed given to each particle, on particles that support it. | | amount | How many particles to spawn. | Editing from the editor is easier and safer, but knowing the format helps if you generate crates outside the game. Example of the Idle Animation In-Game <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp91-ezgif.com-video-to-gif-converter (1).gif" alt="" width="563"><figcaption><p>Example of the Default Idle Animation</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations/idle-animations --- # 🎇 Opening Animations Opening animations are the main animations played when opening a crate. They are divided into three phases: * [**Pre Open**](pre-open-animations.md) - Plays before the crate opens. * [**Post Open**](post-open-animations.md) - Plays after the crate opens. * [**Reward Display**](#reward-display-animations) - Plays when the winning reward is revealed. GUI animations also show to Bedrock players. <figure><img src="../../../.gitbook/assets/editor/engine/opening-animation.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations</p></figcaption></figure> ## Animation Phases Each phase has its own slot in the Opening Animations menu, showing which animation is currently set for it. Left-click a slot to pick the animation for that phase, and right-click it to edit that animation's own settings when it is customizable. The active phase is marked as such, and a phase left on **None** simply plays nothing at that stage. ### Pre Open The phase playing before the crate opens, and the slot showing which animation is currently set for it. <figure><img src="../../../.gitbook/assets/editor/opening-animations/pre-open.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ### Post Open The phase playing once the crate has opened, while the reward is being decided. <figure><img src="../../../.gitbook/assets/editor/opening-animations/post-open.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ### Reward Display The phase revealing the won reward. This slot also carries the colour the animation is played in. <figure><img src="../../../.gitbook/assets/editor/opening-animations/reward-display.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ## Virtual Opening All GUI animations also support **virtual openings**, allowing players to open crates via the `/crate open` command. Virtual openings still require the crate to be placed in the world and [**Allow Open Command**](../../crates/README.md#allow-open-command) to be enabled for that crate. ## Skip on ESC GUI animations can also have **Skip on ESC** enabled. When active, closing the inventory will immediately skip the animation and grant the reward to the player. <figure><img src="../../../.gitbook/assets/editor/opening-animations/skip-on-esc.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ## GUI Phase Settings Right-clicking the selected GUI animation in the animation list opens its Phase Settings, which restyle that animation for this crate only: * **Title** - The menu title shown while the animation plays. * **Filler**, **Marker Normal**, **Marker Flicker** and the glass colors - The panes the animation is drawn with. Only the ones the animation uses are listed. Drop any item on one, a custom item from a resource pack included, and its custom model data and item model are kept. * **Chance Lore** - Lines added under every reward shown in the animation. `%chance%` is the player's chance of winning it. Flash Cycle has no Phase Settings. ## Display Settings From the Opening Animation menu, the Display Settings button lets you fine-tune where the reward display item and its name appear: * **Item Position** (X/Y/Z) - Offsets the floating reward display item. * **Name Position** (X/Y/Z) - Offsets the reward's name tag, independently from the item itself. <figure><img src="../../../.gitbook/assets/editor/opening-animations/display-settings.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> The same offsets can also be written by hand in the crate file, described in [Extra Options](../../crates/README.md#extra-options). ## Animation Presets Instead of configuring the Pre Open, Post Open, and Reward Display animations one by one, you can apply a preset from the Opening Animations menu to set all three phases at once to a matching combination. Selecting an already-applied preset removes it, resetting the crate back to no preset. <figure><img src="../../../.gitbook/assets/editor/opening-animations/presets.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ### Choosing a Preset Each preset lists the three animations it applies, so you can see the combination before selecting it. <figure><img src="../../../.gitbook/assets/editor/opening-animations/lightning-storm.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations > Presets</p></figcaption></figure> ## Reward Display Animations Left-clicking the Reward Display slot opens the list of animations available for this phase. Each entry shows whether it is customizable and whether it supports virtual openings, and the ones your plan or add-ons do not include are shown as locked. <figure><img src="../../../.gitbook/assets/editor/opening-animations/fire-spiral.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ### Random Animation ⭐ The **Random** animation will play a random animation that is available *** ### Default Animation The **Default** animation triggers an explosion with particles and sound when the crate is opened. **Virtual Opening:** No **Customizable:** No **Material:** Flint https://www.youtube.com/watch?v=7Ga-cWG3TX8 Default Animation - In Game *** ### Helix Animation The **Helix** animation creates an upward-moving helix of particles after the crate is opened. **Virtual Opening:** No **Customizable:** No **Material:** Nether Star https://www.youtube.com/watch?v=05yHApp-KUw Helix Animation - In Game *** ### Smoke Spiral The **Smoke Spiral** animation summons smoke particles beneath the crate, forming a spiral effect. **Virtual Opening:** No **Customizable:** Yes **Material:** Firework Star https://www.youtube.com/watch?v=ORdWQhN3osc Smoke Spiral Animation - In Game *** ### Fire Spiral The **Fire Spiral** animation spins flame particles in a rotating spiral around the reward display, with colored ambient particles orbiting alongside it. The animation's color can also be customized. **Virtual Opening:** No **Customizable:** No **Material:** Magma Cream https://www.youtube.com/watch?v=t7jEATrCud0 Fire Spiral Animation - In Game *** ### Physical Item The **Physical Item** animation closes the crate and ejects the reward as a floating physical item, surrounded by particles. **Virtual Opening:** No **Customizable:** No **Material:** Clay https://www.youtube.com/watch?v=eEXa2DD7fkQ Physical Item Animation - In Game *** ### Firework The **Firework** animation periodically launches fireworks above the reward display, each one randomizing its shape and color. **Virtual Opening:** No **Customizable:** No **Material:** Firework Rocket https://www.youtube.com/watch?v=6XU21LyUVvA Firework Animation - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations/opening-animations --- # ⏭️ Post Open Animations Left-clicking the Post Open slot opens the list of animations available for this phase. Each entry shows whether it is customizable and whether it supports virtual openings, and the ones your plan or add-ons do not include are shown as locked. <figure><img src="../../../.gitbook/assets/editor/opening-animations/compact.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ## Random Animation ⭐ The **Random** animation will play a random animation that is available *** ## Ball Animation The **Ball** animation spawns a ball from the crate that bounces around before disappearing. **Virtual Opening:** No **Customizable:** No **Material:** Slime Ball https://www.youtube.com/watch?v=c12rDg3I96A Ball Animation - In Game *** ## Swirl Animation The The **Swirl** animation creates a swirling effect with particles above the crate after it’s opened. **Virtual Opening:** No **Customizable:** Yes **Material:** Nether Star https://www.youtube.com/watch?v=DnJy9xevoS0 Swirl Animation - In Game *** ## Fire The **Fire** animation starts a circular spiral of lava above the crate, summoning a spinning, floating magma skull. **Virtual Opening:** No **Customizable:** No**Material:** Blaze Rod https://youtu.be/DD1FmTAuSQY Fire Animation - In Game *** ## Compact The **Compact** animation shatters the crate into a floating block head that rises up while spinning rapidly, then slows to a stop as colored particles trail around it. **Virtual Opening:** No **Customizable:** No**Material:** Enderpearl https://youtu.be/OCr1YlP1kGQ Compact Animation - In Game *** ## Rotating Head The **Rotating Head** animation opens the crate and raises a large skull that spins rapidly before gradually slowing to a stop. **Virtual Opening:** No **Customizable:** No**Material:** Leather https://www.youtube.com/watch?v=Hy6NTxZAQ3Y Rotating Head Animation - In Game *** ## Spinner The **Spinner** animation cycles through the crate's possible rewards, gradually slowing down until it lands on the winning reward. **Virtual Opening:** No **Customizable:** No**Material:** Gold Nugget https://youtu.be/YVY7U2puaiA Spinner Animation - In Game *** ## CSGO - GUI The **CSGO** animation opens a GUI with a horizontal reel of rewards that scrolls past a marker, gradually slowing down until it stops on the winning reward. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Chest https://youtu.be/l3SVsFGHGgg CSO Animation - In Game *** ## Colored CSGO - GUI ⭐ The **CSGO** animation opens a GUI with a horizontal reel of rewards that scrolls past a marker, gradually slowing down until it stops on the winning reward. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Magenta Banner https://youtu.be/NIPYzHwr0hI Colored CSGO Animation - In Game *** ## Spotlight - GUI ⭐ The **Spotlight** animation opens a GUI and sweeps a beam across 9 columns of rewards, slowing down over several laps until it stops on the column holding the winning reward. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Redstone Lamp https://youtu.be/e05mGfj7I_g Spotlight Animation - In Game *** ## Rainbow - GUI The **Rainbow** animation scrolls across the GUI while rewards cycle, locking in from the outside until the center reveals the winner. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Pink Dye https://youtu.be/W5u0t8XZfGs Rainbow Animation - In Game *** ## Flip Cards - GUI The **Flip Cards** animation flips over in random order to reveal rewards, ending with the winning card as the rest disappear. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Map https://youtu.be/TVsgXBFk9lQ Flip Cards Animation - In Game *** ## Blackout - GUI ⭐ The **Blackout** animation cycles rewards before darkening the GUI from the outside in, leaving the center to reveal the winner. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Dragon Egg https://youtu.be/xWJDYbKr7fM Blackout Animation - In Game *** ## Snake - GUI The **Snake** animation sends two snakes toward the center, where they meet to reveal the winning reward. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Cactus https://youtu.be/_rNpijI3g0Y Snake Animation - In Game *** ## Ring Carousel - GUI ⭐ The **Ring Carousel** animation opens a GUI with two rings of rewards spinning in opposite directions around a marker. **Virtual Opening:** Yes **Customizable:** Yes**Material:** Clock <!-- TODO - PICTURE --> ## Flash Cycle - GUI The **Flash Cycle** animation opens a GUI where the surrounding slots rapidly flash through colors while the center slot cycles through rewards. **Virtual Opening:** Yes **Customizable:** No**Material:** Magenta Glazed Terracotta <!-- TODO - PICTURE --> ## Creeper The **Creeper** animation summons a creeper that is struck by lightning and explodes into a shower of rewards. **Virtual Opening:** No **Customizable:** No**Material:** Creeper Head https://youtu.be/2KGr9elZ2WI Creeper Animation - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations/opening-animations/post-open-animations --- # ⏮️ Pre Open Animations Left-clicking the Pre Open slot opens the list of animations available for this phase. Each entry shows whether it is customizable and whether it supports virtual openings, and the ones your plan or add-ons do not include are shown as locked. <figure><img src="../../../.gitbook/assets/editor/opening-animations/fire.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ## Random Animation ⭐ The **Random** animation will play a random animation that is available *** ## Default Animation The **Default** animation simply opens and closes the crate. **Virtual Opening:** No **Customizable:** No **Material:** Flint https://www.youtube.com/watch?v=jDWJUCr9-8M Default Animation - In Game *** ## Crack Animation The **Crack** animation starts with a loud banging noise and particle effects, then proceeds to open the crate. **Virtual Opening:** No **Customizable:** No **Material:** Melon Seeds https://youtu.be/AnmYfCJGD_8 Crack Animation - In Game *** ## Lighting The **Lightning** animation starts with a creeper charge sound, and then multiple lightnings are summoned. **Virtual Opening:** No **Customizable:** No **Material:** Stick https://youtu.be/Gxjt95mk41E Lightning Animation - In Game *** ## Key Opener The **Key Opener** animation will summon a key that rotates to unlock the crate. This key can also be customized using your model data, allowing you to adjust its offset and direction. **Virtual Opening:**No **Customizable:** Yes **Material:** Tripwire Hook https://youtu.be/7fwdwpBi_BA Key Opener Animation - In Game *** ## Fire The **Fire** animation will spawn fire particles beneath the crate that spread out. After that, it will summon lava particles that instantly drop to the ground. **Virtual Opening:** No **Customizable:** No **Material:** Blaze Powder https://www.youtube.com/watch?v=ntWA2SNOK4g Fire Animation - In Game *** ## Blasting The **Blasting** animation summons firework effects from above, aimed at the crate. When they hit, the crate opens and an explosion occurs. The animation’s color can also be customized. **Virtual Opening:** No**Customizable:** No **Material:** Firework Star https://www.youtube.com/watch?v=rSDsFcHq2iQ Blasting Animation - In Game *** ## Sonic Boom The **Sonic Boom** animation spirals energy upward from the crate into a rising point above it. Once charged, it releases a sonic boom shockwave followed by an explosion, and the crate opens. **Virtual Opening:** No **Customizable:** No **Material:** Warden Spawn Egg https://youtu.be/UUJVPm3DIT0 Sonic Boom Animation - In Game *** ## Cyclone Heart Animation ⭐ The **Cyclone Hearts** animation spawns hearts around the crate that swirl in a cyclone effect and eventually enter the crate. **Virtual Opening:** No **Customizable:** No **Material:** Red Dye https://www.youtube.com/watch?v=YxCudbpza2I Heart Cyclone Animation - In Game *** ## Rainbow Animation ⭐ The **Rainbow** animation summons a rainbow that starts from the left side of the crate and ends on the right side. **Virtual Opening:** No **Customizable:** No **Material:** Amethyst Shard https://www.youtube.com/watch?v=-uXGvMrcKHM Rainbow Animation - In Game *** ## Froggo Boom ⭐ The **Froggo Boom** animation summons a frog that falls onto the crate. If a player is nearby, it will deal fake damage to them with its tongue. After that, the frog will jump and dive into the crate. **Virtual Opening:** No **Customizable:** No **Material:** Frog Spawn Egg https://www.youtube.com/watch?v=lcfcvCY45Bc Froggo Animation - In Game *** ## Chicken Jockey ⭐ The **Chicken Jockey** animation summons a chicken jockey that falls onto the crate. The chicken then charges at the player, dashing and dealing fake damage. After the attack, they disappear. **Virtual Opening:** No **Customizable:** No **Material:** Zombie Head https://www.youtube.com/watch?v=oRj7usHIvXU Chicken Jockey Animation - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations/opening-animations/pre-open-animations --- # 💎 Reward Display Animations Left-clicking the Reward Display slot opens the list of animations available for this phase. Each entry shows whether it is customizable and whether it supports virtual openings, and the ones your plan or add-ons do not include are shown as locked. <figure><img src="../../../.gitbook/assets/editor/opening-animations/fire-spiral.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Animations > Opening Animations</p></figcaption></figure> ## Random Animation ⭐ The **Random** animation will play a random animation that is available *** ## Default Animation The **Default** animation triggers an explosion with particles and sound when the crate is opened. **Virtual Opening:** No **Customizable:** No **Material:** Flint https://www.youtube.com/watch?v=7Ga-cWG3TX8 Default Animation - In Game *** ## Helix Animation The **Helix** animation creates an upward-moving helix of particles after the crate is opened. **Virtual Opening:** No **Customizable:** No **Material:** Nether Star https://www.youtube.com/watch?v=05yHApp-KUw Helix Animation - In Game *** ## Smoke Spiral The **Smoke Spiral** animation summons smoke particles beneath the crate, forming a spiral effect. **Virtual Opening:** No **Customizable:** Yes **Material:** Firework Star https://www.youtube.com/watch?v=ORdWQhN3osc Smoke Spiral Animation - In Game *** ## Fire Spiral The **Fire Spiral** animation spins flame particles in a rotating spiral around the reward display, with colored ambient particles orbiting alongside it. The animation's color can also be customized. **Virtual Opening:** No **Customizable:** No **Material:** Magma Cream https://www.youtube.com/watch?v=t7jEATrCud0 Fire Spiral Animation - In Game *** ## Physical Item The **Physical Item** animation closes the crate and ejects the reward as a floating physical item, surrounded by particles. **Virtual Opening:** No **Customizable:** No **Material:** Clay https://www.youtube.com/watch?v=eEXa2DD7fkQ Physical Item Animation - In Game *** ## Firework The **Firework** animation periodically launches fireworks above the reward display, each one randomizing its shape and color. **Virtual Opening:** No **Customizable:** No **Material:** Firework Rocket https://www.youtube.com/watch?v=6XU21LyUVvA Firework Animation - In Game Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/animations/opening-animations/reward-display-animations --- # 💐 Crate Block Engine The engine decides how the crate is shown in the world: a [Vanilla Block](#vanilla-block), a [Vanilla Model](#vanilla-model) with custom model data, or an animated model from [Model Engine](#model-engine) or [Better Model](#better-model). <figure><img src="../../.gitbook/assets/editor/crates/crate-block-engine.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Vanilla Block This is the default engine for a crate, and it's the simplest option. With this engine, you can select a specific block to act as your crate block. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 155339 (1).png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ### Crate Blocks For the vanilla crate block, you can set any block available in Minecraft. Certain blocks, like chests, ender chests, shulker boxes, and trapped chests, will also include their default vanilla opening animations. <figure><img src="../../.gitbook/assets/Screenshot 2025-01-10 161949.png" alt=""><figcaption><p>Select a Vanilla Block</p></figcaption></figure> If you can't find the block you are looking for in the Selection menu, you can specify it in the crate's config manually. ### Player Heads When you select Player Head as the crate material type, you can specify a value for the head to replicate. <figure><img src="../../.gitbook/assets/image (24).png" alt="" width="521"><figcaption><p>Chat input for the Player Head</p></figcaption></figure> #### Getting the Head Value If you are using Paper, hold the player head in your main hand and run the **/paper dumpitem** command. This will return the value of the skull, which you can then use as the value for the crate. <figure><img src="../../.gitbook/assets/image (26).png" alt=""><figcaption><p>Player Head Value</p></figcaption></figure> #### In-Game Preview The following is an example of using TNT as the vanilla block crate type. <figure><img src="../../.gitbook/assets/image (29).png" alt="" width="563"><figcaption><p>Vanilla Crate Block</p></figcaption></figure> ## Vanilla Model With the Vanilla model, you can assign custom model data to your material, allowing you to use a custom model for your crate. However, due to the limitations of this engine, it cannot display animations. The crate will only appear in its static form. <figure><img src="../../.gitbook/assets/editor/crates/crate-block-engine.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> When you right-click this option, a menu will appear where you can set the material and custom model data for the item. To easily check the material and custom model data of an item (if you're using Paper), the best way is to use the **/paper dumpitem** command while holding the item in your main hand. ### Material The material is the vanilla item your model is applied to, and it is the item the crate is displayed as. Your resource pack applies the model to a specific material, so this has to be set to that same one, otherwise the custom data below has nothing to resolve against. <figure><img src="../../.gitbook/assets/editor/engine/material.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ### Custom Data The custom data is the value that points to the model inside your resource pack. Typing a number sets the Custom Model Data of the material, which is how custom models are selected on every supported version. <figure><img src="../../.gitbook/assets/editor/engine/custom-data.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> On 1.21.4 and newer, the same option also accepts an Item Model instead, described in the **Item Model (1.21.4+)** section further down. ### Scale The scale is a size multiplier for the model, where 1.0 is the model's normal size. <figure><img src="../../.gitbook/assets/editor/engine/scale.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ### Position and Rotation If your model isn't positioned correctly, don't worry. You can adjust it using the "offset" and "rotation degrees" options. These allow you to fine-tune the position and orientation of the model to ensure it displays perfectly. <figure><img src="../../.gitbook/assets/editor/engine/rotation-degrees.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> Each axis has its own offset, so the model can be moved on all three of them. ### Item Model (1.21.4+) On servers running 1.21.4 or newer, the "Custom Data" option also accepts an Item Model value as an alternative to Custom Model Data. Typing a number is treated as Custom Model Data, while typing a namespaced key (e.g. `minecraft:example`) is treated as an Item Model. Only one of the two can be set at a time, setting one automatically clears the other. #### In-Game Preview The following is an example of using the [Water Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model. <figure><img src="../../.gitbook/assets/image (30).png" alt="" width="526"><figcaption><p>Vanilla Model Block</p></figcaption></figure> ## Model Engine > **Info:** This feature is only available in the premium version of Phoenix Crates. > **Info:** This engine type requires [Model Engine 4](https://mythiccraft.io/index.php?pages/official-modelengine4-download/) (4.0.3 or newer) to be installed. With this engine, you can use models imported via Model Engine as your crate models. We've streamlined the process to make it as simple as possible, allowing you to edit your models directly through the in-game editor, making your life easier. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201337.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ### Model Name The first step is to assign the model name for your crate. The model name is the ID of the model you've imported via Model Engine. For example, if the model ID is **bat\_crate**, you should select the **bat\_crate** bbmodel <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201912 (1).png" alt=""><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ### Scale You can adjust the scale of the model, between 0.1 and 10. <figure><img src="../../.gitbook/assets/editor/engine/scale-2.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ### Animations * **Idle animation**: The default animation when the crate is inactive. * **First opening phase**: The initial stage of the crate opening. * **Second opening phase**: The middle stage of the crate opening. * **Third opening phase**: The final stage of the crate opening. * **Close animation**: The animation that plays when the crate closes. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 202512.png" alt=""><figcaption></figcaption></figure> All these options are configured separately through their respective items. There's also an option to set a delay, allowing you to sync the animations if they occur later than the default timing. This ensures that the particles and animations look smoother and more cohesive. #### In-Game Preview The following is an example of using the [Fire Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model using Model Engine 4. <figure><img src="../../.gitbook/assets/number_8-ezgif.com-video-to-gif-converter (1).gif" alt=""><figcaption><p>Model Engine Block</p></figcaption></figure> ## Better Model > **Info:** This engine type requires [Better Model](https://modrinth.com/plugin/bettermodel) to be installed. With this engine, you can use models imported via Better Model as your crate models. We've streamlined the process to make it as simple as possible, allowing you to edit your models directly through the in-game editor, making your life easier. <figure><img src="../../.gitbook/assets/editor/crates/engine/better-model-engine.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ### Model Name The first step is to assign the model name for your crate. The model name is the ID of the model you've imported via Better Model. For example, if the model ID is **bat\_crate**, you should select the **bat\_crate** bbmodel <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201912 (1).png" alt=""><figcaption><p>Editor > Crates > Crate > BetterModel</p></figcaption></figure> ### Scale You can adjust the scale of the model, between 0.1 and 10. <figure><img src="../../.gitbook/assets/editor/bettermodel/scale.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > BetterModel</p></figcaption></figure> ### Animations * **Idle animation**: The default animation when the crate is inactive. * **First opening phase**: The initial stage of the crate opening. * **Second opening phase**: The middle stage of the crate opening. * **Third opening phase**: The final stage of the crate opening. * **Close animation**: The animation that plays when the crate closes. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 202512.png" alt=""><figcaption></figcaption></figure> All these options are configured separately through their respective items. There's also an option to set a delay, allowing you to sync the animations if they occur later than the default timing. This ensures that the particles and animations look smoother and more cohesive. #### In-Game Preview The following is an example of using the [Fire Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model using Better Model. <figure><img src="../../.gitbook/assets/number_8-ezgif.com-video-to-gif-converter (1).gif" alt=""><figcaption><p>Better Model Block</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crate-engine-mode --- # 🌷 Better Model > **Info:** This engine type requires [Better Model](https://modrinth.com/plugin/bettermodel) to be installed. ## Better Model With this engine, you can use models imported via Better Model as your crate models. We've streamlined the process to make it as simple as possible, allowing you to edit your models directly through the in-game editor, making your life easier. <figure><img src="../../.gitbook/assets/editor/crates/engine/better-model-engine.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Model Name The first step is to assign the model name for your crate. The model name is the ID of the model you've imported via Better Model. For example, if the model ID is **bat\_crate**, you should select the **bat\_crate** bbmodel <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201912 (1).png" alt=""><figcaption><p>Editor > Crates > Crate > BetterModel</p></figcaption></figure> ## Scale You can adjust the scale of the model, between 0.1 and 10. <figure><img src="../../.gitbook/assets/editor/bettermodel/scale.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > BetterModel</p></figcaption></figure> ## Animations: * **Idle animation**: The default animation when the crate is inactive. * **First opening phase**: The initial stage of the crate opening. * **Second opening phase**: The middle stage of the crate opening. * **Third opening phase**: The final stage of the crate opening. * **Close animation**: The animation that plays when the crate closes. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 202512.png" alt=""><figcaption></figcaption></figure> All these options are configured separately through their respective items. There's also an option to set a delay, allowing you to sync the animations if they occur later than the default timing. This ensures that the particles and animations look smoother and more cohesive. ### In-Game Preview The following is an example of using the [Fire Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model using Better Model. <figure><img src="../../.gitbook/assets/number_8-ezgif.com-video-to-gif-converter (1).gif" alt=""><figcaption><p>Better Model Block</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crate-engine-mode/better-model --- # 🌹 Model Engine > **Info:** This feature is only available in the premium version of Phoenix Crates. > **Info:** This engine type requires [Model Engine 4](https://mythiccraft.io/index.php?pages/official-modelengine4-download/) (4.0.3 or newer) to be installed. ## Model Engine With this engine, you can use models imported via Model Engine as your crate models. We've streamlined the process to make it as simple as possible, allowing you to edit your models directly through the in-game editor, making your life easier. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201337.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Model Name The first step is to assign the model name for your crate. The model name is the ID of the model you've imported via Model Engine. For example, if the model ID is **bat\_crate**, you should select the **bat\_crate** bbmodel <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 201912 (1).png" alt=""><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ## Scale You can adjust the scale of the model, between 0.1 and 10. <figure><img src="../../.gitbook/assets/editor/engine/scale-2.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ## Animations: * **Idle animation**: The default animation when the crate is inactive. * **First opening phase**: The initial stage of the crate opening. * **Second opening phase**: The middle stage of the crate opening. * **Third opening phase**: The final stage of the crate opening. * **Close animation**: The animation that plays when the crate closes. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 202512.png" alt=""><figcaption></figcaption></figure> All these options are configured separately through their respective items. There's also an option to set a delay, allowing you to sync the animations if they occur later than the default timing. This ensures that the particles and animations look smoother and more cohesive. ### In-Game Preview The following is an example of using the [Fire Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model using Model Engine 4. <figure><img src="../../.gitbook/assets/number_8-ezgif.com-video-to-gif-converter (1).gif" alt=""><figcaption><p>Model Engine Block</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crate-engine-mode/model-engine --- # 🌻 Vanilla Block ## Vanilla Block Engine This is the default engine for a crate, and it's the simplest option. With this engine, you can select a specific block to act as your crate block. <figure><img src="../../.gitbook/assets/Screenshot 2024-10-06 155339 (1).png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Crate Blocks For the vanilla crate block, you can set any block available in Minecraft. Certain blocks, like chests, ender chests, shulker boxes, and trapped chests, will also include their default vanilla opening animations. <figure><img src="../../.gitbook/assets/Screenshot 2025-01-10 161949.png" alt=""><figcaption><p>Select a Vanilla Block</p></figcaption></figure> If you can't find the block you are looking for in the Selection menu, you can specify it in the crate's config manually. ## Player Heads When you select Player Head as the crate material type, you can specify a value for the head to replicate. <figure><img src="../../.gitbook/assets/image (24).png" alt="" width="521"><figcaption><p>Chat input for the Player Head</p></figcaption></figure> ### Getting the Head Value If you are using Paper, hold the player head in your main hand and run the **/paper dumpitem** command. This will return the value of the skull, which you can then use as the value for the crate. <figure><img src="../../.gitbook/assets/image (26).png" alt=""><figcaption><p>Player Head Value</p></figcaption></figure> ### In-Game Preview The following is an example of using TNT as the vanilla block crate type. <figure><img src="../../.gitbook/assets/image (29).png" alt="" width="563"><figcaption><p>Vanilla Crate Block</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crate-engine-mode/vanilla-block --- # 🌺 Vanilla Model ## Vanilla Model Engine With the Vanilla model, you can assign custom model data to your material, allowing you to use a custom model for your crate. However, due to the limitations of this engine, it cannot display animations. The crate will only appear in its static form. <figure><img src="../../.gitbook/assets/editor/crates/crate-block-engine.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> When you right-click this option, a menu will appear where you can set the material and custom model data for the item. To easily check the material and custom model data of an item (if you're using Paper), the best way is to use the **/paper dumpitem** command while holding the item in your main hand. ## Material The material is the vanilla item your model is applied to, and it is the item the crate is displayed as. Your resource pack applies the model to a specific material, so this has to be set to that same one, otherwise the custom data below has nothing to resolve against. <figure><img src="../../.gitbook/assets/editor/engine/material.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ## Custom Data The custom data is the value that points to the model inside your resource pack. Typing a number sets the Custom Model Data of the material, which is how custom models are selected on every supported version. <figure><img src="../../.gitbook/assets/editor/engine/custom-data.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> On 1.21.4 and newer, the same option also accepts an Item Model instead, described in the **Item Model (1.21.4+)** section further down. ## Scale The scale is a size multiplier for the model, where 1.0 is the model's normal size. <figure><img src="../../.gitbook/assets/editor/engine/scale.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> ## Position and Rotation If your model isn't positioned correctly, don't worry. You can adjust it using the "offset" and "rotation degrees" options. These allow you to fine-tune the position and orientation of the model to ensure it displays perfectly. <figure><img src="../../.gitbook/assets/editor/engine/rotation-degrees.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Engine</p></figcaption></figure> Each axis has its own offset, so the model can be moved on all three of them. ## Item Model (1.21.4+) On servers running 1.21.4 or newer, the "Custom Data" option also accepts an Item Model value as an alternative to Custom Model Data. Typing a number is treated as Custom Model Data, while typing a namespaced key (e.g. `minecraft:example`) is treated as an Item Model. Only one of the two can be set at a time, setting one automatically clears the other. ### In-Game Preview The following is an example of using the [Water Elemental](https://www.myphoenixstore.com/en/items/elemental-model-pack) crate model. <figure><img src="../../.gitbook/assets/image (30).png" alt="" width="526"><figcaption><p>Vanilla Model Block</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crate-engine-mode/vanilla-model --- # 📦 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. 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 --- # 🖌️ 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> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates/edit-crate --- # 🔓 Extra Options ## 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> In-game, each axis of both offsets has its own option inside [Display Settings](../animations/opening-animations/README.md#display-settings). ## 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/extra-options --- # 💬 Hologram ## Hologram Every crate can show a hologram floating above it. Phoenix Crates has its own built-in hologram system, so it does not depend on any external plugins, and everything about it belongs to the crate itself, which means two crates can look completely different. <figure><img src="../../.gitbook/assets/editor/crate/hologram.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Hologram Lines The lines are the text shown above the crate. Clicking them opens a menu with every line at once, where you can write, reorder and remove them together, then confirm to apply them all. Alongside PlaceholderAPI placeholders, the lines understand `%name%` for the crate's display name, `%cooldown%` for the player's remaining open cooldown, and `%virtual_keys%` for how many virtual keys they hold for this crate. <figure><img src="../../.gitbook/assets/editor/crate/hologram-lines.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Hologram Offset The offset is the height of the hologram above the crate. <figure><img src="../../.gitbook/assets/editor/crate/hologram-offset.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> > **Info:** Turning on the [Preview Reward](README.md#preview-reward) raises the hologram by 0.75 blocks so the two do not overlap, which this offset can bring back down. ## Line Gap The line gap is the vertical space between two lines. A smaller value packs the lines closer together. <figure><img src="../../.gitbook/assets/editor/crate/line-gap.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Hologram Scale The scale is the size of the text, where 1.0 is the normal size. <figure><img src="../../.gitbook/assets/editor/crate/hologram-scale.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Text Opacity The opacity decides how solid the text is, from 0 (invisible) to 255 (solid). <figure><img src="../../.gitbook/assets/editor/crate/text-opacity.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Billboard The billboard decides how the hologram rotates to face the player. | Mode | Behaviour | | ---------- | --------------------------------------------------------------------- | | Center | Follows the player on every axis. This is the default. | | Vertical | Follows the player sideways only, staying upright. | | Horizontal | Follows the player up and down only. | | Fixed | Never rotates, always facing the direction it was placed in. | <figure><img src="../../.gitbook/assets/editor/crate/billboard.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## See Through When enabled, the hologram stays visible through blocks. <figure><img src="../../.gitbook/assets/editor/crate/see-through.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Text Shadow Decides whether the text is drawn with a drop shadow behind it. <figure><img src="../../.gitbook/assets/editor/crate/text-shadow.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> ## Background Color The color behind the text. An alpha of 0 removes the background entirely. <figure><img src="../../.gitbook/assets/editor/crate/background-color.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Hologram</p></figcaption></figure> The value accepts any of these: | Format | Example | Notes | | ----------- | ----------- | -------------------------------- | | `A,R,G,B` | `128,0,0,0` | Half transparent black. | | `#AARRGGBB` | `#80000000` | Hex with alpha. | | `#RRGGBB` | `#000000` | Hex without alpha, fully opaque. | A value that cannot be read falls back to 25% black rather than to transparent, so a background that unexpectedly shows up usually means a typo here. > **Info:** Every option on this page applies to all placed crates of that type immediately, with no reload. > **Info:** The style options used to live in `templates.yml` and were shared by every crate. Updating the plugin copies that file's values into all of your crates and then removes it, so your holograms keep the look they had. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates/hologram --- # ⛓️ Link Keys ## Link Keys This option allows you to link the key to the crates you want it to be able to open. <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 ⭐ Lets a crate that needs a key also be opened by paying its open cost, described on [Misc Options](misc-options.md#key-skips-cost). <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> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates/link-keys --- # 💥 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 With this option, you can set a specific amount required for users to open a crate. If the value is set to 0, this option is disabled. <figure><img src="../../.gitbook/assets/editor/crates/open-cost-engine.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate</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> ## 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. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates/misc-options --- # 💸 Open Money Cost ## Open Money Cost Open Money Cost is an alternative way for players to open crates without needing a key. If you want to use the open money cost alone, make sure to disable the key requirement. The plugin currently supports 8 methods for the open money cost, these are the following: | Engine | Requires | Plan | | ------ | -------- | ---- | | None | Nothing, this is the default and means the cost is disabled | Lite | | XP | Nothing, it uses the player's experience levels | Lite | | Vault | [Vault](https://www.spigotmc.org/resources/vault.34315/) and an economy plugin | Lite | | PlayerPoints | [PlayerPoints](https://modrinth.com/plugin/playerpoints) | Premium | | VotingPlugin | [VotingPlugin](https://www.spigotmc.org/resources/votingplugin.15358/) | Premium | | ExcellentEconomy | [ExcellentEconomy](https://www.spigotmc.org/resources/excellenteconomy.106334/) | Premium | | Placeholder | [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) | Premium | | PhoenixCurrencies | PhoenixCurrencies | Premium | An engine whose plugin is not installed cannot be selected. For ExcellentEconomy and PhoenixCurrencies, right-click the engine to also pick which of that plugin's currencies is charged. When a crate needs no key and the [Mass Opening](../../add-ons/mass-opening/README.md#paying-with-money) add-on is enabled for it, players can open it several times at once and pay the cost once per opening. ### Placeholder Currency The Placeholder engine turns any balance exposed through PlaceholderAPI into a crate cost, for example tokens or gems from another plugin. Select the Placeholder engine on the crate's open cost and right-click it to set the cost amount and the currency. The currency is shared by every crate that uses the Placeholder engine: * **Balance Placeholder** returns the player's balance. Commas are ignored and `k`, `m`, `b`, `t` suffixes are read, so `1.5k` counts as 1500. * **Withdraw Command** runs from the console to take the cost. `%player%`, `%amount%` and `%amount_int%` (rounded up) are filled in. * **Display Name** is shown after the amount, as in `250 Tokens`. * **Whole Numbers** rounds every cost up to a whole number. > **Warning:** The plugin cannot tell whether the withdraw command worked. Test it once on a player with a known balance. Fill in both fields before using the engine. Without a balance placeholder no player can afford the crate, and without a withdraw command it opens without taking anything. ### Whole Numbers and Decimals Not every engine can charge a fraction: * **Vault**, **ExcellentEconomy** and **PhoenixCurrencies** accept decimal amounts, so `19.99` works. * **XP**, **PlayerPoints** and **VotingPlugin** are whole numbers only. A decimal is cut down to the whole number below it, so `2.9` charges `2`. ExcellentEconomy and PhoenixCurrencies decide this per currency, so a currency without decimals behaves like the second group. Placeholder follows its Whole Numbers setting. ### Confirmation Before the cost is taken the player gets a confirmation menu showing what they are about to pay. That menu can be turned off server-wide with **Disable Confirmation Menus** in the editor's Settings, which sends players straight to the opening. <figure><img src="../../.gitbook/assets/editor/crates/open-cost-engine.png" alt=""><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/crates/open-money-cost --- # 🔑 Keys Keys have their own category in the in-game editor, next to crates and rewards. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp26-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Editor > Keys</p></figcaption></figure> Key settings that live on the crate or reward side are documented there: [Key Priority](../crates/README.md#key-priority), [Link Keys](../crates/README.md#link-a-key) and the [Key Requirement](../rewards-mode/README.md#key-requirement) of selective rewards. ## Edit Key ### Identifier The unique ID the plugin uses internally. It is not the name players see. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204922.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> > **Danger:** Changing the identifier disconnects every player's progress tied to the key. ### Display Name The name shown in messages when a crate is opened. Supports Minecraft color codes and hex colors in the `&#D6D045` format. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 205030.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Key Item The item used as the key, a Tripwire Hook by default. Drop any item on it to copy its material, name and lore. Keys players already hold keep working after the item is changed; only a new identifier breaks them. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp27-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Glowing Key Adds the enchantment glint by applying an enchantment with the hide enchantments flag. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204540.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Virtual Key Stores the key on the player instead of as an item, so it cannot be duplicated. When enabled, physical copies of the key stop working. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204400.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Guarantee Rarity Reward 💎 Assigns rarities to the key so every opening with it gives a reward from one of them. Needs the [Rarity](https://www.phoenixplugins.com/product/rarities-addon) add-on. <figure><img src="../../.gitbook/assets/editor/keys/key_rarity.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Misc Options ### Enabled A disabled key stays on the server but cannot be given or used. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 210759.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Delete Key Deletes the key after a confirmation menu. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 210623.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> > **Danger:** Deleted keys cannot be restored. ## Link Crates Choose which crates this key opens. The same link can be made from the crate side with [Link Keys](../crates/README.md#link-keys). <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 211810.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ### Link a Crate <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp48-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Editor > Keys > Key > Link Crates</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/keys --- # 🎨 Edit Key ## Identifier With this option, you can set an identifier for the key. Note that the key identifier is unique and used internally by the plugin, and its different from the display name. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204922.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> > **Danger:** If the identifier is changed, all player progress associated with the key will no longer work. ## Display Name With this option, you can adjust the display name of the key. The display name is typically shown in the 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/Screenshot 2025-06-30 205030.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Key Item With this option, you can customize the key for your crate. By default, it is a Tripwire Hook. You can drag and drop the item you want to use, and it will automatically copy its name and lore. If you change the material of the crate while players already have the key, they will still be able to use the previous material. The key will only break if you change the crate identifier. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp27-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Glowing Key With this feature, you can make your key have a glowing effect. Note, that the plugin adds an enchantments and the hide enchantments tag to the item. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204540.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Virtual Key Virtual keys provide a more secure method for using keys and prevent users from duplicating them on your server. By default, this feature is disabled. If enabled, the crate can only be opened with virtual keys, and physical keys will no longer be usable. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 204400.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Guarantee Rarity Reward 💎 With this option, you can assign multiple rarities to a key, guaranteeing that the player receives a reward from one of those rarities. :point\_right: [You can purchase this add-on on Phoenix Plugins](https://www.phoenixplugins.com/product/rarities-addon) <figure><img src="../../.gitbook/assets/editor/keys/key_rarity.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/keys/edit-key --- # ⛓️ Link Crates ## Link Crates This option allows you to link the key to the crates you want it to be able to open. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 211810.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Link a Crate With **Link a Crate**, you can specify which crates can be opened by that specific key. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp48-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Editor > Keys > Key > Link Crates</p></figcaption></figure> <!-- > **Info:** With the Pro Plan, you are allowed you to link more than 1 crates per key. --> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/keys/link-crates --- # 🛍️ Misc Options ## Enabled With this option, you can disable the key. The key will remain to the server, but it will no longer be accessible to obtain or use. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 210759.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> ## Delete Key This option allows you to permanently delete a key. Note that selecting it will first open a confirmation menu before the key is deleted. <figure><img src="../../.gitbook/assets/Screenshot 2025-06-30 210623.png" alt="" width="563"><figcaption><p>Editor > Keys > Key</p></figcaption></figure> > **Danger:** This option is permanent, and keys can't be restored. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/keys/misc-options --- # 📰 Reward Config Editing > **Danger:** If you copy and paste a reward, make sure to change its identifier, as it must be unique. ## Edit Rewards You can also edit the rewards through the configuration file if you prefer to manage everything manually. ## Format: The following option is the method you can use for vanilla items. \ **Note:** This option cannot be configured through the in-game editor, as the editor uses the bukkit format to also support custom properties and modded Items. ```yaml display-item: material: PAPER win-items: '0': material: PAPER ``` ## Material: Allows you to set a material on your item. > ```yaml > material: TEXT > ``` > > > **Supported material values:** > > > > * Vanilla (`DIAMOND`). > > * [HeadDatabase ](https://www.spigotmc.org/resources/head-database.14280)(`hdb:id`) > > * [ItemsAdder](https://www.spigotmc.org/resources/%E2%9C%A8itemsadder%E2%AD%90emotes-mobs-items-armors-hud-gui-emojis-blocks-wings-hats-liquids.73355) (`itemsadder:namespace:id`) > > * [Nexo](https://mcmodels.net/products/13172/nexo?srsltid=AfmBOoocUPY8FdXiOkDqM4Rml1Gs449TBz0x_FoKwJBgG8IYvkvMNJ2H) (`nexo:id`) > > * [Mythic Items](https://mythiccraft.io/index.php?ewr-porta) (`mythicitem:id`) > > * [MMOItems](https://www.spigotmc.org/resources/%EF%B8%8F%E2%9A%94%EF%B8%8F-mmoitems-%E2%9A%94%EF%B8%8F-items-weapons-armor-sets-tiers-editor-gui-skills.39267) (`mmoitem:type:id` ) > > * [ExecutableItems](https://www.spigotmc.org/resources/%E2%9A%94%EF%B8%8Fexecutableitems-%E2%AD%90-customize-all-items-add-abilities-%E2%AD%90-ai-items-generation-on-the-discord-%E2%9C%85.83070) (`executableitem:id`) > > * [CraftEngine](https://modrinth.com/plugin/craftengine) (`craftengine:id`) > > > > > - [Materials Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/Material.html) > **Info:** For hooked items (ItemsAdder, Nexo, MMOItems, ExecutableItems, CraftEngine, etc.), the `id` is the custom item's own identifier as registered in that plugin. ## Hooked Materials A hooked material is the hook name, a colon, then the id the other plugin knows the item by. Only the first colon separates the two, so everything after it reaches that plugin exactly as written. > **Danger:** The separator is a colon, never a dash. `itemsadder-medieval_crates-crate_key` is read as a plain material name, matches none, and is reported as an unknown material in the console. The hook is never reached. The same value written with colons resolves. | Hook | Value | Example | | --------------- | ------------------------ | ------------------------------------ | | ItemsAdder | `itemsadder:namespace:id`| `itemsadder:medieval_crates:crate_key` | | MMOItems | `mmoitem:type:id` | `mmoitem:SWORD:cutlass` | | Nexo | `nexo:id` | `nexo:ruby_sword` | | CraftEngine | `craftengine:id` | `craftengine:default:ruby_sword` | | Mythic Items | `mythicitem:id` | `mythicitem:excalibur` | | ExecutableItems | `executableitem:id` | `executableitem:magic_wand` | | HeadDatabase | `hdb:id` | `hdb:1234` | ItemsAdder and MMOItems ids are built from two parts of their own, so those values have three parts in total. `itemsadder:crate_key` sends only `crate_key` to ItemsAdder and resolves to nothing, and an MMOItems value with no type is rejected. For the rest, pass the id exactly as the plugin registers it, namespace included where it has one. > ```yaml > material: itemsadder:medieval_crates:crate_key > ``` The same values work in every `material` field of the plugin, the [menus](../configurations/customize-menus.md#item-material) included. > **Info:** When the hook name is valid but the plugin is not installed, or the id resolves to nothing, the item becomes a placeholder rather than the crate failing to load. On a reward it names the hook in its lore, in a menu it is a barrier. ## Display Name Allows you to set a display name on your item. > ```yaml > display-name: '&eExample Reward' > ``` > **Success:** This option also supports [MiniMessage](https://docs.advntr.dev/minimessage/format) Format. ## Lore: Allows you to set a custom lore on your item. > ```yaml > lore: > - '&cLine 1' > - '&eLine 2' > - '&aLine 3' > ``` > **Success:** This option also supports [MiniMessage](https://docs.advntr.dev/minimessage/format) Format. ## Model Data: Allows you to set custom model data on your item. > ```yaml > model-data: 1000 > ``` ## Item Model: Allows you to set a custom [Item Model](https://minecraft.wiki/w/Items_model_definition) (the modern resource-pack item model component) on your item. > ```yaml > item-model: 'minecraft:custom_paper' > ``` > **Warning:** This option requires the resource pack to actually define the referenced item model. If the model doesn't exist, the item will simply render with its base material's texture. ## Amount: Allows you to set a fixed stack size on your item. > ```yaml > amount: 1 > ``` ## Enchants: Allows you to set enchants on your item. > ```yaml > enchants: > - 'PROTECTION:1' > - 'UNBREAKING:1' > ``` > > > * [Enchantsments Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/enchantments/Enchantment.html) ## Item Flags: Allows you to set item flags on your item, to hide certain tooltip sections (enchants, attributes, "unbreakable", etc). > ```yaml > flags: > - 'HIDE_ENCHANTS' > ``` > > > * [Item Flags Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/inventory/ItemFlag.html) ## Tooltip Style: Allows you to set a custom tooltip style/texture (resource-pack defined) for the item's tooltip box. > ```yaml > tooltip-style: 'minecraft:gui/sprites/widget/inventory_tooltip' > ``` > **Warning:** Requires server version **1.21.2+**. On older server versions this option is ignored. ## Enchantment Glint Override: Allows you to force the enchantment glint (the shimmering/glowing effect) on or off, independently of whether the item is actually enchanted. > ```yaml > enchantment-glint-override: true # Boolean (`true`/`false`) > ``` > **Warning:** Requires server version **1.20.5+**. On older server versions this option is ignored. ## Banner Meta: Allows you to add banner patterns to your item. Works on banners, and on shields (and other blocks that carry banner data). > ```yaml > banner-meta: > - 'RED;STRIPE_BOTTOM' > - 'WHITE;CROSS' > ``` > > > * Each entry follows the format `<DyeColor>;<PatternType>`. > > * [DyeColor Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/DyeColor.html) / [PatternType Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/block/banner/PatternType.html) ## Armor Trim (Material & Pattern): Allows you to apply an armor trim to your item, by setting both the trim material and the trim pattern. > ```yaml > trim-material: IRON > trim-pattern: DUNE > ``` > > > * Both options must be set together. > > * [Armor Trim Materials](https://minecraft.wiki/w/Smithing#Trim_materials) / [Armor Trim Patterns](https://minecraft.wiki/w/Smithing#Trim_patterns) > **Warning:** Requires server version **1.20+**. On older server versions this option is ignored. ## Potion Effects: Allows you to add custom potion effects to a potion item. > ```yaml > potion-effects: > - 'speed;1200;1' > - 'regeneration;600;0' > ``` > > > * Each entry follows the format `<PotionEffectType>;<duration in ticks>;<amplifier>`. > > * [Potion Effect Types Link](https://hub.spigotmc.org/javadocs/bukkit/org/bukkit/potion/PotionEffectType.html) ## RGB: Allows you to set a custom color on your item, using raw RGB values. > ```yaml > rgb: '38, 192, 210' > ``` > > > * Format: `R, G, B` (each `0`-`255`). Applies to leather armor, potions, maps and firework effects. ### Item Config Example The following is an example of a reward with its display item and the actual reward. ```yaml '2': identifier: reward_1759509999284 display-item: material: PAPER # Legacy colors support display-name: '&#C00BD6Paper' lore: - '&cCustom Paper Item' model-data: 1000 enchants: - 'PROTECTION:1' flags: - 'HIDE_ENCHANTS' win-items: '0': material: PAPER # Mini Message Support display-name: '<gradient:#C00BD6:#FD2177>Paper</gradient>' lore: - '<gradient:#C00BD6:#FD2177>Custom Paper Item</gradient>' model-data: 1000 enchants: - 'PROTECTION:1' flags: - 'HIDE_ENCHANTS' ``` Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/reward-config-editing --- # 🏆 Rewards Each reward's own settings are on [Edit Reward](edit-reward.md), [Win Items & Win Commands](win-items-and-commands.md) and [Cooldowns](cooldowns.md). ## Reward Modes The rewards mode decides how players get a reward: [Random](../rewards-mode/README.md#random) draws one by chance, [Selective](../rewards-mode/README.md#selective-non-rng) lets the player pick it. <figure><img src="../../.gitbook/assets/editor/crates/rewards.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate</p></figcaption></figure> ## Add Rewards ### Add a Reward Click the stained glass to add a reward to the crate. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-24 200822.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate > Rewards</p></figcaption></figure> #### In-Game Example Example of adding a reward. <figure><img src="../../.gitbook/assets/number_16-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Diamond Set Example as a Reward</p></figcaption></figure> ### Add Multiple Rewards ⭐ If you don’t want the hassle of adding multiple rewards to your crate one by one, you can shift left click on the glass to quickly add multiple rewards with just a few clicks. Example of adding multiple rewards: <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp80-ezgif.com-video-to-gif-converter (1).gif" alt="" width="563"><figcaption><p>Multiple Rewards Example as Rewards</p></figcaption></figure> > **Info:** This feature is only available with the Premium Plan. ### Reordering You can use the reordering option to sort the rewards in your desired order for the crate's preview menu. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp81-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Reordering Rewards</p></figcaption></figure> ### Max Win Rewards > **Warning:** This features is only available to the Random Rewards Mode. With Max Win Rewards, you can specify how many rewards a user can win by opening a single crate. The minimum number of rewards a user can receive is 1, and the maximum is 5. <figure><img src="../../.gitbook/assets/Screenshot 2025-01-10 212238.png" alt="" width="563"><figcaption><p>Max Win Rewards</p></figcaption></figure> > **Info:** With the Plan, you are allowed to use up to 30 Max Win Rewards. ## Alternative Reward > **Info:** You can't use this feature with the selective reward mode. If a user has previously won a reward with a limit, you can provide an alternative reward instead. This is a great option to ensure users receive a different item if they have already won the original one. <figure><img src="../../.gitbook/assets/editor/reward/alternative-reward.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> This option will only work if it is enabled, so make sure to enable it. ### Customize the Reward An alternative reward works similarly to a normal reward but is only given when the main reward has already been won. By default, the alternative reward is a diamond pickaxe, which will be displayed as the alternative reward if the main item is won. If you don’t want to award the diamond pickaxe, set "Virtual Item" to true. This will make it function only as a display item in the crate while still running the associated commands. <figure><img src="../../.gitbook/assets/editor/reward/alternative-item.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Customize the Item In the editor, you can drag and drop the item you want to assign as a reward. Alternatively, you can edit its display name and lore by left-clicking on the item. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp84-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Example of Customizing an Item</p></figcaption></figure> ### Win Commands & Broadcast Just like a normal reward, an alternative reward has its own Win Commands menu to run commands when it's given, and its own Broadcast toggle to announce it to the server when a player receives it. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards --- # 📦 Add Rewards ## Add a Reward To add a reward to your crate, simply click on the stained glass and create your reward! <figure><img src="../../.gitbook/assets/Screenshot 2025-05-24 200822.png" alt="" width="563"><figcaption><p>Editor > Crates > Crate > Rewards</p></figcaption></figure> ### In-Game Example Example of adding a reward. <figure><img src="../../.gitbook/assets/number_16-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Diamond Set Example as a Reward</p></figcaption></figure> ## Add Multiple Rewards ⭐ If you don’t want the hassle of adding multiple rewards to your crate one by one, you can shift left click on the glass to quickly add multiple rewards with just a few clicks. Example of adding multiple rewards: <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp80-ezgif.com-video-to-gif-converter (1).gif" alt="" width="563"><figcaption><p>Multiple Rewards Example as Rewards</p></figcaption></figure> > **Info:** This feature is only available with the Premium Plan. ## Reordering You can use the reordering option to sort the rewards in your desired order for the crate's preview menu. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp81-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Reordering Rewards</p></figcaption></figure> ## Max Win Rewards > **Warning:** This features is only available to the Random Rewards Mode. With Max Win Rewards, you can specify how many rewards a user can win by opening a single crate. The minimum number of rewards a user can receive is 1, and the maximum is 5. <figure><img src="../../.gitbook/assets/Screenshot 2025-01-10 212238.png" alt="" width="563"><figcaption><p>Max Win Rewards</p></figcaption></figure> > **Info:** With the Plan, you are allowed to use up to 30 Max Win Rewards. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards/add-rewards --- # 🗃️ Alternative Reward > **Info:** You can't use this feature with the selective reward mode. ## Alternative Reward If a user has previously won a reward with a limit, you can provide an alternative reward instead. This is a great option to ensure users receive a different item if they have already won the original one. <figure><img src="../../.gitbook/assets/editor/reward/alternative-reward.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> This option will only work if it is enabled, so make sure to enable it. ## Customize the Reward An alternative reward works similarly to a normal reward but is only given when the main reward has already been won. By default, the alternative reward is a diamond pickaxe, which will be displayed as the alternative reward if the main item is won. If you don’t want to award the diamond pickaxe, set "Virtual Item" to true. This will make it function only as a display item in the crate while still running the associated commands. <figure><img src="../../.gitbook/assets/editor/reward/alternative-item.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Customize the Item In the editor, you can drag and drop the item you want to assign as a reward. Alternatively, you can edit its display name and lore by left-clicking on the item. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp84-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Example of Customizing an Item</p></figcaption></figure> ## Win Commands & Broadcast Just like a normal reward, an alternative reward has its own Win Commands menu to run commands when it's given, and its own Broadcast toggle to announce it to the server when a player receives it. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards/alternative-reward --- # ⏳ Cooldowns ## Cooldowns A reward can be put on a cooldown so it is not won again straight away, either by the same player or by anyone on the server. All of it lives in the reward's Cooldowns menu. <figure><img src="../../.gitbook/assets/editor/reward/cooldowns.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Win Limit Cooldown How long a player must wait before being able to win this reward again. It works together with the [Win Limit](edit-reward.md#win-limits): once a player reaches their limit, this is how long it takes before their count is freed again. <figure><img src="../../.gitbook/assets/editor/reward-cooldowns/win-limit-cooldown.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Cooldowns</p></figcaption></figure> ## Global Win Limit Cooldown The same thing for the whole server: how long must pass before this reward can be won again by anyone, once the [Global Win Limit](edit-reward.md#win-limits) has been reached. <figure><img src="../../.gitbook/assets/editor/reward-cooldowns/global-win-limit-cooldown.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Cooldowns</p></figcaption></figure> ## Time Limited Cooldown How long this reward stays available once its cooldown is started. When it expires, the reward automatically disables itself, which makes it the option to use for a reward that should only exist for a weekend or an event. <figure><img src="../../.gitbook/assets/editor/reward-cooldowns/time-limited-cooldown.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Cooldowns</p></figcaption></figure> ## Cooldown Duration Each of the three opens the same duration menu. ### Units The time is built up from its own units, so a cooldown of a day and a half is set as days and hours rather than counted in seconds. <figure><img src="../../.gitbook/assets/editor/cooldown-duration/minutes.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Cooldowns > Duration</p></figcaption></figure> ### Disable Cooldown The same menu is where a cooldown is switched off again, which sets it back to disabled. <figure><img src="../../.gitbook/assets/editor/cooldown-duration/disable-cooldown.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Cooldowns > Duration</p></figcaption></figure> > **Info:** In the crate file the three are stored in seconds under `cooldowns`, described in [Reward Config Editing](../../configurations/reward-config-editing.md#reward-options). Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards/cooldowns --- # ✏️ Edit Reward ## Weight On a crate using the [Random](../rewards-mode/README.md#random) rewards mode, the weight is what decides how likely this reward is compared to the others in the crate. A higher weight means a bigger share of the openings. <figure><img src="../../.gitbook/assets/editor/reward/weight.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Win Limits A reward can be limited so it is not won endlessly. Both limits can be combined with an [Alternative Reward](README.md#alternative-reward), which is given once the limit is reached. ### Win Limit How many times a single player can win this reward. Every player has their own count. <figure><img src="../../.gitbook/assets/editor/reward/win-limit.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Global Win Limit How many times this reward can be won by everyone on the server combined, which is what makes a reward a one-off across the whole server. <figure><img src="../../.gitbook/assets/editor/reward/global-win-limit.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Cooldowns A reward can be put on a cooldown so it is not won again straight away, by the same player or by anyone on the server. It has its own page: [Cooldowns](cooldowns.md). ## Guaranteed Win A reward can be guaranteed after, or every, a number of openings. The mode and the opening count are set here, and the whole system is described on [Guaranteed Rewards](../../features/guaranteed-rewards.md). <figure><img src="../../.gitbook/assets/editor/reward/guaranteed-win.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Required Keys On a crate using the [Selective (non RNG)](../rewards-mode/README.md#selective-non-rng) rewards mode, players spend keys to redeem the reward they picked. **Key Requirement** sets how many keys this particular reward costs, and defaults to `1`. Use it to price rewards against each other, so a cosmetic costs one key while the best reward in the crate costs five. A player without enough keys is told how many they need and the reward stays unredeemed. The value is exposed to the menus as `%required_keys%`, so the preview can show the price on each reward. <figure><img src="../../.gitbook/assets/editor/reward/key-requirement.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> > **Info:** With the [Rarity](../../add-ons/rarity/) add-on installed, a rarity's own Required Keys value takes over for every reward carrying that rarity, and this setting is ignored. Required Keys does not apply in Random mode, where the crate's own key cost is what matters. ## Requirements The permissions that decide who can win the reward live in their own menu on the reward. <figure><img src="../../.gitbook/assets/editor/reward/requirements.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Required Permission The permission a player must have for this reward to be available to them. If the player lacks it, the reward appears as locked in the preview. This is the opposite of [Restricted Permissions](#restrict-a-reward), which instead prevents players who have the listed permissions from winning it. <figure><img src="../../.gitbook/assets/editor/reward-requirement/required-permission.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Requirements</p></figcaption></figure> ## Win Items & Win Commands What the reward actually gives, whether that is real items, commands, or both, has its own page: [Win Items & Win Commands](win-items-and-commands.md). ## Win Actions The actions run when this reward is won, such as a sound or a title. They replace the win actions of the rarity, the crate and the global settings, as described on [Event Actions](../crates/README.md#event-actions). <figure><img src="../../.gitbook/assets/editor/reward/win-actions.png" alt="" width="563"><figcaption><p>Reward (Win Actions)</p></figcaption></figure> ## Win Message Whether the winner is told they won this reward, and where that message shows up, are two options next to each other. ### Allow Win Message Decides whether the player gets a message at all when they win this specific reward. <figure><img src="../../.gitbook/assets/editor/reward/allow-win-message.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Notification Type Picks where that message is delivered, in the chat or on the action bar. <figure><img src="../../.gitbook/assets/editor/reward/notification-type.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Share with Players Online With this option, when a user wins a specific item, all online players on the server will also receive the same reward. <figure><img src="../../.gitbook/assets/editor/reward/share-with-players-online.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Restrict a Reward This option prevents users from winning the reward if they have any of the specified permissions on the reward. <figure><img src="../../.gitbook/assets/editor/reward-requirement/restricted-permissions.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Requirements</p></figcaption></figure> If a user is assigned to a listed permission, such as `group.default`, they won’t be able to win this reward. Since they won’t have access to it, you can use the [Alternative Reward](README.md#alternative-reward) to give them a different item instead. This option is especially useful for situations where a user already owns a cosmetic item, such as tags, chat colors, prefixes, or other cosmetics. ## Broadcast a Reward To broadcast a message to all online players when a user wins a specific reward, simply enable the Broadcast Message feature. By default this feature is not activated. <figure><img src="../../.gitbook/assets/editor/reward/broadcast-message.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> To modify the broadcast message, you can do so in the main crate settings. ## Display Item With this option, you can customize the material, display name, and lore. Note that this is the display item and will not be given to the user. ### Display Name The name the item carries in the preview, which is also the name used when the reward is announced. <figure><img src="../../.gitbook/assets/editor/reward/display-name.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Display Lore The lore shown under the name, useful for describing what a virtual reward actually gives. <figure><img src="../../.gitbook/assets/editor/reward/display-lore.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> Right-clicking the display item (or any win item in the Win Items menu) gives you a physical copy of it, useful if you want to grab the exact item you configured. An Item Properties sub-menu also lets you fine-tune the display item further: RGB color, item flags, banner patterns, enchantments, custom model data/item model, enchantment glint override, potion effects, armor trim, and tooltip style. ## Reward Identifier With this option, you can set a unique identifier for the reward. By default, the plugin automatically assigns a unique identifier to each reward. Changing this identifier will result in data loss. <figure><img src="../../.gitbook/assets/editor/reward/change-identifier.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> > **Danger:** If the identifier is changed, the player progress will get deleted. ## Enabled With this option, you can disable a single reward. It stays configured on the crate but can no longer be won or picked. <figure><img src="../../.gitbook/assets/editor/reward/enabled.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## Delete Reward With this option, you can delete the reward from your crate. <figure><img src="../../.gitbook/assets/editor/reward/delete-reward.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> > **Danger:** This option is permanent, and rewards can't be restored. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards/edit-reward --- # 🏅 Rewards Mode The rewards mode decides how players get a reward from the crate: [Random](#random) draws one by chance, [Selective (non RNG)](#selective-non-rng) lets the player pick it. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-18 193753.png" alt=""><figcaption><p>Rewards Editor (Reward Mode)</p></figcaption></figure> ## Random In this mode, users receive a reward randomly, based on the weight (chance) assigned to each item. ### Percentage With percentage, you can set the chance of a user receiving a specific reward. The system calculates the percentage of each item based on the total number of items. For example, if you have 2 items, each set to 100%, the system treats them as 50% each. The minimum percentage allowed is 0.05%, and there is no maximum limit. (The default percentage for a reward is 100%). <figure><img src="../../.gitbook/assets/editor/reward/weight.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### In-Game Preview The player uses a key to open the crate and receives a random reward. <figure><img src="../../.gitbook/assets/normal_1-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Normal Crate</p></figcaption></figure> ## Selective (non RNG) With Selective Mode, it's an ethical way to monetize your server because it removes the RNG from crates. Players are able to select the reward they want based on the number of keys required for that reward. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-18 193929.png" alt=""><figcaption><p>Rewards Editor (Selective Mode)</p></figcaption></figure> > **Danger:** Selective mode does not support the reroll, alternative rewards or guaranteed rewards features. ### Key Requirement With Key Requirements, you can specify the number of keys a user must have to redeem a specific reward. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-24 195930.png" alt="" width="563"><figcaption><p>Reward Editor (Selective Mode)</p></figcaption></figure> ### In-Game Preview The player uses a key to open the crate and receives their selected reward. <figure><img src="../../.gitbook/assets/number_2-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Normal Crate (old)</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards-mode --- # 🎁 Random ## Random Mode In this mode, users receive a reward randomly, based on the weight (chance) assigned to each item. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-18 193753.png" alt=""><figcaption><p>Rewards Editor (Reward Mode)</p></figcaption></figure> ## Percentage With percentage, you can set the chance of a user receiving a specific reward. The system calculates the percentage of each item based on the total number of items. For example, if you have 2 items, each set to 100%, the system treats them as 50% each. The minimum percentage allowed is 0.05%, and there is no maximum limit. (The default percentage for a reward is 100%). <figure><img src="../../.gitbook/assets/editor/reward/weight.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ## In-Game Preview: The player uses a key to open the crate and receives a random reward. <figure><img src="../../.gitbook/assets/normal_1-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Normal Crate</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards-mode/random --- # 📬 Selective (non RNG) ## Selective Rewards Mode: With Selective Mode, it's an ethical way to monetize your server because it removes the RNG from crates. Players are able to select the reward they want based on the number of keys required for that reward. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-18 193929.png" alt=""><figcaption><p>Rewards Editor (Selective Mode)</p></figcaption></figure> > **Danger:** Selective mode does not support the reroll, alternative rewards or guaranteed rewards features. ## Key Requirement With Key Requirements, you can specify the number of keys a user must have to redeem a specific reward. <figure><img src="../../.gitbook/assets/Screenshot 2025-05-24 195930.png" alt="" width="563"><figcaption><p>Reward Editor (Selective Mode)</p></figcaption></figure> ## In-Game Preview: The player uses a key to open the crate and receives their selected reward. <figure><img src="../../.gitbook/assets/number_2-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Normal Crate (old)</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards-mode/selective-non-rng --- # 🎒 Win Items & Win Commands ## Physical Reward A physical reward is one that hands the player real items. Those items are the **Win Items**, and a reward can hold as many of them as you want. By default every item in the list is given. <figure><img src="../../.gitbook/assets/editor/reward/win-items.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Add Item Items are added by dropping them into the menu, exactly as they should reach the player, enchantments and custom names included. <figure><img src="../../.gitbook/assets/editor/edit-reward-items/add-item.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Win Items</p></figcaption></figure> ### Edit an Item Each item already in the list can be edited or removed from the same menu, and right-clicking it hands you a copy of it. <figure><img src="../../.gitbook/assets/editor/edit-reward-items/raw-iron.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Win Items</p></figcaption></figure> > **Info:** When a reward is created from an item, that same item is also added as a win item. If you only want it as the [display item](edit-reward.md#display-item), remove it from this list. ### Max Win Item Amount This limits how many of the items are handed out per win, and the ones given are picked at random from the list. That turns a single reward into a small loot pool, for example five items configured with only two of them given each time. Set it to infinite to always give the whole list. <figure><img src="../../.gitbook/assets/editor/edit-reward-items/max-win-item-amount.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Win Items</p></figcaption></figure> ## Virtual Reward A virtual reward gives nothing physical. It has no win items at all, only **Win Commands**, so the reward is whatever those commands do: a balance, a rank, a permission, a kit from another plugin. Set one up by removing every win item and adding the commands instead. The display item stays, so the reward still shows up in the preview like any other. <figure><img src="../../.gitbook/assets/editor/reward/win-commands.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward</p></figcaption></figure> ### Add Command When adding or editing a win-command, a dialog box will pop up asking you to type the command. On older server versions that don't support dialogs, it will fall back to the usual chat input. <figure><img src="../../.gitbook/assets/editor/edit-reward-commands/add-command.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Win Commands</p></figcaption></figure> ### In-Game Example Example of adding a reward that gives balance to the user. <figure><img src="../../.gitbook/assets/Untitledvideo-MadewithClipchamp82-ezgif.com-video-to-gif-converter.gif" alt="" width="563"><figcaption><p>Giving Balance as a Reward</p></figcaption></figure> ### Max Win Command Amount This works the same way as the item one: it caps how many commands of the list are executed per win, chosen at random, and infinite runs all of them. <figure><img src="../../.gitbook/assets/editor/edit-reward-commands/max-win-command-amount.png" alt="" width="375"><figcaption><p>Editor > Crates > Crate > Rewards > Reward > Win Commands</p></figcaption></figure> ## Mixing Both Nothing stops a reward from being both. A reward with win items and win commands gives the items and runs the commands on the same win, which is how a reward like a rank plus its physical kit is built. Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/rewards/win-items-and-commands --- # ⚙️ Settings ## Settings The Settings menu holds the options that apply to the whole plugin rather than to one crate. Everything here is also in [config.yml](../configurations/main-configuration.md), so changing it in-game and changing it in the file do the same thing. <figure><img src="../.gitbook/assets/editor/settings.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Crate Knockback The knockback a player takes when they try to open a crate with the wrong key, or without one. <figure><img src="../.gitbook/assets/editor/settings/crate-knockback.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Crate Quick Open Lets players open a crate straight from their hand, by holding its key and shift right-clicking the crate, without going through the usual opening. <figure><img src="../.gitbook/assets/editor/settings/crate-quick-open.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Key Mainhand Requirement Whether players need the key in their main hand to open a crate. Enabled by default, so a key sitting anywhere in the inventory is not enough. <figure><img src="../.gitbook/assets/editor/settings/key-mainhand-requirement.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Disable Confirmation Menus Skips the confirmation menus, such as the one shown before an [open money cost](crates/open-money-cost.md) is charged or before a selective reward is claimed, sending players straight to the action. <figure><img src="../.gitbook/assets/editor/settings/disable-confirmation-menus.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Crate Despawn Range The distance at which a crate stops being rendered for a player, holograms and effects included. A smaller range costs less on a busy server, a larger one keeps distant crates visible. <figure><img src="../.gitbook/assets/editor/settings/crate-despawn-range.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> ## Event Actions The actions every crate runs when an opening starts, when the rewards are given, when the opening ends and when a player is refused. A crate with its own actions for an event uses those instead, as described on [Misc Options](crates/README.md#event-actions). <figure><img src="../.gitbook/assets/editor/settings/event-actions.png" alt="" width="563"><figcaption><p>Settings (Event Actions)</p></figcaption></figure> ## Language The language the plugin runs in, described on [Languages & Translations](../configurations/languages.md). <figure><img src="../.gitbook/assets/editor/language.png" alt="" width="375"><figcaption><p>Editor > Settings</p></figcaption></figure> > **Info:** The settings that exist only in the file, such as the hologram refresh rate and the internal pool size, are listed in [Main Configuration](../configurations/main-configuration.md). Source: https://www.phoenixplugins.com/docs/phoenix-crates/main-features/settings --- # 🚢 Migration The plugin can import from these crate plugins: * **Excellent Crates** * **Crazy Crates** * **Custom Crate** * **Specialized Crate** * **AdvancedCrates** * **AquaticCrates** <figure><img src=".gitbook/assets/Screenshot%202025-10-05%20123938.png" alt=""><figcaption><p>Editor > Migrations</p></figcaption></figure> ## Limits * That we can only support the latest version of the plugins above. Migration cannot be done from an outdated versions. * We cannot guarantee that all the data from other crate plugins will migrate to ours, but reward items will certainly be migrated. * For AquaticCrates, only reward items are migrated due to the plugin’s very different structure. * A crate block that can't be used as a crate block, such as a block added in a newer Minecraft version, is skipped with a warning. That crate keeps the default block. ## Excellent Crates Imports keys, crates, rewards, placed crates and player data from Excellent Crates 6.0.1 or newer: virtual keys, openings, crate cooldowns and reward win counts. Only the Excellent Crates folder in your plugins folder is needed, the plugin itself does not have to be installed. Items saved in its encoded format are only copied exactly while nightcore is installed. <figure><img src=".gitbook/assets/editor/migrations/excellent-crates.png" alt="" width="563"><figcaption><p>Migrations (Migrate from Excellent Crates (6.0.1+))</p></figcaption></figure> Reward rarities have no equivalent here, so each reward's chance is folded into its own weight. Anything that could not be mapped, such as milestones or a key amount above 1 per opening, is listed in the report. ## Crazy Crates Imports keys, crates, rewards, placed crates and player data from Crazy Crates 4.0 or newer. As with Excellent Crates, only its plugin folder is needed. Menu crates are skipped, and crate types with no matching animation open with the default one. <figure><img src=".gitbook/assets/editor/migrations/crazy-crates.png" alt="" width="563"><figcaption><p>Migrations (Migrate from Crazy Crates (4.0+))</p></figcaption></figure> ## Preview and Apply Excellent Crates and Crazy Crates are imported in two steps, from **Editor > Migrations** or with /crates migrate \<source> \[confirm]. 1. **Preview** (left-click, or the command without `confirm`) reads everything and reports what would be imported, without changing anything. 2. **Apply** (right-click and confirm, or the command with `confirm`) backs up the whole PhoenixCrates folder and the player data first, then imports. Both steps print a summary in chat and write a full report to the migrations folder, listing every item that was renamed, skipped or not mapped. Backups go to the backups folder. * A crate or key whose id is already taken is imported as `<id>_imported`, and a reward as `<crate>_<reward>`. * Virtual keys are added to what players already have. * The Lite version imports up to 5 crates and 5 keys in total, counting the ones you already have. * Each source can be applied once. To run it again, delete its `.applied` file in the migrations folder. > **Warning:** Disable the old plugin after applying, so both plugins do not handle the same crate blocks. ## Phoenix Crates Migration Moving from the Lite version to the Premium version is automatic. The first time the Premium jar starts, it looks for a plugins/PhoenixCratesLite folder next to it and copies everything across into plugins/PhoenixCrates — your crates, keys, translations, templates and the player database, with nothing converted or dropped. <figure><img src=".gitbook/assets/image%20(67).png" alt=""><figcaption></figcaption></figure> ### Note * The copy only runs while plugins/PhoenixCrates does not exist yet. If the Premium jar has already been started once, the folder is there and the migration is skipped. Stop the server, delete or rename that folder, and start again. * Your old PhoenixCratesLite folder is left untouched. Remove the Lite jar afterwards so both versions are not running side by side. * The Lite version has no license, so after migrating you may need to fill in `product-license` in config.yml. See [🪪 Licensing](plugin-information/licensing.md). > **Warning:** If a PhoenixCratesPro folder is also present, it takes priority and the Lite folder is ignored. ## From MCModels <figure><img src=".gitbook/assets/Migrate Now (1).png" alt=""><figcaption></figcaption></figure> > **Info:** Only applies when purchasing the Premium version. Moving to PhoenixCrates from another crates plugin through the MCModels deal gives a 30% discount. Contact support and ask for the migration deal. We may ask you to fill in a short form about your previous plugin and why you are switching. * **Discord** - [Click Here](https://www.myphoenixstore.com/en/media/discord) * **Email** - support@myphoenixstore.com Source: https://www.phoenixplugins.com/docs/phoenix-crates/migration --- # 📥 Migration - McModels > **Info:** This is only applied when purchasing the premium version of the plugin. Hey there! Looking to migrate from another crates plugin to **PhoenixCrates** and get a 30% discount? Contact us through support and ask for the migration deal. We may ask you to complete a short form with a few questions about your previous plugin and your reasons for migrating.\ \ **Discord** - [Click Here](https://www.myphoenixstore.com/en/media/discord)\ **Email** - support@myphoenixstore.com ## Migration Our plugin offers migration support from other crate plugins to our own. Below are the available migration options. * **AquaticCrates** * **AdvancedCrates** * **Specialized Crate** * **Excellent Crates** * **Crazy Crates** * **Custom Crate** <figure><img src=".gitbook/assets/Screenshot 2025-10-05 123938.png" alt="" width="462"><figcaption><p>Editor > Migrations</p></figcaption></figure> ### Note * That we can only support the latest version of the plugins above. Migration cannot be done from an outdated versions. * We cannot guarantee that all the data from other crate plugins will migrate to ours, but reward items will certainly be migrated. * For AquaticCrates, only reward items are migrated due to the plugin’s very different structure. Source: https://www.phoenixplugins.com/docs/phoenix-crates/migration-mcmodels --- # 🤖 Action Types In our system's configuration files, you can utilize various action types to perform different actions. These actions enable you to interact with players, broadcast messages, play sounds, set gamemodes, and much more. ## Action Types | Action List | Description | | ------------------- | -------------------------------------------- | | \[MESSAGE] | Display a custom message to the player | | \[TITLE] | Display a custom title message to the player | | \[ACTION\_BAR] | This is a custom action bar | | \[CLOSE\_INVENTORY] | Close the player's current inventory | | \[COMMAND] | Execute a command (console or player) | | \[GAMEMODE] | Set the player's gamemode | | \[POTION\_EFFECT] | Apply a potion effect to the player | | \[SOUND] | Play a sound for the player | | \[DELAY] | A way to delay some actions | | \[OPEN] | Opens the crate | | \[GOBACK] | Return to the previous menu | Explore each action type to learn more about its syntax and usage. Examples are provided to illustrate how to use these actions effectively in your system or application. ### **Send Chat Message** This action sends a custom message to the player. * **Syntax:** `[MESSAGE] <message>` * **Example:** `[MESSAGE] &aThis is a custom message` Semicolons inside the message are kept, so you do not have to escape them. ### **Send Title Message** This action displays a custom title message to the player. * **Syntax:** `[TITLE] <title>; <subtitle>; <fadein>; <stay>; <fadeout>` * **Example:** `[TITLE] &aCustom title;&7Custom Subtitle; 20; 40; 20` ### **Send Action Bar Message** This action displays a custom action bar message to the player. * **Syntax:** `[ACTION_BAR] <message>` * **Example:** `[ACTION_BAR] This is a custom action bar` ### **Close Inventory** This action closes the inventory the player has open. * **Syntax:** `[CLOSE_INVENTORY]` * **Example:** `[CLOSE_INVENTORY]` ### **Execute Command** This action executes a command either from the console or as a player. * **Syntax:** `[COMMAND] <target>; <command>` * **Example:** `[COMMAND] console; mvtp %player% world` * **Example**: `[COMMAND] player; warp spawn` The target has to be either `console` or `player`. A leading `/` is optional. > **Info:** The action itself only replaces `%player%`. Any other placeholder is passed through untouched, so it will only work if the command you are running resolves it. ### **Change Gamemode** This action sets the gamemode for the player. * **Syntax:** `[GAMEMODE] <gamemode>` * **Example:** `[GAMEMODE] adventure` ### **Give Potion Effect** This action gives the player a potion effect. * **Syntax:** `[POTION_EFFECT] <effect>; <duration>; <amplifier>` * **Example:** `[POTION_EFFECT] speed; 5; 2` The duration is in **seconds**. Any negative value gives an effect that never runs out, so `[POTION_EFFECT] night_vision; -1; 0` is a permanent one. ### **Play Sound** This action plays a sound for the player. * **Syntax:** `[SOUND] <sound>; <volume>; <pitch>` * **Example:** `[SOUND] entity_arrow_hit_player; 1; 1` * **Example:** `[SOUND] minecraft:block.note_block.pling` The sound is either a vanilla name or a sound key, and a key also plays resource-pack sounds such as `myserver:crate.legendary`. Volume and pitch are optional and default to `1`. ### **Delay** This action will make a short pause until it continues executing actions. * **Syntax:** `[DELAY] <seconds>` * **Example:** `[DELAY] 3` * **Example:** `[DELAY] 0.5` Decimals are accepted, so you can pause for less than a second. ### **Open the Crate** This action opens the crate whose preview menu the player currently has open. It takes no arguments, and it only works from a rewards preview menu, which makes it the way to add an "open now" button to a preview. * **Syntax:** `[OPEN]` * **Example:** `[OPEN]` ### **Go Back** This action returns the player to the menu they came from. If there is no previous menu, the inventory is closed instead. It takes no arguments. * **Syntax:** `[GOBACK]` * **Example:** `[GOBACK]` Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/action-types --- # 🤖 Commands ## Commands The following list shows all available commands for the plugin. **Command alias:** `/phoenixcrates`, `/phoenixc`, `/crate`, `/crates` , `/pcrate` ,`/pcrates` <> - Required \ \[] - Optional<br> \[-s] - Flag to run a command silently from the user. \*1 - Supports offline players and players with a full inventory via the Crate Claim Add-on. \*2 - IP Limit, so bots won't get the key/reward/crate too. ## Player Commands **Crate Commands** | Command | Description | | ------- | ----------- | | /crates virtualKeys | Opens a menu with all your virtual keys. | | /crate open \<crate_id> | Open a crate virtually | | /crates forms | Bedrock players only: switches between Bedrock forms and chest menus. Needs the Bedrock opt out to be allowed. | ## Crate Commands **Crate Commands** | Command | Description | | ------- | ----------- | | /crates createCrate \<crate_id> | Create a new crate. | | /crates deleteCrate \<crate_id> | Delete an existing crate. | | /crates editCrate \<crate_id> | Opens the in-game editor directly for the specified crate. | | /crates giveCrate \<crate_id> \<player> \[amount] \[-s] | Gives a player a crate that they can place. | | /crates giveCrateAll \<crate_id> \[amount] \[-s] | Gives everyone online a crate that they can place. | | /crates giveReward \<crate_id> \<reward\_id> \<player> | Gives a player a specific reward from a crate. \*1 | | /crates giveRandomReward \<crate_id> \<player> \[-s] | Gives a player a random reward from a crate. | | /crates preview \<crate_id> \[player] | Opens the preview menu of a crate for the player. | | /crates open \<crate_id> | Opens the nearest placed crate of that type for yourself. | | /crates resetCooldown \<crate_id> \<player> \[-s] | Resets the open cooldown of a crate for a specific player. | | /crates resetGlobalWinLimit \<crate_id> \<reward_id> | Reset the global win count of a reward. | | /crates resetGlobalWinLimitCooldown \<crate_id> \<reward_id> | Reset the global win limit cooldown of a reward. | | /crates resetPlayerWinLimit \<crate_id> \<reward_id> \<player> | Reset a player's win count for a reward. | | /crates resetPlayerWinLimitCooldown \<crate_id> \<reward_id> \<player> | Reset a player's win limit cooldown for a reward. | | /crates restartCooldowns \<crate_id> \<reward_id> | Restart the cooldowns for a specific/every reward. | | /crates setGlobalWinLimit \<crate_id> \<reward_id> \<amount> | Set the global win count of a reward. | | /crates setPlayerWinLimit \<crate_id> \<reward_id> \<player> \<amount> | Set a player's win count for a reward. | | /crates resetOpenings \<player \| \*> \[crate_id \| \*] \[confirm] | Reset a player's crate openings, for one crate or all of them. `*` resets every player and needs `confirm`. | | /crates setOpenings \<player> \<crate_id> \<amount> | Set how many times a player opened a crate. | | /crates attachCrate \<crate_id> | Attach a crate to the block you are looking at. | | /crates detachCrate | Detach the crate from the block you are looking at. | | /crates placeCrate \<crate_id> \<world> \<x> \<y> \<z> \[facing] | Place a crate at a specific world location. | | /crates summonCrate \<crate_id> \<world> \<x> \<y> \<z> | Summon a crate item at a world location. | | /crates summonReward \<crate_id> \<reward_id> \<world> \<x> \<y> \<z> | Summon a reward display item at a world location. | ## Key Commands **Key Commands** | Command | Description | | ------- | ----------- | | /crates editKey \<key_id> | Opens the in-game editor directly for the specified key. | | /crates giveKeyAll \<key_id> \[amount] \[-s] | Gives everyone online a specific number of crate keys. \*1 | | /crates giveKey \<key_id> \<player> \[amount] \[-s] | Gives a player a specific amount of crate keys. \*1 \*2 | | /crates takeKey \<key_id> \<player> \[amount] \[-s] | Takes a specific amount of keys from a player. | | /crates setKey \<key_id> \<player> \<amount> | Set a specific amount of Virtual Keys to the user. | | /crates resetKeyAll \<key_id> | Resets a specific virtual key back to 0 for all players, online and offline. | | /crates checkKeys \<player> | Check the virtual keys of a user. | | /crates virtualKeys | Opens a menu showing your current virtual keys. | | /crates payKey \<key_id> \<player> \[amount] | Pay virtual keys to another player. | | /crates summonKey \<key_id> \<world> \<x> \<y> \<z> | Summon a key item at a world location. | ## Reroll Commands **Reroll Commands** | Command | Description | | ------- | ----------- | | /crates giveReroll \<crate_id> \<player> \[amount] | Gives a player a specific amount of available rerolls. | | /crates takeReroll \<crate_id> \<player> \[amount] | Takes a specific amount of rerolls from a player. | ## General Commands **General Commands** | Command | Description | | ------- | ----------- | | /crates editor | Opens the in-game editor of the plugin. | | /crates editLayout \<menu> | Opens a menu in the [In-Game Menu Editor](../configurations/in-game-menu-editor.md). | | /crates reload | Reload the Phoenix Crates plugin. | | /crates setLanguage \<language> | Switch the plugin language. See [Languages](../configurations/languages.md). | | /crates migrate \<source> \[confirm] | Import from another crate plugin. Without `confirm` it only previews. See [Migration](../migration.md). | | /crates addons | List the official add-ons, which of them are installed, and any third-party add-ons. | The reload reads its files in the background, so the server keeps running while it works. Crates cannot be opened until it finishes, and a second reload is refused while one is running. The editor's reload button works the same way. > **Info:** Commands that change every player's data, such as `resetKeyAll` and `resetOpenings *`, work through the players in batches and show their progress on the action bar, or in the console every 10%. Only one can run at a time, so a second one is refused until the first finishes. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/commands --- # 🪪 Licensing > **Info:** License keys, sessions, startup messages, failures and the grace period work the same for every Phoenix plugin and are covered on the general [Licensing](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing) page. Only the Premium version is licensed; Lite never contacts our servers. ## When Validation Fails The plugin stays enabled and placed crates stay where they are, but every PhoenixCrates command is blocked and any player who runs one is told why. Fix the cause and restart. The causes and their console messages are listed under [When Validation Fails](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing#when-validation-fails). On a network, every server behind the proxy that runs the Premium jar counts as its own [session](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing#sessions). ## Paid Add-ons Each paid add-on is checked against your license when it loads. One you do not own, or one dropped into the Lite version, does not load, and the console names it and the reason. The plugin itself keeps running. Free add-ons are never checked. `/crates addons` lists every official add-on with the installed ones first, each linking to its page on our website. ## Version Notices Players holding `phoenixcrates.admin` are told on join when a newer build is out. `notify-if-new-version` in config.yml turns it off. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/licensing --- # 🔒 Permissions ## Reroll Permissions All permissions related to the reroll feature. **Reroll Permissions** | Permission | Description | | -------------------------------- | ------------------------------------------------- | | phoenixcrates.command.givereroll | Allow user to give a specified amount of rerolls. | | phoenixcrates.command.takereroll | Allow user to take a specified amount of rerolls. | | phoenixcrates.reroll.\<group> | Grants the rerolls of a [reroll group](../features/reroll.md#group-permissions). | `<group>` is the name of the group as typed in the editor. Groups do not stack, only the highest matching one applies. ## Key Permissions **Key Permissions** | Permission | Description | | ----------------------------- | ---------------------------------------------------- | | phoenixcrates.command.givekey | Allow user to give a key | | phoenixcrates.command.givekeyall | Allow user to give a key to everyone | | phoenixcrates.command.takekey | Allow user to take a key. | | phoenixcrates.command.setkey | Allow user to set a specific number of virtual keys. | | phoenixcrates.command.resetkeyall | Allow user to reset a specific virtual key for all players. | ## General Permissions **General Permissions** | Permission | Description | | ------------------------------------ | --------------------------------------------------------------- | | phoenixcrates.admin | Grants access to everything regarding the plugin. | | phoenixcrates.* | Grants all PhoenixCrates permissions (includes phoenixcrates.admin). | | phoenixcrates.command.create | Allows user to create a crate. | | phoenixcrates.command.delete | Allows user to delete a crate. | | phoenixcrates.command.edit | Allow user to open the in-game editor for a specific crate or key. | | phoenixcrates.command.givecrate | Allows user to give a crate. | | phoenixcrates.command.givecrateall | Allows user to give a crate to everyone. | | phoenixcrates.command.givereward | Allow user to give a specified reward. | | phoenixcrates.command.preview | Allow user to use the preview command. | | phoenixcrates.command.editor | Allow user to access the ingame editor and the menu layout editor. | | phoenixcrates.command.reload | Allow user to reload the plugin. | | phoenixcrates.command.setlanguage | Allow user to switch the plugin language. | | phoenixcrates.command.migrate | Allow user to import data from another crate plugin. | | phoenixcrates.command.addons | Allow user to list the available and installed add-ons. | | phoenixcrates.command.open | Allow user to open a crate directly with the open command. | | phoenixcrates.command.resetcooldown | Allow user to reset a player's crate cooldown. | | phoenixcrates.command.giverandomreward | Allow user to give a random reward from a crate. | | phoenixcrates.command.checkkeys | Allow user to check another player's virtual keys. | | phoenixcrates.command.resetglobalwinlimit | Allow user to reset the global win count of a reward. | | phoenixcrates.command.resetplayerwinlimit | Allow user to reset a player's win count for a reward. | | phoenixcrates.command.resetplayerwinlimitcooldown | Allow user to reset a player's win limit cooldown for a reward. | | phoenixcrates.command.resetglobalwinlimitcooldown | Allow user to reset the global win limit cooldown of a reward. | | phoenixcrates.command.restartcooldowns | Allow user to restart the cooldowns for a reward. | | phoenixcrates.command.setglobalwinlimit | Allow user to set the global win count of a reward. | | phoenixcrates.command.setplayerwinlimit | Allow user to set a player's win count for a reward. | | phoenixcrates.command.resetopenings | Allow user to reset crate openings of a player or everyone. | | phoenixcrates.command.setopenings | Allow user to set a player's crate openings. | | phoenixcrates.command.summon | Allow user to summon a crate, key, or reward item at a location. | | phoenixcrates.command.attach | Allow user to attach a crate to the block they are looking at. | | phoenixcrates.command.detach | Allow user to detach a crate from the block they are looking at. | | phoenixcrates.command.place | Allow user to place a crate at a specific world location. | ## Crate Permissions Each crate can be configured to require its own permission before a player is allowed to interact with it. By default, this is `phoenixcrates.crate.<id>`, but it can be customized per crate in the crate configuration file under `permission.permission`, and toggled on/off with `permission.required`. **Crate Permissions** | Permission | Description | | -------------------------- | ------------------------------------------------------------- | | phoenixcrates.crate.\<id> | Allows the player to interact with the crate matching `<id>`. | ## Placing and Removing Crates The command permissions above cover the commands. Doing the same thing by hand in the world is gated on phoenixcrates.admin instead: * Placing a crate item into the world. * Shift + left-clicking a placed crate to remove it. So a builder given `phoenixcrates.command.place` can still only place crates through the command. To let them place crates by hand they need `phoenixcrates.admin`, which grants everything else too. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/permissions --- # 🔍 Placeholders PhoenixCrates supports **PlaceholderAPI**, allowing you to use player data from our plugin in other plugins that also support PlaceholderAPI. Below is a list of the available **PlaceholderAPI placeholders** as well as our **internal placeholders** that you can use in holograms. ## PlaceholderAPI The following is the list of the available placeholders that Phoenixcrates has, make sure to replace the `<id>` with the ID of your crate without using the `<>.` | Placeholders | Description | |-------------------------------------------------------------|--------------------------------------------------------------------------------------------------| | %phoenixcrates\_keys\_\<key_id>% | Returns the number of keys a user has (virtual + physical). | | %phoenixcrates\_cooldown\_\<crate_id>% | Returns the cooldown timer for that specific crate. | | %phoenixcrates\_totalopened\_\<crate_id>% | Returns the total number of how many times a user opened that specific crate. | | %phoenixcrates\_totalopened% | Returns the total number of openings for a user. | | %phoenixcrates\_rerolls\_available\_\<crate_id>% | Returns the amount of rerolls a user has for a crate. | | %phoenixcrates\_guaranteed\_amount\_\<crate_id>% | Returns the number of openings remaining until the user's next guaranteed reward for that crate. | | %phoenixcrates\_guaranteed\_reward\_\<crate_id>% | Returns the name of the next guaranteed reward the user will receive for that crate. | | %phoenixcrates\_winLimit\_\<crate_id>\_\<reward_id>% | Returns the player's win limit progress for a specified reward (amount/limit). | | %phoenixcrates\_globalWinLimit\_\<crate_id>\_\<reward_id>% | Returns the global win limit progress for a specified reward (amount/limit). | | %phoenixcrates\_rewardTimeLimit\_\<crate_id>\_\<reward_id>% | Returns the time remaining until the reward expires. | | %phoenixcrates\_cooldownGlobalWin\_\<crate_id>\_\<reward_id>% | Returns the global win limit cooldown remaining. | | %phoenixcrates\_cooldownWinLimit\_\<crate_id>\_\<reward_id>% | Returns the player's win limit cooldown remaining. | ## Hologram Placeholders These are available in a crate's hologram lines, on top of any PlaceholderAPI placeholder. | Placeholders | Description | | ----------------- | ---------------------------------------------------------------------------------------------- | | %name% | The crate's display name. | | %cooldown% | The viewer's remaining cooldown for this crate, or the "available to open" text when there is none. | | %virtual\_keys% | How many virtual keys the viewer holds across every key linked to this crate. | | %player% | The viewer's name. | | %online% | The number of players online. | | %max\_online% | The server's player limit. | | %plugin\_version% | The installed PhoenixCrates version. | Holograms are per player, so each viewer sees their own cooldown and key count. How often those values refresh is set with `hologram-refresh-rate` in [Main Configuration](../configurations/main-configuration.md). ## Internal Placeholders The following placeholders are available when configuring reward display items, such as in the menus configuration: | Placeholders | Description | | ----------------- | ----------------------------------------------------------- | | %player% | Returns the name of the player. | | %reward\_name% | Returns the display name of the reward. | | %reward\_lore% | Returns the lore of the reward. | | %percentage% | Returns the configured weight/percentage of the reward. | | %chance% | Returns the calculated chance (%) of receiving the reward. | | %required\_keys% | Returns the number of keys required to redeem the reward. | | %amount\_limit% | Returns the number of wins remaining before the reward's win limit is reached. | | %global\_amount\_limit% | Returns the number of wins remaining before the reward's global win limit is reached. | `%percentage%` and `%chance%` keep up to five decimals for values below 0.01, so a very rare reward does not show as 0. | %win\_amount% | Returns the player's current win count for the reward (preview and select-reward menus). | | %win\_limit% | Returns the reward's win limit (preview and select-reward menus). | | %global\_win\_amount% | Returns the current global win count for the reward (preview and select-reward menus). | | %global\_limit% | Returns the reward's global win limit (preview and select-reward menus). | | %cooldown% | Returns the time remaining on the player's win limit cooldown (preview and select-reward menus). | | %global\_cooldown% | Returns the time remaining on the global win limit cooldown (preview and select-reward menus). | | %time% | Returns the time remaining until a time-limited reward expires (preview menu). | | %rarity\_name% | Returns the reward's rarity display name (requires the Rarity Add-on). | | %total\_selections% | Returns how many rewards are selected (mass selection menu). | | %available\_keys% | Returns how many keys the player owns for the crate (mass selection menu). | | %selected\_amount% | Returns how many times that reward is selected (mass selection menu). | Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/placeholders --- # ⁉️ Questions & Answers ## Compatibility and setup <details id="does-the-plugin-support-bedrock-versions"> <summary>Does the plugin support Bedrock players?</summary> Yes, through Geyser. The player menus open as native Bedrock forms, and a menu button with several click actions asks Bedrock players which one to run, so Shift actions in the editor work too. Opening animations that use player heads only show once the skulls are registered in Geyser. See [GeyserMC (Bedrock)](../../configurations/geysermc-bedrock.md). </details> <details id="do-the-gui-animations-work-for-bedrock-players"> <summary>Do the GUI animations work for Bedrock players?</summary> Yes. Opening animations are the same for Bedrock and Java players. The rewards preview, reward selection, confirmation, reroll and virtual keys menus open as Bedrock forms when Floodgate or Geyser is installed on the same server, and players can switch back to chest menus with `/crates forms`. See [Bedrock forms](../../configurations/geysermc-bedrock.md#bedrock-forms). </details> <details id="how-do-i-allow-bedrock-users-view-animations-that-include-skulls"> <summary>How do I show animations that use skulls to Bedrock players?</summary> Bedrock cannot load player head textures on its own. Register every head in Geyser's `skin-hashes` option, following the [Geyser custom skulls guide](https://geysermc.org/wiki/geyser/custom-skulls/). The hashes for every animation are listed under [Bedrock skull textures](../../configurations/geysermc-bedrock.md#bedrock-skull-textures). </details> <details id="is-phoenixcrates-folia-compatible"> <summary>Is PhoenixCrates Folia compatible?</summary> Yes, both the free and the Premium version. Commands run as the player, from rewards or from `[COMMAND] player` actions, work there too. An opening ends when the player leaves the crate's world, `/tp` included, the same as on Paper. </details> <details id="why-isnt-the-newest-minecraft-version-supported-yet"> <summary>Why isn't the newest Minecraft version supported yet?</summary> A new release is added once it has settled, so there is a gap between launch and support. PhoenixCrates is usually one of the first of our plugins to get it. There is no ETA, and updates are free for life. The current list is on [Version Support](../../first-installation.md#version-support). </details> <details id="can-the-plugin-run-as-a-forge-or-fabric-mod"> <summary>Can the plugin run as a Forge or Fabric mod?</summary> No, there is no mod version. Hybrid servers such as Arclight or Mohist can load it, but we do not recommend them, and faults caused by the hybrid itself are not plugin issues. </details> <details id="does-the-plugin-work-without-internet-access"> <summary>Does the plugin work without internet access?</summary> The Lite version runs fully offline. Premium checks its license with our servers, so it needs outbound internet access; see [What happens on startup](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing#what-happens-on-startup). </details> <details id="which-files-do-i-copy-to-another-server"> <summary>Which files do I copy to another server?</summary> Copy `crates/`, `keys/`, `menus/`, `translations/`, `config.yml`, `internal_storage.yml`, `rarities.yml` and the add-on configuration files. Add `locations.yml` if the worlds come along; a location in a world the new server does not have is skipped. Player progress (virtual keys, cooldowns, opened counts, win limits) lives in the database, so point the new server at the same MySQL database or bring the SQLite file. Every file is described on [File Structure](../../configurations/crate-configuration-file.md#file-structure). > **Warning:** A license only allows a limited number of servers at once. Check [Licensing](../licensing.md) before running both. </details> ## Crates and models <details id="why-my-crates-can-only-be-open-by-op-players"> <summary>Why can only operators open my crates?</summary> The crate sits inside spawn protection. Set `spawn-protection` to `0` in `server.properties` and protect the area with a region plugin such as WorldGuard instead. </details> <details id="whats-the-difference-between-attachcrate-and-placecrate"> <summary>What is the difference between attachCrate and placeCrate?</summary> **`/crates attachCrate <crate_id>`** turns the block you are looking at into the crate and keeps its look, so a chest, a barrel or part of a build can become a crate. `/crates detachCrate` undoes it. **`/crates placeCrate <crate_id> <world> <x> <y> <z> [facing]`** places the crate at exact coordinates. Nothing has to be there and you do not have to be nearby, which makes it the one for the console and setup scripts. Premium only. Both need their permission. Placing a crate item by hand needs `phoenixcrates.admin`. See [Permissions](../permissions.md#placing-and-removing-crates). </details> <details id="how-do-i-use-a-custom-model-as-the-crate-block"> <summary>How do I use a custom model as the crate block?</summary> Pick the model through the crate's engine, not by placing the item: [Vanilla Model](../../main-features/crate-engine-mode/README.md#vanilla-model), [Model Engine](../../main-features/crate-engine-mode/README.md#model-engine) or [Better Model](../../main-features/crate-engine-mode/README.md#better-model), depending on where the model comes from. In the free version, right-click the engine item (the experience bottle) to change it. </details> <details id="why-my-custom-models-are-not-being-displayed-correctly"> <summary>Why is my custom model displayed wrong?</summary> **Scrambled model.** A resource pack manager such as ItemsAdder, Oraxen or Nexo is merging Model Engine files into its own pack. Keep Model Engine resources out of that pack so custom model data does not collide. <figure><img src="../../.gitbook/assets/image (33).png" alt=""><figcaption></figcaption></figure> **Too small or too large.** The Vanilla Model engine shows models on an armor stand head. Open the model in Blockbench, go to the Display tab and adjust the head size. <figure><img src="../../.gitbook/assets/image (15).png" alt="" width="563"><figcaption></figcaption></figure> </details> <details id="why-my-custom-model-from-model-engine-keep-flickering"> <summary>Why does my Model Engine model keep flickering?</summary> A region with mob spawning turned off, usually a WorldGuard flag, stops Model Engine models from loading properly. Allow mob spawning in the crate's region. </details> <details id="can-i-change-the-scale-of-a-bettermodel-crate-model"> <summary>Can I change the scale of a Better Model crate model?</summary> Yes, from the Better Model editor. </details> <details id="how-do-i-check-the-animations-of-my-custom-model"> <summary>How do I find the animation IDs of my custom model?</summary> Open the `.bbmodel` file in Blockbench and switch to the Animate tab at the top right. The animation IDs are listed on the left. </details> <details id="why-my-furniture-models-are-being-destroyed-when-clicked"> <summary>Why are my furniture models destroyed when clicked?</summary> Furniture models are not supported directly. With the Vanilla Model engine, convert the furniture into an item with custom model data. </details> ## Opening crates <details id="why-does-my-crate-take-the-key-but-say-it-cant-be-opened"> <summary>Why does my crate take the key but say it cannot be opened?</summary> Another plugin fires the interaction twice, so the crate opens on the first call and refuses the second. Remove plugins one by one to find the one duplicating it. </details> <details id="why-does-my-crate-say-there-are-no-rewards-available"> <summary>Why does my crate say there are no rewards available?</summary> The crate has rewards, but none this player can win right now. Check the reward settings: * The reward is **disabled**. * The player holds one of its **Restricted Permissions**, or misses one of its **Required Permissions**. * Its **Win Limit** or **Global Win Limit** has been reached. * A **Win Limit Cooldown** or **Global Win Limit Cooldown** is still running. * It is **time limited** and the window has passed. With [Rarity](../../add-ons/rarity/) installed, also check that the **rarity is enabled** and that the key's rarities **match** at least one reward. Trying the crate as an operator on a fresh account narrows it down: if it works there the cause is a permission, otherwise a limit or a cooldown. </details> <details id="can-a-player-open-a-crate-with-a-full-inventory"> <summary>Can a player open a crate with a full inventory?</summary> Only with [Crate Claim](../../add-ons/crate-claim/README.md). Without it the player is told the inventory is full and no key is taken. With it the crate opens and whatever does not fit is stored for `/crate claim`. Keys, crates and rewards given by command follow the same rule: dropped at the player's feet without the add-on, stored with it. </details> <details id="why-am-i-told-my-data-is-still-loading"> <summary>Why am I told my data is still loading?</summary> The player's record has not come back from the database yet, and the crate refuses to open rather than read a stale key count. It clears within a second. If it happens all the time, the database is the bottleneck: check that MySQL is reachable, then raise `fetch-timeout` or `maximumPoolSize` in the [connection pool](../../configurations/main-configuration.md#connection-pool). </details> <details id="what-is-the-difference-between-your-chance-and-percentage-in-the-preview"> <summary>What is the difference between "Your Chance" and "Percentage" in the preview?</summary> **Percentage** is the weight the server owner gave the reward. Several rewards can share it. **Your Chance** is the real probability for that player, and all of them add up to 100%. Two rewards set to 100% each give a 50% chance each. </details> <details id="do-reroll-groups-stack"> <summary>Do reroll groups stack?</summary> No. Only the matching group with the highest count applies, so a player in a default group worth 2 and a VIP group worth 10 gets 10. Groups do add to the other sources: ``` free rerolls + best matching group + rerolls given with /crates giveReroll ``` Mass Opening multiplies the total by the number of keys used. Details on [Reroll](../../features/reroll.md#how-the-total-is-calculated). </details> ## Keys and rewards <details id="why-doesnt-an-offline-player-receive-the-key-i-gave-them"> <summary>Why doesn't an offline player receive the key I gave them?</summary> Physical keys can only be given to offline players when [Crate Claim](../../add-ons/crate-claim/README.md) holds them; without it the command is refused. Virtual keys can always be given offline. </details> <details id="why-doesnt-my-key-show-in-the-virtual-keys-menu"> <summary>Why doesn't my key show in the virtual keys menu?</summary> `/crates virtualKeys` only lists a key that is set to **Virtual**, is **enabled**, and that the player owns **at least one** of. A new key stays hidden until you give yourself one with `/crates giveKey`. The menu is customized in [Customize Menus](../../configurations/customize-menus.md#virtual-keys-menu). </details> <details id="will-renaming-a-crate-or-reward-lose-player-progress"> <summary>Will renaming a crate, key or reward lose player progress?</summary> Changing an **identifier** does. The database ties progress to it, so the old records point at nothing: * **Crate** - open cooldowns, opened counts and rerolls. * **Key** - every player's virtual keys of that key. * **Reward** - win counts and win limit cooldowns. * **Rarity** - the rarity link on every reward and key using it. Display names are safe to change at any time. Settle identifiers before a crate goes live. </details> <details id="how-can-i-create-a-reward-where-the-player-doesnt-receive-a-physical-item"> <summary>How do I make a reward that gives no physical item?</summary> Leave the reward item as display only and give the benefit with [win commands](../../main-features/rewards/win-items-and-commands.md), such as a voucher or currency. PlaceholderAPI can randomize the amounts. </details> <details id="how-do-i-remove-the-amount-of-the-item-won-from-the-hologram"> <summary>How do I remove the amount from the reward hologram?</summary> Edit `crate.reward-got` in `translations/translations.en.yml` and remove `&ex%amount%`: ```yaml crate: reward-got: '&a%reward%' ``` <figure><img src="../../.gitbook/assets/image (73).png" alt=""><figcaption></figcaption></figure> </details> <details id="why-when-using-the-chat-from-the-editor-there-are-color-to-the-value"> <summary>Why do values typed in the editor chat get a color?</summary> A chat color or prefix plugin is formatting the message before the editor reads it. Disable that plugin's chat color, or edit the value in the crate file. </details> ## License and purchase <details id="why-does-my-license-say-maximum-concurrent-sessions"> <summary>Why does my license say maximum concurrent sessions reached?</summary> The same license key is active on more servers than your plan allows, usually after copying the plugin to every server behind a proxy. See [Sessions](https://www.phoenixplugins.com/docs/phoenix-plugins/licensing#sessions) on the licensing page. </details> <details id="do-you-offer-refunds"> <summary>Do you offer refunds?</summary> No. A downloaded product is not refundable. See point 7 of the [Terms and Conditions](https://www.phoenixplugins.com/terms-and-conditions). </details> Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers --- # ⁉️ Can a player open a crate with a full inventory? ## Answer Only with the [Crate Claim](../../add-ons/crate-claim/README.md) add-on installed. Without it, a player whose inventory is full is refused before anything happens. They are told their inventory is full and no key is taken, which is deliberate so a reward is never lost to a missing slot. With Crate Claim installed the crate opens normally and anything that does not fit is stored for the player to collect with `/crate claim`. The same applies to keys, crates and rewards handed out by command, which are dropped at the player's feet without the add-on and stored with it. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/can-a-player-open-a-crate-with-a-full-inventory --- # ❔ Can i change the scale of a Better Model crate model? ## Answer Yes. Scaling for Better Model is set from the Better Model editor. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/can-i-change-the-scale-of-a-bettermodel-crate-model --- # ⁉️ Can the plugin run as a Forge or Fabric mod? ## Answer No. It is a Java plugin and there is no mod version of it. Hybrid servers such as Arclight or Mohist can load it, but we do not recommend them. Faults caused by the hybrid itself, such as its own teleport handling, are not plugin issues. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/can-the-plugin-run-as-a-forge-or-fabric-mod --- # ⁉️ Does the plugin support bedrock versions? ## Answer Some features may not work with Bedrock (using Geyser), such as certain actions in the editor due to the lack of a "Shift" option. However, users can still configure settings through the file system. Additionally, opening animations that use heads won't work due to Geyser limitations. In conclusion, while our plugin supports Bedrock versions, it may not function at full potential. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/does-the-plugin-support-bedrock-versions --- # ⁉️ Does the plugin work without internet access? ## Answer Not permanently. The Premium version validates its license against `phoenixplugins.com` when the server starts and keeps renewing it while the server runs, so the machine needs outbound internet access. If our servers cannot be reached, a grace period starts and everything keeps working while the console counts down to its expiry, which covers a temporary outage or a brief network problem. Once it expires the plugin's commands are blocked. If you see the grace period message and your server does have internet, the connection is most likely being blocked by a firewall on the host. The Lite version has no license and never contacts our servers, so it runs fully offline. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/does-the-plugin-work-without-internet-access --- # ⁉️ Do reroll groups stack? ## Answer No. When a player matches more than one reroll group, only the group with the highest reroll count applies. A VIP holding both a default group worth 2 and a VIP group worth 10 gets 10, not 12. Groups do combine with the other two sources though. The total a player opens with is: ``` free rerolls + best matching group + rerolls given with /crates giveReroll ``` When several keys are opened at once through Mass Opening, that total is multiplied by the number of keys used. The full explanation is on the [Reroll](../../features/reroll.md#how-the-total-is-calculated) page. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/do-reroll-groups-stack --- # ⁉️ Do the GUI animations work for Bedrock players? ## Answer Yes, the inventory animations play normally for Bedrock players. There are no Floodgate form menus, so Bedrock players see the same inventory menus as Java players. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/do-the-gui-animations-work-for-bedrock-players --- # ⁉️ Do you offer refunds? ## Answer No. Once the product has been downloaded it is not refundable. See point 7 of our [Terms and Conditions](https://www.phoenixplugins.com/terms-and-conditions). Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/do-you-offer-refunds --- # ❔ How can i create a reward where the player doesn't receive a Physical Item? ## Answer he reward will only be for display purposes, and the player won't receive a physical item. Instead, you can use commands to grant benefits or actions, such as giving a voucher or in-game currency. You can also use PlaceholderAPI to set random quantities for these virtual rewards. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/how-can-i-create-a-reward-where-the-player-doesnt-receive-a-physical-item --- # ❔ How do i allow Bedrock users view animations that include skulls? ## Answer This is a known incompatibility that Bedrock users experience with skulls on servers. Geyser provides an option that allows you to load skulls for Bedrock players, but they must be manually defined in the configuration. Make sure to check their guide on that.\ \ 👉 [Click to view the geyser guide](https://geysermc.org/wiki/geyser/custom-skulls/) ## Skulls Below are the texture links we use for every animation in the plugin that includes player heads. The following method works with the `skin-hashes` option that geyser provides. You will only include the part that is green, like on the example below. ~~http://textures.minecraft.net/texture/~~14e424b1676feec3a3f8ebade9e7d6a6f71f7756a869f36f7df0fc182d436e <details> <summary>Christmas Animation Add-On</summary> **Santa Claus First**:\ 1\) [Santa](http://textures.minecraft.net/texture/14e424b1676feec3a3f8ebade9e7d6a6f71f7756a869f36f7df0fc182d436e) 2) [Kid](http://textures.minecraft.net/texture/5c8d3e33cb1ca1aacf9dad322f4f7519cd7dfa509c33b7dd87b5398ee0ac17a8) **Elf Animation**:\ 1\) [Present](http://textures.minecraft.net/texture/45368f5635ff6c3407f0f356c5b6e0947bcd5e38490c9aa8b8b582a4f21ae3cb) | 2) [Tv](http://textures.minecraft.net/texture/7bbe8fd1aa39f15076e884dfe6ddb9a3f3761db31e2b1f9940b5dfd34d1c4d), 3) [Elf](http://textures.minecraft.net/texture/4ec5455f43426ca1874b5c7b4a492ec3722a502f8b9599e758e133fed8b3c1e4) **Christmas Tree Animation:**\ 1\) [Ornament](http://textures.minecraft.net/texture/2db24dc262631663ba1e3e3398645013dc5cd2331ec9b9f3eb26855a0b104baa)\ \ **Misc for All Animations**: (Should Import for any kind of Animation)\ 1\) **Presents**: a) [White](http://textures.minecraft.net/texture/e47b37e67a89159bf4acc4a44d4328f4efc0181605142288e5eed1ab8aed913c), b) [Green](http://textures.minecraft.net/texture/28dc3c84491c4ff103de6ea01880e2d83432cd4878b84d6b43253cc51fd978e7), c) [Blue](http://textures.minecraft.net/texture/5b85e29f29ec9a90e482ea5b8391bcb4560bbae0dcd15d7ce1d86016b4356e98), d) [Purple](http://textures.minecraft.net/texture/e9e39d91c04c30cc1f530fee798eed279dde60f95c2e1d155c0fdd361d0962ed), e) [Yellow](http://textures.minecraft.net/texture/abd98792dd92d9719894341ac9012a584c4428558fd2c712f78e5f0d4da85470), f) [Red](http://textures.minecraft.net/texture/45368f5635ff6c3407f0f356c5b6e0947bcd5e38490c9aa8b8b582a4f21ae3cb)\ 2\) **Ornaments**: a) [Red](http://textures.minecraft.net/texture/c6f518cdcc30da6e21833f3d90366c3703c27a0170b928fb15b5e51816f4e15e), b) [Orange](http://textures.minecraft.net/texture/ad53ec557eca3c5a08be794164b2e9b6a7fb703a33388f0a9c02c3b16c2945e4), c) [Yellow](http://textures.minecraft.net/texture/c0dac2501c9e756767f6943323ad5955b5a975bb09be12364ef80ea3f1ca7b06), d) [Lime](http://textures.minecraft.net/texture/9b68ca27a304d21e2e8a99a748093f95ae5b148c59d7af0b5670f1d15202502e), e) [Green](http://textures.minecraft.net/texture/41e7340dd4c009c43c398bc40d9aed147014057a7f43722c6cdc9b45837015f5), f) [Dark Green](http://textures.minecraft.net/texture/b605c66347f327c5eed27672d7a0e347f4e36c006353c91b78935ba28116504), g) [Dark Aqua](http://textures.minecraft.net/texture/623323728e9df5c38053176465da1f4c855cd6a3a5f3928a223150e680441a8f), h) [Dark Blue](http://textures.minecraft.net/texture/86f901bbde8cd67520fa0c7ae461ee7ca66ce3c4c481cd5c12fb43712eea6b63), i) [Aqua](http://textures.minecraft.net/texture/29273cb3c79ecd53c13b4d71e9afd919d1dcba1410c2538b8fe099ecd61a6cb4), j) [Very Dark Blue](http://textures.minecraft.net/texture/17f85d2edc530c4f33a35c7cccefea9528812137ae13e040e1169032b4f39c53), k) [Purple](http://textures.minecraft.net/texture/431d901ceeb38d0f9c63ae66cd5a46e33a09c0349d383f5a5c7c3726e0e0e371), l) [Magenta](http://textures.minecraft.net/texture/94b3aed343afb22d536ca60cf95e56cf334c68bc41b1369ec9b06f4dd050e6cb), m) [Pink](http://textures.minecraft.net/texture/87f5c30a117ee8ae80c7858ac42c67b2bbe5e600a60ceeaa2817f862dd89333d) </details> Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/how-do-i-allow-bedrock-users-view-animations-that-include-skulls --- # ❔ How do i check the animations of my custom model? ## Answer The easiest way is to check the .bbmodel file of your crate. If you're using Blockbench, open your model file in the app. In the top right corner, click on the Animate tab. On the left side, you'll see a list of your model's animations, where you can find the animation IDs. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/how-do-i-check-the-animations-of-my-custom-model --- # ❔ How do i remove the amount of the item won from the Hologram? This answer is related to the following example `x1` that displays the amount of the reward that the user receives. <figure><img src="../../.gitbook/assets/image (73).png" alt=""><figcaption></figcaption></figure> ## Answer To edit out the amount of the reward, you need to open the `translations` folder of PhoenixCrates and go to the `translations.en.yml` file and find the following message: ```yaml crate: reward-got: '&ex%amount% &a%reward%' ``` From the message above simply remove the `&ex%amount%`part Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/how-do-i-remove-the-amount-of-the-item-won-from-the-hologram --- # ❔ How do i use a custom model as the crate block? ## Answer The model is chosen through the crate's engine, not by placing the item as a block. Set the engine to Vanilla Entity, Model Engine, or Better Model depending on where your model comes from. In the free version you can right click the engine item, the experience bottle, to change it. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/how-do-i-use-a-custom-model-as-the-crate-block --- # ⁉️ Is PhoenixCrates Folia compatible? ## Answer Yes, both the free and the premium version run on Folia. Commands run as the player, from rewards or from `[COMMAND] player` actions, work there as well. An opening ends when the player leaves the crate's world, `/tp` included, just like on Paper. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/is-phoenixcrates-folia-compatible --- # 🤔 What is the difference between "Your Chance" and "Percentage" in the preview? ## Answer In the preview menu, there are two key concepts: "Percentage" and "Your chance" "Percentage" is the value set by the server owner for a specific reward, indicating its likelihood of being obtained. Multiple rewards can share the same percentage, meaning they have an equal chance of being won. "Your chance" refers to the actual probability of a player winning a particular item. For example, if two items are configured with 100% each, the player has a 50% chance of winning either item. "Your chance" will always total 100%. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/what-is-the-difference-between-your-chance-and-percentage-in-the-preview --- # 🤔 What's the difference between attachCrate and placeCrate? ## Answer **`/crates attachCrate <crate_id>`** turns the block you are looking at into that crate. The block keeps its own appearance, so you can attach a crate to a chest, a barrel or part of a build without the crate replacing it. Use `/crates detachCrate` to undo it. **`/crates placeCrate <crate_id> <world> <x> <y> <z> [facing]`** places the crate at exact coordinates in a named world, with an optional facing direction. Nothing needs to exist there first, and you do not have to be standing nearby, which makes it the one to use from the console or in a setup script. This command is Premium only. Both need the matching permission, and placing a crate item by hand in the world needs `phoenixcrates.admin` instead. See [Permissions](../permissions.md#placing-and-removing-crates). Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/whats-the-difference-between-attachcrate-and-placecrate --- # ❔ Which files do i copy to another server? ## Answer Copy `crates/`, `keys/`, `menus/`, `translations/`, `config.yml`, `internal_storage.yml`, `rarities.yml` and the add-on configuration files. That carries every crate, key, reward and menu across. Placed crates live in `locations.yml`, so copy that too if the worlds are coming with you. A location pointing at a world the new server does not have is skipped. Player progress is not in any of these files. Virtual keys, cooldowns, opened counts and win limits are in the database, so point the new server at the same MySQL database or bring the SQLite file along. The full breakdown of every file is on the [File Structure](../../configurations/file-structure.md) page. > **Warning:** A license only allows a limited number of servers running at once, so remember to check [Licensing](../licensing.md) before starting both servers together. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/which-files-do-i-copy-to-another-server --- # ❓ Why am I told my data is still loading? ## Answer The message "Hold on! We're still loading your data" means the player's record has not finished coming back from the database yet. The crate refuses to open rather than risk reading a stale key count and taking a key it should not. It normally clears within a second and the player can simply click again. If it happens constantly, the database is the bottleneck. Check that your MySQL server is reachable and responsive, then look at the connection pool settings in [Main Configuration](../../configurations/main-configuration.md#connection-pool), where raising `fetch-timeout` or `maximumPoolSize` usually solves it. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-am-i-told-my-data-is-still-loading --- # ❓ Why does my crate say there are no rewards available to me? ## Answer The crate has rewards, but none that this particular player can win right now. Work through the list below, checking the reward's own settings in the editor: * The reward is **disabled**. * The player holds one of the reward's **Restricted Permissions**. * The player is missing one of the reward's **Required Permissions**. * The reward's **Win Limit** has been reached by that player. * The reward's **Global Win Limit** has been reached by everyone combined. * A **Win Limit Cooldown** or **Global Win Limit Cooldown** is still running. * The reward is **time limited** and its window has expired. With the [Rarity](../../add-ons/rarity/) add-on installed there are two more: * The reward's **rarity is disabled**, which makes every reward under it impossible to win. * The key being used has rarities assigned and **none of them match** any reward in the crate. A quick way to narrow it down is to try the same crate as an operator on a fresh account. If it works there, the cause is permission based; if it does not, it is a limit or a cooldown. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-does-my-crate-say-there-are-no-rewards-available --- # ❓ Why does my crate take the key but say it can't be opened? ## Answer Another plugin on your server is firing the interaction twice, so the crate is opened once and then refused on the second call. Test with the other plugins removed to find which one is duplicating the interaction. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-does-my-crate-take-the-key-but-say-it-cant-be-opened --- # ❓ Why does my license say maximum concurrent sessions reached? ## Answer The same license key is active on more servers at once than your plan allows. On a network this usually happens after the plugin is copied to several servers behind the proxy, each of them validating the same key. Stop the servers you do not need running and restart. If you genuinely need more sessions, contact us on [Discord](https://www.phoenixplugins.com/media/discord) and we can raise the limit on your account. A server that crashed without shutting down cleanly can leave its session registered for a short while, so if you are sure nothing else is running, wait a few minutes before getting in touch. While this is unresolved the plugin is not disabled, but all of its commands are blocked. See [Licensing](../licensing.md) for the full picture. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-does-my-license-say-maximum-concurrent-sessions --- # ❓ Why doesn't an offline player receive the key i gave them? ## Answer A physical key cannot be handed to a player who is not online unless the Crate Claim add-on is enabled to hold it for them. Without it the command is refused. Virtual keys are not affected and can always be given offline. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-doesnt-an-offline-player-receive-the-key-i-gave-them --- # ❓ Why doesn't my key show in the virtual keys menu? ## Answer `/crates virtualKeys` only lists a key when all three of these are true: * The key is set to **Virtual** in the editor. A physical key never appears here, however many the player is holding. * The key is **enabled**. * The player owns **at least one** of it. Keys the player has none of are left out rather than shown as zero. So an admin testing a brand new key sees an empty menu until they give themselves one with `/crates giveKey`. The menu itself can be customized in `menus/virtual_keys.yml`. See [Customize Menus](../../configurations/customize-menus.md#virtual-keys-menu). Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-doesnt-my-key-show-in-the-virtual-keys-menu --- # ❓ Why isn't the newest Minecraft version supported yet? ## Answer A new Minecraft release is added once it has settled, so there is a gap between it launching and us supporting it. PhoenixCrates is normally one of the first of our plugins to get it. We do not give an ETA for it. Updates are free for life, so the update reaches you at no extra cost. Check the [Version Support](../version-support.md) page for what is supported right now. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-isnt-the-newest-minecraft-version-supported-yet --- # ❓ Why my crates can only be open by OP Players? ## Answer Only ops can access your crates, the issue may be caused by the "spawn-protection" setting in your "server.properties" file. To fix this, set "spawn-protection" to 0. This will prevent interference and allow all players to access the crates as intended. Additionally, it's recommended to use a plugin like WorldGuard to protect specific regions. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-my-crates-can-only-be-open-by-op-players --- # ❓ Why my custom model from model engine keep flickering? ## Answer One reason this issue might occur is that you are using a protection plugin, such as WorldGuard, which has the mob spawning set to false in that region. This setting can prevent Model Engine models from loading properly. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-my-custom-model-from-model-engine-keep-flickering --- # ❓ Why my custom models are not being displayed correctly? ## Answers ### Messed up Crate Model If you're using a dynamic resource pack handler like ItemsAdder, Oraxen, Nexo or Vanilla Resourcepack, ensure it properly manages Model Engine models. Issues are not caused by our crates plugin but may arise if custom assets and Model Engine resources are unintentionally combined. Verify that your Resourcepack folder doesn’t contain files related to Model Engine to avoid synchronization issues with custom model data. Below is a photo of what was happening to one of our users: <figure><img src="../../.gitbook/assets/image (33).png" alt=""><figcaption></figcaption></figure> ### Smaller / Bigger Crate than the original model If you're using custom models, they might appear too small or too large when imported into Phoenix Crates with the vanilla model engine. Phoenix Crates uses armor stands to display models. To fix this, open the model in BlockBench, go to the Display tab, and adjust the size for when it's placed on an armor stand head. Below is a photo of what was happening on one of our users: <figure><img src="../../.gitbook/assets/image (15).png" alt="" width="563"><figcaption></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-my-custom-models-are-not-being-displayed-correctly --- # ❓ Why my furniture models are being destroyed when clicked? ## Answer PhoenixCrates doesn't have a direct support for furniture models, if you are using the Vanilla Model Engine for your crate, you will need to convert the furniture model into an item with custom model data. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-my-furniture-models-are-being-destroyed-when-clicked --- # ❓ Why when using the chat from the editor there are color to the value? ## Answer This issue is caused by a prefix or chat color plugin that isn't formatting correctly. To fix it, disable your chat color or manually edit it in the crates file. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/why-when-using-the-chat-from-the-editor-there-are-color-to-the-value --- # ❓ Will renaming a crate, key or reward lose player progress? ## Answer Yes. Identifiers are what the database uses to tie progress to a crate, key, reward or rarity, so changing one leaves the old records pointing at something that no longer exists. Concretely, changing an identifier drops: * **Crate** - open cooldowns, opened counts and rerolls for that crate. * **Key** - every player's virtual keys of that key. * **Reward** - win counts and win limit cooldowns for that reward. * **Rarity** - the rarity link on every reward and key using it. Display names are a different thing entirely and are safe to change whenever you like, so rename the display name rather than the identifier if you just want it to read differently in game. Pick your identifiers before the crate goes live and leave them alone afterwards. If you must change one, do it while nobody has progress worth keeping. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/questions-and-answers/will-renaming-a-crate-or-reward-lose-player-progress --- # 📒 Version Support ## Version Support <a href="#version-support" id="version-support"></a> The plugin supports Spigot, any Spigot forks, Paper, any Paper forks, and Folia. It should also work on any custom modded servers. <table><thead><tr><th>Minecraft Version</th><th data-type="checkbox"></th></tr></thead><tbody><tr><td>26.x</td><td>true</td></tr><tr><td>1.21.x</td><td>true</td></tr><tr><td>1.20.4+</td><td>true</td></tr> </table> > As of version 6.0, PhoenixCrates supports 1.20.4+, support for versions lower than that has been dropped. Source: https://www.phoenixplugins.com/docs/phoenix-crates/plugin-information/version-support --- # 🏠 Homepage ## Introduction Phoenix Crates is a unique plugin that provides players with a fun and user-friendly way to add crates to their server. It offers a wide variety of animations, from simple opening and closing to more elaborate effects, all designed to enhance the player's experience. With its intuitive interface, players of all skill levels can easily incorporate these animations. This plugin allows players to elevate their server and create a more exciting, dynamic world. ## Documentation This doc page includes every feature provided by the plugin, both in the free and premium versions. Be sure to take an in-depth look, and if you have any questions or suggestions, feel free to contact our team. - Every feature exclusive to the Premium version is marked with a ⭐ - Every feature exclusive added via an add-on is marked with a 💎 ## Premium Version In the following table, you can see the additional perks available with the premium version of PhoenixCrates. ### Purchase Phoenix Crates from our [Website](https://www.phoenixplugins.com/phoenix-crates) <table data-full-width="false"><thead><tr><th>Free Version</th><th>Premium Plan Extra Perks</th></tr></thead> <tbody><tr><td>Crates Limit 5</td><td>Unlimited Crates</td></tr> <tr><td>Keys Limit 5</td><td>Unlimited Keys</td></tr> <tr><td>25 Opening Animations</td><td>36 Opening Animations</td></tr> <tr><td>1 Keys Linked per Crate</td><td>Unlimited Keys linked</td></tr> <tr><td>Open Cost: None, Level, Vault</td><td>PlayerPoints, VotingPlugin, ExcellentEconomy, PhoenixCurrencies</td></tr> <tr><td>Max Win Rewards 5</td><td>Max Win Rewards 30</td> <tr><td>No Keys priority</td><td>Has Key priority</td></tr> <tr><td>No Share with Everyone Online</td><td>Includes Share with Everyone</td></tr> <tr><td>No Reward cooldowns</td><td>Has Reward cooldowns</td></tr> <tr><td>No Win Item/Command Amount</td><td>Has Win Item/Command Amount</td></tr> <tr><td>No Rerolls</td><td>Includes Rerolls Feature</td></tr> <tr><td>No Clone Crate </td><td>Includes Clone Crate</td></tr> <tr><td>Global Broadcast</td><td>Per Create Broadcast</td></tr> <tr><td>Reward Notification: Chat</td><td>Chat, Action Bar</td></tr> <tr><td>No Toggle Reward Win Message</td><td>Includes Reward Message Toggling</td></tr> <tr><td>Add Rewards Manually</td><td>Add Multiple Rewards</td></tr> <tr><td>SQLite Database Support</td><td>MySQL Database Support</td></tr> <tr><td>Doesn't Include API</td><td>Public API</td></tr> <tr><td>Not An Option to Install Add-ons</td><td>Install Add-ons to the Plugin</td></tr> <tr><td>Community Based Support</td><td>Specialized Support</td></tr> <tr><td>Response Time ( NO ETA )</td><td>Response Time ( 1-48 Hours )</td></tr> <tr><td>Hot Fixes ( NO ETA )</td><td>Bug Fixes ( 1-7 Days )</td></tr> <tr><td>Doesn't Include a Discord Role</td><td>Discord Role</td></tr></tbody></table> The premium version includes all the features of the free version, along with additional premium features. ## Bug Reports Before reporting an issue to our team, make sure you have tested the latest available build. If you are experiencing an issue on an older version, it will likely not be checked by our team. <figure><img src=".gitbook/assets/Phoenix_Thumbnail_Crates.png" alt="" width="563"><figcaption><p>Phoenix Crates</p></figcaption></figure> Source: https://www.phoenixplugins.com/docs/phoenix-crates