VaultCrates

插件

· 作者 itsLarss_

一个功能丰富、完全动画化的箱子插件,适用于 Paper 1.21.x,支持 IA、Vault、PlaceholderAPI 和 Citizens

6 本站下载 0 关注 更新于 1 天前

最新 1.1.3+26.x · 26.3 · Paper / Purpur

一键开服(送7天)

VaultCrates

一个功能丰富、完全动画化的箱子插件,适用于 Paper 26.x

无需 NMS · 无需遗留库 · 无需外部全息图插件


✨ 特性

  • 12 种独特动画 — 每种风格都配有粒子、音效和视觉效果
  • 实体钥匙与虚拟钥匙 — 带有防复制 UUID 追踪的 NBT 标签物品;虚拟钥匙在数据库中按玩家存储
  • 保底机制 — 可配置每种稀有度在开启 N 次后必定掉落
  • 奖励上限 — 全局和每个玩家的奖励次数上限
  • 虚拟钥匙商店 — 玩家通过 /vc shop 使用游戏内货币购买钥匙(需要 Vault 或 VaultUnlocked)
  • 钱袋 — 可右键点击的奖励袋,支持配置随机数量范围
  • 全息图 — 悬浮的 Text Display 实体,无需外部插件;重启后保持存在
  • 放置 ID 系统 — 每个放置的箱子都会获得唯一 ID;使用 /vc remove <id> 移除它
  • 家具箱子 — 使用 ItemsAdder 家具作为箱子,包括多实体家具(显示 + 碰撞箱)
  • 游戏内 GUI 编辑器 — 无需触碰 YAML 文件即可编辑箱子和钥匙
  • 奖励预览 — 分页 GUI,显示归一化后的掉落百分比;可按箱子切换开关
  • 最佳奖品 — 从独立奖池中滚动的保证额外奖励
  • 捆绑物品 — 在主奖励之外提供多个额外物品
  • 可选奖励 — 玩家可以从 N 个随机选项中挑选自己的奖品
  • 里程碑 — 累计开启 X 次箱子后获得额外奖励
  • 奖励页脚 — 自动追加的文本行,显示奖励类型和稀有度
  • NPC 支持 — Citizens、FancyNpcs、ZNPCsPlus、ZNPCs,或通过 /vc linknpc 链接任意实体
  • 多语言 — 内置英语、德语、法语、西班牙语;添加任何语言只需创建一个 messages_<code>.yml 文件
  • 多数据库 — JSON(默认)、SQLite 或 MySQL,支持自动建表
  • 开发者 API — 自定义事件、编程方式开启箱子、钥匙管理

? 依赖

服务端 Paper(或其分支)26.1.x, 26.2 或 26.3
Java 25+

我需要哪个 jar 包?

你的服务端版本 下载
1.21.x VaultCrates-1.0.1.jar
26.1 – 26.1.x VaultCrates-1.1.0-26.1.x.jar
26.2.x VaultCrates-1.1.1-26.2.jar
26.3.x VaultCrates-1.1.2-26.3.jar

每个 jar 包都会在 Minecraft 版本低于其构建版本时拒绝加载。 对于 Minecraft 1.21.x,请使用 VaultCrates 1.0.1。

可选软依赖

插件 测试的 API 版本 用途
Vault / VaultUnlocked + 经济插件 VaultUnlocked 2.20 钥匙商店、基于经济的箱子
PlaceholderAPI 2.12.3 消息和全息图中的占位符
ItemsAdder 4.0.18 自定义物品、箱子方块及家具、:icon: 字体图片
Oraxen 1.220 自定义方块和物品模型
Nexo 1.29 自定义方块和物品模型
ExecutableItems SCore 5.25 将自定义物品作为奖励
MMOItems 6.10 将自定义物品作为奖励
Citizens 2.0.44 NPC 与箱子绑定
FancyNpcs 2.11 NPC 与箱子绑定
ZNPCsPlus 2.0 NPC 与箱子绑定
ZNPCs legacy NPC 与箱子绑定

