UltiKits - 礼包系统

UltiKits 是 UltiTools 的礼包（Kit）管理模块，让你可以创建、管理和分发物品礼包给玩家。

功能概述

UltiKits 提供了一套完整的礼包系统。管理员可以在游戏内通过命令快速创建礼包，也可以用可视化编辑器修改礼包内容。玩家可以通过分页 GUI 界面浏览所有可用礼包，点击即可领取。每个礼包支持独立的价格设定（需要 Vault 经济插件）、等级要求、权限节点、冷却时间和一次性领取限制。领取礼包时还可以自动执行指定的玩家命令和控制台命令。礼包配置采用每个礼包一个 YAML 文件的形式，方便管理。

安装

方法一：通过 UPM 安装（推荐）

在游戏内或控制台执行：

/upm install ultikits.kits

方法二：手动安装

1. 先安装 UltiTools-API 6.3.0 或更高版本，再下载 UltiKits-2.0.0.jar
2. 将 JAR 文件放入 plugins/UltiTools/plugins/ 目录
3. 重启服务器

升级到 2.0.0

先备份配置、礼包文件和领取记录，安装 UltiTools-API 6.3.0 或更高版本，换入 UltiKits-2.0.0.jar 后完整重启。模块在目录中的身份是 ultikits.kits（保留点号），框架更新检查和 /upm update 用它识别模块；框架重载/卸载使用 plugin.yml 名称 UltiTools-Kits。新 JAR 不能靠 /ul reload 加载，现有配置值也不会自动换成新默认值。

检查旧主配置：enabled、kits_per_page、click_cooldown_ms 现在会真的生效，默认仍是 true、28、200。若原文件中 enabled: false，升级后礼包系统将关闭，包括帮助、列表、重载以及已打开编辑器的保存。要恢复，编辑 plugins/UltiTools/pluginConfig/UltiTools-Kits/config/config.yml 设置 enabled: true，执行 /ul reload UltiTools-Kits；不要用同样被关闭的 /kits reload 恢复开关。

首次启动仅在 kits 目录尚不存在时复制 starter.yml：中文为新手礼包，英文为 Starter Kit，未自带对应语言示例时用英文。已有目录不覆盖；自带示例的 items 是空字符串，先用编辑器加入物品再领取。自定义语言从官方 lang/zh.json 复制为 lang/zh-myserver.json，按 kits.claim.success 等新 ASCII 键改写，并在框架 plugins/UltiTools/config.yml 选择 language: zh-myserver 后完整 /ul reload 或重启。官方语言文件启动时会恢复并保留备份，不要直接编辑；副本缺键回退前缀对应的官方语言，未自带该前缀语言的模块回退英文。

快速开始

安装完成后，按照以下步骤创建你的第一个礼包：

1. 准备物品 - 在你的物品栏里放入想要包含在礼包里的物品
2. 创建礼包 - 执行 /kits create welcome，插件会将你物品栏中的所有物品保存为一个名为 welcome 的礼包
3. 查看礼包 - 执行 /kits 打开 GUI 浏览器，你应该能看到刚创建的礼包
4. 领取礼包 - 在 GUI 中点击礼包图标，或执行 /kits claim welcome
5. 编辑礼包 - 执行 /kits edit welcome 打开可视化编辑器，可以直接拖放物品来修改礼包内容

插件首次启动时会自动生成一个名为 starter 的示例礼包配置文件，你可以参考它来手动编写更多礼包。

命令

命令	说明	执行者	示例
/kits	打开礼包浏览 GUI	仅玩家	/kits
/kits claim <名称>	领取指定礼包	仅玩家	/kits claim starter
/kits list	列出所有礼包	玩家/控制台	/kits list
/kits create <名称>	将当前物品栏保存为新礼包	仅玩家	/kits create vip
/kits edit <名称>	打开礼包内容编辑器	仅玩家	/kits edit starter
/kits delete <名称>	删除指定礼包	玩家/控制台	/kits delete oldkit
/kits reload	重新加载所有礼包配置	玩家/控制台	/kits reload

