Lua接口/对象ID与GUID

首页 · 服务端接口 · 调用约定

对象 ID 用于定位当前场景内的运行对象；GUID 用于标识具体角色或珍兽。两者都可能以 number 传给 Lua，但不能互换。

常见标识对照

标识	代表什么	常见使用位置
sceneId	场景编号，不是玩家标识。	与场景对象 ID 配合，指明在哪个场景调用。
selfId / targetId / objId	运行中的场景对象 ID。	GetLevel 的玩家对象、DispatchEventList 的玩家与 NPC 对象。
角色 GUID	具体玩家角色的标识。	GetHumanGUID 返回；LuaFnGuid2ObjId 接收。
珍兽 GUID 高段、低段	共同标识一只珍兽，两项有固定顺序。	LuaFnGetCurrentPetGUID 返回；LuaFnIsPetAvailableByGUID 接收。
物品配置编号	物品类型，不是某个背包格或某一件物品的 GUID。	GetItemCount、DelItem 的物品参数。
背包格子位置	物品当前存放的格子，不是永久标识。	EraseItem、GetItemTableIndexByIndex 的位置参数。

参数叫 selfId 不保证一定是玩家；怪物或珍兽接口可能要求其他对象类型。先看该函数的对象要求，再使用回调传入的标识。

角色对象 ID 与 GUID 转换

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

GetHumanGUID 接收有效玩家的场景对象 ID，返回角色 GUID；对象无效等失败路径为 -1。LuaFnGuid2ObjId 只有找到的对象是玩家且仍在传入场景时才返回对象 ID，否则为 -1。它不是跨场景寻人或传送接口，也不用于转换珍兽 GUID。

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

珍兽 GUID 按高段、低段传递

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

高段在第三位、低段在第四位，第二项仍是拥有者的玩家对象 ID。没有召唤珍兽等路径没有两个返回值，先检查结果再传参；不要只接第一项，也不要调换顺序。

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

场景变化后重新取得对象

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

相关问题

• 函数不存在或提示 nil
• 参数类型与传入顺序
• 返回值为 0、负数或空字符串
• 服务端与客户端的调用范围

服务端调用约定 · 服务端调用示例

示例依据当前服务端注册名称和参数读取顺序核对；sceneId、selfId 等上下文及业务编号由实际回调提供。Lua 语法检查不能代替游戏内实测。