【后端接口】rangeharm：范围伤害接口的十一个参数与群体结算

实战应用：用在哪里

rangeharm 是群体伤害的引擎级接口：以坐标为圆心的范围内目标一次结算伤害，法师的 AOE 技能、机关陷阱、爆炸物全都收敛到这一个接口。十一个参数把范围、威力、目标筛选、特效、命中数全部做成可配置项。

接口签名与基础用法

---范围伤害 targetX/Y:中心 range:半径 power:威力 addtype:加成类型 targettype:目标筛选
function rangeharm(actor, targetX, targetY, range, power, addtype, addvalue, checkstate, targettype, effectid, harmNum) end

-- 爆炸陷阱：3 格半径，威力 500，仅怪物，命中上限 8
rangeharm(actor, x, y, 3, 500, 0, 0, 0, 2, 6, 8)

targetX 与 targetY 是伤害圆心（可以不是施法者脚下），range 是半径格数，power 是基础威力。targettype 的三档筛选（全部、仅人物、仅怪物）让同一个接口既能打怪又能做 PVP 机关，effectid 给命中的目标身上挂受击特效。harmNum 是命中上限，防止范围里塞了五十只怪一次全清的失控。

陷阱机关的组合

-- 地面陷阱：踩中触发范围伤害
function triggerTrap(actor, trapId)
    local trap = traps[trapId]
    rangeharm(actor, trap.x, trap.y, trap.radius, trap.power, 0, 0, 0, 0, trap.effect, trap.limit)
    playeffect(actor, trap.effectId, 0, 0, 1, 0, 1)
end

陷阱的配置化：半径、威力、特效、命中上限全部进配置表，机关的实现在运行期只是参数的搬运工。addtype 与 addvalue 是威力的修正通道：按攻击加成、按等级加成的不同算法在这两个参数里选型。checkstate 参数做目标状态的预筛，只打特定状态的目标（如只打中poison的）让组合技有了引擎级支持。

验证与监控

rangeharm 的单次结算目标数分布监控，顶满 harmNum 的释放占比说明范围密度需要再平衡。

踩坑记录

威力参数曾经的语义是固定伤害，有人理解为倍率传了 1.5，全屏怪掉一滴血，参数语义的注释里加上了示例值。targettype 的筛选遗漏曾经让陷阱误伤己方阵营，阵营筛选的扩展参数是后来的补丁，PVP 地图的机关全部强制带阵营筛选。

上线要点

范围伤害的结算顺序按距离排序还是按目标列表顺序，引擎的行为要在团队内明确，伤害分配的上限逻辑依赖这个顺序。rangeharm 的调用频率在 BOSS 战的 AOE 连发场景会密集，单次结算的目标数上限参数就是服务器的保护阀。特效 ID 的资源管理与伤害接口解耦，特效删除不影响伤害结算。

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