命令别名：/kit 和 /kits 均可使用。

权限

这些权限节点未声明默认授权，默认仅 OP 拥有；普通玩家需显式授权。要使用下表的基础功能，请按需授予 ultikits.kits.use。例如用 LuckPerms 给默认玩家组授权：

/lp group default permission set ultikits.kits.use true

权限节点	说明	默认
ultikits.kits.use	使用基础功能：浏览 GUI、领取礼包、查看列表	OP（需显式授权普通玩家）
ultikits.kits.admin	管理员功能：创建、编辑、删除、重载礼包	OP

此外，每个礼包可以配置独立的权限节点（见礼包配置中的 permission 字段）。

配置

主配置文件

文件路径：plugins/UltiTools/pluginConfig/UltiTools-Kits/config/config.yml

# 启用礼包系统
enabled: true

# GUI 点击防抖毫秒数（防止连续点击重复领取）
# 范围：50-5000
click_cooldown_ms: 200

# 浏览界面每页显示的礼包数量
# 范围：7-28
kits_per_page: 28

礼包配置文件

每个礼包对应一个独立的 YAML 文件，存放在 plugins/UltiTools/pluginConfig/UltiTools-Kits/kits/ 目录下。文件名即为礼包名（全小写）。

以下是自带的示例文件 kits/starter.yml 的完整内容：

# 礼包显示名称（支持颜色代码）
displayName: "&a新手礼包"

# 描述行（显示在 GUI 图标的 lore 中）
description:
  - "&7新手专属礼包"
  - "&7包含基础装备和工具"

# GUI 中显示的图标材质名（Bukkit Material 枚举名）
icon: GRASS_BLOCK

# 领取费用（0 = 免费，需要安装 Vault 经济插件）
price: 0

# 最低玩家等级要求（0 = 无要求）
levelRequired: 0

# 需要的权限节点（空字符串 = 无要求）
permission: ""

# 是否可重复领取（false = 一次性礼包）
reBuyable: false

# 重复领取的冷却时间（单位：秒，仅 reBuyable 为 true 时生效）
cooldown: 0

# 领取时以玩家身份执行的命令（支持 {player} 占位符）
playerCommands: []

# 领取时以控制台身份执行的命令（支持 {player} 占位符）
consoleCommands: []

# 物品数据（Base64 序列化，由 /kits create 或 /kits edit 自动生成，请勿手动修改）
items: ""

使用教程

创建一个付费 VIP 礼包

假设你想创建一个价格为 500 游戏币的 VIP 礼包，需要 VIP 权限才能领取：

1. 在物品栏里放入钻石剑、钻石甲等 VIP 专属物品
2. 执行 /kits create vip
3. 编辑配置文件 plugins/UltiTools/pluginConfig/UltiTools-Kits/kits/vip.yml：

displayName: "&b&lVIP 专属礼包"
description:
  - "&7VIP 玩家专属物品"
  - "&e包含全套钻石装备"
icon: DIAMOND_SWORD
price: 500
levelRequired: 0
permission: "ultikits.kit.vip"
reBuyable: false
cooldown: 0
playerCommands: []
consoleCommands:
  - "say {player} 领取了 VIP 礼包!"
items: "..."  # 由 /kits create 自动生成

4. 执行 /kits reload 使配置生效
5. 给 VIP 玩家添加权限 ultikits.kit.vip

创建一个每日礼包

每天可以免费领一次：

displayName: "&e&l每日签到礼包"
description:
  - "&7每天领取一次"
  - "&a免费"
icon: CAKE
price: 0
levelRequired: 0
permission: ""
reBuyable: true
cooldown: 86400  # 24小时 = 86400秒
playerCommands: []
consoleCommands: []
items: "..."

创建一个带命令奖励的礼包

