HN 系列 Wiki

主题

这页专门回答一个问题：

HNAttribute 当前到底提供了哪些占位符，应该怎么写，返回的又是什么？

如果你现在是在做：

  • 计分板
  • TAB / HUD
  • 菜单显示
  • 面板数值回显
  • 用 PlaceholderAPI 读属性结果

那这一页就是最快入口。

一、先记住：现在有两套入口 ​

1）业务前缀写法（推荐给服主） ​

text
%hnattr_<属性ID>%

例如：

text
%hnattr_attack_damage%
%hnattr_defense%
%hnattr_in_combat%

2）统一桥接写法（框架视角） ​

text
%hncore_attribute_<key>%

例如：

text
%hncore_attribute_attack_damage%
%hncore_attribute_value.attack_damage%
%hncore_attribute_effective.attack_damage%
%hncore_attribute_in_combat%
%hncore_attribute_buff_count%

一句话理解：

  • hnattr：HNAttribute 的业务前缀入口，推荐日常配置优先使用
  • hncore_attribute_：HNCore 的统一桥接入口，适合统一命名空间视角

当前两套入口都由 HNCore 的统一 PlaceholderProvider 驱动，所以结果逻辑是一致的。

二、最常用的属性值写法 ​

业务前缀入口 ​

text
%hnattr_attack_damage%
%hnattr_defense%
%hnattr_fire_damage%
%hnattr_max_health%

统一桥接入口 ​

text
%hncore_attribute_attack_damage%
%hncore_attribute_value.attack_damage%
%hncore_attribute_effective.attack_damage%

它们的语义可以这样记：

写法说明
%hnattr_attack_damage%业务前缀写法，返回当前最终属性值，推荐服主配置优先使用
%hncore_attribute_attack_damage%统一桥接写法，等价于读取该属性当前值
%hncore_attribute_value.attack_damage%显式读取当前属性值
%hncore_attribute_effective.attack_damage%显式读取 effective 值

大多数面板场景下，attack_damage 和 value.attack_damage 可以理解成同一层语义；effective.xxx 更适合明确想表达“运行时生效值”的场景。

不想要固定两位小数怎么办？ ​

现在属性值占位符支持“自定义小数位数”前缀。

也就是说，你想保留几位小数，就直接在属性 key 前写几：

  • 0：不保留小数
  • 1：保留 1 位小数
  • 2：保留 2 位小数
  • 4：保留 4 位小数

业务前缀入口 ​

text
%hnattr_0.attack_damage%
%hnattr_1.attack_damage%
%hnattr_2.attack_damage%
%hnattr_4.attack_damage%

%hnattr_0.effective.attack_damage%
%hnattr_2.value.attack_damage%

统一桥接入口 ​

text
%hncore_attribute_0.attack_damage%
%hncore_attribute_1.attack_damage%
%hncore_attribute_2.attack_damage%
%hncore_attribute_4.attack_damage%

%hncore_attribute_0.effective.attack_damage%
%hncore_attribute_2.value.attack_damage%

示例 ​

假设 attack_damage = 12.345：

写法结果
%hnattr_attack_damage%12.35
%hnattr_0.attack_damage%12
%hnattr_1.attack_damage%12.3
%hnattr_2.attack_damage%12.35
%hnattr_4.attack_damage%12.3450

如果你做的是：

  • 计分板 / TAB / 简洁 HUD → 优先用 0. 前缀
  • 菜单 / Lore / 详情面板 → 用 1. / 2. / 4. 这种更直观

三、运行时状态与聚合值 ​

除了属性本身，现在还支持一批固定 key：

战斗状态 ​

text
%hnattr_in_combat%
%hnattr_in_combat_int%
%hnattr_combat_time_left%
%hnattr_combat_duration%

%hncore_attribute_in_combat%
%hncore_attribute_in_combat_int%
%hncore_attribute_combat_time_left%
%hncore_attribute_combat_duration%

聚合值 ​

text
%hncore_attribute_buff_count%
%hncore_attribute_group_count%
%hncore_attribute_periodic_count%

含义：

占位符说明返回示例
%hncore_attribute_in_combat%当前是否处于战斗状态true / false
%hncore_attribute_in_combat_int%战斗状态整数版1 / 0
%hncore_attribute_combat_time_left%剩余战斗时间（秒）2.50
%hncore_attribute_combat_duration%当前战斗已持续时间（秒）6.00
%hncore_attribute_buff_count%当前活跃 Buff 数量2
%hncore_attribute_group_count%属性面板首页当前展示的分组数量3
%hncore_attribute_periodic_count%当前活跃周期实例数量1

