SMP Crates

SMP Crates
Folia-supported DonutCrates-style crate system for Survival, SMP, PvP, Factions, and competitive Minecraft networks

Donut-style choose-one reward crates. Virtual keys. Physical keys. KeyAll. Crate blocks. Preview menus. Confirm menus. Holograms. PlaceholderAPI. MySQL. Filesystem storage. Full customization.

Bukkit • Spigot • Paper • Purpur • Folia • PlaceholderAPI • FancyHolograms • DecentHolograms

What is SMP Crates?

SMP Crates is a high-performance Minecraft crate plugin built for SMP servers that want a DonutCrates-style crate experience without fragile behavior, hardcoded rewards, or limited customization.

Players can hold virtual keys, receive physical key items, right-click linked crate blocks, preview rewards, choose one reward from a configurable crate inventory, confirm the selected reward, and claim items or command rewards. Staff can create crate locations, edit hologram lines, give or remove keys, run keyalls, view player history, and import legacy key data.

The plugin is designed around clean production behavior: Folia-safe scheduling, async storage, indexed crate locations, per-player key caches, configurable hologram backends, and per-crate YAML files that are easy to edit.

Result: Donut-style crate UX, ArkFlame-grade implementation, Folia support, and full server-owner control.

DonutCrates-style Gameplay

Choose-one reward flow — players open a crate, view rewards, select the reward they want, and claim it.
Preview support — left-click crate blocks to inspect rewards without spending a key.
Right-click open flow — right-click linked crate blocks to open the reward selection menu.
Confirm menu — optional confirmation GUI prevents accidental reward claims.
Physical keys — give players real key items with hidden plugin markers.
Virtual keys — store keys in player data and show counts through menus, holograms, and placeholders.
Virtual-first or physical-first behavior — configure whether virtual keys are consumed before physical keys.
Open-without-key preview option — optionally allow locked crate menus so players can see what they are missing.
Opening announcements — broadcast configurable messages when players claim rewards.

Default Crates Included

SMP Crates ships with ready-to-edit Donut-style crate files. Each crate has its own block material, display name, key item, menu layout, hologram sections, rewards, and opening announcement.

common-crate — starter green crate using a lime shulker-box style, diamond gear/items, and a 4-row reward menu.
rare-crate — upgraded green crate with stronger diamond-tier rewards and a 4-row reward menu.
gold-crate — spawner-focused gold crate using a yellow shulker-box style and a compact 4-row reward menu.
amethyst-crate — premium amethyst crate with custom tools, commands, potions, special items, and a 4-row reward menu.
crimson-crate — red/netherite-style crate with stronger PvP and progression rewards.
prime-crate — high-tier light-blue crate with a larger 5-row menu and more reward slots.
ultimate-crate — cyan ultimate crate with high-value combat, utility, and progression rewards.

Every crate is a YAML file under plugins/SMPCrates/crates/. Add, delete, copy, rename, or redesign crates without touching code.

Crate Blocks and Location Linking

Place-to-link crate blocks — /smpcrates get <crate> gives a hidden-marker crate placement item.
Automatic crate linking — placing the crate item links that world position to the crate ID.
Indexed location lookup — crate block interactions are resolved through a location index instead of scanning.
Protected crate blocks — linked crate blocks are protected from breaking unless the player has permission.
/smpcrates setcrate — link the block you are looking at to a crate.
/smpcrates removecrate — remove a crate link from the block you are looking at.
Invalid-world cleanup option — configure how loaded locations behave when worlds or crates are missing.
Hologram rebuild on link/remove — holograms are rebuilt when crate locations change.

Reward System

Rewards are fully controlled from crate YAML files.

Inventory slot control — place each reward in an exact menu slot.
Physical item rewards — give the configured icon/item directly when no commands are configured.
Command rewards — run console commands when the player selects a reward.
Reward placeholders — commands and messages can use %player%, %crate%, %crate_id%, %reward%, and %reward_id%.
Opening announcement messages — broadcast configurable reward announcements.
Inventory-full protection — physical reward claims check inventory space before consuming the reward flow.
Reward history — claimed rewards are recorded in player history when keys are consumed.
Review mode — admins can open crate review menus without consuming player keys.

Advanced Item Configuration

SMP Crates supports simple items and advanced serialized items.