领取后同时执行命令（比如给玩家经验）：

displayName: "&d&l奖励礼包"
description:
  - "&7领取后获得额外奖励"
icon: EXPERIENCE_BOTTLE
price: 100
levelRequired: 10
permission: ""
reBuyable: true
cooldown: 3600  # 1小时
playerCommands:
  - "me 领取了奖励礼包"
consoleCommands:
  - "xp give {player} 100"
  - "say {player} 领取了奖励礼包"
items: "..."

用 GUI 编辑器修改礼包内容

1. 执行 /kits edit starter，会打开一个 6 行的箱子界面
2. 前 5 行（45 个格子）是物品区，可移动和加入物品，不能在格子内丢弃或复制预填物品
3. 最后一行是控制栏：
   • 绿宝石 - 保存
   • 书本 - 显示礼包信息
   • 屏障 - 取消退出
4. 摆放好物品后点击绿宝石保存

主配置如何生效

配置项	类型	默认值	行为
enabled	布尔值	true	false 时命令、领取、保存和翻页拒绝；已有窗口不强制关闭
kits_per_page	整数	28	7-28，一页礼包数与页数指示器一致；下次打开使用新值
click_cooldown_ms	整数	200	50-5000 毫秒，过快的图标点击无提示地忽略

修改这三项后 /ul reload UltiTools-Kits；礼包 YAML 文件修改后 /kits reload（先保证 enabled 为 true）。已打开浏览页若因礼包减少或每页数量改变而超出范围，会退回最后一页并保留翻页按钮。price、cooldown、levelRequired 使用未加引号的非负数字；负数或非数字会警告并用 0 继续，不是拒绝整个礼包，因此可能让礼包变免费或取消要求，务必修正。缺少 displayName 时按语言显示 Kit / 礼包。

领取失败与奖励命令

领取按扣款 → 保存领取记录 → 发物品 → 安排奖励命令的顺序执行。付费但无经济提供者会明确提示缺少经济插件，不是余额不足；扣款被拒就不发物品、不写记录，日志每个礼包每会话警告一次，/kits reload 重置。记录写入失败会拒绝领取并退款，退款也失败会提示并记下玩家、礼包、金额供管理员退回。JSON 的异步落盘错误不能在领取时发现；不要据此承诺崩服后记录一定持久化。

背包空间按服务器实际堆叠行为检查，放不下在扣款前拒绝；发放时仍剩下的物品会掉在玩家脚下并提示，而不是销毁。玩家奖励命令在下一刻按列表顺序执行，然后执行控制台命令，可安全打开另一个界面；到那时玩家已离线则不执行玩家命令并逐条记录。失败的玩家命令会通知玩家，玩家或控制台命令失败均记录礼包、命令和玩家；领取仍有效、不退款、不自动重试，由管理员看日志补发。/kits list 和余额不足提示的价格使用经济系统的格式，不写死美元符号。

编辑、保存与文件冲突

成功保存会回复「已保存礼包: <礼包名>」，只改原文件的 items，其他设置、注释和未知键逐字节保留。加载后在磁盘改过文件会拒绝保存，先 /kits reload 再重新打开编辑器；非 UTF-8 或写 items 会连带改变其他内容（如 YAML 锚点）也拒绝，原因见日志。失败不改变已加载礼包；关闭后退还新增物品并收回预填物品，先收回再退还以腾出背包空间，Esc 关闭时光标物品也核对，取消不写文件。

格子内禁止 Q/Ctrl+Q 丢弃与创造模式中键复制。但先把预填物品移到自己的背包再丢弃/复制仍绕过该限制，这是现有限制：只给可信管理员编辑权限，不要在编辑过程中这样操作。背包外流的物品不能承诺找回。

