Smart Crates

# Smart Crates

A modern, production-ready **crate system** for **PaperMC 1.21 – 1.21.4** with a unique **dual-mode** design: a roulette-style **Classic Roll** and a player-driven **Choose Reward** mode — plus floating **holograms**, invisible **virtual keys** and a free **reward preview** menu on every crate.

## ✨ Features

- **Mode 1 — Classic Roll**: a scrolling reward strip slows down and lands on a weighted-random reward, marked with glowing pointers
- ️ **Mode 2 — Choose Reward**: the player opens a menu and picks a reward manually (optional confirmation screen, chances ignored)
- **Reward preview**: right-click any crate to see all rewards without spending a key, then open straight from the preview — with animation, instantly, or via the choose menu depending on the mode
- ️ **Holograms**: floating labels above every placed crate (vanilla TextDisplay, no dependencies), fully configurable per crate file
- **Custom crate textures**: set `block-custom-model-data` in a crate file (with a resource pack) and a floating item with your texture appears above the crate
- **Virtual keys**: per-crate `virtual-keys: true` replaces physical items with invisible per-player balances (stored as currency), shown live above the crate as *"You have X keys!"*
- ️ **One file per crate**: every crate lives in its own `crates/<id>.yml` — copy, rename, edit, `/sc reload`
- **Secure keys**: material, name, lore, custom model data, glow + anti-fake `PersistentDataContainer` tag
- **Physical crates**: turn any block into a crate with `/sc set <id>` (survives restarts in `data/crates.yml`)
- **Powerful rewards**: items, custom names/lore, amounts, enchantments, custom model data and **multiple console commands** with `%player%`
- **Configurable sounds & particles** for every event (or `NONE` to disable)
- ️ **Anti-exploit**: fake-key rejection, click/shift-click/drag blocking, single-opening lock, key consumed exactly once, disconnect-safe rolls
- **Colors**: legacy `&` codes and hex (`&#RRGGBB`, `<#RRGGBB>`)
- **Everything configurable**: all messages, GUI sizes, filler, buttons, animation speed

## How players use it

1. **Left-click** a crate block with its key (or virtual balance) → opens the crate directly
2. **Right-click** a crate block → free **preview** of all rewards with open buttons (no key needed to look)
3. Mode 1: watch the roll and win — or use **Quick Open** to skip the animation
4. Mode 2: pick your reward and confirm

## ️ Commands

Aliases: `/scrates`, `/sc`. Full tab-completion included.

| Command | Description |
|---|---|
| `/sc list` | Show all crates and their modes |
| `/sc create <id>` | Create a new crate file in `crates/<id>.yml` |
| `/sc delete <id>` | Delete a crate and its file |
| `/sc setname <id> <name>` | Change the crate display name (`&` and hex colors allowed) |
| `/sc setgui <id> <name>` | Change the inventory window title |
| `/sc setmode <id> <1\|2>` | `1` = Classic roll, `2` = Choose Reward |
| `/sc edit <crate>` | Edit the crate in a Minecraft menu (green dye saves) |
| `/sc set <id>` | Turn the block you are looking at into this crate |
| `/sc remove [crate]` | Unbind the looked-at block, or all blocks of a crate |
| `/sc givekey <player> <crate> [amount]` | Give key(s) to one player |
| `/sc givekeyall <crate> [amount]` | Give key(s) to every online player |
| `/sc reload` | Reload config, messages and all crate files |
| `/sc help` | In-game command guide |

## Permissions

| Permission | Description | Default |
|---|---|---|
| `smartcrates.admin` | Full access (parent of all below) | op |
| `smartcrates.create` | Create crates | op |
| `smartcrates.delete` | Delete crates | op |
| `smartcrates.reload` | Reload the plugin | op |
| `smartcrates.givekey` | Give keys to a player | op |
| `smartcrates.givekeyall` | Give keys to everyone | op |

## Quick setup

1. Drop the jar into `plugins/` and restart — example crates (`basic`, `epic`, `legendary`, `vote`, `summer`) generate automatically
2. `/sc create mycrate`, edit `plugins/SmartCrates/crates/mycrate.yml`, `/sc reload`
3. Look at a block and run `/sc set mycrate`
4. `/sc givekey Steve mycrate 3` — done!

## Files

```
plugins/SmartCrates/
├── config.yml # global settings, GUI, sounds, animation, preview click
├── messages.yml # all messages + help lines
├── crates/ # one file per crate (basic.yml, epic.yml, ...)
├── data/crates.yml # placed crate blocks
└── data/virtualkeys.yml # virtual key balances
```

## ❓ FAQ

**Which versions are supported?**
PaperMC 1.21 – 1.21.4 with Java 21.

**Do I need a database?**
No. Everything is stored in local YAML files.

**Can players preview without a key?**
Yes — the preview (right-click by default) is free. A key is consumed only when actually opening.

**Can I change what right-click does?**
Yes — `preview.click` in `config.yml`: `RIGHT_CLICK` (default), `LEFT_CLICK`, `SHIFT_LEFT_CLICK` or `SHIFT_RIGHT_CLICK`. The other click always opens directly.

**How do virtual keys work?**
Set `virtual-keys: true` in a crate file. `/sc givekey` then adds invisible balance instead of items, and opening consumes from it. The hologram above the crate shows each player's own balance. Works with both Mode 1 and Mode 2.

**How do custom crate textures work?**
Vanilla blocks can't carry CustomModelData, so SmartCrates shows your texture as a floating glowing item above the crate (vanilla ItemDisplay). Set `block-custom-model-data` to your resource pack's number (plus `block-display-material` and `block-display-height`), run `/sc reload` — done. `0` disables it.

**My old config.yml has a `crates:` section — will it break?**
No. Version 1.1.0+ migrates it automatically into the `crates/` folder on first start.