【后端接口】setontimer：个人定时器的 ID 管理与跨服标记

实战应用：用在哪里

setontimer 是挂在玩家身上的秒级定时器：毒 tick、增益倒计时、副本节奏全靠它驱动。接口的四个参数里藏着两套纪律：ID 的管理纪律与跨服标记的判断纪律，用好了是节奏器，用不好是泄漏源。

接口签名与基础用法

---添加个人定时器 actor:玩家 id:定时器ID RunTick:间隔秒 RunTime:次数 kf:跨服继续
function setontimer(actor, id, RunTick, RunTime, kf) end

-- 中毒 tick：每 2 秒一跳，共 7 跳，跨服继续
setontimer(actor, 9001, 2, 7, 1)

RunTick 是间隔秒数，RunTime 是执行次数，次数执行完引擎自动移除定时器——自动移除是这套接口的精髓，不需要业务层手动清理常规定时器。id 是业务自定义的编号，同一个 id 重复添加会覆盖旧定时器，利用覆盖语义可以做到"刷新毒"而不会叠出双份 tick。

移除与跨服

-- 解毒时移除毒 tick
setofftimer(actor, 9001)

-- 跨服战场里继续走的女神祝福：kf 置 1
setontimer(actor, 9002, 60, 30, 1)

提前解除用 setofftimer 按同一 id 移除，解毒、驱散、死亡清理都走这一对接口。kf 参数置 1 后定时器在跨服地图继续执行，置 0 或缺省则进跨服即暂停，跨服玩法携带的增益必须显式置 1，否则玩家进了跨服战场增益静默失效，客诉的典型来源。

验证与监控

个人定时器的存活数按 id 分布监控，单玩家存活定时器超过 20 个即为泄漏预警。

踩坑记录

定时器 id 早期各业务随手起数字，两个业务撞了同一个 id 互相覆盖对方的定时器，毒 tick 把回血 tick 关掉的事故排查了一晚上，此后 id 段位按业务分配表管理。RunTime 不传次数的定时器（永久型）在玩家下线后是否继续走的语义也踩过坑，确认过引擎行为是下线暂停上线恢复，把这条写进了接口注释。

上线要点

个人定时器与全局定时器（setontimerex）的分工要清晰：跟随玩家生命周期的用个人版，全服节奏的用全局版。中毒这类周期伤害的结算体放在定时器回调里要做 pcall 保护，单次回调的异常不能中断后续 tick。定时器回调里的上下文要在注册时闭包捕获，回调触发时玩家可能已下线，判空是回调体的第一行。

本文由 996 技术组基于 996 引擎官方知识库与浮生梦老师课程体系整理。团队长期从事传奇类引擎 Lua 后端逻辑、客户端界面与商业版本交付，内容以官方知识库与真实项目为出处，按版本持续修订。