手放文件名可以有大写，保存/删除使用实际加载文件。不要让 VIP.yml 与 vip.yml 定义同名礼包；一份仍可能加载供领取，但编辑、保存、新建、删除均拒绝并列出冲突，先备份并移走多余文件再 reload。新名字不能含 /、\ 或 ..，已有但未重载或无法解析的文件也不会被覆盖。删除失败会报告未删除、保持加载且记录路径；请排查权限后重试。编辑器保存原子替换，新建文件仍可能在崩服时残缺，保留备份。卸载 /upm uninstall UltiTools-Kits 后 /kits、/kit 会真正注销。

常见问题

安装后不生效怎么办？

确认以下几点：

• JAR 文件放在 plugins/UltiTools/plugins/ 目录下（不是 plugins/ 根目录）
• 服务器已完全重启（不是 /reload）
• 控制台没有报错信息
• UltiTools-API 版本 >= 6.3.0

改了配置文件没效果？

修改礼包 YAML 文件后，执行 /kits reload 重新加载。修改主配置 config.yml 后，需要执行 /ul reload 或重启服务器。

权限怎么设置？

1. 基础使用权限 ultikits.kits.use 默认仅 OP 拥有，普通玩家需显式授权
2. 管理权限 ultikits.kits.admin 默认只有 OP
3. 单个礼包的权限在礼包配置文件的 permission 字段设置，留空表示不额外检查礼包权限，仍需 ultikits.kits.use
4. 使用权限插件（如 LuckPerms）给玩家或权限组添加对应权限

经济系统不生效怎么办？

UltiKits 的价格功能需要安装 Vault 插件和一个经济插件（如 EssentialsX、CMI 等）。确保：

• 服务器安装了 Vault
• 安装了至少一个支持 Vault 的经济插件
• 礼包的 price 字段设置了大于 0 的值

物品栏为空怎么创建礼包？

/kits create 命令会自动读取你当前物品栏中的非空物品。如果你的物品栏完全为空，命令会提示"物品栏为空"。请先在物品栏里放入需要的物品后再执行命令。你也可以先创建一个礼包，然后用 /kits edit <名称> 打开编辑器，在编辑器中直接放入物品。

冷却时间怎么设置？

1. 首先将 reBuyable 设为 true（允许重复领取）
2. 然后设置 cooldown 为冷却秒数，例如：
   • cooldown: 3600 表示 1 小时
   • cooldown: 86400 表示 1 天
   • cooldown: 604800 表示 1 周
3. 如果 reBuyable 为 false，则礼包只能领取一次，冷却时间无效

更新日志

v2.0.0

变更

• 本版本需要 UltiTools 6.3.0 或更高版本，并在 plugin.yml 中声明 api-version: 630（上一个发布版本 1.0.0 声明的是 620）。UltiTools 6.2.0 至 6.2.5 会接受 1.0.0 的声明；现在它们会在加载时拒绝本模块，并给出 UltiTools 版本过旧的警告，以 plugin.yml 的 name: 即 UltiTools-Kits 指代本模块。6.2.0 之前的框架本来就拒绝 1.0.0 （UltiKits/UltiTools-Reborn#544）。

• plugin.yml 现在声明 identify-string: ultikits.kits，即本模块在 UltiCloud 模块目录中的条目键。框架的更新检查和 /upm update 会跳过未声明该键的模块，因此本模块现在会参与两者：带有同一键的更高发布版本会在启动时提示， 并可用 /upm update 安装（UltiKits/UltiTools-Reborn#474）。

• 首次启动时创建的示例礼包现在跟随服务器的 language：英文服务器得到英文说明的 Starter Kit，中文服务器得到 新手礼包，模块没有示例的语言使用英文版。此前唯一的示例在任何语言下都是中文。已有安装不受影响：只有礼包文件夹尚不 存在时才会复制示例（UltiKits/UltiKits#33）。

