周期效果与实例系统

这页不追求把所有字段都堆成参数表，而是先帮你建立一个更清晰的心智：

周期系统为什么重要
direct 和 instance 有什么根本区别
你怎样最快跑通第一个效果
出问题时该怎么查

如果你只是想直接抄模板，建议同时看：

周期效果 Cookbook

一、先理解：这套系统到底在解决什么

HNAttribute 的周期系统已经不只是“一个单独的回血任务”了，而是一套统一 runtime，可以同时承载：

周期回血
周期掉血
DOT
HOT
带来源 / 目标语义的实例效果
带条件、重施策略、生命周期 hooks 的运行时实例

所以你可以把它理解成：

Buff 负责状态标记和属性增减
periodic 负责周期行为和运行时实例

如果你要做的是：

中毒
灼烧
流血
HOT
持续回复
有 tick 条件的状态玩法

这页就是核心文档。

二、最先要理解的区别：direct vs instance

`direct`

适合：

简单周期回血
简单周期掉血
不需要单独实例追踪的效果

工作方式可以理解成：

定时扫描实体
条件成立
直接执行动作

它更像“定时规则”。

`instance`

适合：

DOT / HOT
需要 stack / merge / refresh 的状态
需要运行时 inspect / debug 的效果
需要生命周期 hooks 的效果

工作方式可以理解成：

定时扫描实体
条件成立
创建一个目标周期实例
后续由统一运行系统持续驱动它跳动

它更像“真正活着的一条状态实例”。

一句话选型

你只是想做简单周期动作 → direct
你要做真正状态玩法 → instance

持续状态类玩法，优先考虑 instance。

三、配置现在放哪里

当前统一入口已经改成目录式：

text

