** ? UltraStarterKits - 完整插件文档
? 概述
UltraStarterKits 是一款面向运行在 Paper 或 Spigot 上的 Minecraft 1.21.x 服务器的优质企业级模组管理插件。它提供了一套完整的玩家模组管理解决方案,拥有直观的图形用户界面 (GUI)、强大的权限系统和广泛的自定义选项。
? 为何称其为“终极”?
- 生产就绪:经过实战检验的代码,包含错误处理与优化
- 网络兼容:全面支持 MySQL,适用于 BungeeCord/Velocity 网络架构
- 高度可定制:每条消息、GUI 元素和功能均可配置
- 性能优化:异步操作、连接池、智能缓存
- 开发者友好:代码架构清晰,提供全面的 API
? 适用场景
- 生存服务器 - 新手模组、每日奖励、等级特权
- 空岛网络 - 岛屿起始套装、VIP 模组、月度奖励
- 监狱服务器 - 基于等级的模组、矿点奖励、进度系统
- PvP 服务器 - 竞技场模组、装备配置、快速获取装备
- 小游戏网络 - 游戏专属模组、团队装备配置
✨ 核心功能
? 模组管理
| 功能 |
描述 |
| 无限模组 |
根据需要创建任意数量的自定义模组 |
| 完整 NBT 支持 |
保留所有物品数据,包括自定义模型数据、名称、背景故事和附魔 |
| 物品序列化 |
Base64 编码确保 100% 保留物品数据 |
| 随机物品 |
基于概率的战利品系统(例如:稀有物品 50% 掉落率) |
| 模组分类 |
将模组组织到不同类别中(基础、高级、每日、PvP 等) |
| 模组过期 |
限时模组,在特定日期后失效 |
| 定时可用性 |
仅限周末的模组、一天中特定时段的限制 |
? 权限与访问控制
| 功能 |
描述 |
| LuckPerms 集成 |
直接 API 集成(不仅仅是 Vault) |
| 按模组权限 |
每个模组独立的权限节点 |
| 基于等级的覆盖 |
不同等级拥有不同的冷却时间/使用次数 |
| 群组检测 |
同时检查主群组和继承的群组 |
| 显示名称 |
显示 "VIP" 而非 "kit.use.vip" |
| 绕过权限 |
管理员权限可绕过所有限制 |
⏱️ 冷却系统
| 功能 |
描述 |
| 灵活的时间格式 |
支持秒、分钟、小时、天、周 |
| 等级覆盖 |
VIP 获得 12 小时冷却,MVP 获得 6 小时冷却等 |
| 冷却追踪 |
重启后持久化存储冷却时间 |
| 过期通知 |
可选的冷却时间到期通知 |
| 显示格式 |
完整格式 (1d 2h 30m)、短格式 (1d 2h)、秒数 (95400) |
| 无冷却选项 |
使用 "never" 或 -1 实现即时领取 |
? 使用限制
| 功能 |
描述 |
| 有限使用次数 |
1 次、5 次、100 次模组 |
| 无限使用次数 |
配合冷却时间的无限领取 |
| 基于等级的限制 |
不同等级拥有不同的使用次数 |
| 使用追踪 |
持久化存储领取计数 |
| 使用重置 |
管理员命令重置使用数据 |
? 世界管理
| 功能 |
描述 |
| 全局白名单 |
限制插件仅在特定世界中生效 |
| 按模组指定世界 |
模组仅在指定世界中可用 |
| 多世界支持 |
不同世界对应不同模组 |
| 世界变更检测 |
进入世界时自动发放新手模组 |
| 绕过权限 |
管理员可在任何地方使用模组 |
? GUI 系统
| 功能 |
描述 |
| 主模组菜单 |
美观的分页模组选择 GUI |
| 预览模式 |
100% 安全的仅查看模组预览 |
| 锁定模组显示 |
显示不可用模组及其要求 |
| 可点击商店链接 |
基于 MiniMessage 的可点击 URL |
| 管理员编辑 GUI |
可视化拖拽式模组编辑器 |
| 确认对话框 |
带有警告信息的删除确认 |
| 分页 |
30+ 模组的自动分页 |
| 自定义图标 |
每个模组的自定义材质和模型数据 |
| 发光图标 |
可选的附魔发光效果 |
| 动态背景故事 |
实时显示冷却时间/使用次数 |
? 存储选项
| 类型 |
用例 |
优点 |
缺点 |
| YAML |
单个服务器 |
设置简单,人类可读 |
不兼容网络架构 |
| SQLite |
中小型服务器 |
无需外部数据库,速度快 |
不兼容网络架构 |
| MySQL |
网络、大型服务器 |
网络同步,可扩展性强 |
需要 MySQL 服务器 |
? 集成
| 插件 |
集成级别 |
功能 |
| LuckPerms |
⭐⭐⭐⭐⭐ 深度 |
群组、权限、前缀、后缀、等级检测 |
| Vault |
⭐⭐⭐⭐ 完整 |
经济成本、权限回退 |
| PlaceholderAPI |
⭐⭐⭐⭐⭐ 深度 |
15+ 个自定义占位符 |
| bStats |
⭐⭐⭐ 标准 |
匿名使用指标 |
? 效果与反馈
| 效果类型 |
可定制 |
按模组定制 |
| 音效 |
✅ 是 |
✅ 是 |
| 粒子 |
✅ 是 |
✅ 是 |
| 标题 |
✅ 是 |
✅ 是 |
| 副标题 |
✅ 是 |
✅ 是 |
| 动作栏 |
✅ 是 |
✅ 是 |
| 聊天消息 |
✅ 是 |
✅ 是 |
| 广播 |
✅ 是 |
✅ 是 |
| 烟花 |
✅ 是 |
✅ 是 |
? 高级功能
| 功能 |
描述 |
| 新手模组 |
首次加入每个世界时自动发放 |
| 经济成本 |
收取费用以领取模组(Vault) |
| 经验值要求 |
要求经验等级才能领取 |
| 物品要求 |
消耗物品以领取模组 |
| 命令执行 |
在领取模组时运行命令(控制台/玩家/OP) |
| 一次性奖励 |
仅在首次领取时提供额外物品 |
| 自动保存 |
可配置的自动保存间隔 |
| 缓存系统 |
用于提升性能的智能缓存 |
| 异步操作 |
非阻塞数据库操作 |
| 连接池 |
HikariCP 用于 MySQL 优化 |
? 技术规格
系统要求
Minecraft 版本:1.21+
服务器软件:Paper(推荐)或 Spigot
Java 版本:17 或更高
内存:分配给插件操作的最小 512MB
数据库:MySQL 5.7+ 或 MariaDB 10.3+(可选)
依赖项
必需:
- 无(完全独立运行)
软依赖(可选):
- LuckPerms 5.4+(用于高级权限管理)
- Vault 1.7+(用于经济功能)
- PlaceholderAPI 2.11+(用于占位符)
性能指标
平均内存占用:20-50MB(取决于套件数量)
数据库查询:完全异步,非阻塞
缓存过期时间:5 分钟(可配置)
GUI 渲染时间:<5 毫秒
领取套件时间:<10 毫秒
启动时间:<1 秒
? 安装指南
第 1 步:下载
- 下载
UltraStarterKits
第 2 步:安装
停止你的服务器
stop
将 JAR 文件放入 plugins 文件夹
cp UltraStarterKits-1.0.0.jar /path/to/server/plugins/
启动服务器(生成配置文件)
start
第 3 步:初始配置
等待服务器完全启动
插件会在 plugins/UltraStarterKits/ 中生成默认配置
创建的文件:
plugins/UltraStarterKits/
├── config.yml 主配置文件
├── kits.yml 套件定义
├── messages.yml 所有消息
├── guis.yml GUI 布局
└── playerdata.yml 玩家数据(如果使用 YAML 存储)
第 4 步:配置存储(可选)
编辑 config.yml
storage:
type: "MYSQL" 从 YAML 更改为 MYSQL
mysql:
host: "localhost"
port: 3306
database: "ultrakits"
username: "root"
password: "your_password"
第 5 步:重载配置
在游戏中或控制台执行
/skit reload
第 6 步:创建你的第一个套件
方法 1:使用命令
1. 将物品放入你的背包
2. /skit create starter kit.use.starter 1 never all
方法 2:使用 GUI
1. /skit edit starter
2. 在 GUI 中放置物品
3. 点击“保存套件”
⚙️ 配置
config.yml - 主要设置
常规设置
启用详细日志记录以进行故障排除
debug-mode: false
启动时检查更新
check-updates: true
存储配置
storage:
YAML = 文件存储(简单)
SQLITE = 本地数据库(性能更好)
MYSQL = 远程数据库(适用于网络)
type: "YAML"
mysql:
host: "localhost"
port: 3306
database: "ultrakits"
username: "root"
password: "password"
pool-size: 10 繁忙服务器请增加此值
use-ssl: false
每隔 X 分钟自动保存(0 = 仅手动保存)
auto-save-interval: 5
世界白名单
world-whitelist:
enabled: false 设为 true 以限制世界
worlds:
- "world"
- "world_nether"
- "world_the_end"
- "skyblock"
denied-message: "&c本世界中不可用套件!"
新手套件设置
starter-kit:
enabled: true
发放前的延迟(允许其他插件加载玩家数据)
delay-seconds: 3
发送欢迎消息
message-on-receive: true
向在安装插件前已加入的玩家发放
give-to-existing-players: false
GUI 设置
gui:
main-menu:
title: "&8&l✦ &6&l套件选择 &8&l✦"
rows: 6 1-6 行
filler:
enabled: true
material: "GRAY_STAINED_GLASS_PANE"
name: " "
锁定套件设置
locked-kit:
icon: "BARRIER"
name: "&c&l? %kit_name% &c(已锁定)"
lore:
- "&c&l✘ &c你无权访问!"
- "&7需要:&e%required_rank%"
- "&e点击获取商店链接!"
click-message:
- ""
- "&c&l✘ &c你无权访问 &e%kit_name%&c!"
- "<click:open_url:'%store_url%'>&a&l[点击此处购买]</click>"
- ""
store-url: "https://store.yourserver.com"
sound: "ENTITY_VILLAGER_NO"
特效设置
effects:
default-claim-sound: "ENTITY_PLAYER_LEVELUP"
default-claim-particles:
enabled: true
type: "TOTEM_OF_UNDYING"
count: 50
default-title:
enabled: true
title: "&a&l✓ 套件已领取!"
subtitle: "&7你获得了 &e%kit_name%"
fade-in: 10
stay: 40
fade-out: 10
经济设置
economy:
enabled: true 需要 Vault
format: "&a$%amount%"
refund-percentage: 100 如果领取失败则退款
冷却设置
cooldowns:
FULL: 1d 2h 30m 15s
SHORT: 1d 2h
SECONDS: 95415
display-format: "FULL"
notify-on-expire: true
notify-message: "&a&l✓ &a你的 &e%kit_name% &a套件现在可用了!"
库存设置
inventory:
DROP = 将物品掉落在地上
DENY = 取消套件领取
PARTIAL = 能放多少放多少,剩余的掉落
full-inventory-action: "DROP"
dropped-items-message: "&e部分物品已被掉落在地上!"
kits.yml - 套件定义
基础套装结构
kits:
kitname:
显示名称(支持颜色代码)
display-name: "&a&l新手套装"
描述(在 GUI 中显示)
description:
- "&7用于起步的基础物品"
- "&7终身仅限领取一次"
GUI 图标
icon:
material: "CHEST"
custom-model-data: 0
glowing: true
所需权限
permission: "kit.use.starter"
排名显示名称(用于 GUI)
required-rank-display: "Default"
分类(可选)
category: "Basic"
最大使用次数(-1 = 无限次)
max-uses: 1
冷却时间(30s, 5m, 2h, 1d, 1w, never)
cooldown: "never"
基于排名的冷却覆盖设置
cooldown-overrides:
vip: "12h"
mvp: "6h"
elite: "3h"
可用该套装的世界
worlds:
- "all" 或列出具体世界名称
新手套装设置
is-starter-kit: true
starter-kit-worlds:
- "world"
套装物品
items:
0:
slot: 0
material: "DIAMOND_SWORD"
amount: 1
name: "&b&l新手剑"
lore:
- "&7你的第一把武器!"
enchantments:
sharpness: 2
unbreaking: 1
custom-model-data: 0
unbreakable: false
chance: 1.0 1.0 = 100%, 0.5 = 50%
音效与粒子效果
sound: "ENTITY_PLAYER_LEVELUP"
particles:
type: "TOTEM_OF_UNDYING"
count: 100
title-message: "&a&l✓ 已领取套装!"
subtitle-message: "&7享受你的物品吧!"
actionbar-message: "&a成功领取套装!"
chat-messages:
- "&a你获得了新手套装!"
broadcast-message: "&e%player% &a领取了新手套装!"
firework-effect: true
领取时执行的命令
commands-on-claim:
- "[console] give %player% apple 1"
- "[player] me received a kit!"
- "[op] gamemode survival"
高级功能
economy-cost: 1000 需要 Vault 插件支持
required-xp-level: 5
required-items:
- material: "DIAMOND"
amount: 5
consume-required-items: true
expiry-date: -1 Unix 时间戳 或 -1
available-days: 留空表示始终可用
- "SATURDAY"
- "SUNDAY"
available-time-start: "08:00" HH:mm 格式
available-time-end: "20:00"
one-time-bonus: true
bonus-items:
0:
material: "DIAMOND_BLOCK"
amount: 1
物品属性参考
items:
0:
必填项
material: "DIAMOND_SWORD" 材料名称
可选项
amount: 1 堆叠数量 (1-64)
slot: 0 背包栏位 (0-35)
显示信息
name: "&b&l自定义名称" 物品名称
lore: 物品描述
- "&7第一行"
- "&7第二行"
附魔
enchantments:
sharpness: 5
unbreaking: 3
fire_aspect: 2
looting: 3
mending: 1
特殊属性
custom-model-data: 12345 自定义模型数据
unbreakable: true 不可破坏标志
随机物品
chance: 0.5 50% 概率给予
Base64 序列化(自动生成)
base64: "..." 完整 NBT 数据保留
messages.yml - 自定义消息
消息类别
前缀
prefix: "&FFD700&l✦ &6UltraKits &8» &r"
套装消息
kit-claimed: "&a您已成功领取 &e%kit_name%&a!"
kit-on-cooldown: "&c该套装正在冷却中!&7剩余时间:&e%time_remaining%"
kit-no-permission: "&c您没有权限使用该套装!"
kit-already-claimed: "&c您已经达到了该套装的最大领取次数!"
kit-not-found: "&c未找到套装 '&e%kit_name%&c'!"
kit-wrong-world: "&c此套装在当前世界中不可用!"
kit-inventory-full: "&c您的背包已满!请腾出一些空间。"
管理员消息
kit-created: "&a套装 '&e%kit_name%&a' 创建成功!"
kit-deleted: "&a套装 '&e%kit_name%&a' 已删除!"
kit-items-set: "&a已为套装 '&e%kit_name%&a' 设置了 &e%count% &a个物品!"
kit-given: "&a已向 &e%player%&a 发放套装 '&e%kit_name%&a'!"
data-reset: "&a已重置玩家 &e%player%&a 关于套装 '&e%kit_name%&a' 的数据!"
reload-success: "&a所有配置已成功重载!"
错误消息
player-not-found: "&c玩家 '&e%player%&c' 未找到或处于离线状态!"
no-permission: "&c您没有权限执行此操作!"
wrong-world: "&c此世界中不可使用套装!"
使用说明消息
usage:
skit-claim: "&c用法:&e/skit claim <kit>"
skit-give: "&c用法:&e/skit give <player> <kit> [bypass]"
消息中的占位符
%player% - 玩家名称
%kit_name% - 套装内部名称
%kit_displayname% - 带颜色的套装显示名称
%time_remaining% - 格式化后的冷却时间
%uses_remaining% - 剩余使用次数
%max_uses% - 最大使用次数
%cost% - 经济成本
%required_rank% - 所需排名
%permission% - 所需权限
%world% - 世界名称
guis.yml - GUI 自定义
主菜单布局
main-menu:
title: "&8&l✦ &6&l套装选择 &8&l✦"
rows: 6
filler:
enabled: true
material: "GRAY_STAINED_GLASS_PANE"
name: " "
套装出现的栏位(自动填充)
kit-slots:
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 19
- 20
... 更多栏位
buttons:
previous-page:
slot: 48
material: "ARROW"
name: "&a&l« 上一页"
hide-if-first-page: true
next-page:
slot: 50
material: "ARROW"
name: "&a&l下一页 »"
hide-if-last-page: true
page-indicator:
slot: 49
material: "PAPER"
name: "&e第 %current% / %total% 页"
close:
slot: 53
material: "BARRIER"
name: "&c&l关闭"
预览菜单
preview-menu:
title: "&8预览中:&6%kit_name%"
rows: 6
buttons:
back:
slot: 49
material: "ARROW"
name: "&c&l« 返回模组"
info:
slot: 45
material: "BOOK"
name: "&e&l%kit_name%"
lore:
- "&7权限:&f%permission%"
- "&7使用次数:&f%uses%"
- "&c此仅为预览!"
? 命令参考
玩家命令
/skit
打开主要的模组选择图形用户界面 (GUI)。
用法: /skit
别名: /kit, /kits, /starterkit, /ultrakits, /uk
权限: ultrakits.use
示例:
/skit
打开包含所有可用模组的 GUI
/skit list
打开模组列表 GUI(与 /skit 相同)。
用法: /skit list
权限: ultrakits.use
/skit claim <kit>
按名称领取特定模组。
用法: /skit claim <kitname>
权限: ultrakits.use + 模组专属权限
参数:
示例:
/skit claim starter
/skit claim daily
/skit claim vip
验证逻辑:
- 检查模组是否存在
- 验证权限
- 验证冷却时间
- 确认剩余使用次数
- 检查世界限制
- 验证背包空间
/skit preview <kit>
打开模组内容的只读预览视图。
用法: /skit preview <kitname>
权限: ultrakits.use
示例:
/skit preview vip
/skit preview mvp
功能:
- 100% 安全(无法取走物品)
- 显示所有模组物品
- 显示模组信息
- 提供返回按钮
/skit info <kit>
在聊天栏显示详细的模组信息。
用法: /skit info <kitname>
权限: ultrakits.use
输出示例:
✦ 模组信息:Starter Kit ✦
名称:starter
权限:kit.use.starter
描述:
用于起步的基础物品
终身仅限领取一次
最大使用次数:1
冷却时间:无
世界:所有世界
起始模组:是
物品数量:8
您的剩余使用次数:1
您的冷却状态:就绪!
/skit cooldown <kit>
检查模组的剩余冷却时间。
用法: /skit cooldown <kitname>
权限: ultrakits.use
示例:
/skit cooldown daily
输出:Daily Kit 冷却时间:5小时 32分 15秒
/skit cooldown vip
输出:VIP Kit 已准备好领取!
管理员命令
/skit create <name> <permission> <uses> <cooldown> <world>
根据您当前的背包内容创建一个新模组。
用法: /skit create <name> <permission> <uses> <cooldown> <world>
权限: ultrakits.admin.create
参数:
<name> - 模组内部名称(小写,无空格)
<permission> - 所需权限(例如 kit.use.vip)
<uses> - 最大使用次数 (1, 5, unlimited(无限), -1)
<cooldown> - 冷却时间 (30s, 5m, 24h, never(永不), -1)
<world> - 世界限制 (all(所有), world(指定世界), skyblock)
示例:
创建一次性起始模组
/skit create starter kit.use.starter 1 never all
创建具有 24 小时冷却时间的 VIP 模组
/skit create vip kit.use.vip unlimited 24h all
仅适用于 PvP 世界的 PvP 模组
/skit create pvpkit kit.use.pvp unlimited 5m pvp
创建每周模组
/skit create weekly kit.use.weekly unlimited 7d all
流程:
- 将物品放入您的背包(按您想要的顺序排列)
- 运行创建命令
- 插件捕获所有背包物品
- 以默认设置创建模组
- 使用其他命令或编辑 GUI 进行进一步自定义
/skit delete <kit>
永久删除一个模组。
用法: /skit delete <kitname>
权限: ultrakits.admin.delete
示例:
/skit delete oldkit
打开确认 GUI
安全措施:
- 打开确认对话框
- 显示模组物品数量
- 警告永久删除操作
- 点击确认以删除
- 点击取消以中止
/skit edit <kit>
打开可视化的模组编辑器 GUI。
用法: /skit edit <kitname>
权限: ultrakits.admin.edit
示例:
/skit edit vip
打开 6 行背包编辑器
功能:
- 拖放物品
- 可视化物品排列
- 保存按钮
- 取消按钮
- 设置按钮(显示当前配置)
/skit setitems <kit>
根据您当前的背包内容设置模组物品。
用法: /skit setitems <kitname>
权限: ultrakits.admin.edit
示例:
1. 在背包中排列物品
2. 运行命令
/skit setitems vip
输出:为模组 'vip' 设置了 15 个物品!
/skit additem <kit>
将您当前手持的物品添加到模组中。
用法: /skit additem <kitname>
权限: ultrakits.admin.edit
示例:
1. 手持一把钻石剑
2. 运行命令
/skit additem vip
输出:已将钻石剑添加到模组 'vip'!
/skit removeitem <kit> <slot>
从特定槽位移除物品。
用法: /skit removeitem <kitname> <slot>
权限: ultrakits.admin.edit
参数:
示例:
/skit removeitem vip 5
输出:已从模组 'vip' 的槽位 5 移除物品!
/skit seticon <kit>
将 GUI 图标设置为您当前手持的物品。
用法: /skit seticon <kitname>
权限: ultrakits.admin.edit
示例:
1. 手持一块金块
2. 运行命令
/skit seticon vip
输出:将 'vip' 的图标设置为 GOLD_BLOCK!
/skit setpermission <kit> <permission>
更改所需的权限。
用法: /skit setpermission <kitname> <permission>
权限: ultrakits.admin.edit
示例:
/skit setpermission vip kit.use.vipplus
输出:将 'vip' 的权限设置为 kit.use.vipplus!
/skit setuses <kit> <amount>
设置最大使用次数。
用法: /skit setuses <kitname> <amount|unlimited>
权限: ultrakits.admin.edit
示例:
/skit setuses starter 1
输出:将 'starter' 的最大使用次数设置为 1!
/skit setuses daily unlimited
输出:将 'daily' 的最大使用次数设置为 Unlimited(无限)!
/skit setuses weekly 52
输出:将 'weekly' 的最大使用次数设置为 52!
/skit setcooldown <kit> <time>
设置冷却时间。
用法: /skit setcooldown <kitname> <time|never>
权限: ultrakits.admin.edit
时间格式:
30s - 30 秒
5m - 5 分钟
2h - 2 小时
1d - 1 天
1w - 1 周
never 或 -1 - 无冷却
示例:
/skit setcooldown daily 24h
/skit setcooldown vip 12h
/skit setcooldown pvp 5m
/skit setcooldown starter never
/skit setworld <kit> <world>
设置世界限制。
用法: /skit setworld <kitname> <world|all>
权限: ultrakits.admin.edit
示例:
/skit setworld pvpkit pvp
输出:已将 'pvpkit' 的世界设置为 pvp!
/skit setworld daily all
输出:已将 'daily' 的世界设置为所有世界!
/skit setworld skyblock skyblock_world
/skit setstarterkit <kit> <true|false>
切换初始套件状态。
用法: /skit setstarterkit <kitname> <true|false>
权限: ultrakits.admin.edit
示例:
/skit setstarterkit starter true
输出:'starter' 的初始套件状态已设置为启用!
/skit setstarterkit daily false
输出:'daily' 的初始套件状态已设置为禁用!
/skit give <player> <kit> [bypass]
向玩家发放套件。
用法: /skit give <player> <kitname> [bypass]
权限: ultrakits.admin.give
参数:
<player> - 玩家名称(必须在线)
<kitname> - 要发放的套件
[bypass] - 可选:绕过所有限制
示例:
/skit give Steve starter
发放 starter 套件(检查所有限制)
/skit give Steve vip bypass
发放 VIP 套件(绕过冷却、使用次数、权限限制)
/skit give Steve daily true
等同于 bypass
使用场景:
/skit reset <player> [kit|all]
重置玩家的套件数据。
用法: /skit reset <player> [kitname|all]
权限: ultrakits.admin.reset
示例:
重置特定套件
/skit reset Steve starter
输出:已重置 Steve 在 'starter' 套件中的数据!
重置所有套件
/skit reset Steve all
输出:已重置 Steve 的所有套件数据!
将被重置的内容:
- 使用次数
- 冷却时间戳
- 已领取奖励的标志位
- (不会删除套件本身)
/skit reload
重新加载所有配置文件。
用法: /skit reload
权限: ultrakits.admin.reload
可在控制台运行: 是
示例:
/skit reload
输出:所有配置已成功重新加载!
将被重新加载的内容:
- config.yml
- kits.yml
- messages.yml
- guis.yml
- 文件中的所有套件
注意: 缓存中的玩家数据不会被重置
? 权限系统
权限层级
ultrakits.*
├── ultrakits.admin
│ ├── ultrakits.admin.create
│ ├── ultrakits.admin.delete
│ ├── ultrakits.admin.edit
│ │ ├── ultrakits.admin.edit.items
│ │ ├── ultrakits.admin.edit.icon
│ │ └── ultrakits.admin.edit.settings
│ ├── ultrakits.admin.give
│ ├── ultrakits.admin.reset
│ └── ultrakits.admin.reload
│
├── ultrakits.use
│ ├── ultrakits.command.list
│ ├── ultrakits.command.claim
│ ├── ultrakits.command.preview
│ ├── ultrakits.command.info
│ ├── ultrakits.command.cooldown
│ └── ultrakits.command.help
│
└── ultrakits.bypass.*
├── ultrakits.bypass.cooldown
├── ultrakits.bypass.uses
├── ultrakits.bypass.world
├── ultrakits.bypass.permission
└── ultrakits.bypass.cost
权限节点参考
| 权限 |
默认值 |
描述 |
ultrakits.* |
op |
完全访问所有功能 |
ultrakits.admin |
op |
所有管理命令 |
ultrakits.use |
true |
基本套件使用 |
ultrakits.bypass.* |
op |
绕过所有限制 |
ultrakits.bypass.cooldown |
op |
无冷却时间 |
ultrakits.bypass.uses |
op |
无限使用次数 |
ultrakits.bypass.world |
op |
在任何世界中使用套件 |
ultrakits.bypass.permission |
op |
访问所有套件 |
ultrakits.bypass.cost |
op |
免费套件 |
kit.use.<kitname> |
false |
访问特定套件的权限 |
LuckPerms 设置示例
基础玩家(默认组)
授予基础套件访问权限
lp group default permission set ultrakits.use true
lp group default permission set kit.use.starter true
lp group default permission set kit.use.daily true
VIP 等级
创建 VIP 组
lp creategroup vip
设置父级组
lp group vip parent add default
添加 VIP 套件权限
lp group vip permission set kit.use.vip true
lp group vip permission set kit.use.daily true
将 VIP 设为玩家的父级组
lp user Steve parent set vip
? 高级功能
基于等级的冷却覆盖
工作原理:
- 在套件配置中设置基础冷却时间
- 检测 LuckPerms 组名
- 如果玩家的组有覆盖设置,则使用该设置
配置示例:
kits:
daily:
cooldown: "24h" 所有人的默认值
cooldown-overrides:
vip: "18h" VIP 等待 18 小时
mvp: "12h" MVP 等待 12 小时
elite: "6h" Elite 等待 6 小时
ultimate: "1h" Ultimate 等待 1 小时
实际案例:
普通玩家:领取套件 → 等待 24 小时
VIP 玩家:领取套件 → 等待 18 小时
MVP 玩家:领取套件 → 等待 12 小时
Elite 玩家:领取套件 → 等待 6 小时
世界限制系统
全局白名单
将整个插件限制在特定的世界中。
config.yml
world-whitelist:
enabled: true
worlds:
- "world"
- "survival"
- "skyblock"
效果: 在其他世界中命令无效。
按套件指定世界
将单个套件限制在特定的世界中。
kits.yml
kits:
pvp-kit:
worlds:
- "pvp"
- "arena"
survival-kit:
worlds:
- "survival"
global-kit:
worlds:
- "all"
使用场景:
- PvP 套件仅在 PvP 世界可用
- 生存套件不能在创造模式世界中开启
- Skyblock 专属初始套件包
经济集成 (Vault)
设置
- 安装 Vault + 经济插件(EssentialsX 等)
- 在配置中启用:
economy:
enabled: true
format: "&a$%amount%"
套件配置
kits:
premium:
economy-cost: 5000 花费 $5000
功能
- 自动检查余额
- 领取时扣除金钱
- 领取失败时退款
- 在 GUI 中显示费用
设置步骤:
- 安装 MySQL 服务器
- 创建数据库:
CREATE DATABASE ultrakits;
- 使用凭据配置插件
- 重启服务器(表会自动创建)
网络设置 (BungeeCord):
所有服务器使用相同的 MySQL 配置
玩家数据在网络中自动同步
? PlaceholderAPI 集成
安装
- 安装 PlaceholderAPI:
/papi download ultrakits
- 重载:
/papi reload
可用的占位符
单个套件占位符
| 占位符 |
输出示例 |
描述 |
%ultrakit_uses_remaining_<kit>% |
3 |
套件的剩余使用次数 |
%ultrakit_uses_total_<kit>% |
5 |
最大总使用次数 |
%ultrakit_cooldown_<kit>% |
3600 |
冷却时间(秒) |
%ultrakit_cooldown_formatted_<kit>% |
1h 30m |
格式化后的时间 |
%ultrakit_can_claim_<kit>% |
true |
玩家是否可以领取 |
%ultrakit_has_permission_<kit>% |
false |
玩家是否有权限 |
%ultrakit_kit_displayname_<kit>% |
&a&lStarter Kit |
套件显示名称 |
%ultrakit_kit_exists_<kit>% |
true |
套件是否存在 |
全局占位符
| 占位符 |
输出示例 |
描述 |
%ultrakit_total_kits_claimed% |
47 |
玩家已领取的套件总数 |
%ultrakit_available_kits_count% |
8 |
当前可用的套件数量 |
%ultrakit_next_available_kit% |
Daily Kit |
下一个可领取的套件名称 |
%ultrakit_total_kits% |
15 |
服务器上的套件总数 |
%ultrakit_player_group% |
vip |
玩家的 LuckPerms 组别 |
❓ 常见问题与故障排除
一般问题
Q: 支持哪些 Minecraft 版本?
A: Paper 或 Spigot 上的 Minecraft 1.21.x。
Q: 必须用 Paper 吗,Spigot 可以吗?
A: 两者均可,但推荐使用 Paper 以获得更好的性能和原生的 Adventure API 支持。
Q: 这与 BungeeCord/Velocity 兼容吗?
A: 是的!使用 MySQL 存储,并在所有服务器上配置相同的数据库。
Q: 我可以将消息翻译成其他语言吗?
A: 可以!所有消息都在 messages.yml 中,完全可自定义。
安装问题
Q: 插件启动时未加载
A: 检查控制台错误。常见问题:
- Java 版本不正确(需要 Java 17+)
- Minecraft 版本不正确(需要 1.21+)
- JAR 文件损坏(重新下载)
Q: 命令无效
A: 验证:
- 插件已启用(
/plugins 显示绿色)
- 您拥有权限(
ultrakits.use)
- 世界在白名单中(如果启用了白名单)
数据库问题
Q: MySQL 无法连接
A: 检查清单:
- MySQL 服务器正在运行
- 数据库存在(
CREATE DATABASE ultrakits;)
- 凭据正确
- 端口正确(默认 3306)
- 主机正确(通常是
localhost)
- 防火墙允许连接
Q: SQLite 文件被锁定
A: 通常由以下原因引起:
- 多个服务器使用同一文件
- 之前的服务器崩溃
- 解决方案:重启服务器或删除
.db 文件(警告:会删除数据)
Q: 玩家数据未保存
A: 检查:
- 自动保存已启用
- 数据库连接正常工作
- 控制台中的错误消息
- 手动保存:
/skit reload
套件问题
Q: 套件物品未能正确保存
A: 这通常发生在自定义 NBT 数据上。修复方法:
- 使用 Paper(比 Spigot 具有更好的 NBT 支持)
- 使用
/skit edit GUI 重新创建套件
- 检查控制台的序列化错误
Q: 附魔不起作用
A: 确保:
- 附魔名称正确(小写,下划线分隔)
- 示例:
sharpness: 5 而不是 Sharpness: V
- 使用 Minecraft 附魔 ID
Q: 自定义模型数据未保存
A: 在配置中设置:
custom-model-data: 12345
权限问题
Q: 每个人都可以使用所有套件
A: 检查:
- 套件权限设置正确
- 玩家没有
ultrakits.* 通配符权限
- 已安装并正常运行 LuckPerms
Q: LuckPerms 组别未被检测
A: 验证:
- 已安装并启用 LuckPerms
- 插件检测到 LuckPerms(检查启动日志)
- 组名完全匹配(区分大小写)
Q: 等级覆盖不起作用
A: 确保:
- 配置中的组名与 LuckPerms 组名匹配
- 玩家在该组中(
/lp user <player> info)
- 示例:
cooldown-overrides:
vip: "12h" 必须与 LuckPerms 组 "vip" 匹配
冷却时间问题
Q: 冷却时间不起作用
A: 检查:
- 时间格式正确(
24h 而不是 24hours)
- 套件配置中设置了冷却时间
- 玩家没有绕过权限
Q: 冷却时间显示错误
A: 验证:
- 服务器时间正确
- 没有修改时间的冲突插件
- 重载插件:
/skit reload
GUI 问题
Q: GUI 无法打开
A: 原因:
- 背包已满(服务器阻止打开)
- 缺少权限
- 世界不在白名单中
Q: 预览 GUI 中的物品可以被拿走
A: 这不应该发生。如果发生:
- 报告为 bug
- 更新到最新版本
- 检查是否有冲突的库存插件
Q: 分页不起作用
A: 通常发生在:
- 套件过多(100+)
- GUI 配置错误
- 修复:调整
guis.yml 中的 kit-slots
性能问题
Q: 打开 GUI 时服务器卡顿
A: 优化建议:
- 减少套件数量(分成类别)
- 使用 MySQL 代替 YAML
- 增加缓存过期时间
- 检查其他导致卡顿的插件
Q: 内存占用过高
A: 正常用法为 20-50MB。如果更高:
- 缓存了过多的套件
- 清除缓存:重启服务器
- 减少自动保存频率
错误消息
Q: “找不到套件”,尽管它确实存在
A: 常见原因:
- 套件名称拼写错误(区分大小写)
- 套件未加载(重载:
/skit reload)
kits.yml 文件损坏
问:“序列化物品失败”
答:物品包含不受支持的 NBT 数据:
- 简化该物品
- 移除自定义 NBT 数据
- 仅使用原版物品
问:启动时出现“数据库错误”
答:请检查以下内容:
- 数据库凭据(用户名/密码)
- 数据库服务器是否正在运行
- 网络连接是否正常
- 控制台中的具体 SQL 错误信息
? 支持与资源
官方链接
- Discord: discord.gg/ultrakits
获取帮助
功能请求
请在以下平台提交功能请求:
Bug 报告
请提供以下信息:
- 服务端版本
- 插件版本
- 错误日志
- 复现步骤
- 截图(如果是 GUI 相关问题)
? 许可与致谢
插件名称: UltraStarterKits
版本: 1.0.0
作者: geturplugins
许可证: 保留所有权利
? 感谢您的支持!
感谢您选择 UltraStarterKits!我们希望它能提升您的服务器体验,并为玩家带来出色的游玩感受。
如果您喜欢这款插件,请:
- ⭐ 留下五星好评
- ? 推荐给其他服务器管理员
- ? 加入我们的 Discord 社区
祝您服务器管理愉快!?
** ? UltraStarterKits - Complete Plugin Documentation
? Overview
UltraStarterKits is a premium, enterprise-grade kit management plugin designed for Minecraft 1.21.x servers running Paper or Spigot. It provides a complete solution for managing player kits with an intuitive GUI, powerful permission system, and extensive customization options.
? What Makes It Ultimate?
- Production-Ready: Battle-tested code with error handling and optimization
- Network-Compatible: Full MySQL support for BungeeCord/Velocity networks
- Highly Customizable: Every message, GUI, and feature is configurable
- Performance-Optimized: Async operations, connection pooling, smart caching
- Developer-Friendly: Clean code architecture and comprehensive API
? Perfect For
- Survival Servers - Starter kits, daily rewards, rank perks
- Skyblock Networks - Island starter packs, VIP kits, monthly rewards
- Prison Servers - Rank-based kits, mine rewards, progression systems
- PvP Servers - Arena kits, loadouts, quick gear access
- Minigame Networks - Game-specific kits, team loadouts
✨ Key Features
? Kit Management
| Feature |
Description |
| Unlimited Kits |
Create as many custom kits as needed |
| Full NBT Support |
Preserves all item data including custom model data, names, lore, enchantments |
| Item Serialization |
Base64 encoding ensures 100% item data preservation |
| Random Items |
Chance-based loot system (e.g., 50% chance for rare items) |
| Kit Categories |
Organize kits into categories (Basic, Premium, Daily, PvP, etc.) |
| Kit Expiry |
Time-limited kits that expire on specific dates |
| Scheduled Availability |
Weekend-only kits, time-of-day restrictions |
? Permission & Access Control
| Feature |
Description |
| LuckPerms Integration |
Direct API integration (not just Vault) |
| Per-Kit Permissions |
Individual permission nodes per kit |
| Rank-Based Overrides |
Different cooldowns/uses for different ranks |
| Group Detection |
Checks both primary and inherited groups |
| Display Names |
Show "VIP" instead of "kit.use.vip" |
| Bypass Permissions |
Admin permissions to bypass all restrictions |
⏱️ Cooldown System
| Feature |
Description |
| Flexible Time Format |
Support for seconds, minutes, hours, days, weeks |
| Rank Overrides |
VIPs get 12h cooldown, MVPs get 6h, etc. |
| Cooldown Tracking |
Persistent cooldown storage across restarts |
| Expiry Notifications |
Optional notifications when cooldowns expire |
| Display Formats |
Full (1d 2h 30m), Short (1d 2h), Seconds (95400) |
| No Cooldown Option |
Use "never" or -1 for instant re-claim |
? Usage Limits
| Feature |
Description |
| Limited Uses |
1-time, 5-time, 100-time kits |
| Unlimited Uses |
Infinite re-claims with cooldown |
| Rank-Based Limits |
Different use counts per rank |
| Use Tracking |
Persistent storage of claim counts |
| Use Reset |
Admin command to reset usage data |
? World Management
| Feature |
Description |
| Global Whitelist |
Restrict plugin to specific worlds |
| Per-Kit Worlds |
Kit only works in designated worlds |
| Multi-World Support |
Different kits for different worlds |
| World Change Detection |
Auto-give starter kits on world entry |
| Bypass Permission |
Admins can use kits anywhere |
? GUI System
| Feature |
Description |
| Main Kit Menu |
Beautiful paginated kit selection GUI |
| Preview Mode |
100% secure view-only kit preview |
| Locked Kit Display |
Shows unavailable kits with requirements |
| Clickable Store Links |
MiniMessage-powered clickable URLs |
| Admin Edit GUI |
Visual drag-and-drop kit editor |
| Confirmation Dialogs |
Deletion confirmations with warnings |
| Pagination |
Auto-pagination for 30+ kits |
| Custom Icons |
Per-kit custom materials and model data |
| Glowing Icons |
Optional enchantment glow effect |
| Dynamic Lore |
Real-time cooldown/uses display |
? Storage Options
| Type |
Use Case |
Pros |
Cons |
| YAML |
Single servers |
Easy setup, human-readable |
Not network-compatible |
| SQLite |
Small-medium servers |
No external DB needed, fast |
Not network-compatible |
| MySQL |
Networks, large servers |
Network sync, scalable |
Requires MySQL server |
? Integrations
| Plugin |
Integration Level |
Features |
| LuckPerms |
⭐⭐⭐⭐⭐ Deep |
Groups, permissions, prefixes, suffixes, rank detection |
| Vault |
⭐⭐⭐⭐ Full |
Economy costs, permission fallback |
| PlaceholderAPI |
⭐⭐⭐⭐⭐ Deep |
15+ custom placeholders |
| bStats |
⭐⭐⭐ Standard |
Anonymous usage metrics |
? Effects & Feedback
| Effect Type |
Customizable |
Per-Kit |
| Sounds |
✅ Yes |
✅ Yes |
| Particles |
✅ Yes |
✅ Yes |
| Titles |
✅ Yes |
✅ Yes |
| Subtitles |
✅ Yes |
✅ Yes |
| Action Bar |
✅ Yes |
✅ Yes |
| Chat Messages |
✅ Yes |
✅ Yes |
| Broadcasts |
✅ Yes |
✅ Yes |
| Fireworks |
✅ Yes |
✅ Yes |
? Advanced Features
| Feature |
Description |
| Starter Kits |
Auto-give on first join per world |
| Economy Costs |
Charge money for kit claims (Vault) |
| XP Requirements |
Require XP levels to claim |
| Item Requirements |
Consume items to claim kit |
| Command Execution |
Run commands on kit claim (console/player/op) |
| One-Time Bonuses |
Extra items on first claim only |
| Auto-Save |
Configurable auto-save intervals |
| Cache System |
Smart caching for performance |
| Async Operations |
Non-blocking database operations |
| Connection Pooling |
HikariCP for MySQL optimization |
? Technical Specifications
System Requirements
Minecraft Version: 1.21+
Server Software: Paper (recommended) or Spigot
Java Version: 17 or higher
RAM: Minimum 512MB allocated to plugin operations
Database: MySQL 5.7+ or MariaDB 10.3+ (optional)
Dependencies
Required:
- None (fully standalone)
Soft Dependencies (Optional):
- LuckPerms 5.4+ (for advanced permissions)
- Vault 1.7+ (for economy features)
- PlaceholderAPI 2.11+ (for placeholders)
Performance Metrics
Average RAM Usage: 20-50MB (depends on kit count)
Database Queries: Fully async, non-blocking
Cache Expiry: 5 minutes (configurable)
GUI Render Time: <5ms
Kit Claim Time: <10ms
Startup Time: <1 second
? Installation Guide
Step 1: Download
- Download
UltraStarterKits
Step 2: Install
Stop your server
stop
Place JAR in plugins folder
cp UltraStarterKits-1.0.0.jar /path/to/server/plugins/
Start server (generates config files)
start
Step 3: Initial Configuration
Wait for server to fully start
Plugin generates default configs in plugins/UltraStarterKits/
Files created:
plugins/UltraStarterKits/
├── config.yml Main configuration
├── kits.yml Kit definitions
├── messages.yml All messages
├── guis.yml GUI layouts
└── playerdata.yml Player data (if using YAML storage)
Step 4: Configure Storage (Optional)
Edit config.yml
storage:
type: "MYSQL" Change from YAML to MYSQL
mysql:
host: "localhost"
port: 3306
database: "ultrakits"
username: "root"
password: "your_password"
Step 5: Reload Configuration
In-game or console
/skit reload
Step 6: Create Your First Kit
Method 1: Command
1. Put items in your inventory
2. /skit create starter kit.use.starter 1 never all
Method 2: GUI
1. /skit edit starter
2. Place items in GUI
3. Click "Save Kit"
⚙️ Configuration
config.yml - Main Settings
General Settings
Enable verbose logging for troubleshooting
debug-mode: false
Check for updates on startup
check-updates: true
Storage Configuration
storage:
YAML = File storage (simple)
SQLITE = Local database (better performance)
MYSQL = Remote database (for networks)
type: "YAML"
mysql:
host: "localhost"
port: 3306
database: "ultrakits"
username: "root"
password: "password"
pool-size: 10 Increase for busy servers
use-ssl: false
Auto-save every X minutes (0 = manual save only)
auto-save-interval: 5
World Whitelist
world-whitelist:
enabled: false Set to true to restrict worlds
worlds:
- "world"
- "world_nether"
- "world_the_end"
- "skyblock"
denied-message: "&cKits are not available in this world!"
Starter Kit Settings
starter-kit:
enabled: true
Delay before giving (allows other plugins to load player data)
delay-seconds: 3
Send welcome message
message-on-receive: true
Give to players who joined before plugin installation
give-to-existing-players: false
GUI Settings
gui:
main-menu:
title: "&8&l✦ &6&lKit Selection &8&l✦"
rows: 6 1-6 rows
filler:
enabled: true
material: "GRAY_STAINED_GLASS_PANE"
name: " "
Locked Kit Settings
locked-kit:
icon: "BARRIER"
name: "&c&l? %kit_name% &c(Locked)"
lore:
- "&c&l✘ &cYou don't have access!"
- "&7Required: &e%required_rank%"
- "&eClick for store link!"
click-message:
- ""
- "&c&l✘ &cYou don't have access to &e%kit_name%&c!"
- "<click:open_url:'%store_url%'>&a&l[CLICK HERE TO PURCHASE]</click>"
- ""
store-url: "https://store.yourserver.com"
sound: "ENTITY_VILLAGER_NO"
Effects Settings
effects:
default-claim-sound: "ENTITY_PLAYER_LEVELUP"
default-claim-particles:
enabled: true
type: "TOTEM_OF_UNDYING"
count: 50
default-title:
enabled: true
title: "&a&l✓ Kit Claimed!"
subtitle: "&7You received &e%kit_name%"
fade-in: 10
stay: 40
fade-out: 10
Economy Settings
economy:
enabled: true Requires Vault
format: "&a$%amount%"
refund-percentage: 100 Refund if claim fails
Cooldown Settings
cooldowns:
FULL: 1d 2h 30m 15s
SHORT: 1d 2h
SECONDS: 95415
display-format: "FULL"
notify-on-expire: true
notify-message: "&a&l✓ &aYour &e%kit_name% &akit is now available!"
Inventory Settings
inventory:
DROP = Drop items on ground
DENY = Cancel kit claim
PARTIAL = Give what fits, drop rest
full-inventory-action: "DROP"
dropped-items-message: "&eSome items were dropped on the ground!"
kits.yml - Kit Definitions
Basic Kit Structure
kits:
kitname:
Display name (supports color codes)
display-name: "&a&lStarter Kit"
Description (shown in GUI)
description:
- "&7Basic items to get started"
- "&7Claim once per lifetime"
GUI icon
icon:
material: "CHEST"
custom-model-data: 0
glowing: true
Permission required
permission: "kit.use.starter"
Rank display name (for GUI)
required-rank-display: "Default"
Category (optional)
category: "Basic"
Max uses (-1 = unlimited)
max-uses: 1
Cooldown (30s, 5m, 2h, 1d, 1w, never)
cooldown: "never"
Rank-based cooldown overrides
cooldown-overrides:
vip: "12h"
mvp: "6h"
elite: "3h"
Worlds where kit is available
worlds:
- "all" or list specific worlds
Starter kit settings
is-starter-kit: true
starter-kit-worlds:
- "world"
Kit items
items:
0:
slot: 0
material: "DIAMOND_SWORD"
amount: 1
name: "&b&lStarter Sword"
lore:
- "&7Your first weapon!"
enchantments:
sharpness: 2
unbreaking: 1
custom-model-data: 0
unbreakable: false
chance: 1.0 1.0 = 100%, 0.5 = 50%
Effects
sound: "ENTITY_PLAYER_LEVELUP"
particles:
type: "TOTEM_OF_UNDYING"
count: 100
title-message: "&a&l✓ Kit Claimed!"
subtitle-message: "&7Enjoy your items!"
actionbar-message: "&aSuccessfully claimed kit!"
chat-messages:
- "&aYou received the starter kit!"
broadcast-message: "&e%player% &aclaimed the starter kit!"
firework-effect: true
Commands on claim
commands-on-claim:
- "[console] give %player% apple 1"
- "[player] me received a kit!"
- "[op] gamemode survival"
Advanced features
economy-cost: 1000 Requires Vault
required-xp-level: 5
required-items:
- material: "DIAMOND"
amount: 5
consume-required-items: true
expiry-date: -1 Unix timestamp or -1
available-days: Leave empty for always
- "SATURDAY"
- "SUNDAY"
available-time-start: "08:00" HH:mm format
available-time-end: "20:00"
one-time-bonus: true
bonus-items:
0:
material: "DIAMOND_BLOCK"
amount: 1
Item Properties Reference
items:
0:
Required
material: "DIAMOND_SWORD" Material name
Optional
amount: 1 Stack size (1-64)
slot: 0 Inventory slot (0-35)
Display
name: "&b&lCustom Name" Item name
lore: Item lore
- "&7Line 1"
- "&7Line 2"
Enchantments
enchantments:
sharpness: 5
unbreaking: 3
fire_aspect: 2
looting: 3
mending: 1
Special properties
custom-model-data: 12345 Custom model data
unbreakable: true Unbreakable flag
Random items
chance: 0.5 50% chance to give
Base64 serialization (auto-generated)
base64: "..." Full NBT preservation
messages.yml - Customizable Messages
Message Categories
Prefix
prefix: "&FFD700&l✦ &6UltraKits &8» &r"
Kit Messages
kit-claimed: "&aYou successfully claimed &e%kit_name%&a!"
kit-on-cooldown: "&cThis kit is on cooldown! &7Available in: &e%time_remaining%"
kit-no-permission: "&cYou don't have permission to use this kit!"
kit-already-claimed: "&cYou've already claimed this kit the maximum number of times!"
kit-not-found: "&cKit '&e%kit_name%&c' was not found!"
kit-wrong-world: "&cThis kit is not available in this world!"
kit-inventory-full: "&cYour inventory is full! Please make some space."
Admin Messages
kit-created: "&aKit '&e%kit_name%&a' has been created successfully!"
kit-deleted: "&aKit '&e%kit_name%&a' has been deleted!"
kit-items-set: "&aSet &e%count% &aitems for kit '&e%kit_name%&a'!"
kit-given: "&aGave kit '&e%kit_name%&a' to &e%player%&a!"
data-reset: "&aReset &e%player%&a's data for kit '&e%kit_name%&a'!"
reload-success: "&aAll configurations reloaded successfully!"
Error Messages
player-not-found: "&cPlayer '&e%player%&c' not found or is offline!"
no-permission: "&cYou don't have permission to do that!"
wrong-world: "&cKits are not available in this world!"
Usage Messages
usage:
skit-claim: "&cUsage: &e/skit claim <kit>"
skit-give: "&cUsage: &e/skit give <player> <kit> [bypass]"
Placeholders in Messages
%player% - Player name
%kit_name% - Kit internal name
%kit_displayname% - Kit display name with colors
%time_remaining% - Formatted cooldown time
%uses_remaining% - Remaining uses
%max_uses% - Maximum uses
%cost% - Economy cost
%required_rank% - Required rank
%permission% - Required permission
%world% - World name
guis.yml - GUI Customization
Main Menu Layout
main-menu:
title: "&8&l✦ &6&lKit Selection &8&l✦"
rows: 6
filler:
enabled: true
material: "GRAY_STAINED_GLASS_PANE"
name: " "
Slots where kits appear (auto-fill)
kit-slots:
- 10
- 11
- 12
- 13
- 14
- 15
- 16
- 19
- 20
... more slots
buttons:
previous-page:
slot: 48
material: "ARROW"
name: "&a&l« Previous Page"
hide-if-first-page: true
next-page:
slot: 50
material: "ARROW"
name: "&a&lNext Page »"
hide-if-last-page: true
page-indicator:
slot: 49
material: "PAPER"
name: "&ePage %current% / %total%"
close:
slot: 53
material: "BARRIER"
name: "&c&lClose"
Preview Menu
preview-menu:
title: "&8Previewing: &6%kit_name%"
rows: 6
buttons:
back:
slot: 49
material: "ARROW"
name: "&c&l« Back to Kits"
info:
slot: 45
material: "BOOK"
name: "&e&l%kit_name%"
lore:
- "&7Permission: &f%permission%"
- "&7Uses: &f%uses%"
- "&cThis is a preview only!"
? Commands Reference
Player Commands
/skit
Opens the main kit selection GUI.
Usage: /skit
Aliases: /kit, /kits, /starterkit, /ultrakits, /uk
Permission: ultrakits.use
Example:
/skit
Opens GUI with all available kits
/skit list
Opens the kit list GUI (same as /skit).
Usage: /skit list
Permission: ultrakits.use
/skit claim <kit>
Claims a specific kit by name.
Usage: /skit claim <kitname>
Permission: ultrakits.use + kit-specific permission
Arguments:
<kitname> - The internal name of the kit
Examples:
/skit claim starter
/skit claim daily
/skit claim vip
Validation:
- Checks if kit exists
- Verifies permission
- Validates cooldown
- Confirms remaining uses
- Checks world restriction
- Verifies inventory space
/skit preview <kit>
Opens a view-only preview of the kit contents.
Usage: /skit preview <kitname>
Permission: ultrakits.use
Examples:
/skit preview vip
/skit preview mvp
Features:
- 100% secure (cannot take items)
- Shows all kit items
- Displays kit information
- Back button to return
/skit info <kit>
Displays detailed kit information in chat.
Usage: /skit info <kitname>
Permission: ultrakits.use
Example Output:
✦ Kit Info: Starter Kit ✦
Name: starter
Permission: kit.use.starter
Description:
Basic items to get started
Claim once per lifetime
Max Uses: 1
Cooldown: None
Worlds: All Worlds
Starter Kit: Yes
Items: 8
Your Remaining Uses: 1
Your Cooldown: Ready!
/skit cooldown <kit>
Checks remaining cooldown time for a kit.
Usage: /skit cooldown <kitname>
Permission: ultrakits.use
Examples:
/skit cooldown daily
Output: Daily Kit cooldown: 5h 32m 15s
/skit cooldown vip
Output: VIP Kit is ready to claim!
Admin Commands
/skit create <name> <permission> <uses> <cooldown> <world>
Creates a new kit from your current inventory.
Usage: /skit create <name> <permission> <uses> <cooldown> <world>
Permission: ultrakits.admin.create
Arguments:
<name> - Kit internal name (lowercase, no spaces)
<permission> - Required permission (e.g., kit.use.vip)
<uses> - Max uses (1, 5, unlimited, -1)
<cooldown> - Cooldown time (30s, 5m, 24h, never, -1)
<world> - World restriction (all, world, skyblock)
Examples:
Create a one-time starter kit
/skit create starter kit.use.starter 1 never all
Create a VIP kit with 24h cooldown
/skit create vip kit.use.vip unlimited 24h all
Create a PvP kit only for pvp world
/skit create pvpkit kit.use.pvp unlimited 5m pvp
Create a weekly kit
/skit create weekly kit.use.weekly unlimited 7d all
Process:
- Put items in your inventory (arrange them as you want)
- Run the create command
- Plugin captures all inventory items
- Kit is created with default settings
- Further customize with other commands or edit GUI
/skit delete <kit>
Deletes a kit permanently.
Usage: /skit delete <kitname>
Permission: ultrakits.admin.delete
Example:
/skit delete oldkit
Opens confirmation GUI
Safety:
- Opens confirmation dialog
- Shows kit item count
- Warns about permanent deletion
- Click confirm to delete
- Click cancel to abort
/skit edit <kit>
Opens the visual kit editor GUI.
Usage: /skit edit <kitname>
Permission: ultrakits.admin.edit
Example:
/skit edit vip
Opens 6-row inventory editor
Features:
- Drag-and-drop items
- Visual item arrangement
- Save button
- Cancel button
- Settings button (shows current config)
/skit setitems <kit>
Sets kit items from your current inventory.
Usage: /skit setitems <kitname>
Permission: ultrakits.admin.edit
Example:
1. Arrange items in your inventory
2. Run command
/skit setitems vip
Output: Set 15 items for kit 'vip'!
/skit additem <kit>
Adds your held item to the kit.
Usage: /skit additem <kitname>
Permission: ultrakits.admin.edit
Example:
1. Hold a diamond sword
2. Run command
/skit additem vip
Output: Added Diamond Sword to kit 'vip'!
/skit removeitem <kit> <slot>
Removes an item from a specific slot.
Usage: /skit removeitem <kitname> <slot>
Permission: ultrakits.admin.edit
Arguments:
<slot> - Slot number (0-based index)
Example:
/skit removeitem vip 5
Output: Removed item at slot 5 from kit 'vip'!
/skit seticon <kit>
Sets the GUI icon to your held item.
Usage: /skit seticon <kitname>
Permission: ultrakits.admin.edit
Example:
1. Hold a gold block
2. Run command
/skit seticon vip
Output: Set icon for 'vip' to GOLD_BLOCK!
/skit setpermission <kit> <permission>
Changes the required permission.
Usage: /skit setpermission <kitname> <permission>
Permission: ultrakits.admin.edit
Example:
/skit setpermission vip kit.use.vipplus
Output: Set permission for 'vip' to kit.use.vipplus!
/skit setuses <kit> <amount>
Sets maximum uses.
Usage: /skit setuses <kitname> <amount|unlimited>
Permission: ultrakits.admin.edit
Examples:
/skit setuses starter 1
Output: Set max uses for 'starter' to 1!
/skit setuses daily unlimited
Output: Set max uses for 'daily' to Unlimited!
/skit setuses weekly 52
Output: Set max uses for 'weekly' to 52!
/skit setcooldown <kit> <time>
Sets cooldown time.
Usage: /skit setcooldown <kitname> <time|never>
Permission: ultrakits.admin.edit
Time Format:
30s - 30 seconds
5m - 5 minutes
2h - 2 hours
1d - 1 day
1w - 1 week
never or -1 - No cooldown
Examples:
/skit setcooldown daily 24h
/skit setcooldown vip 12h
/skit setcooldown pvp 5m
/skit setcooldown starter never
/skit setworld <kit> <world>
Sets world restriction.
Usage: /skit setworld <kitname> <world|all>
Permission: ultrakits.admin.edit
Examples:
/skit setworld pvpkit pvp
Output: Set world for 'pvpkit' to pvp!
/skit setworld daily all
Output: Set world for 'daily' to All Worlds!
/skit setworld skyblock skyblock_world
/skit setstarterkit <kit> <true|false>
Toggles starter kit status.
Usage: /skit setstarterkit <kitname> <true|false>
Permission: ultrakits.admin.edit
Examples:
/skit setstarterkit starter true
Output: Starter kit status for 'starter' set to Enabled!
/skit setstarterkit daily false
Output: Starter kit status for 'daily' set to Disabled!
/skit give <player> <kit> [bypass]
Gives a kit to a player.
Usage: /skit give <player> <kitname> [bypass]
Permission: ultrakits.admin.give
Arguments:
<player> - Player name (must be online)
<kitname> - Kit to give
[bypass] - Optional: bypasses all restrictions
Examples:
/skit give Steve starter
Gives starter kit (checks all restrictions)
/skit give Steve vip bypass
Gives VIP kit (bypasses cooldown, uses, permissions)
/skit give Steve daily true
Same as bypass
Use Cases:
- Reward players
- Compensate for bugs
- Event prizes
- Testing kits
/skit reset <player> [kit|all]
Resets player kit data.
Usage: /skit reset <player> [kitname|all]
Permission: ultrakits.admin.reset
Examples:
Reset specific kit
/skit reset Steve starter
Output: Reset Steve's data for kit 'starter'!
Reset all kits
/skit reset Steve all
Output: Reset all kit data for Steve!
What Gets Reset:
- Use counts
- Cooldown timestamps
- Bonus received flags
- (Does NOT delete kits themselves)
/skit reload
Reloads all configuration files.
Usage: /skit reload
Permission: ultrakits.admin.reload
Can be run from console: Yes
Example:
/skit reload
Output: All configurations reloaded successfully!
What Gets Reloaded:
- config.yml
- kits.yml
- messages.yml
- guis.yml
- All kits from file
Note: Player data in cache is NOT reset
? Permissions System
Permission Hierarchy
ultrakits.*
├── ultrakits.admin
│ ├── ultrakits.admin.create
│ ├── ultrakits.admin.delete
│ ├── ultrakits.admin.edit
│ │ ├── ultrakits.admin.edit.items
│ │ ├── ultrakits.admin.edit.icon
│ │ └── ultrakits.admin.edit.settings
│ ├── ultrakits.admin.give
│ ├── ultrakits.admin.reset
│ └── ultrakits.admin.reload
│
├── ultrakits.use
│ ├── ultrakits.command.list
│ ├── ultrakits.command.claim
│ ├── ultrakits.command.preview
│ ├── ultrakits.command.info
│ ├── ultrakits.command.cooldown
│ └── ultrakits.command.help
│
└── ultrakits.bypass.*
├── ultrakits.bypass.cooldown
├── ultrakits.bypass.uses
├── ultrakits.bypass.world
├── ultrakits.bypass.permission
└── ultrakits.bypass.cost
Permission Nodes Reference
| Permission |
Default |
Description |
ultrakits.* |
op |
Full access to everything |
ultrakits.admin |
op |
All admin commands |
ultrakits.use |
true |
Basic kit usage |
ultrakits.bypass.* |
op |
Bypass all restrictions |
ultrakits.bypass.cooldown |
op |
No cooldowns |
ultrakits.bypass.uses |
op |
Unlimited uses |
ultrakits.bypass.world |
op |
Use kits in any world |
ultrakits.bypass.permission |
op |
Access all kits |
ultrakits.bypass.cost |
op |
Free kits |
kit.use.<kitname> |
false |
Access to specific kit |
LuckPerms Setup Examples
Basic Player (Default Group)
Give basic kit access
lp group default permission set ultrakits.use true
lp group default permission set kit.use.starter true
lp group default permission set kit.use.daily true
VIP Rank
Create VIP group
lp creategroup vip
Set parent group
lp group vip parent add default
Add VIP kit permissions
lp group vip permission set kit.use.vip true
lp group vip permission set kit.use.daily true
Set VIP as primary group for player
lp user Steve parent set vip
? Advanced Features
Rank-Based Cooldown Overrides
How It Works:
- Base cooldown is set in kit config
- LuckPerms group names are detected
- If player's group has an override, it's used instead
Example Configuration:
kits:
daily:
cooldown: "24h" Default for everyone
cooldown-overrides:
vip: "18h" VIPs wait 18 hours
mvp: "12h" MVPs wait 12 hours
elite: "6h" Elites wait 6 hours
ultimate: "1h" Ultimates wait 1 hour
Real-World Example:
Default player: Claims kit → waits 24 hours
VIP player: Claims kit → waits 18 hours
MVP player: Claims kit → waits 12 hours
Elite player: Claims kit → waits 6 hours
World Restriction System
Global Whitelist
Restricts the entire plugin to specific worlds.
config.yml
world-whitelist:
enabled: true
worlds:
- "world"
- "survival"
- "skyblock"
Effect: Commands don't work in other worlds.
Per-Kit Worlds
Restricts individual kits to specific worlds.
kits.yml
kits:
pvp-kit:
worlds:
- "pvp"
- "arena"
survival-kit:
worlds:
- "survival"
global-kit:
worlds:
- "all"
Use Cases:
- PvP kits only in PvP worlds
- Survival kits not in creative worlds
- Skyblock-specific starter packs
Economy Integration (Vault)
Setup
- Install Vault + economy plugin (EssentialsX, etc.)
- Enable in config:
economy:
enabled: true
format: "&a$%amount%"
Kit Configuration
kits:
premium:
economy-cost: 5000 Costs $5000
Features
- Automatic balance check
- Deducts money on claim
- Refunds if claim fails
- Shows cost in GUI
Setup Steps:
- Install MySQL server
- Create database:
CREATE DATABASE ultrakits;
- Configure plugin with credentials
- Restart server (tables auto-create)
Network Setup (BungeeCord):
Same MySQL config on all servers
Players' data syncs automatically across network
? PlaceholderAPI Integration
Installation
- Install PlaceholderAPI:
/papi download ultrakits
- Reload:
/papi reload
Available Placeholders
Per-Kit Placeholders
| Placeholder |
Output Example |
Description |
%ultrakit_uses_remaining_<kit>% |
3 |
Remaining uses for kit |
%ultrakit_uses_total_<kit>% |
5 |
Total max uses |
%ultrakit_cooldown_<kit>% |
3600 |
Cooldown in seconds |
%ultrakit_cooldown_formatted_<kit>% |
1h 30m |
Formatted time |
%ultrakit_can_claim_<kit>% |
true |
If player can claim |
%ultrakit_has_permission_<kit>% |
false |
If has permission |
%ultrakit_kit_displayname_<kit>% |
&a&lStarter Kit |
Kit display name |
%ultrakit_kit_exists_<kit>% |
true |
If kit exists |
Global Placeholders
| Placeholder |
Output Example |
Description |
%ultrakit_total_kits_claimed% |
47 |
Total kits claimed by player |
%ultrakit_available_kits_count% |
8 |
Kits currently available |
%ultrakit_next_available_kit% |
Daily Kit |
Next claimable kit name |
%ultrakit_total_kits% |
15 |
Total kits on server |
%ultrakit_player_group% |
vip |
Player's LuckPerms group |
❓ FAQ & Troubleshooting
General Questions
Q: What Minecraft versions are supported?
A: Minecraft 1.21.x on Paper or Spigot.
Q: Do I need Paper or will Spigot work?
A: Both work, but Paper is recommended for better performance and native Adventure API support.
Q: Is this compatible with BungeeCord/Velocity?
A: Yes! Use MySQL storage and configure the same database on all servers.
Q: Can I translate messages to other languages?
A: Yes! All messages are in messages.yml and fully customizable.
Installation Issues
Q: Plugin doesn't load on startup
A: Check console for errors. Common issues:
- Wrong Java version (need Java 17+)
- Wrong Minecraft version (need 1.21+)
- Corrupted JAR file (re-download)
Q: Commands don't work
A: Verify:
- Plugin is enabled (
/plugins shows green)
- You have permission (
ultrakits.use)
- World is whitelisted (if whitelist is enabled)
Database Issues
Q: MySQL won't connect
A: Checklist:
- MySQL server is running
- Database exists (
CREATE DATABASE ultrakits;)
- Credentials are correct
- Port is correct (default 3306)
- Host is correct (usually
localhost)
- Firewall allows connection
Q: SQLite file is locked
A: Usually caused by:
- Multiple servers using same file
- Previous server crash
- Solution: Restart server or delete
.db file (WARNING: deletes data)
Q: Player data not saving
A: Check:
- Auto-save is enabled
- Database connection is working
- Console for error messages
- Manually save:
/skit reload
Kit Issues
Q: Kit items aren't saving correctly
A: This usually happens with custom NBT data. Fix:
- Use Paper (better NBT support than Spigot)
- Recreate kit using
/skit edit GUI
- Check console for serialization errors
Q: Enchantments not working
A: Ensure:
- Enchantment names are correct (lowercase, underscores)
- Example:
sharpness: 5 not Sharpness: V
- Use Minecraft enchantment IDs
Q: Custom model data not saving
A: Set in config:
custom-model-data: 12345
Permission Issues
Q: Everyone can use all kits
A: Check:
- Kit permissions are set correctly
- Players don't have
ultrakits.* wildcard
- LuckPerms is installed and working
Q: LuckPerms groups not detected
A: Verify:
- LuckPerms is installed and enabled
- Plugin detects LuckPerms (check startup log)
- Group names match exactly (case-sensitive)
Q: Rank overrides not working
A: Ensure:
- Group name in config matches LuckPerms group
- Player is in that group (
/lp user <player> info)
- Example:
cooldown-overrides:
vip: "12h" Must match LuckPerms group "vip"
Cooldown Issues
Q: Cooldown not working
A: Check:
- Time format is correct (
24h not 24hours)
- Cooldown is set in kit config
- Player doesn't have bypass permission
Q: Cooldown shows wrong time
A: Verify:
- Server time is correct
- No conflicting plugins modifying time
- Reload plugin:
/skit reload
GUI Issues
Q: GUI doesn't open
A: Causes:
- Inventory is full (server blocks opening)
- Permission missing
- World not whitelisted
Q: Items can be taken from preview GUI
A: This shouldn't happen. If it does:
- Report as a bug
- Update to latest version
- Check for conflicting inventory plugins
Q: Pagination not working
A: Usually happens when:
- Too many kits (100+)
- GUI config is wrong
- Fix: Adjust
kit-slots in guis.yml
Performance Issues
Q: Server lags when opening GUI
A: Optimization tips:
- Reduce kit count (split into categories)
- Use MySQL instead of YAML
- Increase cache expiry time
- Check for other laggy plugins
Q: High RAM usage
A: Normal usage is 20-50MB. If higher:
- Too many kits cached
- Clear cache: restart server
- Reduce auto-save frequency
Error Messages
Q: "Kit not found" even though it exists
A: Common causes:
- Typo in kit name (case-sensitive)
- Kit not loaded (reload:
/skit reload)
- Corrupted
kits.yml
Q: "Failed to serialize item"
A: Item has unsupported NBT:
- Simplify the item
- Remove custom NBT
- Use vanilla items only
Q: "Database error" on startup
A: Check:
- Database credentials
- Database server is running
- Network connection
- Console for specific SQL error
? Support & Resources
Official Links
- Discord: discord.gg/ultrakits
Getting Help
Feature Requests
Submit feature requests on:
Bug Reports
Include:
- Server version
- Plugin version
- Error logs
- Steps to reproduce
- Screenshots (if GUI issue)
? License & Credits
Plugin Name: UltraStarterKits
Version: 1.0.0
Author: geturplugins
License: All Rights Reserved
? Thank You!
Thank you for choosing UltraStarterKits! We hope it enhances your server and provides an excellent experience for your players.
If you enjoy the plugin, please:
- ⭐ Leave a 5-star review
- ? Recommend to other server owners
- ? Join our Discord community
Happy server management! ?**
评论 0
登录后参与评分
还没有评论,来抢沙发吧