QKits
QKits 是一款现代化的 Paper/Purpur 1.21.11 套件管理、自定义和分发插件,专为竞技 PvP 赛事、内容创作者的生存多人游戏(SMP)以及锦标赛服务器打造。作为 QTeams 和 QWorlds 的配套插件,QKits 将无损二进制 NBT 物品序列化与 Mojang 的原生对话框 UI (io.papermc.paper.dialog) 以及 1.21.11 2D Atlas Sprite 组件 (ObjectContents.sprite) 相结合,直接在悬停提示框和游戏内套件编辑器中渲染图形化的 2D 物品网格,无需任何客户端模组或资源包。
核心架构与功能
1. 三种套件类别及命名前缀(Full、Inventory i_、Armor a_)
QKits 将装备配置组织为三个独立的命名空间,以便不同类别的套件可以共享基础名称而不会产生冲突:
- 完整套件(
<kitname>): 保存所有 36 个存储槽 + 1 副手槽 + 4 个护甲槽。支持完全装备,或独立提取/更新**仅背包+副手(+inv)或仅护甲(+armor)**部分。
- 背包套件(
i_<kitname>): 保存 36 个存储槽 + 1 副手槽(不触碰玩家已穿戴的护甲)。在命令和标签补全中始终引用为 i_<name>。
- 护甲套件(
a_<kitname>): 保存 4 个护甲槽(头盔、胸甲、护腿、靴子),并直接自动装备到玩家身上,不触碰其背包或副手。始终引用为 a_<name>。
2. 像素对齐的三列原生对话框 UI 与 2D 物品 Sprite 网格
- 统一的三列仪表板(
/qk): 以带边框、像素对齐的三列表格形式并排显示完整套件、背包套件(i_)和护甲套件(a_)(│ Full │ Inv │ Armor │),其中完整套件的名称始终可见。
- 点击套件名称: 立即为自己装备该套件。
- 悬停套件名称或
[✎]: 显示图形化 2D 物品 Sprite 提示框,从左到右展示套件的护甲 Sprite、副手 Sprite、3x9 主背包行和 1x9 快捷栏行。
- 点击
[✎]: 打开菜单内的套件编辑器。
- 点击
[✖]: 打开删除确认对话框。
- 角色感知的公开选择器(非 OP 玩家的
/qk): 非 OP 玩家看到一个干净的三列选择器,仅显示标记为 Public 的套件;点击套件即可领取,悬停预览其 2D 物品网格。
3. 菜单内 2D Sprite 背包编辑器与 54 槽拖放网格
- 对话框内的可视化 2D Sprite 布局:
[✎] 套件编辑器使用实际的 2D 物品纹理(minecraft:items、minecraft:blocks、minecraft:gui)渲染左侧的 4 个护甲槽、中间从左到右的 9x4 背包网格以及右侧的副手槽。
- 一键分配手部和覆盖: 悬停对话框中的任意槽位可查看其完整的 Minecraft 物品提示框;点击任意槽位可用当前主手中的物品替换它;或使用**“保存我的背包:[All] [Inv] [Armor]”**从当前装备覆盖套件(或仅覆盖完整套件的某一部分)。
- 交互式 54 槽箱子网格(
[Slot Grid]): 随时启动一个实时的 54 槽箱子编辑器,物理地拖放、移动和重新排列跨 36 个存储槽、4 个护甲槽和 1 个副手槽的物品。
4. 菜单内护甲纹饰工作室([Trim Studio])
- 实时 2D 纹饰护甲预览: 直接在对话框菜单内自定义护甲纹饰,无需生成世界实体。
- 全部 18 种图案与 11 种材质: 对单个护甲部件或一次性应用于全部 4 件护甲应用18 种纹饰图案(
Silence、Bolt、Flow、Spire、Ward、Eye、Rib、Vex、Tide、Snout、Sentry、Dune、Coast、Wild、Wayfinder、Shaper、Raiser、Host)和11 种纹饰材质(Amethyst、Gold、Diamond、Netherite、Emerald、Redstone、Lapis、Quartz、Copper、Iron、Resin),并观察左侧的 2D 纹饰护甲 Sprite 实时更新。
5. 带有原生等级与持续时间滑杆的药水效果引擎
- 26 种可选效果(
/qk potions <kit>): 附加自定义药水效果(Speed、Strength、Fire Resistance、Regeneration、Resistance、Jump Boost、Invisibility、Absorption、Wind Charged、Weaving、Oozing 等),在装备套件时自动生效。
- 原生数值范围滑杆: 点击任意效果会打开两个带有实时数值指示器的
DialogInput.numberRange 滑杆:
- 效果等级滑杆:
1 至 10(步长 1)。
- 效果持续时间滑杆:
30 sec 至 960 sec / 16 mins(以 30 sec 为间隔)。
6. 智能装备、空槽验证与按生命领取限制
- 特定类型清除与替换 vs. 安全合并:
- 当启用替换(
☑)(默认)时,装备操作仅清除属于该套件类型的槽位(例如,a_ 护甲套件仅清除 4 个护甲槽;i_ 背包套件仅清除存储槽+副手槽)。
- 当**替换(
☐)**未勾选时,QKits 会在装备前验证玩家是否有足够的空槽来容纳所有物品——如果没有,则取消装备并告知玩家需要释放多少个槽位,以防止物品掉落在地上。
- 按生命/大厅访问领取限制与冷却时间: 可将公开套件配置为“每生命/每次大厅访问一次”(默认)、
0s、10s、30s、1m 或 5m。设置为“每生命/每次大厅访问一次”时,非 OP 玩家每回合可领取一次该套件,且当他们在世界中死亡或访问 QWorlds 虚空大厅(例如回合结束后或被大厅踢棍击中后)时,其领取锁定会自动重置。
- QWorlds 虚空大厅保护锁定: 当非 OP 玩家站在
qwlobby_hub 内时,自动阻止其领取套件,以确保大厅遗迹永远不会被覆盖。
7. Lossless Paper 1.21.11 Binary NBT Serialization
- 使用 Paper 原生的
ItemStack.serializeAsBytes() / ItemStack.deserializeBytes() 方法,在异步保存的 kits.yml 文件中以 Base64 格式编码物品。
- 保留 100% 的物品数据:MiniMessage 十六进制渐变、自定义小型大写字母字体、附魔、自定义耐久度、不可破坏标志、盔甲纹饰、属性修饰符、药水内容物,以及已填充的潜影盒或包裹。
命令与权限参考
玩家命令
/qk(或 /kit、/kits)— 打开公共套装选择器对话框(对于 OP 则打开完整的管理面板)。
/qk claim <kit | i_kit | a_kit> — 领取一个公共套装(Tab 补全会自动筛选出公共套装)。
/qk search <query> — 按名称过滤套装面板。
管理员与 OP 命令 (qkits.admin 或 OP)
/qk save <full|inv|armor> <name> — 将您当前的装备保存为全套装(<name>)、仅背包套装(i_<name>)或仅盔甲套装(a_<name>)。
/qk give <kit | i_kit | a_kit> [player|@team|@box|@a|@p|@r|@s|r] [all|inv|armor] — 向任何玩家、QTeams @team、QWorlds @box、分数选择器(如 @red[50%]、@box[1/2])或随机玩家(r)发放套装(或仅全套装中的 inv 或 armor 部分)。
/qk extract <full_kit> <inv|armor> [target] — 从全套装中提取仅包含“背包+副手”或“盔甲”的部分。
/qk update <kit | i_kit | a_kit> [all|inv|armor] — 用当前背包中的物品覆盖已保存的套装(或全套装的特定部分)。
/qk edit <kit | i_kit | a_kit> — 打开该套装的编辑对话框。
/qk potions <kit | i_kit | a_kit> — 打开药水效果与滑块对话框。
/qk delete <kit | i_kit | a_kit> — 打开删除确认对话框。
/qk perm <kit | i_kit | a_kit> <op|everyone|toggle> — 设置非 OP 玩家是否可以领取该套装。
/qk clearmode <kit | i_kit | a_kit> <on|off|toggle> — 切换装备时是否先清空目标槽位。
/qk cooldown <kit | i_kit | a_kit> <once|0|10|30|60|300> — 设置非 OP 玩家的领取限制/冷却时间。
/qk icon <kit | i_kit | a_kit> <hand|auto|material> — 自定义套装的显示图标,同时保持其名称不变。
/qk reload — 从磁盘重新加载 kits.yml。
服务器要求与软依赖
- 服务器软件: Paper 或 Purpur 1.21.11。
- Java 运行时: Java 21。
- 软依赖:
QTeams (2.0.0+) — 启用 @team 套装分发及跨插件导航功能。
QWorlds (3.0.0+) — 启用 @box 套装分发、分数选择器及虚空大厅领取保护功能。
QKits
QKits is a modern Paper/Purpur 1.21.11 kit management, customization, and distribution plugin built for competitive PvP events, content creator SMPs, and tournament servers. Designed as the companion to QTeams and QWorlds, QKits combines lossless binary NBT item serialization with Mojang's Native Dialog UI (io.papermc.paper.dialog) and 1.21.11 2D Atlas Sprite components (ObjectContents.sprite), rendering graphical 2D item grids directly inside hover tooltips and the in-menu kit editor without requiring any client mods or resource packs.
Core Architecture & Features
1. Three Kit Categories & Naming Prefixes (Full, Inventory i_, Armor a_)
QKits organizes loadouts into three independent namespaces so kits can share base names across categories without conflict:
- Full Kits (
<kitname>): Saves all 36 Storage Slots + 1 Offhand Slot + 4 Armor Slots. Supports full equipping or independent extraction/updating of Inventory + Offhand Only (+inv) or Armor Only (+armor).
- Inventory Kits (
i_<kitname>): Saves 36 Storage Slots + 1 Offhand Slot (leaves the player's worn armor untouched). Always referenced as i_<name> in commands and tab-completion.
- Armor Kits (
a_<kitname>): Saves the 4 Armor Slots (Helmet, Chestplate, Leggings, Boots) and auto-equips them directly onto the player without touching their inventory or offhand. Always referenced as a_<name>.
2. Pixel-Aligned 3-Column Native Dialog UI & 2D Item Sprite Grids
- Unified 3-Column Dashboard (
/qk): Displays Full Kits, Inventory Kits (i_), and Armor Kits (a_) side-by-side in a framed, pixel-aligned 3-column table (│ Full │ Inv │ Armor │) where full kit names are always visible.
- Click Kit Name: Immediately equips the kit on yourself.
- Hover Kit Name or
[✎]: Displays a graphical 2D Item Sprite Tooltip showing the kit's Armor sprites, Offhand sprite, 3x9 Main Inventory rows, and 1x9 Hotbar row left-to-right.
- Click
[✎]: Opens the in-menu Kit Editor.
- Click
[✖]: Opens a Delete Confirmation Dialog.
- Role-Aware Public Selector (
/qk for Non-OPs): Non-OP players see a clean 3-column selector showing only kits marked Public, where clicking a kit claims it and hovering previews its 2D item grid.
3. In-Menu 2D Sprite Inventory Editor & 54-Slot Drag-and-Drop Grid
- Visual 2D Sprite Layout inside the Dialog: The
[✎] Kit Editor renders the 4 Armor Slots on the left, the 9x4 Left-to-Right Inventory Grid in the center, and the Offhand Slot on the right using actual 2D item textures (minecraft:items, minecraft:blocks, minecraft:gui).
- 1-Click Hand Assignment & Overwriting: Hover any slot in the Dialog to inspect its full Minecraft item tooltip, click any slot to replace it with the item in your main hand, or use
Save My Inv: [All] [Inv] [Armor] to overwrite the kit (or just one section of a Full Kit) from your current gear.
- Interactive 54-Slot Chest Grid (
[Slot Grid]): Launch a live 54-slot chest editor at any time to physically drag, drop, and rearrange items across the 36 storage, 4 armor, and 1 offhand slots.
4. In-Menu Armor Trim Studio ([Trim Studio])
- Live 2D Trimmed Armor Preview: Customize armor trims directly inside the Dialog menu without spawning world entities.
- All 18 Patterns & 11 Materials: Apply any of the 18 Trim Patterns (
Silence, Bolt, Flow, Spire, Ward, Eye, Rib, Vex, Tide, Snout, Sentry, Dune, Coast, Wild, Wayfinder, Shaper, Raiser, Host) and 11 Trim Materials (Amethyst, Gold, Diamond, Netherite, Emerald, Redstone, Lapis, Quartz, Copper, Iron, Resin) to a single armor piece or All 4 Pieces at Once, and watch the 2D trimmed armor sprites update live on the left.
5. Potion Effects Engine with Native Level & Duration Sliders
- 26 Selectable Effects (
/qk potions <kit>): Attach custom potion effects (Speed, Strength, Fire Resistance, Regeneration, Resistance, Jump Boost, Invisibility, Absorption, Wind Charged, Weaving, Oozing, etc.) that automatically apply when the kit is equipped.
- Native Number-Range Sliders: Clicking any effect opens two
DialogInput.numberRange sliders with live numeric indicators:
- Effect Level Slider:
1 to 10 (step 1).
- Effect Duration Slider:
30 sec to 960 sec / 16 mins (in 30 sec intervals).
6. Smart Equipping, Open-Slot Verification & Per-Life Claim Limits
- Type-Specific Clear & Replace vs. Safe Merge:
- When
Replace (☑) is enabled (default), equipping clears only the slots belonging to that kit type (e.g., an a_ Armor Kit only clears the 4 armor slots; an i_ Inventory Kit only clears storage + offhand).
- When
Replace (☐) is unchecked, QKits verifies that the player has enough empty slots to fit every item before equipping—if not, it cancels the equip and tells the player how many slots to free up so items never drop on the ground.
- Per-Life / Lobby-Visit Claim Limits & Cooldowns: Configure public kits to
Once Per Life / Lobby Visit (default), 0s, 10s, 30s, 1m, or 5m. When set to Once Per Life / Lobby Visit, non-OPs can claim the kit once per round, and their claim lock automatically resets when they die in a world or visit the QWorlds Void Lobby (e.g., after a round or when hit with the Lobby Kick Stick).
- QWorlds Void Lobby Protection Lock: Automatically blocks non-OP players from claiming kits while standing inside
qwlobby_hub so lobby relics are never overwritten.
7. Lossless Paper 1.21.11 Binary NBT Serialization
- Encodes items using Paper's native
ItemStack.serializeAsBytes() / ItemStack.deserializeBytes() in Base64 inside an asynchronously saved kits.yml file.
- Preserves 100% of item data: MiniMessage hex gradients, custom small-caps fonts, enchantments, custom durability, unbreakable flags, armor trims, attribute modifiers, potion contents, and filled Shulker Boxes or Bundles.
Command & Permission Reference
Player Commands
/qk (or /kit, /kits) — Opens the Public Kit Selector Dialog (or the full Admin Dashboard for OPs).
/qk claim <kit | i_kit | a_kit> — Claims a public kit (tab-completion automatically filters to public kits).
/qk search <query> — Filters the kit dashboard by name.
Admin & Operator Commands (qkits.admin or OP)
/qk save <full|inv|armor> <name> — Saves your current loadout as a Full (<name>), Inventory (i_<name>), or Armor (a_<name>) kit.
/qk give <kit | i_kit | a_kit> [player|@team|@box|@a|@p|@r|@s|r] [all|inv|armor] — Gives a kit (or just the inv or armor half of a Full Kit) to any player, QTeams @team, QWorlds @box, fractional selector (@red[50%], @box[1/2]), or random player (r).
/qk extract <full_kit> <inv|armor> [target] — Extracts only the Inventory+Offhand or Armor from a Full Kit.
/qk update <kit | i_kit | a_kit> [all|inv|armor] — Overwrites a saved kit (or a specific section of a Full Kit) from your current inventory.
/qk edit <kit | i_kit | a_kit> — Opens the Kit Editor Dialog for that kit.
/qk potions <kit | i_kit | a_kit> — Opens the Potion Effects & Sliders Dialog.
/qk delete <kit | i_kit | a_kit> — Opens the Delete Confirmation Dialog.
/qk perm <kit | i_kit | a_kit> <op|everyone|toggle> — Sets whether non-OP players can claim the kit.
/qk clearmode <kit | i_kit | a_kit> <on|off|toggle> — Toggles whether equipping clears target slots first.
/qk cooldown <kit | i_kit | a_kit> <once|0|10|30|60|300> — Sets the claim limit/cooldown for non-OP players.
/qk icon <kit | i_kit | a_kit> <hand|auto|material> — Customizes the kit's display icon while keeping its name intact.
/qk reload — Reloads kits.yml from disk.
Server Requirements & Soft Dependencies
- Server Software: Paper or Purpur 1.21.11.
- Java Runtime: Java 21.
- Soft Dependencies:
QTeams (2.0.0+) — Enables @team kit distribution and cross-plugin navigation.
QWorlds (3.0.0+) — Enables @box kit distribution, fractional selectors, and Void Lobby claim protection.
评论 0
登录后参与评分
还没有评论,来抢沙发吧