【后端接口】addbuff：BUFF 接口的叠加层数与属性表

实战应用：用在哪里

addbuff 是状态系统的入口：中毒、加速、护盾、变身全走这一个接口。它的参数表把 BUFF 的四要素（时长、叠加、施放者、属性修正）一次配齐，配合 buff 表驱动，策划调整一个 BUFF 不需要动代码。

接口签名与叠加

---添加buff obj:玩家|怪物 buffid:10000起步 time:单位看buff表 OverLap:叠加层 objOwner:施放者 abil:属性表
function addbuff(obj, buffid, time, OverLap, objOwner, abil) end

-- 给玩家加 60 秒攻击强化，叠 2 层，带属性表
addbuff(actor, 10001, 60, 2, actor, { [1] = 200, [4] = 20 })

obj 参数玩家与怪物通吃，同一接口给怪上减益给玩家上增益。abil 属性表用属性 ID 做键：1 号位配 200 点攻击、4 号位配 20 点防御，属性修正随 BUFF 生效与到期自动挂卸，不需要业务手工加减。objOwner 登记施放者，光环类 BUFF 的施放者死亡后自动消散的规则靠这个字段驱动。

查询与判断

-- 施毒前判断目标是否已有同系 BUFF
function poisonOrRefresh(target)
    if hasbuff(target, 10010) then
        addbuff(target, 10010, 60, 1, actor)
        sendmsg(actor, 1, "目标已中毒，刷新时长")
    else
        addbuff(target, 10010, 60, 1, actor)
        sendmsg(actor, 1, "目标中毒")
    end
end

hasbuff 先判后加是刷新与新增的分流写法，配合 OverLap 参数实现叠层或刷新两种策略。getbuffinfo 能取出 BUFF 的剩余时间与当前层数，界面上毒圈的剩余秒数显示就是读的这个接口。BUFF 的时长单位以 buff 表配置为准：同一个接口传 60，毒表按秒算就是 60 秒，跳跃表按跳算就是 60 跳，单位的解释权在配置侧。

验证与监控

BUFF 的叠加层数分布监控，层数长期顶在配置上限说明叠加规则需要复盘。

踩坑记录

buffid 从 10000 起步是引擎保留段的约定，有脚本用了 9999 与引擎内置 BUFF 撞车，表现为玩家无故变身，id 段位规范写进接口注释后绝迹。abil 属性表的键写错为字符串（["1"]=200 而不是 [1]=200）时属性不生效且无报错，属性表的键类型断言进了配表校验。

上线要点

给怪物上 BUFF 时注意 obj 传怪物对象，玩家与怪物的 BUFF 表是同一张但生效字段不同，怪物吃速度类 BUFF 的行为要在配表时单独验证。BUFF 的叠加上限在 buff 表里配，OverLap 传超上限的值引擎按上限钳制，业务层不必自行判断。驱散类功能的实现就是按 BUFF 分组遍历清除，给 BUFF 分组打标签的配表习惯能让驱散规则简单一半。

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