material — any supported Bukkit/Spigot/Paper material name with compatibility fallback.
name — MiniMessage or legacy-colored display names.
lore — configurable multi-line lore.
amount — stack size control.
enchantments — configurable enchantment maps.
item flags — hide attributes, enchantments, unbreakable state, and other metadata where supported.
custom-model-data — modern resource-pack item model support by reflection.
base64 / serialized item data — preserve complex custom items from modern Bukkit serialization.
skull-base64 / texture — custom head texture support.
trim material / trim pattern — armor-trim support through modern reflective compatibility.
hidden plugin markers — crate items and keys can be tagged so normal items cannot fake crate behavior.

The plugin uses compatibility utilities instead of modern-only hard imports, keeping legacy and modern server support cleaner.

Virtual and Physical Keys

Virtual key storage — player keys are stored by UUID and crate ID.
Physical key items — give players real key items with configurable display and lore.
Offline-safe virtual keys — /smpcrates givekey and /smpcrates removekey can work through stored UUID data.
Online physical keys — /smpcrates givephysicalkey gives real key items to online players.
Inventory protection options — optionally prevent dropping or moving physical keys.
Hidden-marker physical keys — prevent normal tripwire hooks from acting as crate keys.
Virtual-before-physical toggle — configure which key type is consumed first.
Key history — received, removed, physical, and claimed actions can be recorded.

Menus and Player UX

Reward selection menu — players choose the reward they want from the crate inventory.
Preview menu — players can inspect crate rewards before opening.
Review menu — staff can open a crate review for another player.
Confirm menu — optional final confirmation before claiming the selected reward.
History menu — view crate history entries with crate, action, amount, reward, and timestamp.
Admin menu holder — admin-focused menu structure for crate management workflows.
Configurable rows — crate inventories can use 1–6 rows, with Prime using an extra row by default.
Configurable background items — each crate can define its own background icon.
Click-safe handling — crate menu clicks are cancelled and routed through explicit menu holders.

Hologram System

SMP Crates includes a configurable hologram layer for crate locations.

FancyHolograms support — preferred backend when installed.
DecentHolograms support — fallback backend when FancyHolograms is not present.
No forced hologram dependency — if no backend exists, crates still work without holograms.
Per-crate hologram sections — multiple vertical sections per crate, each with its own height and lines.
Per-line formatting — each line can override scale, background, shadow, see-through, billboard, alignment, brightness, and offset.
Global hologram defaults — configure common scale, background, text shadow, spacing, refresh, and offset once.
Placeholder lines — key counts and countdowns can be shown through PlaceholderAPI-compatible placeholders.
Command editing — add, set, delete, and adjust hologram lines from commands.

scale — per-line text scale.
background — transparent or backend-supported background values.
text-shadow — text shadow toggle.
see-through — visibility behavior where supported.
billboard — center/fixed/facing behavior depending on backend.
text-alignment — line alignment where supported.
shadow-strength and shadow-radius — advanced text shadow tuning where supported.
brightness block/sky — optional brightness override for modern hologram backends.
y-offset and global offset[/B] — precise vertical alignment for all crate holograms.

PlaceholderAPI Support

%smpcrates_<crateId>% — returns the player virtual key count for a crate.
%smpcrates_<crateId>_keys% — alias for the same key count.
%smpcrates_keyall_countdown% — returns the next automatic keyall countdown.
%donut_<crateId>% — optional Donut-style placeholder alias.
%donut_keyall_countdown% — optional Donut-style keyall countdown alias.
Non-blocking expansion — uncached players return a safe fallback instead of blocking database I/O.
Hologram placeholder preservation — hologram lines preserve PAPI placeholders for backend rendering.

The Donut alias can be enabled or disabled in config.yml with placeholderapi.register-donut-alias.

Automatic KeyAll

Timed automatic keyall — run automatic key distribution on a configured interval.
Multiple crate keys — configure which crate IDs and amounts are distributed.
Virtual or physical mode — send stored keys or physical key items.
Permission filter — optionally give keys only to players with a permission.
Alert messages — configurable messages when players receive automatic keys.
Sound support — configurable sound aliases, volume, and pitch.
Title/subtitle/actionbar support — configurable visual alerts for keyall events.
Countdown placeholder — expose remaining time through PlaceholderAPI.

Storage and Performance

SMP Crates is built for production servers where key data and reward history must not lag gameplay.

Filesystem storage — default per-player YAML files under data/players/<uuid>.yml.
MySQL storage — optional MySQL backend with automatic table creation.
HikariCP — pooled MySQL connections shaded into the plugin.
Async persistence — storage saves and loads run through an I/O executor instead of blocking gameplay.
Cached player data — online players use cached key counts for quick crate opening and placeholders.
Shutdown save wait — configurable timeout to flush player data on disable.
History cap — configurable maximum history entries per player.
Fallback-to-filesystem option — configurable safety fallback if MySQL initialization fails.
Location index — crate block lookup uses indexed block positions instead of scanning the world.

