集成与 API | HN 系列 Wiki

这页只回答一件事：HNAttribute 能和哪些外部系统对接，以及每种接法最适合做什么。

如果你现在想查的是：

MythicMobs 具体 mechanic 参数 → 看 MythicMobs 联动速查表
DOT / HOT / runtime 原理 → 看周期效果与实例系统
Buff 模板与属性修饰 → 看 Buff 系统

一、当前有哪些集成入口

HNAttribute 当前最主要的外部集成有三类：

PlaceholderAPI
MythicMobs
Java API

你可以这样理解：

PlaceholderAPI：给面板、菜单、计分板读结果
MythicMobs：给技能、怪物、条件系统接玩法入口
Java API：给其他插件直接读值、注入来源、控制 Buff

二、PlaceholderAPI

如果你现在只是想快速查 %hnattr_<属性ID>% 怎么写，直接跳： PlaceholderAPI 占位符速查表

如果服务器安装了 PlaceholderAPI，HNAttribute 当前有两套入口：

text

%hnattr_<属性ID>%
%hncore_attribute_<key>%

推荐记法：

服主 / 配置作者：优先使用 %hnattr_*%
开发者 / 框架视角：需要统一表达时再使用 %hncore_attribute_*%

完整示例与两套入口的对照，建议直接继续看：

PlaceholderAPI 占位符速查表

例如：

text

%hnattr_attack_damage%
%hnattr_0.attack_damage%
%hnattr_2.attack_damage%
%hnattr_in_combat%

%hncore_attribute_attack_damage%
%hncore_attribute_0.attack_damage%
%hncore_attribute_2.attack_damage%
%hncore_attribute_value.attack_damage%
%hncore_attribute_effective.attack_damage%
%hncore_attribute_in_combat%
%hncore_attribute_buff_count%
%hncore_attribute_group_count%
%hncore_attribute_periodic_count%

其中：

%hnattr_%：面向 HNAttribute 用户的业务前缀入口，推荐服主/配置作者优先使用
%hncore_attribute_%：HNCore 统一桥接入口，适合从框架视角统一理解各业务命名空间

现在这两套入口都由 HNCore 的统一占位符服务驱动：

hnattr 是 attribute 命名空间的业务别名前缀
hncore_attribute 是同一个命名空间的统一桥接写法
两者结果逻辑一致，只是对外书写形式不同

它适合做什么

计分板显示玩家当前属性
菜单里展示攻击力、生命值、元素值
做实时 HUD / 面板数值回显
统一读取战斗状态、Buff 数量、周期数量等运行时聚合值

你要特别注意什么

这些占位符返回的是当前最终属性值，不是某一层原始值。

也就是说，它会同时吃到：

装备来源
Buff 来源
其他插件注入来源
属性映射 / 派生属性来源

如果你配置了 mapping.targets，占位符读到的就是映射已经结算后的结果。

需要现成模板时，可以直接参考插件自带的 attributes/mapping-demo.yml。

如果你更想直接拿一套可用主属性上服测试，也可以直接用 attributes/rpg-derived.yml。

这套模板默认已经包含 strength / agility / vitality / intellect / magic_power，其中 vitality 会派生生命恢复。

所以如果你看到面板数值不对，不要先怀疑 PlaceholderAPI，先回 HNAttribute 自己查：

text

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

三、MythicMobs

如果服务器安装了 MythicMobs，HNAttribute 会额外提供三组能力：

1）怪物属性标签

MythicMobs 生物配置里可以写属性文本，当前默认按顺序读取：

text

Attribute
attribute

例如：

yaml

Attribute:
  - "攻击力: 100"
  - "火焰伤害: 20"
  - "火焰抗性: 10"

这些文本会像装备 Lore 一样进入属性解析流程。

如果这些怪物属性里又存在派生关系，例如：

strength -> attack_damage
attack_damage -> crit_multiplier

那么怪物基础属性、以及怪物后续吃到 Buff 之后的最终属性，都会重新走同一套映射结算。

2）怪物 `damage-modifiers` 配置糖

MythicMobs 怪物现在还可以直接写：