所有软依赖均通过反射加载 — VaultCrates 在未安装任何这些依赖的情况下也能正常运行。


? 安装

  1. 选择适合你 Minecraft 版本的 jar 包(见上表),并将其放入 plugins/ 文件夹
  2. 启动或重启服务器 — 示例配置文件会自动生成
  3. 获取一个可放置的箱子:/vc getcrate ExampleRound
  4. 在任何地方放置它 — 全息图会出现,且放置位置会自动保存
  5. 给自己一把钥匙:/vc key give <name> ExampleRound 1
  6. 右键点击箱子以开启

? 命令

所有命令均使用 /vc(别名:/vaultcrates, /crate)。

箱子管理

命令 权限 描述
/vc getcrate <crate> vaultcrates.admin 获取可放置的箱子物品
/vc create <name> vaultcrates.admin 在游戏内创建新的箱子配置
/vc list vaultcrates.admin 列出所有已加载的箱子
/vc errors vaultcrates.admin 显示配置加载错误
/vc reload vaultcrates.admin 重新加载所有配置和全息图
/vc editor <crate> vaultcrates.admin 打开游戏内 GUI 编辑器
/vc keyeditor <crate> vaultcrates.admin 打开游戏内钥匙编辑器

放置管理

命令 权限 描述
/vc placements vaultcrates.admin 列出所有已放置实例及其 ID 和坐标
/vc remove <id> vaultcrates.admin 根据 ID 移除已放置的箱子

提示: 放置宝箱时,放置 ID 会显示在聊天栏中。 方块宝箱: Shift + 左键点击可破坏并移除该方块(需要权限 vaultcrates.admin)。 家具宝箱: Shift + 左键点击仅显示 ID —— 请使用 /vc remove <id> 命令将其移除,以免有人误删宝箱。

物理钥匙(物品)

命令 权限 描述
/vc give <player> <crate> [amount] vaultcrates.give 给予物理钥匙
/vc sgive <player> <crate> [amount] vaultcrates.give 静默给予
/vc giveall <crate> [amount] vaultcrates.give 向所有在线玩家发放

虚拟按键

指令 权限 描述
/vc key give <玩家> <箱子> [数量] vaultcrates.key 添加虚拟钥匙
/vc key sgive <玩家> <箱子> [数量] vaultcrates.key 静默添加
/vc key giveall <箱子> [数量] vaultcrates.key 发送给所有在线玩家
/vc key set <玩家> <箱子> <数量> vaultcrates.key 设置钥匙余额
/vc key balance <player> <crate> vaultcrates.key 查看钥匙余额
/vc key withdraw <player> <crate> [amount] vaultcrates.key 提取虚拟钥匙
/vc shop vaultcrates.shop 打开虚拟钥匙商店

背包

命令 权限 描述
/vc pouch give <player> <pouch> [amount] vaultcrates.pouch 给予一个皮包
/vc pouch sgive <player> <pouch> [amount] vaultcrates.pouch 静默给予
/vc pouch giveall <pouch> [amount] vaultcrates.pouch 给予所有在线玩家
/vc pouch list vaultcrates.pouch 列出所有已加载的皮包

NPC 关联

命令 权限 描述
/vc linknpc <crate> vaultcrates.linknpc 关联最近的实体或 Citizens NPC(需在 3 格范围内)
/vc linknpc <crate> fancynpcs <name> vaultcrates.linknpc 通过名称关联 FancyNpcs NPC
/vc linknpc <crate> znpcsplus <id> vaultcrates.linknpc 通过 ID 关联 ZNPCsPlus NPC
/vc linknpc <crate> znpcs <name> vaultcrates.linknpc 通过名称关联 ZNPCs NPC

FancyNpcs 和 ZNPCsPlus 的 NPC 基于数据包且没有真实的实体,因此通过名称/ID 进行关联。 通过 NPC 开启宝箱需要钥匙,就像直接开启宝箱一样。


? 权限

