玩家套装

Hytale 的 PlayerKitsPlugin

为 Hytale 服务器提供的一个强大、功能丰富的套装管理插件，允许管理员创建、管理和分发预定义的物品集给玩家，并具有丰富的自定义选项。

功能

核心功能

• 创建套装：使用一条命令将玩家物品栏保存为可重复使用的套装
• 多物品栏支持：套装包含存储栏、盔甲栏、快捷栏、工具槽和背包物品
• 基于权限的访问：为每个套装分配特定权限
• 冷却系统：为每个套装配自定义冷却时间（从秒到小时）
• 轻松分发：通过直观的命令将套装给予自己或其他玩家

管理工具

• 批量操作：一次性保存、重载或删除多个套装
• 冷却管理：通过命令查看和重置玩家冷却时间
• 套装信息：详细查看套装内容和元数据
• 基于文件的存储：每个套装保存为独立的 JSON 文件，便于备份

玩家体验

• 套装浏览器：列出所有可用套装，支持分页
• 冷却显示：实时冷却追踪，显示格式化剩余时间
• 权限反馈：当玩家缺乏所需权限时显示清晰消息
• 物品栏安全：非破坏性的套装应用，尊重现有物品

命令

玩家命令

命令	权限	描述
/kit list <page>	razorplay.playerkitsplugin.command.kit.list	列出所有可用套装（分页）
/kit get <kitId>	razorplay.playerkitsplugin.command.kit.get	领取你拥有权限的套装

管理员命令

命令	权限	描述
/kit create <kitId> <displayName> [description]	razorplay.playerkitsplugin.command.kit.create	从当前物品栏创建套装
/kit delete <kitId> --confirm	razorplay.playerkitsplugin.command.kit.delete	永久删除一个套装
/kit give <player> <kitId>	razorplay.playerkitsplugin.command.kit.give	给予其他玩家一个套装
/kit reload	razorplay.playerkitsplugin.command.kit.reload	从磁盘重载所有套装

冷却管理

命令	权限	描述
/kit cooldown clear	razorplay.playerkitsplugin.command.kit.cooldown.clear	清除所有玩家的所有冷却
/kit cooldown check <player> <kitId>	razorplay.playerkitsplugin.command.kit.cooldown.check	检查玩家对某个套装的冷却
/kit cooldown reset <player>	razorplay.playerkitsplugin.command.kit.cooldown.reset	重置指定玩家的所有冷却

🔧 配置

文件结构

mods/RazorPlay_PlayerKitsPlugin/
├── kits/                 # 独立的套装 JSON 文件
│   ├── starter.json
│   ├── warrior.json
│   └── ...
├── cooldowns.json        # 玩家冷却数据

套装属性

每个套装可以配置以下内容：

• ID：唯一标识符（不能包含空格或斜杠）
• 名称：向玩家显示的显示名称
• 描述：可选的描述
• 权限：所需的权限节点（留空表示公开）
• 冷却时间：使用间隔时间（秒），设置为 0 表示无冷却
• 物品：包含盔甲和背包在内的完整物品栏

权限节点

razorplay.playerkitsplugin.command.kit.*          # 所有套装命令
razorplay.playerkitsplugin.command.kit.create     # 创建套装
razorplay.playerkitsplugin.command.kit.delete     # 删除套装
razorplay.playerkitsplugin.command.kit.give       # 给予他人套装
razorplay.playerkitsplugin.command.kit.reload     # 重载套装
razorplay.playerkitsplugin.command.kit.cooldown.* # 所有冷却命令

自定义套装权限

为特定套创建自定义权限： kit.mykit.use # 示例：针对 "mykit" 的自定义权限

🔌 API 集成

PlayerKitsPlugin 为开发者提供全面的 API

// 获取 KitAPI 实例
KitAPI kitAPI = PlayerKitsPlugin.getKitAPI();

// 通过编程方式创建套装
Kit kit = kitAPI.createKit("id", "name", player, "description");

// 给予玩家套装
boolean success = kitAPI.giveKit(player, playerRef, "kitId");

// 用于自定义行为的事件系统
kitAPI.registerListener(new KitEventListener() {
    @Override
    public void onKitClaimed(KitClaimEvent event) {
        // 套装被领取时的自定义逻辑
    }
});

// 异步权限检查
CompletableFuture<List<Kit>> availableKits = kitAPI.getAvailableKitsAsync(
    playerId, 
    (uuid, permission) -> checkPermissionAsync(uuid, permission)
);

🎮 使用示例

1. 创建新手套装

/kit create starter Starter "Basic tools and armor for new players"

2. 设置每日奖励

1. 创建冷却时间为 24 小时的套装：/kit create daily Daily
2. 编辑 JSON 文件，设置 "Cooldown": 86400（24 小时，以秒为单位）
3. 设置权限："Permission": "kit.daily.use"

3. 导入社区套装

/kit import /path/to/community_kit.json

📋 安装

1. 下载最新版本的 PlayerKitsPlugin.jar
2. 将其放入 Hytale 服务器的 mods/ 目录
3. 启动或重载你的服务器
4. 插件会自动创建必要的目录和文件

🔍 技术细节

存储系统

• 套装：独立的 JSON 文件，位于 mods/PlayerKitsPlugin/kits/
• 冷却时间：集中式 JSON 文件，基于玩家追踪
• 序列化：使用 Hytale 的 Codec 系统实现可靠的物品序列化

性能特性

• 缓存：针对玩家的套装可用性缓存（30 秒 TTL）
• 异步操作：非阻塞的文件 I/O 和权限检查
• 高效加载：按需懒加载套装文件

安全特性

• 输入验证：对套装 ID 进行清理，防止文件系统问题
• 错误处理：全面的异常处理，附带详细日志
• 数据完整性：通过独立的套装文件自动备份

🐛 故障排除

常见问题

1. “找不到套装”：确保套装 ID 正确且区分大小写
2. 权限被拒绝：检查权限节点和 LuckPerms/群组设置
3. 物品栏未保存：创建套装时确认玩家物品栏中有物品
4. 文件错误：检查 mods/RazorPlay_PlayerKitsPlugin/ 目录的文件权限

日志

查看服务器日志以获取详细的错误信息：

• 带有 [PlayerKitsPlugin] 前缀的消息显示插件活动
• 警告表示非关键问题
• 错误需要立即处理

🤝 贡献

发现 Bug 或有功能请求？请在 GitHub 仓库中提交 Issue！

📄 许可

本插件基于 MIT 许可提供。详情请见 LICENSE 文件。

---

🙏 鸣谢

开发者：Razorplay 测试：欢迎你的贡献！