yaml

damage-modifiers:
  physical: 0.8
  fire: 1.5
  ice: 0.5

你可以把它理解成“怪物模板自带的按伤害类型最终倍率表”：

physical: 0.8 → 物理伤害最终只吃 80%
fire: 1.5 → 火伤最终吃 150%
ice: 0.5 → 冰伤最终只吃 50%

它和 fire_resistance / ice_resistance 的区别是：

*_resistance：属于通道属性层
damage-modifiers：属于怪物配置层的最终按类型倍率修正

所以它特别适合做：

Boss 弱火、抗冰这种模板糖
阶段怪对某元素临时脆弱
不想额外扩一批属性时，直接在 Mythic 配置里表达

3）技能 Mechanic 接入

当前 MythicMobs 侧主要可接：

hna-damage
hna-buff / hna-removebuff / hna-clearbuff
hna-dot / hna-hot
hna-clearot / hna-cleardot / hna-clearhot
hna-triggerot / hna-triggerdot / hna-triggerhot
hna-detonateot / hna-detonatedot / hna-detonatehot
hna-hasbuff / hna-hasot

这意味着 MythicMobs 现在不只是能“打一段伤害”，还可以直接接入：

Buff 状态层
统一 periodic runtime
即时补跳 / 引爆结算
条件判断与排查链路

元素赋予与一次性技能元素伤害怎么理解

当前默认模型里，fire_damage 代表的是火焰通道伤害数值。

它默认表示的是：

你有多少火焰通道值
而不是系统内置的“火焰赋予开关”

也就是说，当前没有内置 fire_imbue 这一层布尔语义；如果 fire 通道启用且攻击方 fire_damage > 0，它就可以参与默认通道结算。

如果你想做“必须先有火焰赋予，火伤才生效”，推荐：