权限 默认值 描述
vaultcrates.* op 所有权限
vaultcrates.admin op 放置/破坏箱子、重载、编辑器、getcrate、placements、remove
vaultcrates.open true 打开箱子
vaultcrates.give op 发放实体钥匙
vaultcrates.key op 管理虚拟钥匙
vaultcrates.shop true 打开虚拟钥匙商店
vaultcrates.linknpc op 将实体/NPC 与箱子关联
vaultcrates.pouch op 发放钱袋
vaultcrates.bypass op 绕过冷却时间和被阻止的命令

⚙️ 配置

config.yml — 关键设置

# 语言:en(默认)| de | fr | es | 或任何自定义区域代码
Language: en

Storage:
  Type: JSON          # JSON(默认)| SQLITE | MYSQL
  KeyUuidExpiryDays: 365

Settings:
  Cant_Open_Creative: false
  Must_Hold_Key_In_Hand: false
  Cant_Drop_Key: false
  Crate_Radius: 3     # 两个箱子之间的最小距离,0 = 关闭

Keys:
  Virtual_Keys_Enabled: true
  Physical_Keys_Enabled: true

Shop:
  Enabled: true
  VirtualKeys: true   # true = 虚拟钥匙;false = 实体钥匙物品

Win_Message: "&8[&6VaultCrates&8] &7你从 &e{crate_name}&7 中获得了 {reward_name} &8[{rarity}&8]"

RewardFooter:         # 附加到每个奖励物品上的额外描述行
  Enabled: false
  Fallback: "Reward"
  Lines:
    - ""
    - "&8奖励类型 » &7{reward_type}"
    - "&8稀有度 » &7{rarity_name}"

箱子配置 (crates/MyCrate.yml)

Animation: ROUND          # 参见动画列表
Material: ENDER_CHEST
IAModel: "namespace:my_crate"   # 可选 — ItemsAdder 方块或家具
Size: 1                   # 每次开启获得的奖励数量
PreviewEnabled: true
ShowChanceInPreview: true
ShiftInstantlyOpen: false

HologramLines:
  - "&6&l我的箱子"
  - "&7右键点击打开"

KeyCrate:
  Require: true
  KeysRequired: 1
  Material: TRIPWIRE_HOOK
  Name: "&6&l我的箱子钥匙"
  MatchNBT: true

FinalMessage: []          # 开启时向所有玩家广播(留空以禁用)

Prizes:
  diamond:
    Name: "&b&l钻石"
    Rarity: epic           # common | rare | epic | legendary | jackpot | mega_jackpot | custom
    Chance: 10.0           # 相对权重 — 无需总和为 100
    Material: DIAMOND
    Amount: 1
    Glow: true             # 仅视觉效果闪烁 — 物品仍可正常附魔
    GiveItem: true
    Type: "Item"           # 可选 — 在 RewardFooter 中显示为 {reward_type}
    Enchantments:
      sharpness: 5
      "myplugin:soulbound": 1   # 来自附魔插件的附魔,通过命名空间 ID
    Commands: []
    EnchantCommands: []    # 在给予物品后运行(用于没有注册附魔的附魔插件)
    MessagesToPlayer: []
    BroadcastMessages: []
    GlobalLimit: 0         # 0 = 无限制
    PlayerLimit: 0

BestPrizes:
  legendary_item:
    Name: "&6&l传说之剑"
    Chance: 100.0
    Material: NETHERITE_SWORD
    GiveItem: true

可用稀有度

ID 显示名称 发光颜色
common Common 灰色
rare Rare 绿色
epic Epic 紫色
legendary Legendary 金色
jackpot Jackpot 红色
mega_jackpot ✦ Mega Jackpot ✦ 深红色

可以在 config.yml 的 Rarities: 下添加自定义稀有度,支持设置保底阈值、发光颜色和广播消息。

钱袋配置 (pouches/MyPouch.yml)

Name: "MoneyPouch"
DisplayName: "&6&l钱袋"
Material: SUNFLOWER
Glow: true
Commands:
  - "eco give {player_name} {random_number}"
MinNumber: 500
MaxNumber: 5000

? 多语言

默认捆绑了四种语言:

