Lua接口/服务端调用示例

以下代码放入已有服务端回调中。sceneId、selfId 来自回调；NPC 对话还需要有效 targetId。物品、任务和脚本编号由本服配置提供。

读取角色信息

local name = GetName(sceneId, selfId)
local level = GetLevel(sceneId, selfId)
local hp = GetHp(sceneId, selfId)
local x, z = GetWorldPos(sceneId, selfId)

NPC对话

BeginEvent(sceneId)
AddText(sceneId, "当前等级：" .. GetLevel(sceneId, selfId))
EndEvent(sceneId)
DispatchEventList(sceneId, selfId, targetId)

BeginEvent 开始并清空对话，AddText 添加内容，DispatchEventList 将内容发送给玩家。EndEvent 不会自动显示对话。

查询物品数量

-- itemTypeSn 为当前业务使用的物品配置编号
local count = GetItemCount(sceneId, selfId, itemTypeSn)
if count >= 5 then
    -- 满足数量要求后的处理
end

这里统计已装备与背包物品之和，未验证锁定状态，不能直接等同于可扣除数量。

选择物品接口

用途	接口与条件
统计拥有数量	GetItemCount：包括已装备物品，不过滤锁。
统计可用数量	LuaFnGetAvailableItemCount：仅背包，排除交易锁和密码锁，不限绑定。
查找背包位置	GetBagPosByItemSn：不限制锁；GetItemBagPos：可排除交易锁，但不排除密码锁。
查找可用位置	GetBagPosByItemSnAvailableBind：排除两种锁；第四参 0 不限绑定，1 只找绑定。
按编号扣数量	LuaFnDelAvailableItem：第三参是物品配置编号，第四参是正整数数量。失败可能已部分扣除。
按位置删整格	EraseItem：第三参是背包位置，删除该格全部堆叠；调用前检查物品编号与锁。

查找并读取背包物品

local bagPos = GetBagPosByItemSn(sceneId, selfId, itemTypeSn)
if bagPos >= 0 then
    local count = LuaFnGetItemCountInBagPos(sceneId, selfId, bagPos)
    if count > 0 then
        -- count 仅为这一格的堆叠数量
    end
end

位置 0 是有效格子，失败为 -1，应使用 bagPos >= 0。位置会因物品移动而改变，不能跨回调长期缓存。

扣除可用物品

-- itemTypeSn 是有效物品配置编号
local needCount = 5
if LuaFnGetAvailableItemCount(sceneId, selfId, itemTypeSn) >= needCount then
    local result = LuaFnDelAvailableItem(sceneId, selfId, itemTypeSn, needCount)
    if result == 1 then
        -- 扣除流程报告成功后的业务处理
    else
        -- 停止处理；可能已经部分扣除，不自动重试
    end
end

计数不会预留物品；扣除也不会在数量不足时回滚。这个示例不构成完整兑换事务，扣除与发奖、重复领取保护及异常恢复需要在具体业务中处理并实测。

发放物品

-- itemTypeSn 为已确认有效的物品配置编号
BeginAddItem(sceneId)
AddItem(sceneId, itemTypeSn, 1)
if EndAddItem(sceneId, selfId) == 1 then
    AddItemListToHuman(sceneId, selfId)
end

AddItem 加入待发列表，EndAddItem 只检查能否接收，AddItemListToHuman 执行发放。最后一步无返回值，本示例不提供事务或重复领取保护。

函数名称

local level1 = GetLevel(sceneId, selfId)
local level2 = LuaFnGetLevel(sceneId, selfId)

这两个名称都在注册表中，指向同一接口。其他函数不能据此自行增删 LuaFn 前缀。

以上示例已对照当前接口实现，尚未在游戏内执行。