• 语言键已从中文句子改为 ASCII 键（例如 kits.claim.success）。本模块的官方语言文件 （plugins/UltiTools/pluginConfig/UltiTools-Kits/ 下的 lang/en.json 和 lang/zh.json）归 UltiTools 所有： 自 UltiTools-API 6.3.0 起，被修改过的官方文件会在每次启动时恢复为自带内容，修改过的副本作为备份保留并在服务器日志中注明， 因此在其中所做的修改不会保留。要自定义消息，请把官方文件复制为以语言代码加连字符开头、只含 ASCII 字母、数字、_ 和 - 的新名称 （zh.json → zh-myserver.json），按新键修改副本，然后在 plugins/UltiTools/config.yml 中设置 language: zh-myserver （框架和所有模块共用这一个设置）。副本中没有的消息取自名称开头对应的官方文件（此处为 zh），没有该名称文件的模块若自带该前缀对应的官方语言则使用它，否则使用其官方 en。从未改过语言文件的服务器无需任何操作。

移除

• 删除了「领取礼包时发生错误」消息及其背后的领取结果：没有任何领取会产生这个结果，因此该消息从来无法显示。每种领取结果 仍有各自的回复。翻译过 kits.claim.error 条目的运维可以删掉它（UltiKits/UltiKits#27）。

修复

• 礼包编辑器保存（/kits edit <礼包> 后点击保存）现在只把该礼包的 items 写入文件。此前它会按已加载的礼包重写整个文件： 所有注释和模块不认识的键被删除，加载时被替换的值被写回（无效的 icon 写成 CHEST，负数或非数字的 price、levelRequired、 cooldown 写成 0，拼错的 reBuyable 写成 false），加载后的手动修改被还原。现在其余每一行都逐字节保持不变。礼包文件在 加载后被修改过时不保存，编辑器会提示先执行 /kits reload；写入物品会改动文件中的其他内容（例如 YAML 锚点）或文件不是 UTF-8 文本时也不保存，编辑器提示未保存，原因见服务器日志。/kits create 仍然只会新建文件（UltiKits/UltiKits#43）。

• 礼包的玩家奖励命令（playerCommands）现在和控制台命令一样，在领取后的下一刻执行，而不是在领取过程中执行。从礼包界面点击领取时， 命令此前在背包点击事件内运行，会打开其他界面的奖励命令可能打不开，或在领取成功后被礼包界面自己的关闭立即关掉。命令仍按 列表顺序、先于控制台命令执行；未执行的命令仍会告知玩家并记录警告，只是晚一刻；届时已离线的玩家不会执行任何玩家奖励命令， 每条命令都会记录为未执行（UltiKits/UltiKits#41）。

• 礼包文件里负数或非数字的 price、cooldown、levelRequired 不再被无声地当作「没有」。此前 price: -5 会让礼包免费， levelRequired: -1 取消等级要求，负数 cooldown 取消冷却，带引号的 price: "250" 被当作 0，且都不记录日志。现在加载 礼包时会记录一条警告，点名礼包、键和原值，并改用该键的默认值（0）；0、正数和未填写的键不变（UltiKits/UltiKits#40）。

• 在 Paper 1.21.1 及更早版本上，放得下的超量物品堆不再被误判为「背包已满」而拒绝领取。这些版本向空格放入物品时按背包上限 （99）而不是物品上限（64）放置；模块现在会在启动时探测一次服务器的实际行为并据此计算空格。此前不会丢失物品：领取在扣款 前就被拒绝（UltiKits/UltiKits#38）。

• 礼包奖励命令未能执行时，现在会如实报告，而不是被忽略。以玩家身份执行的命令若不存在、被拒绝或出错，会告诉玩家是哪项 奖励没有执行；无论玩家命令还是控制台命令，失败都会记录一条写明礼包、命令和玩家的警告。领取仍然有效且不退款，运维可 手动补发。此前两类命令的结果都被丢弃，领取直接报告成功（UltiKits/UltiKits#25）。

