HN 系列 Wiki

主题

HNCore v3.0.0 ​

  • 发布日期：2026-04-20
  • 发布提交：d9cd572
  • 版本定位：移除过时 API，修复 Groovy 脚本系统，提升代码质量

版本定位 ​

v3.0.0 是一个 破坏性更新版本，主要目标是：

  1. 清理技术债务 - 移除长期标记为 @Deprecated 的过时 API
  2. 统一 API 版本 - 仅支持 Minecraft 1.20.1+，移除旧版本兼容代码
  3. 修复核心问题 - 解决 Groovy 脚本监听器注册失败的根本原因
  4. 改进开发体验 - 修复 Windows 环境下的路径问题，优化构建流程

破坏性变更 ​

1. 移除过时 API ​

来源提交：d26a939（2026-04-20，[重构] 移除过时 API 和兼容代码）

移除的类和方法：

  • TaskUtil 工具类 - 已删除

    • 替代方案：使用 HNCoreAPI.getScheduler()

  • MessageManager 实现类 - 已删除

    • 替代方案：使用 MessageFacade
    • 临时兼容：提供了 MessageServiceAdapter 适配器

  • MessageService 接口 - 标记为 @Deprecated(forRemoval = true)

    • 替代方案：使用 MessageFacade

  • StorageMysqlService.inTransaction() 方法 - 已删除

    • 原因：DatabaseService.TransactionCallback 已被移除

迁移示例：

java
// 旧代码（已失效）
TaskUtil.runTask(plugin, () -> {
    // 任务逻辑
});

// 新代码
HNCoreAPI.getScheduler().runTask(() -> {
    // 任务逻辑
});

2. ItemMeta API 变更 ​

来源提交：d26a939

变更内容：

  • 移除 ItemMeta.getDisplayName() 和 getLore() 的兜底调用
  • 仅使用 1.20.1+ 的 Component API（displayName() 和 lore()）

影响：

  • 不再支持 Minecraft 1.20.1 以下版本
  • 服务器必须运行在 Paper 1.20.1 或更高版本

3. 最低版本要求 ​

新的最低要求：

  • Minecraft 版本：1.20.1+
  • 服务端类型：Paper 或兼容服务端
  • Java 版本：17+

重要修复 ​

1. Groovy 脚本监听器注册失败 ​

来源提交：c3d9f69 + 27c6fc6（2026-04-20）

问题描述： 所有 Groovy 脚本加载后显示"已启用"，但实际上监听器没有注册，脚本功能完全不生效。

根本原因： HNCoreBootstrap.initScripts() 中，featureScriptManager.reload() 在 HNCoreServices.register() 之前执行。当脚本的 onGroovyRegister() 通过 HNCoreAPI.registerGroovyListener() 获取管理器时，它还没被注册到服务容器，导致返回 null，监听器被静默丢弃。

修复方案： 将 HNCoreServices.register(FeatureScriptManager.class, featureScriptManager) 移到 reload() 之前，确保脚本执行时能找到管理器实例。

影响的脚本：

  • AutoRespawn
  • KeepInventory
  • DurabilityProtect
  • HealthScale
  • 以及所有其他使用 HNCoreAPI.registerGroovyListener() 的脚本

2. HNCoreAPI.getPlugin() 返回 null ​

来源提交：27c6fc6

问题描述： HNCoreAPI.getPlugin() 始终返回 null，导致所有依赖插件实例的脚本（如 AutoRespawn、ClearDroppedItems）无法正常工作。

根本原因： HNCorePlatformImpl 不是 JavaPlugin 的子类，而 getPlugin() 方法检查 platform instanceof JavaPlugin，导致返回 null。

修复方案： 在 HNCorePlatform 接口新增 getJavaPlugin() 方法，由 HNCorePlatformImpl 返回内部持有的 HNCore 插件实例。

3. Windows 环境下 JAR 资源释放失败 ​

来源提交：79a0dc4 + efc25e7（2026-04-20）

问题 1：路径解析错误

  • Windows 上 file: URL 格式为 file:/D:/path
  • 简单移除 file: 前缀后变成 /D:/path，在 Windows 上无效
  • 修复：添加 Windows 路径修正逻辑，移除前导斜杠

问题 2：文件名中的空格

  • 开发版本号格式 版本-SNAPSHOT+hash 中的 + 号在文件名中被转换为空格
  • 导致 JAR 路径解析失败
  • 修复：将格式改为 版本-SNAPSHOT-hash

脚本优化 ​

1. AutoRespawn 脚本 ​

来源提交：27c6fc6

优化内容：

  • 改用 runTaskLater 延迟 1 tick 执行复活
  • 确保死亡事件处理完毕后再执行复活逻辑
  • 避免与其他插件的死亡事件处理冲突

2. HealthScale 脚本 ​