plugins/HNAttribute/periodic/settings.yml
plugins/HNAttribute/periodic/*.yml

推荐这样理解：

settings.yml：全局设置
其他 *.yml：具体效果定义

例如默认资源通常会是：

text

plugins/HNAttribute/periodic/settings.yml
plugins/HNAttribute/periodic/regen.yml
plugins/HNAttribute/periodic/dot-demo.yml
plugins/HNAttribute/periodic/instance-demo.yml

settings.yml 常见内容大致是：

yml

combat-timeout: 100

debug:
  enabled: false
  key-filter: []

而效果文件既可以直接把 effect 写在顶层，也可以包在 effects: 节点下。

例如：

yml

effects:
  some-effect:
    ...

四、先跑一个最简单的 direct 效果

下面这个例子适合拿来确认“声明式周期”本身工作正常。

yml

tutorial-direct-heal:
  enabled: true
  selector: players
  interval: 20
  condition:
    mode: expression
    script: target_health < target_max_health && target_health_regen > 0
  actions:
    - type: heal
      amount:
        mode: expression
        script: target_health_regen

这段配置是什么意思

每 20 tick 扫描一次玩家
如果玩家未满血，且 health_regen > 0
就按 health_regen 的值回血

怎么验证

给自己装备一件带 生命恢复: 5 的物品
保存 periodic/settings.yml 与 periodic/*.yml
执行：

text

/hnattr reload

自己受一点伤
脱战后观察是否回血

direct 最容易踩的点

它不会创建实例，所以：

text

/hnattr periodic list

通常看不到它。

如果你需要运行中的实例追踪，请改用 instance 模式。

五、再跑一个最简单的 instance 效果

下面这个例子更适合做“第一条真正的 DOT”。

yml

tutorial-self-poison:
  enabled: true
  mode: instance
  selector: players
  interval: 40
  tags: [tutorial, poison]
  condition:
    mode: expression
    script: target_health > 4
  instance:
    source: self
    interval: 20
    duration: 60
    reapply-mode: refresh
    tick-condition:
      mode: expression
      script: target_health > 1
    fail-policy: cancel
  actions:
    - type: damage
      amount: 1

怎么理解它

每 40 tick 扫描一次玩家
条件成立时，给玩家自己挂一个周期实例
实例每 20 tick 造成 1 点伤害
持续 60 tick
如果血量太低，就直接取消实例

怎么验证

把它加进某个 periodic/*.yml 文件，例如 periodic/tutorial.yml
执行：

text

/hnattr reload

查看实例：

text

/hnattr periodic list

查看详情：

text

/hnattr periodic inspect tutorial-self-poison

打开日志：

text

/hnattr periodic debug detail tutorial-self-poison

六、刚开始最该关心哪些字段

这一节不再把字段堆成大表，只保留你最容易用到的几组。

1）effect 层：决定“什么时候创建效果”

最常用：

enabled：是否启用
selector：选谁
interval：多久扫描一次
mode：direct 还是 instance
condition：满足什么条件才命中
actions：命中后执行什么动作
tags：给效果统一打标签

一句话理解：

effect 层负责“扫谁、什么时候触发、触发后做什么”。

2）instance 层：决定“实例怎么活”

最常用：

source：来源实体怎么选
interval：实例多久跳一次
duration：实例活多久
reapply-mode：重复施加时怎么处理
max-stacks：最多叠多少层
tick-condition：每跳前再检查什么
fail-policy：条件失败是 skip 还是 cancel

一句话理解：

instance 层负责“这条状态实例之后怎么跳、怎么续、怎么结束”。

3）hooks 层：决定“关键生命周期要不要做附加动作”

最常用：

on-apply
on-tick
on-skip
on-cancel
on-expire

适合做：

立即补一小段伤害
每跳附带动作
被打断时做收尾动作
正常结束时做一次爆发

七、最常用的几个设计点怎么选

`source` 怎么选

当前 instance.source 支持：

none
self
owner
nearest-player
nearest-mob
nearest-living

推荐这样记：

目标自己承受效果 → self
宠物 / 召唤物类玩法 → owner
光环 / 最近施法者类效果 → nearest-player 或 nearest-living

`reapply-mode` 怎么选

最常用的几种：

`refresh`

已有实例时刷新持续与参数。

适合：

中毒刷新
HOT 刷新
大多数传统状态技能

`stack`

在层数上限内叠层。

适合：

流血层数
灼烧层数
可见层数玩法

`merge`

把数值和次数一起合并。

适合：

想让重复命中越来越痛
希望持续时间也叠加的效果

`ignore`

已有实例就跳过。

适合：

同 key 只允许存在一个实例的玩法

`tick-condition` 和 `fail-policy` 怎么理解

tick-condition 是“每一跳执行前再检查一次”。

例如：

yml

tick-condition:
  mode: expression
  script: target_health > 1

fail-policy 常用两个值：

skip：本次不执行，但实例保留到下一跳
cancel：本次失败就直接结束实例

最实用的选择方法：

你想“条件偶尔不满足，只跳过一下” → skip
你想“条件不满足就直接结束状态” → cancel

八、脚本里现在能用什么上下文

周期脚本当前已经统一成：

source
target
self（等于 target）
attr（等于 target_attr）
source_attr
target_attr
effect

还支持平铺变量，例如：

target_health
target_max_health
source_health
source_present
target_attack_damage
source_fire_damage
effect_run
effect_completed_runs
effect_max_runs

一个实用例子：

groovy

source_present && target_health < target_max_health && effect_run <= 3

九、如何调试周期实例

先记住这 3 个最重要的：

text

/hnattr periodic list
/hnattr periodic inspect <key>
/hnattr periodic debug detail <key>

看列表

text

/hnattr periodic list
/hnattr periodic list all
/hnattr periodic list Steve

看详情

text

/hnattr periodic inspect tutorial-self-poison

打开 debug

text

/hnattr periodic debug detail tutorial-self-poison

其他常用辅助

只看配置状态：

text

/hnattr periodic debug status

按目标或来源清理：

text

/hnattr periodic clear Steve tutorial-self-poison
/hnattr periodic clearpair Steve Zombie tutorial-dot
/hnattr periodic clearall

十、MythicMobs 的 `hna-dot / hna-hot` 怎么理解

现在可以把它们理解成：

向同一套 periodic runtime 发起目标周期请求。

例如：

text

hna-dot{amount=2;duration=60;interval=20;mode=refresh;key="burn-dot"} @target

text

hna-hot{amount=2;duration=60;interval=20;mode=refresh;key="regen-hot"} @target

它们的核心差异

两者共用同一套 periodic runtime，核心差异只有一个：

hna-dot：周期性造成伤害
hna-hot：周期性造成治疗

也就是：

hna-dot = 周期实例 + DAMAGE action
hna-hot = 周期实例 + HEAL action

Mythic 里的即时结算入口

当前版本新增了两类语义：

`hna-triggerot` / `hna-triggerdot` / `hna-triggerhot`

语义是：

对匹配实例立刻额外执行一次 tick
然后正常扣掉 1 次 repeat

一句话理解：

补跳一跳

`hna-detonateot` / `hna-detonatedot` / `hna-detonatehot`

语义是：

按 stacks 提前结算若干次剩余 repeat
把未来若干跳的值一次性合并执行
consume=true 时会真的扣掉这些剩余 repeat；consume=false 时只做演示，不改实例状态
aggregate=true 时会按“来源 + action 签名”聚合成更少的结算段

一句话理解：

提前清算未来若干跳

更完整的 Mythic 参数速查不要在这页硬找，直接去：

MythicMobs 联动速查表

十一、新手最推荐的实装顺序

第一轮

先跑通一个 direct 回血
再跑通一个 instance 掉血
学会 list / inspect / debug

第二轮

给实例加 tick-condition
再加 fail-policy
最后再加 on-expire / on-cancel

第三轮

接 MythicMobs 的 hna-dot / hna-hot
用统一命令排查
再考虑更复杂的来源选择与层数玩法

十二、这一页最该记住的重点

direct 适合简单周期动作，instance 适合真正状态运行时。
DOT / HOT 现在已经和声明式实例统一进同一套 runtime。
tick-condition + fail-policy + hooks 是这套系统最强的三件套。
周期系统的排查入口不是猜配置，而是：

text

/hnattr periodic list
/hnattr periodic inspect <key>
/hnattr periodic debug detail <key>

一、先理解：这套系统到底在解决什么 ​

二、最先要理解的区别：direct vs instance ​

direct ​

instance ​

一句话选型 ​

三、配置现在放哪里 ​

四、先跑一个最简单的 direct 效果 ​

这段配置是什么意思 ​

怎么验证 ​

direct 最容易踩的点 ​

五、再跑一个最简单的 instance 效果 ​

怎么理解它 ​

怎么验证 ​

六、刚开始最该关心哪些字段 ​

1）effect 层：决定“什么时候创建效果” ​

2）instance 层：决定“实例怎么活” ​

3）hooks 层：决定“关键生命周期要不要做附加动作” ​

七、最常用的几个设计点怎么选 ​

source 怎么选 ​

reapply-mode 怎么选 ​

refresh ​

stack ​

merge ​

ignore ​

tick-condition 和 fail-policy 怎么理解 ​

八、脚本里现在能用什么上下文 ​

九、如何调试周期实例 ​

看列表 ​

看详情 ​

打开 debug ​

其他常用辅助 ​

十、MythicMobs 的 hna-dot / hna-hot 怎么理解 ​

它们的核心差异 ​

Mythic 里的即时结算入口 ​

hna-triggerot / hna-triggerdot / hna-triggerhot ​

hna-detonateot / hna-detonatedot / hna-detonatehot ​

十一、新手最推荐的实装顺序 ​

第一轮 ​

第二轮 ​

第三轮 ​

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

一、先理解：这套系统到底在解决什么

二、最先要理解的区别：direct vs instance

`direct`

`instance`

一句话选型

三、配置现在放哪里

四、先跑一个最简单的 direct 效果

这段配置是什么意思

怎么验证

direct 最容易踩的点

五、再跑一个最简单的 instance 效果

怎么理解它

怎么验证

六、刚开始最该关心哪些字段

1）effect 层：决定“什么时候创建效果”

2）instance 层：决定“实例怎么活”

3）hooks 层：决定“关键生命周期要不要做附加动作”

七、最常用的几个设计点怎么选

`source` 怎么选

`reapply-mode` 怎么选

`refresh`

`stack`

`merge`

`ignore`

`tick-condition` 和 `fail-policy` 怎么理解

八、脚本里现在能用什么上下文

九、如何调试周期实例

看列表

看详情

打开 debug

其他常用辅助

十、MythicMobs 的 `hna-dot / hna-hot` 怎么理解

它们的核心差异

Mythic 里的即时结算入口

`hna-triggerot` / `hna-triggerdot` / `hna-triggerhot`

`hna-detonateot` / `hna-detonatedot` / `hna-detonatehot`

十一、新手最推荐的实装顺序

第一轮

第二轮

第三轮

十二、这一页最该记住的重点