Smart Crates
适用于 PaperMC 1.21 – 1.21.4 的现代、生产就绪的箱子系统,采用独特的双模式设计:轮盘赌风格的经典抽取 (Classic Roll) 和玩家驱动的选择奖励 (Choose Reward) 模式——此外还包含浮动全息图、不可见的虚拟钥匙以及每个箱子自带的免费奖励预览菜单。
✨ 功能特性
- ? 模式 1 — 经典抽取 (Classic Roll):滚动的奖励条减速并停在加权随机的奖励上,带有发光指针标记
- ?️ 模式 2 — 选择奖励 (Choose Reward):玩家打开菜单并手动选择奖励(可选确认屏幕,忽略概率)
- ? 奖励预览:右键点击任意箱子即可查看所有奖励而无需消耗钥匙,然后直接从预览中开启——根据模式不同,支持动画效果、即时开启或通过选择菜单进行
- ?️ 全息图:放置在每个箱子上的浮动标签(使用原版 TextDisplay,无依赖项),每个箱子的配置文件均可完全自定义配置
- ? 自定义箱子纹理:在箱子文件中设置
block-custom-model-data(配合资源包),箱子上方会出现带有你纹理的浮动物品
- ? 虚拟钥匙:在每个箱子文件中设置
virtual-keys: true,将物理物品替换为不可见的玩家专属余额(以货币形式存储),并在箱子上方实时显示为*“你有 X 把钥匙!”*
- ?️ 一箱一文件:每个箱子都拥有自己的
crates/<id>.yml 文件——复制、重命名、编辑,然后执行 /sc reload
- ? 安全钥匙:材质、名称、描述、自定义模型数据、发光效果 + 防伪造
PersistentDataContainer 标签
- ? 实体箱子:通过
/sc set <id> 将任何方块变成箱子(重启后保存在 data/crates.yml 中)
- ? 强大奖励:物品、自定义名称/描述、数量、附魔、自定义模型数据以及多条控制台命令,支持
%player% 占位符
- ? 可配置的音效与粒子效果:针对每个事件(或设置为
NONE 以禁用)
- ?️ 防作弊:拒绝假钥匙、阻止点击/shift-点击/拖拽、单次开启锁定、钥匙仅被消耗一次、断开连接安全的抽取机制
- ? 颜色支持:传统
& 代码和十六进制颜色 (&#RRGGBB, <#RRGGBB>)
- ? 全量可配置:所有消息、GUI 大小、填充物、按钮、动画速度等均可自定义
? 玩家使用方法
- 左键点击持有对应钥匙(或拥有虚拟余额)时的箱子方块 → 直接开启箱子
- 右键点击箱子方块 → 免费预览所有奖励及开启按钮(无需钥匙即可查看)
- 模式 1:观看滚动结果并赢取奖励——或使用快速开启 (Quick Open) 跳过动画
- 模式 2:选择你的奖励并确认
?️ 命令
别名:/scrates, /sc。完整制表符补全支持。
| 命令 |
描述 |
/sc list |
显示所有箱子及其模式 |
/sc create <id> |
在 crates/<id>.yml 创建新箱子文件 |
/sc delete <id> |
删除箱子及其文件 |
/sc setname <id> <name> |
更改箱子显示名称(允许使用 & 和十六进制颜色) |
/sc setgui <id> <name> |
更改库存窗口标题 |
/sc setmode <id> <1|2> |
1 = 经典抽取,2 = 选择奖励 |
/sc edit <crate> |
在 Minecraft 菜单中编辑箱子(绿色染料用于保存) |
/sc set <id> |
将你注视的方块设置为该箱子 |
/sc remove [crate] |
解除注视方块的绑定,或解除某个箱子的所有方块绑定 |
/sc givekey <player> <crate> [amount] |
给一名玩家发放钥匙 |
/sc givekeyall <crate> [amount] |
给所有在线玩家发放钥匙 |
/sc reload |
重载配置、消息和所有箱子文件 |
/sc help |
游戏内命令指南 |
? 权限
| 权限节点 |
描述 |
默认值 |
smartcrates.admin |
完全访问权限(包含以下所有权限) |
op |
smartcrates.create |
创建箱子 |
op |
smartcrates.delete |
删除箱子 |
op |
smartcrates.reload |
重载插件 |
op |
smartcrates.givekey |
给玩家发放钥匙 |
op |
smartcrates.givekeyall |
给所有人发放钥匙 |
op |
? 快速设置
- 将 jar 文件放入
plugins/ 目录并重启服务器——示例箱子(basic, epic, legendary, vote, summer)会自动生成
- 执行
/sc create mycrate,编辑 plugins/SmartCrates/crates/mycrate.yml,然后执行 /sc reload
- 注视一个方块并运行
/sc set mycrate
- 执行
/sc givekey Steve mycrate 3 ——完成!
? 文件结构
plugins/SmartCrates/
├── config.yml # 全局设置、GUI、音效、动画、预览点击
├── messages.yml # 所有消息 + 帮助行
├── crates/ # 每个箱子一个文件(basic.yml, epic.yml, ...)
├── data/crates.yml # 已放置的箱子方块
└── data/virtualkeys.yml # 虚拟钥匙余额
❓ 常见问题
支持哪些版本?
PaperMC 1.21 – 1.21.4,需 Java 21。
我需要数据库吗?
不需要。所有内容均存储在本地 YAML 文件中。
玩家可以在没有钥匙的情况下预览吗?
可以——预览(默认为右键点击)是免费的。只有在实际开启时才会消耗钥匙。
我可以更改右键点击的功能吗?
可以——在 config.yml 中的 preview.click 选项:RIGHT_CLICK(默认)、LEFT_CLICK、SHIFT_LEFT_CLICK 或 SHIFT_RIGHT_CLICK。另一种点击方式始终直接开启。
虚拟钥匙是如何工作的?
在箱子文件中设置 virtual-keys: true。此时 /sc givekey 会添加不可见的余额而非物品,开启时会从中扣除。箱子上方的全息图会显示每位玩家的独立余额。同时支持模式 1 和模式 2。
自定义箱子纹理是如何工作的?
原版方块无法携带 CustomModelData,因此 SmartCrates 会在箱子上方显示为你纹理的浮动发光物品(使用原版 ItemDisplay)。将 block-custom-model-data 设置为资源包中的数值(加上 block-display-material 和 block-display-height),运行 /sc reload ——完成。设置为 0 则禁用此功能。
我的旧版 config.yml 中有 crates: 部分——这会破坏兼容性吗?
不会。1.1.0+ 版本会在首次启动时自动将其迁移到 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
- Left-click a crate block with its key (or virtual balance) → opens the crate directly
- Right-click a crate block → free preview of all rewards with open buttons (no key needed to look)
- Mode 1: watch the roll and win — or use Quick Open to skip the animation
- 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
- Drop the jar into
plugins/ and restart — example crates (basic, epic, legendary, vote, summer) generate automatically
/sc create mycrate, edit plugins/SmartCrates/crates/mycrate.yml, /sc reload
- Look at a block and run
/sc set mycrate
/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.
评论 0
登录后参与评分
还没有评论,来抢沙发吧