代码 语言
en English (默认)
de German / Deutsch
fr French / Français
es Spanish / Español

使用自定义或地区性语言:

  1. 在插件文件夹中创建 messages_pt_br.yml(或任意 messages_<code>.yml)
  2. 在 config.yml 中设置 Language: pt_br
  3. 运行 /vc reload

回退链顺序: messages_en_us.yml → messages_en.yml → messages.yml


?️ 存储后端

类型 说明
JSON 默认。无需配置。所有数据存储在 data/ 目录下。
SQLITE 基于文件的 SQL。内置驱动程序——无需额外的 jar 包。
MYSQL 完整的 MySQL / MariaDB 支持。表会自动创建。

存储的数据包括:虚拟钥匙、保底计数器、奖励上限、里程碑进度、已使用的钥匙 UUID。


? 动画效果

名称 样式
ROUND 老虎机式——物品循环滚动,减速并锁定中奖者
ROUND2 神秘箱子式——BARRIER 箱子环绕飞行;闪电揭示奖品
QUICK 快速老虎机式——与 ROUND 相同但速度更快(约 3 秒)
COSMIC 轨道式——双反向旋转环,中心物品上下浮动
DISPLAY 单物品循环展示奖品并落在中奖者上
PYRAMID 三层金字塔式——物品分层旋转
CONTRABAND 物品向上漂浮并逐个消失
INSTANT 无动画——粒子爆发,立即给予奖励
AIR_STRIKE 物品从高处落下并伴随闪电打击
BREAKOUT 物品向外迸发然后弧形返回
METEOR_SHOWER 物品如雨般落下并带有火焰轨迹
YIN_YANG 两个圆环以阴阳图案汇聚

? 自定义物品支持

# 在奖励中:
Material:     "namespace:item_id"   # ItemsAdder 物品
OraxenModel:  "item_id"
NexoModel:    "item_id"
EIModel:      "my_item_id"          # ExecutableItems
MMOItem:      "TYPE:item_id"        # 例如 SWORD:my_sword

# 在宝箱或钥匙上:
IAModel:      "namespace:item_id"
OraxenModel:  "item_id"
NexoModel:    "item_id"

ItemsAdder 字体图像(:icon_name:)可在所有文本字段中使用:名称、描述、全息图和消息。


? PlaceholderAPI

占位符 返回值
%vaultcrates_keys_<CrateName>% 该宝箱的虚拟钥匙数量
%vaultcrates_opens_<CrateName>% 玩家打开该宝箱的总次数
%vaultcrates_pity_<CrateName>_<rarityId>% 当前保底计数器数值
%vaultcrates_milestone_<CrateName>_<milestoneId>% claimed / ready / needs N more opens
%vaultcrates_is_animating% true / false
%vaultcrates_active_animations% 服务器当前活动的动画数量

? 开发者 API

VaultCratesAPI api = VaultCratesAPI.get();

// 虚拟钥匙
int keys = api.getVirtualKeys(player.getUniqueId(), "MyCrate");
api.addVirtualKeys(player.getUniqueId(), "MyCrate", 5);
api.removeVirtualKeys(player.getUniqueId(), "MyCrate", 1);

// 实体钥匙
api.givePhysicalKey(player, crate, 3);

// 以编程方式开启宝箱
api.openCrate(player, api.getCrate("MyCrate"), crateLocation);

// 事件监听
@EventHandler
public void onCrateOpened(CrateOpenedEvent e) {
    List<Reward> rewards = e.getRewards();
    Reward best = e.getBestReward();
}

? 许可证

VaultCrates 是免费软件,根据 GNU General Public License v3.0 许可。 你可以按照 GPL-3.0 的条款使用、修改和重新分发它——修改后的版本必须同样以开源形式发布。 完整文本请参阅 LICENSE。


由 itslarss 用 ❤️ 制作

你是这个资源的作者?登录后可认领此资源。

评论 0

0.0
暂无评分
5 星
0
4 星
0
3 星
0
2 星
0
1 星
0
我的评分

登录后参与评分

还没有评论,来抢沙发吧

评论配图

相似资源