HNCore v1.5.0

• 发布日期：2026-04-19
• 发布提交：ac253a2
• 版本定位：新增统一奖励系统、成本扣除系统、经济桥接，为下游插件提供公共业务轮子

版本定位

v1.5.0 这一轮的核心目标是 消除下游插件的重复代码。

在 HNSignIn、HNMail、HNWarehouse 等下游插件中，发现大量重复的业务模式：

• 奖励发放（命令、物品、经济、权重随机）
• 成本扣除（经济、物品、权限检查）
• HNEconomy 反射桥接

这些重复代码每个插件约 400-1500 行，维护成本高且容易出现不一致。

这一轮通过将这些公共业务模式沉淀到 HNCore，让下游插件可以直接调用统一 API，大幅减少重复代码。

本次重点新增

1. 统一奖励系统（reward 包）

来源提交：ac253a2（2026-04-19，[新增] 统一奖励系统、成本扣除系统、经济桥接、配置解析工具）

核心能力：

• 支持 5 种奖励类型：COMMAND / MESSAGE / ITEM_SPEC / LIBRARY_ITEM / MONEY
• 支持权重随机池（复用 WeightedPool）
• 统一配置格式，兼容现有下游插件
• 自动占位符替换、物品发放策略

API 入口：

RewardService rewardService = HNCoreAPI.getRewardService();
RewardDefinition reward = rewardService.parse(config);
RewardGrantResult result = rewardService.grant(player, reward);

预计收益：

• HNSignIn 可减少 ~800 行奖励发放代码
• HNMail 可减少 ~250 行邮件附件代码

2. 成本扣除系统（cost 包）

来源提交：ac253a2

核心能力：

• 支持 6 种成本类型：MONEY / ITEM / PERMISSION / EXPERIENCE / PLACEHOLDER / COMMAND
• 批量扣除 + 失败自动回滚
• 策略模式设计，支持自定义 evaluator
• 统一配置格式

API 入口：

CostService costService = HNCoreAPI.getCostService();
List<CostEntry> costs = costService.parse(config);
CostConsumeResult result = costService.checkAndConsume(player, costs);

预计收益：

• HNSignIn 可减少 ~500 行补签成本代码
• HNWarehouse 可减少 ~400 行需求检查代码

3. HNEconomy 统一桥接（economy 包）

来源提交：ac253a2 + 8a4e6ee（2026-04-19，[更新] 增强 EconomyBridge API，支持货币元数据和金额格式化）

核心能力：

• 统一反射桥接 HNEconomy API
• 支持余额查询、扣除、存入
• 支持货币元数据查询（scale、symbol、maxBalance）
• 支持金额格式化和解析（支持小数）
• 优雅降级（HNEconomy 不可用时返回失败结果）

API 入口：

EconomyBridge economy = HNCoreAPI.getEconomyBridge();
if (economy.isAvailable()) {
    EconomyTransactionResult result = economy.withdraw(playerId, "gold", 100, "购买物品");
    String formatted = economy.formatAmount("gold", 1050); // "10.50"
}

预计收益：

• HNSignIn 可减少 ~432 行反射代码
• HNMail 可减少 ~237 行反射代码
• HNWarehouse 可减少 ~64 行反射代码

4. 配置解析工具（ConfigValues）

来源提交：ac253a2

核心能力：

• 类型安全的配置值转换（stringValue / intValue / doubleValue / booleanValue）
• 安全的列表转换（stringList）
• 深拷贝嵌套 Map
• 标准化标识符（normalizeIdentifier）

使用示例：

int value = ConfigValues.intValue(config.get("amount"), 0);
List<String> list = ConfigValues.stringList(config.get("items"));

新增 Groovy 脚本

NoMiningExp - 挖掘时不再掉落经验

来源提交：bc15c81（2026-04-19，[新增] Groovy 脚本：挖掘时不再掉落经验）

功能：

• 支持配置生效世界列表
• 支持配置受影响的方块类型（可精确控制哪些矿石不掉经验）
• 默认禁用，需手动开启

NoWorldGrowth - 暂停世界生长规则

来源提交：5e0026e + 1f33e47（2026-04-19，[优化] 增强 NoWorldGrowth 脚本，支持更多世界规则控制）

功能：

• 阻止植物生长（作物、树苗等）
• 阻止方块蔓延（草方块、菌丝等）
• 阻止树叶枯萎
• 阻止冰雪融化与形成
• 阻止铜块氧化
• 阻止海龟蛋孵化
• 阻止炼药锅收集雨雪
• 所有功能可独立开关

NoWaterFlow - 让水/岩浆停止流动

来源提交：5e0026e

功能：

• 阻止水流动
• 阻止岩浆流动（可选）
• 支持配置生效世界列表

NoLavaDamage - 不再受到岩浆/火焰伤害

来源提交：5e0026e

功能：

• 取消岩浆伤害
• 取消火焰伤害（接触火方块，可选）
• 取消燃烧伤害（着火后的持续伤害，可选）
• 支持配置生效世界列表

构建系统优化

来源提交：88aaac3 + 5079203（2026-04-19，[构建] 调整版本号自动递增规则）

优化内容：

• 调整版本号递增规则：
  • [新增] → minor +1（新功能）
  • [更新] [优化] [修复] → patch +1（改进/修复）
  • [重构] → major +1（破坏性变更）
  • [脚本] [配置] [文档] [构建] → 不变（非核心代码）
• 插件构建文件名改为 HNCore-版本号.jar（更简洁）

下游迁移指南

来源提交：7c5d196 + 3b085a1（2026-04-19，[文档] 添加 1.5.0 下游插件迁移指南）

文档位置：DOWNSTREAM_MIGRATION_1.5.0.md

内容包含：

• 适用插件与收益评估
• 详细迁移步骤（5 步）
• 代码对比示例
• 配置格式示例
• 迁移检查清单（针对 HNSignIn / HNMail / HNWarehouse）
• 常见问题 FAQ

总结

v1.5.0 通过新增三大公共轮子（奖励系统、成本扣除系统、经济桥接），预计可帮助下游插件减少 400-1500 行重复代码，大幅降低维护成本。

同时新增 4 个 Groovy 脚本，进一步扩展 HNCore 的开箱即用能力。