Folia, Paper, Spigot, Bukkit, Purpur

Folia supported — plugin.yml declares folia-supported: true.
Folia-aware scheduling — entity, region, global, async, and delayed tasks are routed through SchedulerService.
No direct Folia compile dependency — Folia APIs are detected reflectively to keep shared code compatible.
Java 8 target — source and bytecode target Java 8.
Bukkit/Spigot/Paper 1.8–1.21+ style compatibility — compiled against Spigot 1.8.8 API with modern features accessed carefully.
api-version: 1.13 — configured for modern Bukkit-family servers while keeping legacy fallback behavior.
Modern feature reflection — custom model data, trims, modern materials, skull textures, and scheduler behavior are handled through compatibility utilities.

Commands

/smpcrates help — show command help.
/smpcrates reload — reload configuration, crates, language files, holograms, and services.
/smpcrates version — show plugin version.
/smpcrates list — list configured crates.
/smpcrates get <crate> [amount] — get crate placement item(s).
/smpcrates give <player> <crate> [amount] [physical|virtual] — give keys with short alias syntax.
/smpcrates givekey <player> <crate> [amount] [physical|virtual] — give virtual or physical keys.
/smpcrates removekey <player> <crate> [amount] — remove virtual keys.
/smpcrates givephysicalkey <player> <crate> [amount] — give physical key items to an online player.
/smpcrates keyall <crate> [amount] [permission] [physical|virtual] — give keys to online players.
/smpcrates openreview <player> <crate> — open a crate review menu for a player.
/smpcrates history [player] [page] — view crate/key history.
/smpcrates import [dry] [delete] — import legacy keys.yml data.
/smpcrates setcrate <crate> — link the targeted block to a crate.
/smpcrates removecrate — remove the targeted crate link.
/smpcrates hologram addline <crate> <section> <line> — add a hologram line.
/smpcrates hologram setline <crate> <section> <index> <line> — edit a hologram line.
/smpcrates hologram delline <crate> <section> <index> — delete a hologram line.
/smpcrates hologram setoption <crate> <section> <line> <option> <value> — set line-level hologram options.
/smpcrates hologram deloption <crate> <section> <line> <option> — remove line-level hologram options.

smpcrates.admin — full administration access.
smpcrates.reload — reload plugin files.
smpcrates.version — view plugin version.
smpcrates.list — list crates.
smpcrates.get — get crate placement items.
smpcrates.givekey — give virtual or physical keys.
smpcrates.removekey — remove keys.
smpcrates.givephysicalkey — give physical key items.
smpcrates.keyall — run keyall.
smpcrates.openreview — open review menus.
smpcrates.history — view key/reward history.
smpcrates.import — import legacy key data.
smpcrates.place — link crate blocks.
smpcrates.break — remove linked crate blocks.
smpcrates.hologram — edit holograms.

Configuration Files

SMP Crates is configuration-first. Server owners can control crate files, menus, holograms, languages, keys, storage, placeholders, automatic keyalls, and database behavior.

config.yml — language settings, storage, locations, interactions, menus, holograms, PlaceholderAPI, key behavior, automatic keyall, and database settings.
lang/en.yml — English messages, menus, command help, and history labels.
lang/es.yml — Spanish language file.
crates/common-crate.yml — Common crate configuration.
crates/rare-crate.yml — Rare crate configuration.
crates/gold-crate.yml — Gold crate configuration.
crates/amethyst-crate.yml — Amethyst crate configuration.
crates/crimson-crate.yml — Crimson crate configuration.
crates/prime-crate.yml — Prime crate configuration.
crates/ultimate-crate.yml — Ultimate crate configuration.
data/players/<uuid>.yml — filesystem player key/history data when filesystem storage is enabled.
data/locations.yml — crate block location index.
data/keys.yml — legacy key file import source.

display-name — crate name shown in menus, messages, holograms, and announcements.
permission — optional permission required to open a crate.
icon — crate placement/admin icon.
block-materials — allowed block materials for linked crate blocks.
inventory — menu title, rows, background icon, and layout.
key-item — physical key material, name, lore, and amount.
hologram — per-section heights and lines.
opening-announcement — broadcast messages when rewards are claimed.
rewards — slot, icon, commands, amount, and reward behavior.

