SchackCrates

Animated crates for Paper servers that you can set up without leaving the game.

You make a crate, click items in your inventory to add them as rewards, pick an animation and place the crate wherever you want. You never have to touch YAML if you don't want to. If you do like config files, everything is still there, cleanly laid out and commented.

Besides normal crates there are also Case Battles. 2 to 4 players open the same crates at once, and whoever pulls the highest total value walks away with everything.

Features

• 12 opening animations: 6 in a GUI, 5 in 3D above the crate, and an instant option
• Everything is editable in game: crates, rewards, chances, rarities, keys, holograms, particles and global settings
• Case Battles for 2-4 players, with a lobby, live reels and a shared pot
• Pity system, so after X unlucky openings a player is guaranteed something of a chosen rarity
• Server-wide reward limits (for example, only 5 beacons can ever be won)
• Stats and history: personal and server stats, recent wins, top lists, and real vs. configured chances side by side
• Holograms and idle particles built in, using display entities, so you don't need a separate hologram plugin
• Virtual and physical keys. Virtual keys can be given to offline players, which is handy for stores and voting
• 28 PlaceholderAPI placeholders (PAPI is optional)
• English and Polish out of the box. Translating is easy, and language files update without wiping your changes
• Players never lose rewards. The reward is picked before the animation starts, so leaving, closing the GUI, a reload or a restart won't eat it

Animations

Animation	Type	Description
Roulette	GUI	The classic CS:GO row of items that slows down and stops under the pointer
Wheel	GUI	A glowing selector goes around a ring of items
Shuffle	GUI	The center slot cycles through rewards while the frame flashes
Cascade	GUI	Items snake their way into the middle
Choice	GUI	The player picks one of a few hidden rewards
Slots	GUI	A slot machine with three reels that stop one by one
Spin	3D	An item rises out of the crate, spinning through the possible rewards
Orbit	3D	Rewards circle above the crate and smash together into the winning one
Meteor	3D	A meteor crashes into the crate and the reward comes up from the impact
Vortex	3D	Items spin upward in a tornado, then collapse into the reward
Carousel	3D	A wheel of fortune appears above the crate, turned toward the player
Instant	none	Just gives the reward, no animation

You can tweak the speed, sounds, colors and size of each animation in animations.yml.

In-game editor

Run /crates editor and you've got everything in one place.

Rewards. Click any item in your inventory to add it. From there you can set its weight, rarity, amount, name and lore, add extra items, console commands, messages or broadcasts, give it a value, and set a global limit.

Crate. Display name, animation (there's a preview button so you can see it first), key item, hologram lines, particles and their pattern, cooldown, permission, mass opening and the preview menu.

Locations. Place a crate with /crates set <crate> or with a placeable crate block. You can also teleport to locations and remove them from here.

Global settings. Language, key rules, broadcasts, holograms, particles and a few other things.

Changes save right away, no reload needed. All texts support MiniMessage (gradients, hex colors) as well as the old & codes.

Case Battles

Here's how a battle goes:

1. Someone runs /battle and sets it up: which crates are the rounds, how many players (2-4), and whether it's public or private.
2. Every player puts in the same keys, and the plugin holds onto them until the battle ends. Public battles get announced in chat with a clickable [JOIN] button.
3. Once the lobby is full, everyone opens the same crates at the same time in a shared GUI. Each player gets their own reel, and they stop one after another.
4. Whoever has the highest total value takes all the rewards from every player. If it's a tie, a coin flip decides.

If a battle gets cancelled, everyone gets their keys back. Players can leave in the middle of a battle without losing anything, and if a reward doesn't fit in someone's inventory it goes to their stash (/crates claim). A reward's value comes from its rarity by default, but you can also set it by hand for each reward.

Pity, limits and stats

Pity is set per crate. For example, you can make the 30th unlucky opening in a row always give a Legendary or better. Players can check how close they are in the preview and in /keys.

Global limits work like stock. Once a reward has been won as many times as its limit allows, it's removed from the crate and shows up as SOLD OUT.

Stats are available through /crates stats, /crates history and /crates top (most crates opened and most battles won). Each crate also has its own reward stats, where you can see how often something actually dropped compared to the chance you configured.

Commands

Command	Description
/crates editor [crate]	Open the editor
/crates give <player|*> <crate> [amount] [virtual|physical]	Give keys
/crates take <player> <crate> [amount]	Take virtual keys
/crates set <crate> / /crates remove	Turn the block you're looking at into a crate, or remove it
/crates placer <crate>	Get a placeable crate block
/crates open <crate> [player]	Open a crate for free
/crates create <id> / /crates delete <id>	Create or delete a crate
/crates resetpity <player> <crate>	Reset someone's pity counter
/crates resetlimit <crate> <reward>	Reset how many times a limited reward has been won
/crates language <code>	Change the language
/crates version	Check for updates
/crates reload	Reload all files
/crates preview <crate>	Preview rewards
/keys	See your keys
/crates stats [player], /crates history [player|server], /crates top	Stats
/crates claim	Your reward stash
/battle	Case battle lobby (create, join <id>, leave, spectate <id>, invite <player>)

Permissions

Permission	Default	Description
schackcrates.admin	op	Editor and all admin commands (includes everything below)
schackcrates.use	everyone	Open crates
schackcrates.preview	everyone	Preview rewards
schackcrates.keys	everyone	Use /keys
schackcrates.stats	everyone	Own stats, history and top lists
schackcrates.stats.others	op	Other players' stats
schackcrates.battle	everyone	Create, join and watch case battles
schackcrates.bypass.cooldown	op	Skip crate cooldowns
schackcrates.update	op	Update notifications and /crates version

You can also give each crate its own required permission.

PlaceholderAPI

All placeholders start with %schackcrates_. A few of them:

keys_<crate>, opened_total, pity_left_<crate>, cooldown_<crate>, last_win, rank, top_<n>_name, battles_won, limit_<crate>_<reward>, server_opened_total

Getting started

1. Drop the jar into your plugins folder and start the server. Two example crates will be created for you.
2. Look at any block and type /crates set common.
3. Give yourself a few keys with /crates give <your name> common 5.
4. Right-click the crate to open it, left-click to see what's inside, or shift + right-click to use all your keys at once.
5. Open /crates editor and start changing things to fit your server.

Requirements

• Paper or a Paper fork like Purpur, Minecraft 1.21.1
• Java 21 or newer
• PlaceholderAPI if you want placeholders (not required)

Spigot won't work, since the plugin relies on Paper's API.

Other info

All data is saved as YAML in the plugin's data/ folder.

The plugin checks Modrinth for new versions and lets admins know when one is out. If you don't want that, set update-checker.enabled to false in config.yml.

It also uses bStats for anonymous usage stats (number of servers, versions, which features get used). You can turn bStats off for all plugins in plugins/bStats/config.yml.

If you find a bug or have an idea for something new, let me know!