HN 系列 Wiki

主题

如果你第一次接触 HNCore，又想快速理解“这个插件到底能做什么、哪些能力适合服主直接用、哪些能力适合下游模块复用”，这篇文档可以作为总入口来看。

一句话理解 HNCore ​

HNCore 不是单一功能插件，而是一套 公共能力底座。

你可以把它理解成三层：

  • 服主可直接使用的能力：GroovyScripts、工具箱、重载与状态命令
  • 多服/共享层能力：共享数据库、共享存储、共享键值、Redis Pub/Sub
  • 给其他插件复用的能力：物品库统一解析、统一授权接入、GUI Kit、公式引擎、消息工具、Java API

也就是说，HNCore 一方面能直接给服主提供功能，另一方面也能给像 HNMail 这样的业务模块做基础设施。

最值得先知道的 5 项能力 ​

1. GroovyScripts 脚本系统 ​

这是目前最适合服主直接上手的一层。

HNCore 当前内置的默认示例脚本包括：

  • KeepInventory
  • WorldProtect
  • ExplosionProtect
  • AutoRespawn
  • EndermanProtect
  • NoHunger
  • DurabilityProtect
  • VoidProtect
  • PvpControl
  • MobSpawnControl
  • NoDrop
  • NoFireSpread
  • NoRain
  • NoFallDamage
  • FixedTime
  • ClearDroppedItems
  • NoDamageIndicator

它适合做什么 ​

  • 不想自己写插件，但想快速开关一组常见服务器功能
  • 想按世界控制 PvP、方块交互、爆炸、天气、掉落、虚空保护
  • 想把大厅/主城/展示世界整理成较稳定的运行环境

怎么启用 ​

  1. 首次启动后确认以下目录已生成：
text
plugins/HNCore/GroovyScripts/
plugins/HNCore/GroovyConfig/
  1. 打开对应脚本配置，把：
yml
enabled: true
  1. 执行：
text
/hncore reload scripts
/hncore scripts enabled

怎么理解“脚本” ​

这里的脚本不是一次性命令片段，而是可以被注册、注销、重载的功能模块。

也就是说：

  • 它可以监听事件
  • 它可以持有运行时逻辑
  • /hncore reload scripts 会按生命周期重新装载

如果你是服主，可以把它简单理解成：

一组可以按需启用、按需组合、按需重载的小功能模块。

2. 共享物品库解析 ​

这是 HNCore 目前最实用的“给业务模块复用”的能力之一。

HNCore 现在会统一兼容以下外部物品库：

  • mythic，别名：mm
  • neige，别名：ni
  • baikiruto，别名：bi

这层能力解决什么问题 ​

以前业务模块如果要支持多个物品库，通常要自己分别接：

  • MythicMobs API
  • NeigeItems API
  • Baikiruto API

现在可以统一改成：

java
HNCoreAPI.resolveLibraryItem(source, itemId, amount)

这样像 HNMail、商店、礼包、任务奖励之类的模块就不需要自己再对接每个物品库插件。

支持的写法 ​

完整来源名：

  • mythic:<itemId>
  • neige:<itemId>
  • baikiruto:<itemId>

短别名写法：

  • mm:<itemId>
  • ni:<itemId>
  • bi:<itemId>

在代码里怎么用 ​

java
var result = HNCoreAPI.resolveLibraryItem("bi", "example_item", 1);
if (result.isSuccess()) {
    ItemStack item = result.itemStack();
} else {
    logger.warn("解析失败: " + result.errorCode());
}

在邮箱 HNMail 里怎么用 ​

邮箱模板里可以直接写附件来源：

yml
attachments:
  - type: item
    source: bi
    item: example_item
    amount: 1

也可以写完整名：

yml
source: baikiruto

怎么确认当前来源可用 ​

先执行：

text
/hncore status

你会看到类似：

  • 来源 mythic
  • 来源 neige
  • 来源 baikiruto
  • 以及对应别名和当前可用/不可用状态

如果来源不可用，通常说明：

  • 对应插件没安装
  • 插件未启用
  • API 尚未就绪

3. 共享存储与消息总线 ​

如果你只做单服，可能暂时用不到这层；但如果你有多服、代理服、跨服同步需求，这层就非常重要。

HNCore 当前统一提供：

  • 共享数据库
  • 共享存储 MySQL
  • 共享存储 Redis
  • 共享键值存储
  • 共享消息总线（Redis Pub/Sub）

适合什么场景 ​

  • 多服间同步某些业务状态
  • 下游模块共享 Redis / MySQL 能力
  • 让业务模块不再自己维护连接池与订阅线程