• 现在控制台奖励命令的调度本身失败时（UltiTools 在查找之后、调度之前被禁用，或调度器出于其它原因拒绝该任务）， 会像既有的「无法调度」情形一样记录日志，且该礼包列表中排在它之后的控制台命令仍会继续尝试执行。此前该失败会在扣款、 记录和物品发放都已完成之后逃出领取流程，既不为该命令记录任何警告，也会静默跳过列表中排在它之后的所有控制台命令 （UltiKits/UltiKits#39 复查 #25）。

• /kits list 和「余额不足，需要 …」回复现在按服务器经济系统自己的格式显示礼包价格，与礼包浏览界面一致。此前它们写死 $ 并显示原始数字（($100.0)），货币不是美元的服务器上同一价格会有两种写法（UltiKits/UltiKits#34）。

• 在没有经济插件的服务器上领取付费礼包时，现在会如实提示（「此礼包需要付费，但服务器没有可用的经济插件」），礼包浏览界面 显示「服务器没有经济系统」。此前两处都显示「余额不足」，但任何余额都无法满足，也掩盖了经济系统缺失（UltiKits/UltiKits#32）。

• 礼包编辑界面（/kits edit）现在会保存移动和新增的物品：可以在格子内移动物品、从自己的背包放入物品，保存后写入礼包。 此前 GUI 库会取消格子内的每一次点击，保存时只是把打开时的物品原样再存一遍。底部按钮行保持固定。未成功保存就关闭 编辑界面时，玩家放入格子的物品会退还给玩家，而不是随界面一起丢弃（UltiKits/UltiKits#16）。

• 现在在编辑界面的格子中取出预填充的礼包物品后按取消（或以非成功保存的其它方式关闭窗口），不会再让玩家白得一份重复物品。 取消操作从不写入礼包文件，因此礼包仍持有该物品；关闭时格子里对不上打开时数量的部分，现在会像找回玩家新增的物品那样， 从它可能所在的任何位置收回：玩家自己的背包（常见情形），或者——如果是在拖动途中按 Esc 关闭窗口、物品尚未放置时—— 仍停留在光标上；这种情况下也会在物品被服务器交还给玩家之前收回。取消编辑现在在两个方向上都不产生任何得失 （UltiKits/UltiKits#38 复查 #39）。

• 现在在编辑界面的格子中对预填充物品按 Q（或 Ctrl+Q），或在创造模式下按住鼠标中键（复制），都不再产生任何效果。前者会把 物品扔进世界，是上面的找回机制既看不到也够不到的地方；后者会保留原物品不动、在光标上放一份免费副本，因此找回机制根本 不会发现有任何缺失需要收回。无论哪一种，此前取消编辑都会让礼包文件保持不变，同时多出一份该物品的重复品——落在地上， 或进了玩家的背包。两者都只在格子内被拒绝：本编辑界面所基于的 GUI 库只在格子内才会执行这类拒绝，对于完全发生在玩家 自己背包内的点击则不会——先把预填充物品移出格子（一次普通操作），再在背包内按 Q 丢弃或克隆，仍会在两步之内达到同样的 结果；这是已知的限制，已上报供决策，本次未修复（UltiKits/UltiKits#39 复查）。

• 现在在背包已满的情况下取消编辑，会先收回礼包自身的物品副本，再退还玩家新增的物品，使被退还的物品落入刚刚腾出的格位， 而不是因为没有空位被丢在玩家脚下。此前顺序相反：把个人物品与预填充物品互换进格子后，即使下一步就会腾出所需的那个格位， 该个人物品仍可能被丢在地上——面临消失或被他人拾取的风险（UltiKits/UltiKits#39 复查）。

• 修复：领取记录写入失败时拒绝领取并退款，一次性礼包不会因存储故障被重复领取。领取顺序改为先扣款、再写入记录、再发放； 记录无法写入时不发放任何物品、不执行奖励命令，并提示玩家重试。若退款也失败，会如实告知玩家，并在控制台记录包含玩家、礼包和金额的错误（UltiKits/UltiKits#26）。