其中：

  • combat_time_left 与 combat_duration 返回秒数字符串
  • buff_count / group_count / periodic_count 返回整数

四、这些值到底读的是哪一层 ​

这里返回的是：

当前最终结果 / 当前运行时状态

也就是说，它会把下面这些来源都一起算进去：

  • 装备 Lore / PDC / NBT
  • Buff 来源
  • 其他系统注入来源
  • 属性映射派生来源
  • 运行时战斗状态 / Buff 数量 / 周期实例数量

注意：PlaceholderAPI 只能读取玩家的属性，不能读取怪物 / 非玩家实体的属性。

所以它不是：

  • 单件装备原始值
  • 某个 Buff 单独提供的值
  • 某一条来源明细

如果你要查“为什么这个值会变成这样”，不要只盯着占位符，要回到 HNAttribute 的命令链路：

text
/hnattr inspect
/hnattr lookup
/hnattr source
/hnattr trace <属性ID>

五、返回规则 ​

情况返回结果
玩家在线，属性存在两位小数的数值字符串，如 120.00
玩家在线，聚合值存在整数或固定格式字符串，如 2、3、2.50
玩家不在线 / 玩家对象为空0 或 false（取决于具体 key）
属性 ID 不存在空 / 无结果（由 PAPI 侧表现决定）

你最需要记住的两点：

  1. 这是面向在线玩家与当前运行时的结果读取
  2. 属性 ID 拼错时，不会帮你自动猜

六、最容易写错的地方 ​

1）把显示名当属性 ID ​

错误示例：

text
%hnattr_攻击力%

正确写法通常应该是：

text
%hnattr_attack_damage%
%hncore_attribute_attack_damage%

占位符这里要写的是 属性 ID，不是中文显示名。

2）把业务前缀入口和统一桥接入口混成一套语法 ​

正确示例：

text
%hnattr_attack_damage%
%hncore_attribute_attack_damage%
%hncore_attribute_value.attack_damage%

现在也可以这样写：

text
%hnattr_value.attack_damage%
%hnattr_effective.attack_damage%

也就是说，hnattr 这套业务前缀入口不再只是最简单的 hnattr_<属性ID>，它同样可以表达 value. / effective. 这类更细的语义；只是从可读性上看，很多团队仍然会把这类写法优先放到 hncore_attribute_ 统一桥接入口下。

3）只看 PAPI，不回头排查 HNAttribute ​

很多时候真正的问题不在 PlaceholderAPI，而在：

  • 装备没读到
  • Buff 没挂上
  • 周期实例没跑起来
  • 你看的属性 ID 根本不是最终参与结算的那个

排查顺序建议：

text
/hnattr inspect
/hnattr lookup
/hnattr source
/hnattr trace attack_damage

如果你怀疑的是模板道具或运行时持久化，再补：

text
/hnattr item list
/hnattr runtime show <玩家>

七、最推荐的搭配用法 ​

面板 / 菜单显示 ​

text
攻击力: %hncore_attribute_attack_damage%
防御力: %hncore_attribute_defense%
暴击率: %hncore_attribute_crit_chance%%
Buff数: %hncore_attribute_buff_count%
周期数: %hncore_attribute_periodic_count%

HUD / 计分板 ​

text
ATK %hnattr_attack_damage%
DEF %hnattr_defense%
HP+ %hncore_attribute_health_regen%
Combat %hncore_attribute_in_combat_int%

配服时联动排查 ​

text
面板显示值
↓
%hncore_attribute_attack_damage%
↓
/hnattr trace attack_damage
↓
确认具体是哪条来源把它抬高/压低了

八、和 MythicMobs 内部占位符的区别 ​

这页说的是 PlaceholderAPI 占位符：

text
%hnattr_attack_damage%
%hncore_attribute_attack_damage%

它和 MythicMobs 内部占位符不是同一套语法。

MythicMobs 那边当前另外提供：

text
<buff.力量提升.time>
<buff.力量提升.level>
<periodic.burn-dot.has>
<periodic.burn-dot.stacks>

如果你要查 MythicMobs 这条线，优先看：

九、最短排查清单 ​

如果你现在只想知道怎么最快确认“占位符是不是对的”，就按这个顺序：

text
1. /hnattr inspect
2. /hnattr lookup
3. /hnattr trace <属性ID>
4. 再回去看 %hnattr_% 或 %hncore_attribute_%

如果 lookup / trace 都对了，占位符通常就不会是问题本体。

HN 系列插件文档

Copyright © 2024