最重要的原则 ​

  • 连接池由 HNCore 统一维护
  • Redis 连接由 HNCore 统一维护
  • Pub/Sub 线程由 HNCore 统一维护
  • 下游模块只通过 HNCoreAPI 取服务

最常用命令 ​

text
/hncore status
/hncore reload

如果你后面要排查 Redis、MySQL、跨服同步，先学会看这两个命令的输出，比直接进业务模块找配置更有效。

4. GUI Kit ​

HNCore 现在还提供了一套可复用 GUI 基础设施。

它的目标不是把所有业务逻辑塞进配置，而是把这些重复劳动抽出来：

  • 标题
  • 布局
  • 背景板
  • 分页槽位
  • 导航按钮
  • 占位符渲染
  • 分页列表骨架

主要组成 ​

  • GuiTemplate
  • GuiTemplateLoader
  • GuiTemplateRenderer
  • GuiContext
  • AbstractPagedGui<T>
  • GuiNavItems

适合什么界面 ​

  • 邮箱列表
  • 黑名单列表
  • 商店页
  • 奖励页
  • 设置页
  • 详情页

当前原则 ​

  • 模板负责外观和布局
  • Java 代码负责点击逻辑和数据来源

所以它更像“轻量 GUI 基础设施”，而不是重型配置驱动框架。

5. Java API ​

如果你自己也在开发业务插件，那 HNCoreAPI 就是最重要的入口。

它当前可提供的能力包括：

  • 日志
  • 配置管理
  • 统一调度器与玩家查找
  • 共享数据库
  • 共享存储 / PubSub
  • 公式引擎
  • 消息工具
  • GUI Kit
  • 共享物品库门面与 ItemFacade
  • 统一授权接入
  • GroovyScripts 集成接口

一个典型的思路是：

  • 要日志：getLogger(...)
  • 要配置：createConfigManager(...)
  • 要统一调度：getScheduler()
  • 要玩家查找：getPlayerLookupService()
  • 要共享存储 / PubSub：看共享数据库状态、getSharedPubSubService() 与 ClusterBus 这一组
  • 要物品库解析：getItemLibraryGateway()，需要更高层物品能力时看 getItemFacade()
  • 要统一授权：registerLicensedPlugin(...)
  • 要 GUI：createGuiTemplateLoader(...) / createGuiTemplateRenderer() / createGuiNavigator(...)

服主最常用的命令应该先记住哪些 ​

建议优先记住这几组：

脚本相关 ​

text
/hncore reload scripts
/hncore scripts list
/hncore scripts enabled

核心状态 / 重载 ​

text
/hncore status
/hncore reload

工具箱 ​

text
/hncore tools

一条推荐上手路径 ​

如果你想最快理解 HNCore，建议按这个顺序：

第一步：确认插件生成了哪些目录 ​

先看：

  • plugins/HNCore/config.yml
  • plugins/HNCore/storage.yml
  • plugins/HNCore/GroovyScripts/
  • plugins/HNCore/GroovyConfig/

第二步：先启用 1~2 个脚本试试 ​

例如：

  • NoRain
  • NoDrop
  • KeepInventory

然后执行：

text
/hncore reload scripts

第三步：学会看状态 ​

执行：

text
/hncore status

重点看：

  • 共享数据库
  • Redis / MySQL
  • Pub/Sub
  • 共享物品库来源状态

第四步：如果你有下游插件，再看 API ​

例如你在用 HNMail：

  • 模板邮件里可以直接写物品库来源
  • HNMail 会通过 HNCore 统一解析物品附件

第五步：如果你自己开发，再进入 GUI Kit / Java API ​

这时再看：

HNCore 更适合哪些人 ​

如果你是服主 ​

你最应该关心：

  • GroovyScripts 怎么开
  • /hncore status 怎么看
  • storage.yml 怎么配置
  • 外部物品库来源现在支持哪些

如果你是业务插件开发者 ​

你最应该关心：

  • HNCoreAPI 能拿到哪些共享服务
  • 共享物品库怎么统一解析
  • GUI Kit 怎么接
  • 共享存储 / PubSub / ClusterBus 怎么复用

如果你是纯二开作者，建议下一篇直接读：

当前一个非常实用的组合思路 ​

如果你已经在用 HNMail，那么可以把 HNCore 理解成这样：

  • HNCore 负责兼容 mythic / neige / baikiruto
  • HNMail 负责把解析出来的 ItemStack 变成邮件附件
  • 服主只需要在模板中写 source + item + amount

这就是公共能力下沉后的典型效果：

  • HNCore 统一解决“怎么取物品”
  • HNMail 只解决“怎么发邮件”

建议继续阅读 ​

HN 系列插件文档

Copyright © 2024