• 修复：超出最大堆叠数的物品不再在领取时被销毁。领取前按背包实际的放置方式判断能否放下（先补满相同物品的未满堆，每个物品堆按自身的最大堆叠数拆分），放不下时先拒绝领取且不扣款； 仍放不下的部分会掉落在玩家脚下并提示（UltiKits/UltiKits#24）。

• 修复：礼包文件删除失败（或礼包文件夹无法读取）时，/kits delete 不再报告删除成功。礼包会保持加载，执行者会被告知未删除，控制台会记录该文件或文件夹的路径， 因此被告知已删除的礼包不会在下次 /kits reload 或重启后重新出现。删除和保存礼包现在使用礼包加载时的那个文件，因此文件名含大写字母的手放礼包文件（如 VIP.yml） 也能像其他礼包一样被删除，并能从编辑界面保存。编辑界面保存失败时不再改动已加载的礼包，领取时发放的仍是文件中的物品。当多个文件定义同一礼包时（在区分大小写的文件系统上同时存在 VIP.yml 和 vip.yml），/kits edit、编辑界面的保存按钮、/kits create 和 /kits delete 不做任何修改并列出这些文件；其中一个仍会被加载，礼包照常可以领取，/kits reload 也会在控制台列出这些文件（UltiKits/UltiKits#23）。/kits create 现在会拒绝含 /、\ 或 .. 的礼包名（以前会把礼包文件写到 kits 文件夹之外），也会拒绝礼包文件夹中已有文件（手工放入但未 reload 的，或无法解析的）加载为该名字的礼包名，并列出该文件而不是覆盖它（UltiKits/UltiKits#37）。新礼包的文件（/kits create）仍按以前版本的方式写入，创建过程中崩服可能留下残缺文件；模块的崩溃安全写入在 UltiKits/UltiTools-Reborn#545 中跟踪。自 UltiKits/UltiKits#43 起，编辑界面的保存以原子方式替换文件。

• language: zh 现在对原先写死为英文的文本生效：礼包编辑器保存按钮的说明（Click to save kit contents）、 /kits help 中 edit、create、delete、reload 四行，以及八条控制台日志（礼包扣款被拒、礼包文件加载失败或图标无效、 保存礼包文件、复制示例礼包、序列化或反序列化礼包物品、更新领取记录失败）。没有 displayName 的礼包文件的后备显示名 现在按语言为 Kit / 礼包，不再总是 Kit。/kits 命令描述此前在两份语言文件中都缺失、在任何语言下都显示中文句子， 现在 language: en 下为 Kit management command。英文措辞不变，错误之处除外：/kits help 中 claim 一行原为 Available （界面状态标签），现为 Claim a kit；/kits create 失败和礼包编辑器保存失败原先都显示 Error claiming kit，现分别为 Error creating kit 和 Error saving kit（UltiKits/UltiKits#31）。

• 礼包系统关闭期间，礼包编辑界面的保存操作现在会被拒绝。此前管理员若在运维把 enabled 改为 false 之前就打开了 /kits edit，仍可点击保存并修改礼包内容；现在保存按钮会回复“礼包系统当前已关闭”， 且不写入任何内容（UltiKits/UltiKits#13）。

• 礼包浏览界面不会再出现「页码超出总页数的空白页面」。当界面打开期间礼包列表变短时——/kits reload 删除了礼包，或 kits_per_page 被调大导致总页数减少——原先所在的页可能已不存在；现在会改为显示最后 一个真实存在的页面，翻页按钮同样正常（UltiKits/UltiKits#13）。

• config/config.yml: kits_per_page 现在真正决定礼包浏览界面一页显示多少个礼包。此前无论该键写什么， 界面都按硬编码的 28 分页；现在按 kits_per_page 取值，其默认值仍为 28，因此从未修改过该键的服务器 行为不变。界面 Page x/y 指示器的总页数同样依据该值（UltiKits/UltiKits#13）。

