雪舞：维护服务端 Lua 接口：核对参数、返回值、边界条件与调用示例

2026-09-07T11:53:16Z

维护服务端 Lua 接口：核对参数、返回值、边界条件与调用示例

新页面

__NOTOC__
<div class="lua-reference" style="max-width:1200px;margin:0 auto;line-height:1.8;color:#29343a;font-family:Arial,'Microsoft YaHei',sans-serif;letter-spacing:0;overflow-wrap:anywhere;">
[[首页|首页]] · [[Lua接口/服务端函数索引|服务端接口]] · [[Lua接口/服务端调用约定|调用约定]]

函数在哪一端注册，就在相应的脚本运行环境中调用。服务端、客户端和独立 Lua 解释器不共享同一张函数表。

== 三类调用环境 ==
{| class="wikitable" style="width:100%;table-layout:fixed;border-collapse:collapse;font-size:13px;"
! scope="col" style="text-align:left;background:#edf3f2;padding:8px;" | 环境
! scope="col" style="text-align:left;background:#edf3f2;padding:8px;" | 通常处理的工作
! scope="col" style="text-align:left;background:#edf3f2;padding:8px;" | 本知识库的适用范围
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 服务端游戏脚本
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | NPC 对话、任务、玩家属性、背包、场景等游戏逻辑。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 服务端函数索引覆盖当前 GameServer 注册名称；还要满足对应场景、玩家或怪物等对象条件。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 客户端界面脚本
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 窗口、界面事件、显示及已实现的客户端请求。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 客户端有独立注册入口与参数约定；不能直接照搬服务端函数的名称、参数或返回值。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 独立 Lua 环境
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 语法检查及不依赖游戏的 Lua 代码。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 不会自动拥有游戏引擎注册函数。语法通过不代表游戏内可调用或有效。
|}
同名函数也可能来自不同端或脚本封装。看到某个名称可调用，只能说明当前作用域有这个函数，不能单凭名称判断它的来源或业务能力。

== 服务端示例的前提 ==
<pre style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:13px;line-height:1.7;padding:12px;background:#f5f7f8;border:1px solid #dbe3e6;">-- 放在已有的服务端玩家回调中
-- sceneId、selfId 由该回调提供
if type(GetLevel) ~= "function" then
return
end
if type(sceneId) ~= "number" or type(selfId) ~= "number" then
return
end
local level = GetLevel(sceneId, selfId)
if type(level) == "number" and level >= 0 then
-- 处理当前玩家等级
end</pre>
上面的检查不能创建场景或玩家对象。在客户端文件中声明两个同名变量，或复制这个函数调用，不会得到有效的服务端上下文。

== 显示在客户端不等于由客户端调用 ==
[[Lua接口/服务端/BeginEvent|BeginEvent]]、[[Lua接口/服务端/AddText|AddText]]、[[Lua接口/服务端/DispatchEventList|DispatchEventList]] 由服务端脚本调用，对话最终显示在客户端；[[Lua接口/服务端/AddItemListToHuman|AddItemListToHuman]] 也是服务端发放物品。判断运行端应看脚本入口和注册位置，不应只看最终效果出现在哪里。

== 两端配合的边界 ==
客户端操作需要通过项目已经实现的请求、事件或协议到达服务端，再由服务端在合法上下文中调用游戏接口。服务器需重新核对当前玩家、物品、数量及业务条件；客户端显示的数据不等于服务端已确认的结果。

[[Lua接口/服务端/CallScriptFunction|CallScriptFunction]] 用于服务端脚本入口之间的调用，不能执行客户端界面函数，也不是把任意 Lua 函数名发给另一端运行的通用通道。具体客户端入口、协议字段及调用链须按现有实现核对，未核对的部分需要实测。

== 排查调用范围 ==
# 确认执行文件由哪个进程加载：服务端任务或场景脚本、客户端 UI 资源，还是独立解释器。
# 在对应端核对完整注册名称和参数；服务端索引中存在不等于客户端也存在，客户端存在也不等于服务端已注册。
# 确认当前回调真正提供的场景编号、对象 ID 或界面对象，不从另一端直接挪用同名变量。
# 函数为 nil 时转到 [[Lua接口/函数不存在|函数不存在或提示 nil]]；函数存在但结果异常时核对 [[Lua接口/参数类型与顺序|参数]] 和 [[Lua接口/返回值判断|返回值]]。
# 独立 Lua 工具可以检查语法。模拟返回值只能测试脚本分支，无法验证真实场景查找、物品扣除、网络消息或持久化效果；这些仍需要实测。

客户端接口尚未在这批服务端索引中逐项整理。本页说明调用边界，不把未核对的客户端函数名列为可用接口。

== 相关问题 ==
* [[Lua接口/函数不存在|函数不存在或提示 nil]]
* [[Lua接口/参数类型与顺序|参数类型与传入顺序]]
* [[Lua接口/返回值判断|返回值为 0、负数或空字符串]]
* [[Lua接口/对象ID与GUID|对象 ID 与 GUID 的区别]]

[[Lua接口/服务端调用约定|服务端调用约定]] · [[Lua接口/服务端调用示例|服务端调用示例]]

<div style="margin-top:20px;padding-top:10px;border-top:1px solid #dbe3e6;color:#657078;font-size:12px;">示例依据当前服务端注册名称和参数读取顺序核对；sceneId、selfId 等上下文及业务编号由实际回调提供。Lua 语法检查不能代替游戏内实测。</div>

</div>

Lua接口/服务端与客户端调用范围 - 版本历史

雪舞：​维护服务端 Lua 接口：核对参数、返回值、边界条件与调用示例

雪舞：维护服务端 Lua 接口：核对参数、返回值、边界条件与调用示例