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

对象 ID 用于定位当前场景内的运行对象；GUID 用于标识具体角色或珍兽。两者都可能以 number 传给 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;" | <code style="white-space:normal;overflow-wrap:anywhere;">sceneId</code>
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 场景编号，不是玩家标识。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 与场景对象 ID 配合，指明在哪个场景调用。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | <code style="white-space:normal;overflow-wrap:anywhere;">selfId / targetId / objId</code>
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 运行中的场景对象 ID。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | GetLevel 的玩家对象、DispatchEventList 的玩家与 NPC 对象。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 角色 GUID
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 具体玩家角色的标识。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | GetHumanGUID 返回；LuaFnGuid2ObjId 接收。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 珍兽 GUID 高段、低段
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 共同标识一只珍兽，两项有固定顺序。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | LuaFnGetCurrentPetGUID 返回；LuaFnIsPetAvailableByGUID 接收。
|-
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 物品配置编号
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | 物品类型，不是某个背包格或某一件物品的 GUID。
| style="padding:8px;vertical-align:top;overflow-wrap:anywhere;" | GetItemCount、DelItem 的物品参数。
|-
| 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;" | EraseItem、GetItemTableIndexByIndex 的位置参数。
|}
参数叫 selfId 不保证一定是玩家；怪物或珍兽接口可能要求其他对象类型。先看该函数的对象要求，再使用回调传入的标识。

== 角色对象 ID 与 GUID 转换 ==
<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 guid = GetHumanGUID(sceneId, selfId)
if type(guid) ~= "number" or guid == -1 then
return
end

local objId = LuaFnGuid2ObjId(sceneId, guid)
if type(objId) == "number" and objId >= 0 then
local level = GetLevel(sceneId, objId)
if type(level) == "number" and level >= 0 then
-- 成功读取该场景玩家的等级
end
end</pre>
[[Lua接口/服务端/GetHumanGUID|GetHumanGUID]] 接收有效玩家的场景对象 ID，返回角色 GUID；对象无效等失败路径为 -1。[[Lua接口/服务端/LuaFnGuid2ObjId|LuaFnGuid2ObjId]] 只有找到的对象是玩家且仍在传入场景时才返回对象 ID，否则为 -1。它不是跨场景寻人或传送接口，也不用于转换珍兽 GUID。

不能把 guid 直接传给 GetLevel 的第二项。即使碰巧与某个对象 ID 数值相同，也不能证明两者是同一个对象。[[Lua接口/服务端/LuaFnGetGUID|LuaFnGetGUID]] 和 [[Lua接口/服务端/LuaFnObjId2Guid|LuaFnObjId2Guid]] 同样要求传入玩家对象 ID，不能只凭函数名认为支持任何对象。

== 珍兽 GUID 按高段、低段传递 ==
<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 petGuidHigh, petGuidLow = LuaFnGetCurrentPetGUID(sceneId, selfId)
if type(petGuidHigh) == "number" and type(petGuidLow) == "number" then
local available = LuaFnIsPetAvailableByGUID(
sceneId, selfId, petGuidHigh, petGuidLow)
if available == 1 then
-- 当前召唤珍兽通过交易锁和密码锁检查
end
end</pre>
高段在第三位、低段在第四位，第二项仍是拥有者的玩家对象 ID。没有召唤珍兽等路径没有两个返回值，先检查结果再传参；不要只接第一项，也不要调换顺序。

两段一起构成珍兽标识，单独一段为 0 不足以判定无效。保持原有分段传递，避免自行拼成一个大整数或字符串后再传给数值参数；其他 GUID 类型的布局必须按对应接口核对。

== 场景变化后重新取得对象 ==
对象 ID 不能当成跨下线、跨场景的持久标识，背包位置也不能跨整理或移动长期缓存。延时回调前后，玩家可能已经离开场景；需要在业务允许的上下文中重新定位并验证对象。GUID 并不保证角色当前在线或处于指定场景，跨场景业务的具体入口和效果需要实测。

== 相关问题 ==
* [[Lua接口/函数不存在|函数不存在或提示 nil]]
* [[Lua接口/参数类型与顺序|参数类型与传入顺序]]
* [[Lua接口/返回值判断|返回值为 0、负数或空字符串]]
* [[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接口/对象ID与GUID - 版本历史

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

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