• config/config.yml: click_cooldown_ms 现在真正决定礼包浏览界面的点击防抖窗口。此前无论该键写什么， 界面都使用硬编码的 200 毫秒；现在按 click_cooldown_ms 取值，其默认值仍为 200，因此从未修改过该键的 服务器行为不变（UltiKits/UltiKits#13）。

• config/config.yml: enabled 现在真正可以关闭礼包系统。此前没有任何代码读取它，无论其取值如何礼包系统 都处于启用状态。设为 false 后，/kits（/kit）的每一条子命令——包括不带参数的浏览界面、claim、 list、edit、create、delete 与 reload——都会回复“礼包系统当前已关闭”并不再执行任何操作。默认值 仍为 true，因此从未修改过该键的服务器行为不变。该开关在命令执行时读取，而非模块加载时读取，因此 /ul reload UltiTools-Kits 即可生效，无需重启服务器。/kits help 以及任何无法识别的 /kits 参数同样会被 拒绝，而不是列出一串全部会被拒绝的子命令。开关切换时玩家已经打开的浏览界面不会被强制关闭，但在其中点击礼包 会收到同样的拒绝提示而不是领取成功，翻页按钮也会拒绝打开新页面，因此开关关闭期间既领取不到礼包，也看不到 新的礼包列表页。领取的拦截放在礼包服务内部而非各个命令中，因此将来新增的领取入口同样受该开关约束 （UltiKits/UltiKits#13）。

• 付费礼包若扣款未真正成功，现在不再发放。此前只要余额检查通过而扣款本身失败——余额在两次调用之间被 花掉，或经济插件拒绝了该笔交易——/kits claim <名称> 与礼包浏览界面仍会把物品发给玩家、执行礼包 配置的玩家命令与控制台命令、把一次性礼包记为已领取，浏览界面还会提示价格“已扣除”。现在两条路径都会 回复“扣款失败，礼包未领取”，既不发放也不记录，服务器控制台还会输出一条包含礼包名、玩家名与金额的 WARNING——每个礼包每个会话只输出一次，避免经济系统故障时刷屏；/kits reload 可重置 （UltiKits/UltiKits#20）。

• 领取成功时，领取记录现在先于礼包配置的玩家命令与控制台命令写入，而非之后。此前奖励命令若执行 失败，会出现玩家已被扣款、已拿到物品、却没有领取记录的状态，使一次性礼包被悄悄重新变为可领取 （UltiKits/UltiKits#20）。

• 执行 /upm uninstall UltiTools-Kits 后，本模块的 /kits（/kit）命令现在会被真正移除。此前该命令会一直 保留到服务器重启，因为本模块用一个空方法替换了框架的卸载方法（UltiKits/UltiKits#18）。

v1.0.0 (2026-02-13)

新增：礼包系统核心功能

• 新增：分页 GUI 浏览器，支持翻页显示所有可用礼包
• 新增：GUI 编辑器，管理员可拖放物品编辑礼包内容
• 新增：/kits create 命令从当前物品栏快速创建礼包
• 新增：/kits claim 命令和 GUI 点击领取礼包
• 新增：/kits list 命令列出所有礼包
• 新增：/kits edit 命令打开可视化编辑器
• 新增：/kits delete 命令删除礼包
• 新增：/kits reload 命令重新加载配置
• 新增：Vault 经济系统集成（礼包定价）
• 新增：每礼包独立冷却时间
• 新增：一次性礼包（不可重复领取）
• 新增：等级要求限制
• 新增：每礼包独立权限节点
• 新增：领取时执行玩家命令和控制台命令（支持 {player} 占位符）
• 新增：YAML 配置，每礼包一个文件
• 新增：Base64 物品序列化存储
• 新增：中英文双语支持

贡献者

Ling Bao

页面历史

最后编辑于 4 分钟前

查看完整历史

d914a72-Merge pull request #11 from UltiKits/fix/sweep-g-userdoc