来源提交：27c6fc6

优化内容：

  • 将配置读取移到 runTask 闭包内部
  • 避免捕获过期配置引用
  • 确保每次应用时使用最新配置

3. DurabilityProtect 脚本 ​

来源提交：27c6fc6 + f25cd57

新增功能：

  • 新增 permission-mode 配置项，支持两种权限模式：
    • bypass（默认）：有权限的人不享受无限耐久（用于让管理员绕过保护）
    • require：只有有权限的人才能享受无限耐久（用于限制特权）

配置示例：

yaml
# 权限节点
permission: hncore.scripts.durabilityprotect.bypass

# 权限模式
# - "bypass"：拥有该权限的玩家不享受无限耐久（用于让管理员绕过保护）
# - "require"：只有拥有该权限的玩家才能享受无限耐久（用于限制特权）
permission-mode: bypass

其他改进 ​

1. 组织级版本号管理 ​

来源提交：2f60190 + 48de14f + 63251a6（2026-04-19）

新增功能：

  • Git Hook 自动版本号同步机制
  • 三大版本号管理方案（自动递增、手动控制、混合模式）
  • 统一的版本号管理模板

2. ProGuard 混淆优化 ​

来源提交：38ee4af + 2c9ccc1 + 08dc536 + 217a9ea（2026-04-19）

优化内容：

  • 增强混淆效果，使用易混淆字符字典
  • 新增多种混淆配置方案
  • 完整的 ProGuard 优化指南
  • 便捷构建脚本

3. 日志系统优化 ​

来源提交：a07e6b7

优化内容：

  • 调整 Logger 颜色，提升可读性

迁移指南 ​

从 2.x 迁移到 3.0.0 ​

1. 检查最低版本要求 ​

确保你的服务器满足以下要求：

  • Minecraft 版本：1.20.1+
  • 服务端类型：Paper 或兼容服务端
  • Java 版本：17+

2. 替换过时 API ​

TaskUtil → HNCoreAPI.getScheduler()

java
// 旧代码
TaskUtil.runTask(plugin, () -> {
    // 任务逻辑
});

TaskUtil.runTaskLater(plugin, () -> {
    // 延迟任务
}, 20L);

// 新代码
HNCoreAPI.getScheduler().runTask(() -> {
    // 任务逻辑
});

HNCoreAPI.getScheduler().runTaskLater(() -> {
    // 延迟任务
}, 20L);

MessageManager → MessageFacade

java
// 旧代码
MessageService messageService = HNCoreAPI.getMessageService(plugin);
String message = messageService.getMessage("path.to.message");

// 新代码
MessageFacade messageFacade = HNCoreAPI.getMessageFacade();
String message = messageFacade.render("path.to.message", PlaceholderContext.create());

3. 更新 ItemMeta 使用 ​

如果你的代码直接使用了 ItemMeta.getDisplayName() 或 getLore()，需要改用 Component API：

java
// 旧代码（不再支持）
String displayName = meta.getDisplayName();
List<String> lore = meta.getLore();

// 新代码
Component displayName = meta.displayName();
List<Component> lore = meta.lore();

// 如果需要转换为字符串
String displayNameStr = LegacyComponentSerializer.legacySection().serialize(displayName);

4. 检查 Groovy 脚本配置 ​

确保所有需要启用的 Groovy 脚本在配置文件中设置了 enabled: true：

yaml
# GroovyConfig/KeepInventory.yml
enabled: true
# ... 其他配置

性能影响 ​

  • ✅ 无性能损失
  • ✅ 移除过时代码，减少维护负担
  • ✅ 修复脚本系统后，所有脚本正常工作
  • ✅ Windows 环境下资源释放正常

已知问题 ​

  • 无

相关文档 ​

完整文档 ​

示例代码 ​

  • 调度器使用: HNCoreAPI.getScheduler()
  • 消息系统: MessageFacade

总结 ​

v3.0.0 是一个重要的里程碑版本，通过移除过时 API 和修复核心问题，为 HNCore 的长期发展奠定了坚实基础。

主要收益：

  1. 代码质量提升 - 移除技术债务，代码更清晰
  2. 脚本系统修复 - 所有 Groovy 脚本现在可以正常工作
  3. 跨平台支持 - 修复 Windows 环境下的路径问题
  4. API 统一 - 仅支持 1.20.1+，简化维护

升级建议：

  • 如果你使用了 TaskUtil 或 MessageManager，请按照迁移指南更新代码
  • 如果你的服务器版本低于 1.20.1，请先升级服务器
  • 如果你使用了 Groovy 脚本，升级后脚本将正常工作

下一步计划：

  • 继续完善 Groovy 脚本生态
  • 优化性能和内存使用
  • 新增更多实用功能

HN 系列插件文档

Copyright © 2024