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

2026-09-07T11:53:15Z

维护服务端 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接口/服务端调用约定|调用约定]]

先查函数的返回约定，再判断值。0、负数、空字符串、nil 不能用同一条成功规则处理。

== 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;" | 在 if 中
! scope="col" style="text-align:left;background:#edf3f2;padding:8px;" | 注意事项
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">nil</code>
| 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;" | <code style="white-space:normal;overflow-wrap:anywhere;">false</code>
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 假
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | Lua 布尔值；不等同于数值 0。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">0</code>
| 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;" | <code style="white-space:normal;overflow-wrap:anywhere;">-1</code> 等负数
| 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;" | <code style="white-space:normal;overflow-wrap:anywhere;">""</code>
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 真
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 空字符串也会进入 if result then 分支。
|}
只有 nil 和 false 为假。<code style="white-space:normal;overflow-wrap:anywhere;">if result then</code> 不能用来判断返回数字的接口是否成功；<code style="white-space:normal;overflow-wrap:anywhere;">result == true</code> 也不会把数字 1 当作 true。

== 按接口区分 ==
{| 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;" | 应如何理解
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/EndAddItem|EndAddItem]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 1 表示当前可接收列表，0 表示不能接收，-1 表示疲劳限制或对象无效等失败。检查通过后仍需发放。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/GetItemCount|GetItemCount]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 0 表示计数为零，不是函数不存在；-1 是对象无效等失败路径。计数范围包括已装备物品。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/GetBagPosByItemSn|GetBagPosByItemSn]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 0 是有效背包位置，-1 表示未找到或失败，判断位置用 >= 0。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/GetName|GetName]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 返回字符串，失败可返回空字符串。先确认类型，再检查是否为空。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/LuaFnIsItemLocked|LuaFnIsItemLocked]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 1 是交易锁，0 是未发现交易锁，-2 是位置越界，-1 是玩家无效等失败。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/LuaFnDelAvailableItem|LuaFnDelAvailableItem]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 正数量扣除流程报告成功为 1，失败为 0；非正数量直接返回 1 但不扣除，失败也可能已部分扣除。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/AddText|AddText]]、[[Lua接口/服务端/EndEvent|EndEvent]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 无返回值；赋值接收得到 nil，不表示函数不存在。
|}

== 计数与字符串示例 ==
<pre style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:13px;line-height:1.7;padding:12px;background:#f5f7f8;border:1px solid #dbe3e6;">local count = GetItemCount(sceneId, selfId, itemTypeSn)
if type(count) == "number" and count >= 0 then
-- count 为有效计数；0 表示没有计入的物品
else
-- 本次查询未取得有效计数
end

local name = GetName(sceneId, selfId)
if type(name) == "string" and name ~= "" then
-- name 为非空名称
end</pre>
itemTypeSn 必须来自已确认有效的物品配置。不能只写 name ~= ""：nil 也不等于空字符串，类型检查可以避免误判。

== 多个返回值按位置接收 ==
<pre style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:13px;line-height:1.7;padding:12px;background:#f5f7f8;border:1px solid #dbe3e6;">local x, z = GetWorldPos(sceneId, selfId)
if type(x) == "number" and type(z) == "number"
and x ~= -1 and z ~= -1 then
-- x、z 是场景平面坐标
end

local petGuidHigh, petGuidLow = LuaFnGetCurrentPetGUID(sceneId, selfId)
if type(petGuidHigh) == "number" and type(petGuidLow) == "number" then
-- 取得当前召唤珍兽的 GUID 高段、低段
else
-- 无召唤珍兽或未取得结果
end</pre>
[[Lua接口/服务端/GetWorldPos|GetWorldPos]] 失败返回 -1、-1；[[Lua接口/服务端/LuaFnGetCurrentPetGUID|LuaFnGetCurrentPetGUID]] 在没有召唤珍兽等路径不返回值，此时两个变量都是 nil。少接收变量会丢掉后面的结果；给函数调用外面加一对括号，也可能把多返回值收缩成第一项。

== 返回成功不等于整段业务完成 ==
[[Lua接口/服务端/EndAddItem|EndAddItem]] 只检查能否接收，[[Lua接口/服务端/AddItemListToHuman|AddItemListToHuman]] 才执行发放且无返回值。扣除、发放、保存领取记录是不同步骤，不能只看其中一次返回 1 就推断整段业务成功。

未注明的枚举、异常后的背包变化和完整业务结果需要实测。失败后自动重试可能造成重复扣除，先核对具体接口的副作用，见 [[Lua接口/服务端调用示例#扣除可用物品|扣除可用物品示例]]。

== 相关问题 ==
* [[Lua接口/函数不存在|函数不存在或提示 nil]]
* [[Lua接口/参数类型与顺序|参数类型与传入顺序]]
* [[Lua接口/对象ID与GUID|对象 ID 与 GUID 的区别]]
* [[Lua接口/服务端与客户端调用范围|服务端与客户端的调用范围]]

[[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 接口：核对参数、返回值、边界条件与调用示例