【后端接口】mapmove：传送接口的落点范围与地图参数

实战应用：用在哪里

mapmove 是地图跳转的总入口：任务传送、活动进场、死亡回城、GM 拉人全走它。四个参数里 nRange 是最容易被忽略的一个，它决定了落点的散布空间，是传送体验的隐形设计师。

接口签名与定点传送

---飞地图 mapname:地图 nX/nY:坐标 nRange:落点范围
function mapmove(actor, mapname, nX, nY, nRange) end

-- 传送进祖玛寺庙三层，落在坐标 20,30 的周围 3 格
mapmove(actor, "zuma3", 20, 30, 3)

mapname 支持地图 ID 或地图名，坐标是落点中心，nRange 是围绕中心的散布半径：传 0 就精确落在坐标点，传 3 就在 3 格范围内随机。副本与 BOSS 房的传送把 nRange 设成 3 到 5，一批玩家进场不叠在同一格；任务传送要求精确触发的把 nRange 设 0，落点即触发点。

批量传送与安全落点

-- 行会集结：全帮传送到攻城集结点
function rallyGuild(guildId, mapname, x, y)
    local members = getguildonline(guildId)
    for _, name in ipairs(members) do
        local actor = getplayerbyname(name)
        if actor and not actor:IsInBattle() then
            mapmove(actor, mapname, x + math.random(-5, 5), y + math.random(-5, 5), 0)
        end
    end
end

批量传送的散布用业务层随机坐标加 nRange 置 0 的组合，落点控制权留在业务手里。传送前的战斗态校验防止把正在PK的玩家硬拉走，getplayerbyname 按名字反查对象处理离线成员的跳过逻辑。地图的开放状态校验在传送前执行，未开放地图的传送请求直接拒绝并记日志，越权传送的排查从源头做了隔离。

验证与监控

传送流水按地图聚合统计，未开放地图的传送尝试记录是安全监控的固定指标。

踩坑记录

nRange 落点的随机曾经可能落在不可行走格，玩家传进墙里出不来，落点的可达性校验（isemptyinmap）补进接口封装后绝迹。地图参数大小写敏感的坑：地图表里 "Zuma3" 与 "zuma3" 是两个键，传送静默失败，地图名的规范化比对在封装层做了大小写归一。

上线要点

mapmove 与 groupmapmove 的分工：单人传送用 mapmove 逐个控制，整队要一起动的用 groupmapmove 一次调用。传送的读条表现是客户端行为，服务端只负责数据跳转，读条期间玩家断线的重连落点以服务器的跳转结果为准。跨服地图的传送要把跨服标记带全，跳转后的数据同步依赖跳转接口的完整参数。

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