settings — language, fallback language, locale auto-detect, and debug.
storage — filesystem/MySQL mode, save delay, shutdown save timeout, and history cap.
locations — missing crate/world cleanup rules.
interaction — sneaking behavior and locked crate menu behavior.
menus — confirm menu and history menu configuration.
holograms — backend priority, line format, spacing, global offset, and default render options.
placeholderapi — PlaceholderAPI and Donut alias settings.
keys — physical/virtual key behavior and protection options.
automatic-key-all — scheduled key distribution and alerts.
database — MySQL connection, pool, and thread settings.

Integrations

PlaceholderAPI — optional placeholders for key counts and keyall countdowns.
FancyHolograms — optional hologram backend with modern render options.
DecentHolograms — optional hologram backend fallback.
MySQL — optional persistent database storage.
HikariCP — shaded connection pool for MySQL mode.
MiniMessage — modern text formatting in names, lore, menus, and messages.
Legacy color support — accepts & and § formatting where needed.

Why Choose SMP Crates?

Donut-style crate system — familiar choose-one reward flow for SMP players.
Folia supported — scheduler code is designed for modern threaded servers.
High-performance storage — async I/O, cached key data, optional MySQL, and indexed crate locations.
Full customization — every crate, reward, key, menu, hologram, message, and placeholder can be configured.
Virtual and physical keys — support both modern stored keys and classic key items.
Hologram control — FancyHolograms/DecentHolograms support with per-line scale, shadows, backgrounds, and offsets.
Production admin tools — keyall, offline key management, history, review menus, import tools, crate linking, and hologram editing.
Cross-version design — Java 8, Bukkit-family compatibility, modern feature reflection, and legacy-safe fallbacks.
ArkFlame ecosystem quality — built for real SMP networks, not one-off test servers.

FAQ

Is SMP Crates a DonutCrates-style plugin?
Yes. SMP Crates is designed around a Donut-style crate workflow: players use keys, open a crate, choose one reward, and claim it through a clean menu flow.

Is it affiliated with DonutSMP?
No. SMP Crates is an independent ArkFlame Studios plugin inspired by the popular Donut-style crate format.

Does it support Folia?
Yes. The plugin declares folia-supported: true and uses a scheduler service for Folia-aware entity, region, global, delayed, and async tasks.

Does it require PlaceholderAPI?
No. PlaceholderAPI is optional. When installed, SMP Crates registers key-count and keyall countdown placeholders.

Does it require FancyHolograms or DecentHolograms?
No. Holograms are optional. If FancyHolograms or DecentHolograms is installed, SMP Crates can use them. If no hologram backend exists, crates still work.

Can I use physical keys?
Yes. Physical key items are supported and can use hidden markers to prevent fake keys.

Can I use virtual keys?
Yes. Virtual keys are stored per player and crate ID.

Can I give keys to offline players?
Yes. Virtual key give/remove operations are offline-safe through UUID-backed storage.

Can I use MySQL?
Yes. SMP Crates supports filesystem storage by default and optional MySQL storage with HikariCP.

Can I edit rewards?
Yes. Rewards are defined in crate YAML files with exact slots, icons, item data, commands, and reward behavior.

Can I add more crate types?
Yes. Copy an existing crate YAML file, change the crate ID/file name, edit the display, block, key, inventory, hologram, and rewards, then reload.

Can players preview crates?
Yes. Left-clicking linked crate blocks opens the preview menu.

Can I protect crate blocks?
Yes. Linked crate blocks are protected unless the player has smpcrates.break.

Bring Donut-style crates to your SMP with production-grade control.
Install SMP Crates, configure your crate files, link crate blocks, add holograms, and run a fast Folia-supported crate system with virtual keys, physical keys, KeyAll, menus, and full customization.

SEO keywords: SMP Crates, Donut Crates replica, DonutCrates-style plugin, Minecraft crate plugin, Minecraft crates, SMP crate plugin, Folia crates plugin, Paper crates plugin, Spigot crates plugin, Bukkit crates plugin, Purpur crates plugin, virtual keys plugin, physical keys plugin, Minecraft keyall plugin, PlaceholderAPI crates, FancyHolograms crates, DecentHolograms crates, MySQL crates plugin, crate holograms, Minecraft reward crates, choose one reward crates, DonutSMP crates, ArkFlame crates, high performance crates plugin, full customization crates.

SMP Crates v1.0.1

Overview Dependencies Updates (1) History