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

参数按位置传入。变量名相同、都是 number，并不表示含义相同；以具体函数页列出的顺序、类型和编号用途为准。

== 常见参数顺序 ==
{| 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接口/服务端/GetLevel|GetLevel]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, selfId</code>：当前场景编号、该场景内玩家对象 ID。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/AddText|AddText]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, text</code>：第二个参数直接是文字，没有 selfId。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/AddItem|AddItem]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, itemTypeSn, count</code>：物品配置编号、数量；没有 selfId，且只加入待发列表。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/DelItem|DelItem]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, selfId, itemIndex, delCount</code>：此处 itemIndex 是物品配置编号。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/EraseItem|EraseItem]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, selfId, bagIndex</code>：此处 bagIndex 是背包格子位置，删除整格。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/LuaFnGuid2ObjId|LuaFnGuid2ObjId]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, guid</code>：第二项是角色 GUID。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | [[Lua接口/服务端/LuaFnIsPetAvailableByGUID|LuaFnIsPetAvailableByGUID]]
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId, selfId, guidPetHigh, guidPetLow</code>：先玩家对象 ID，再珍兽 GUID 高段、低段。
|}
不要一律给调用补上 sceneId、selfId，也不要凭参数名中的 Index 判断它一定是格子索引。

== 数值、字符串和开关 ==
* number 参数应传数值。<code style="white-space:normal;overflow-wrap:anywhere;">123</code> 和 <code style="white-space:normal;overflow-wrap:anywhere;">"123"</code> 是不同类型，不依赖隐式转换；sceneId、对象 ID、数量等还必须符合该接口要求的整数及范围。
* 按数值读取的开关传 0 或 1，不传 Lua 的 false 或 true。例如 [[Lua接口/服务端/GetItemBagPos|GetItemBagPos]] 的第四参 1 只过滤交易锁；[[Lua接口/服务端/GetBagPosByItemSnAvailableBind|GetBagPosByItemSnAvailableBind]] 的第四参 1 则表示仅找绑定物品，两个 1 的业务含义不同。
* string 参数传字符串。文字要包含在引号中，变量需要先赋值；编码要求与本服脚本和客户端约定一致。
* nil 表示没有值，不能代替一个必填编号。传空字符串也不等于省略参数。
* table、function、userdata 不能直接当物品列表或玩家对象传给这里按 number、string 读取的入口。

== 对话参数示例 ==
<pre style="white-space:pre-wrap;overflow-wrap:anywhere;font-size:13px;line-height:1.7;padding:12px;background:#f5f7f8;border:1px solid #dbe3e6;">if type(sceneId) ~= "number" or type(selfId) ~= "number"
or type(targetId) ~= "number" then
return
end
local message = "任务说明"
BeginEvent(sceneId)
AddText(sceneId, message)
EndEvent()
DispatchEventList(sceneId, selfId, targetId)</pre>
sceneId、selfId、targetId 来自服务端对话回调；targetId 是对话 NPC 的场景对象 ID。type 检查只确认类型，不能证明编号存在或对象类型正确。

== 可选参数不等于任意省略 ==
[[Lua接口/服务端/AddNumText|AddNumText]] 的第四、第五、第六项可省略，默认分别为 -1、-1、无效 ID；前三项仍需按函数页传入。可选位置、默认值及省略方式都应逐项核对，不要自行在中间补上一个玩家 ID。

[[Lua接口/服务端/EndEvent|EndEvent]] 当前不读取参数，既有脚本传入 sceneId 也会忽略；不能据此认为其他函数也允许省略或多传参数。[[Lua接口/服务端/CallScriptFunction|CallScriptFunction]] 把第四项及后续参数转交目标入口，sceneId 同时成为目标入口的第一个实参。

== 调用方式与错误定位 ==
这些注册函数按普通函数调用，不是对象方法。冒号调用会隐式增加一个 self 参数，导致其余位置整体错位。日志中的 <code style="white-space:normal;overflow-wrap:anywhere;">Param 3 is illegal!</code> 指 Lua 调用的第三个位置，不是某个固定业务字段。

当前参数检查会记录不合法位置，但部分入口没有根据检查结果立即停止；出现参数错误日志时应先修正调用，不要把后续的 0、-1 或其他值当成可靠业务结果。

== 相关问题 ==
* [[Lua接口/函数不存在|函数不存在或提示 nil]]
* [[Lua接口/返回值判断|返回值为 0、负数或空字符串]]
* [[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 接口：核对参数、返回值、边界条件与调用示例