【后端接口】callscript 与 gotolabel：脚本互调与标签跳转的引擎写法

实战应用：用在哪里

996 引擎的 NPC 脚本体系按文件加标签组织：callscript 跨文件调用脚本，gotolabel 在脚本内跳转到标签段。NPC 对话的菜单跳转、功能的文件化拆分全靠这两个接口，脚本工程的模块化从这里开始。

跨文件调用

---执行脚本 actor:玩家 filename:脚本文件 label:标签段 range:范围
function callscript(actor, filename, label, range) end

-- 传送员 NPC 把玩家委托给传送脚本
function clicknpc(actor, npcIdx)
    if getnpcname(npcIdx) == "传送员" then
        callscript(actor, "Teleport", "main")
    end
end

callscript 按文件名加标签定位执行段：Teleport 脚本的 main 段被点击触发唤起，脚本文件按功能拆分（Teleport、Lottery、Warehouse），每个文件内部按标签组织段落。脚本的拆分粒度按功能域而不是按 NPC，多个 NPC 共用的传送功能写一份脚本，callscript 的复用让 NPC 脚本免于复制粘贴。

标签跳转与参数

-- 脚本内标签段：@比奇 传送段
-- [@比奇]
-- #ACT
-- mapmove actor 0 330 330
-- 带参数的跨文件调用
callscriptex(actor, "Teleport", "gotoCity", "bichon", 330, 330)

脚本标签段的写法沿用传奇脚本的段落语法（#ACT 行为段），callscriptex 扩展版支持把参数透传给目标段，传送目的地作为参数传入后一份传送脚本服务全服的传送员。脚本互调的层数要控制：A 调 B、B 调 C 的链路超过两层后调试成本陡增，callscript 的调用树在文档里维护。

验证与监控

脚本调用的失败日志（文件不存在、标签不存在）集中监控，脚本的配置错误在发布前扫一遍调用树。

踩坑记录

脚本文件名的编码问题曾经让中文文件名的脚本调用静默失败，脚本文件统一英文命名加注释说明功能。标签段的命名冲突在同一文件内复制粘贴时高发，同名标签后一个覆盖前一个，段落的命名前缀按功能域规范。callscript 的执行是同步的，被调脚本里的长循环会阻塞调用方，脚本内不做重活是脚本工程的纪律。

上线要点

脚本的调用关系图定期梳理，孤儿脚本（无人调用的文件）与不可达段（无入口的标签）在梳理中清理。脚本的入参与出参约定成文，Lua 函数与脚本段落的分工要明确：计算逻辑写 Lua 函数，流程编排写脚本段落。脚本的版本管理同样进 git，脚本回滚的需求在每一次大改后都会出现。

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