自己定义一个独立属性，例如 fire_imbue
在实际使用的 pipelines/*.yml 中，对相关 stage 的公式按 damage_type == 'fire' 或 self_fire_damage 做条件门控

如果你只是想让某个技能这一次明确打成火属性，最直接就是：

yaml

- hna-damage{a=100;damage-type=fire;source-type=skill} @target

这类明确标了 damage-type=fire 的技能伤害，也会吃到怪物自己的 damage-modifiers.fire。

4）Buff / Periodic 内部占位符

如果你现在只是想快速查 <buff.xxx.time> 或 <periodic.xxx.has> 怎么写，直接跳： MythicMobs 内部占位符速查表

当前还会向 MythicMobs 提供 Buff 内部占位符：

text

<buff.力量提升.time>
<buff.力量提升.level>

以及这些同义写法：

remaining
ticks
lv
amplifier

MythicMobs 这条线该怎么读文档

这页不再重复放完整参数表，你可以按下面顺序看：

想知道当前到底有哪些 mechanic 和默认值 → MythicMobs 联动速查表
想理解 DOT / HOT 为什么这样跑 → 周期效果与实例系统
想理解 Buff 为什么最终会变成属性来源 → Buff 系统

MythicMobs 集成最重要的一条

MythicMobs 负责发起动作，HNAttribute 负责属性、状态、周期和结算语义。

所以排查时不要只盯着 Mythic 技能链，要回到 HNAttribute 侧看运行结果：

text

/hnattr buffs
/hnattr source
/hnattr periodic list
/hnattr periodic inspect <key>

四、Java API

当前静态入口类是：

java

import com.github.hnplugins.hnattribute.api.HNAttributeAPI;

已公开的能力

1）属性查询

java

double attackDamage = HNAttributeAPI.getValue(player, "attack_damage");
var allValues = HNAttributeAPI.getAll(player);
boolean exists = HNAttributeAPI.hasAttribute("fire_damage");

适合：

查询玩家当前最终属性
给自定义菜单、任务系统、战斗插件读值
判断某个属性 ID 是否存在

2）来源修饰符注入

java

var modifier = HNAttributeAPI.createModifier(
        "custom:quest-reward",
        "attack_damage",
        Operation.ADD,
        50.0
);
HNAttributeAPI.addModifiers(player, "custom:quest-reward", java.util.List.of(modifier));

移除时：

java

HNAttributeAPI.removeModifiers(player, "custom:quest-reward");

适合：

成就奖励
任务状态加成
活动临时属性
其他插件注入自定义来源

3）装备刷新

java

HNAttributeAPI.refreshEquipment(player);

适合：

你改了玩家装备数据
你自己处理了物品替换
需要主动触发一次装备重读

4）Buff API

java

HNAttributeAPI.applyBuff(player, "力量提升", 100, 1);
HNAttributeAPI.hasBuff(player, "力量提升");
HNAttributeAPI.getBuffLevel(player, "力量提升");
HNAttributeAPI.getBuffRemainingTicks(player, "力量提升");
HNAttributeAPI.removeBuff(player, "力量提升");
HNAttributeAPI.clearBuffs(player);

适合：

用其他插件触发 Buff
做自定义状态技能
查询某个 Buff 是否在身上

5）模板化道具 API

java

var reroll = HNAttributeAPI.createRerollTicket();
var core = HNAttributeAPI.createReforgingCore(2);
var material = HNAttributeAPI.createUpgradeMaterial(8);
var awakening = HNAttributeAPI.createAwakeningStone();

适合：

奖励系统直接发标准业务道具
GM / 调试命令统一构造 token / material
避免在其他模块里重复手搓 ItemStack、PDC、token_id

如果你想系统理解模板道具应该怎么配、怎么发、怎么 inspect，建议继续看：

模板化道具与 ItemSpec

6）按伤害类型倍率修正 API

java

HNAttributeAPI.setDamageTypeModifiers(entity, Map.of(
        "physical", 0.8,
        "fire", 1.5,
        "ice", 0.5
));

double fireTaken = HNAttributeAPI.getDamageTypeModifier(entity, "fire");
HNAttributeAPI.clearDamageTypeModifiers(entity);

也支持按 UUID 调用同名方法。

适合：

运行时给某个实体临时挂“弱火 / 抗冰”
自定义 Boss 阶段切换受伤表
让其他插件复用 HNAttribute 的按类型受伤倍率 runtime

当前没有单独公开什么

当前公开静态 API 里：

已经有属性 API
已经有 Buff API
已经有模板化道具创建 API
已经有按伤害类型倍率修正 API
已经有集群广播 API
但还没有单独对外公开完整的周期实例静态 API

所以周期系统目前更适合通过下面三种方式使用：

periodic/settings.yml 与 periodic/*.yml
MythicMobs 的 hna-dot / hna-hot
/hnattr periodic ... 调试命令

五、集群同步

如果你已经接了 HNCore 的 ClusterBus，那么 HNAttribute 当前可以做：

/hnattr reload cluster
/hnattr refresh <玩家> cluster
/hnattr debug <level> cluster
/hnattr perf reset cluster
HNAttributeAPI.broadcastReload()
HNAttributeAPI.broadcastRefreshEquipment(player)

Java API 侧最常见的写法

java

if (HNAttributeAPI.isSharedSyncAvailable()) {
    HNAttributeAPI.broadcastReload();
}

HNAttributeAPI.refreshEquipment(player);
HNAttributeAPI.broadcastRefreshEquipment(player);

如果你需要更底层地判断当前共享同步是否已经接通，也可以直接拿：

java

var syncService = HNAttributeAPI.getSharedSyncService();
boolean ready = HNAttributeAPI.isSharedSyncAvailable();

runtime snapshot 要怎么理解

当前版本里，跨服运行时同步主要服务于：

玩家 Buff
玩家目标周期实例（DOT / HOT）

它的使用心智是：

本地变化先进入 dirty 队列
flush 定时任务会异步落库
只有跨服相关变化才会额外广播 runtime-snapshot

这条链路目前是内部运行时能力，不是面向二开的完整公开静态 API；如果你想从服主/运维视角系统理解它，建议继续看：

跨服运行时同步说明

这里真正要看什么

真正影响跨服的是 HNCore 的 transport，而不是“命令有没有执行成功”。

要特别区分：

redis：真正跨服
loopback：只在本服本进程内可见

最稳的检查命令是：

text

/hncore cluster status

如果你是多服环境，还应确认：

HNCore 的 ClusterBus 是否正常初始化
storage.yml 里的 Redis 是否可用
cluster.node-id 是否唯一

六、推荐的接入顺序

你是服主 / 策划

推荐顺序：

先跑通声明式配置
再接 MythicMobs 的 hna-buff / hna-dot / hna-hot
最后再考虑 Java 二开

你是二开作者

推荐顺序：

先用 HNAttributeAPI.getValue() 验证属性读取
再用 addModifiers/removeModifiers 管理自定义来源
再用 Buff API 接状态层
如果要接跨服刷新，再补 broadcastRefreshEquipment / broadcastReload
周期实例先走配置或 Mythic 接入

七、这一页最该记住的重点

PlaceholderAPI 负责展示结果，不负责解释结果。
MythicMobs 负责技能入口，HNAttribute 负责属性、状态、周期和结算语义。
Java API 现在最适合做属性读取、自定义来源注入、Buff 控制和跨服刷新广播。
周期实例目前更适合通过配置和 Mythic 使用，而不是直接期待一套完整公开静态 API。
跨服问题优先查 HNCore 的 ClusterBus，而不是先怀疑 HNAttribute 本身。

mythicmobs

placeholderapi

一、当前有哪些集成入口

二、PlaceholderAPI

它适合做什么

你要特别注意什么

三、MythicMobs

1）怪物属性标签

2）怪物 `damage-modifiers` 配置糖

3）技能 Mechanic 接入

元素赋予与一次性技能元素伤害怎么理解

4）Buff / Periodic 内部占位符

MythicMobs 这条线该怎么读文档

MythicMobs 集成最重要的一条

四、Java API

已公开的能力

1）属性查询

2）来源修饰符注入

3）装备刷新

4）Buff API

5）模板化道具 API

6）按伤害类型倍率修正 API

当前没有单独公开什么

五、集群同步

Java API 侧最常见的写法

runtime snapshot 要怎么理解

这里真正要看什么

六、推荐的接入顺序

你是服主 / 策划

你是二开作者

七、这一页最该记住的重点

一、当前有哪些集成入口 ​

二、PlaceholderAPI ​

它适合做什么 ​

你要特别注意什么 ​

三、MythicMobs ​

1）怪物属性标签 ​

2）怪物 damage-modifiers 配置糖 ​

3）技能 Mechanic 接入 ​

元素赋予与一次性技能元素伤害怎么理解 ​

4）Buff / Periodic 内部占位符 ​

MythicMobs 这条线该怎么读文档 ​

MythicMobs 集成最重要的一条 ​

四、Java API ​

已公开的能力 ​

1）属性查询 ​

2）来源修饰符注入 ​

3）装备刷新 ​

4）Buff API ​

5）模板化道具 API ​

6）按伤害类型倍率修正 API ​

当前没有单独公开什么 ​

五、集群同步 ​

Java API 侧最常见的写法 ​

runtime snapshot 要怎么理解 ​

这里真正要看什么 ​

六、推荐的接入顺序 ​

你是服主 / 策划 ​

你是二开作者 ​

七、这一页最该记住的重点 ​

一、当前有哪些集成入口

二、PlaceholderAPI

它适合做什么

你要特别注意什么

三、MythicMobs

1）怪物属性标签

2）怪物 `damage-modifiers` 配置糖

3）技能 Mechanic 接入

元素赋予与一次性技能元素伤害怎么理解

4）Buff / Periodic 内部占位符

MythicMobs 这条线该怎么读文档

MythicMobs 集成最重要的一条

四、Java API

已公开的能力

1）属性查询

2）来源修饰符注入

3）装备刷新

4）Buff API

5）模板化道具 API

6）按伤害类型倍率修正 API

当前没有单独公开什么

五、集群同步

Java API 侧最常见的写法

runtime snapshot 要怎么理解

这里真正要看什么

六、推荐的接入顺序

你是服主 / 策划

你是二开作者

七、这一页最该记住的重点