适用版本: 0.85.0600
函数编写:雪舞
📜 函数功能概述
LuaFnTryRecieveMultiItem 是一个用于在游戏服务器端批量创建物品并添加到玩家背包的Lua函数封装。它提供了完整的物品创建、验证、日志记录和背包管理功能,特别适合实现任务奖励、商城购买等批量物品发放场景。
🎯 核心功能亮点
- 批量物品创建 - 支持单次创建最多255个物品
- 绑定状态控制 - 可指定物品是否为绑定状态
- 完整验证机制 - 玩家状态、物品参数多重验证
- 日志追踪系统 - 详细记录物品创建来源和位置
- 智能背包管理 - 自动处理背包空间不足等情况
📝 参数详细说明
基础参数
参数位置 |
参数类型 |
参数说明 |
示例值 |
1 |
SceneID_t |
场景ID |
1001 |
2 |
ObjID_t |
玩家ID |
15001 |
3 |
INT |
物品ID |
20101001 |
4 |
BYTE |
物品品质 |
3 |
5 |
UINT |
物品数量 |
10 |
6 |
BOOL |
绑定状态(0:非绑,1:绑定) |
1 |
特殊参数说明
-
物品品质(byQuality):
-
绑定状态(bBind):
- 0 = 非绑定(可交易)
- 1 = 绑定(不可交易)
- -1 = 使用物品默认绑定状态
🚀 调用示例代码
基础用法:发放10个绑定物品
-- 发放10个ID为20101001的绑定物品(品质3)
local success = LuaFnTryRecieveMultiItem(sceneId,selfId, 20101001, 3, 10, 1)
if success == 1 then
SystemMsg("成功获得10个绑定宝物!")
else
SystemMsg("物品发放失败,请检查背包空间!")
end
进阶用法:动态品质物品发放
-- 根据玩家VIP等级决定物品品质
function GrantVipReward(playerId, vipLevel)
local quality = 1
if vipLevel >= 3 then quality = 3 end
if vipLevel >= 5 then quality = 5 end
return LuaFnTryRecieveMultiItem(
sceneId
selfId,
VIP_REWARD_ITEM_ID,
quality,
1,
1 -- 绑定状态
)
end
⚠️ 使用注意事项
-
参数验证规则
-
日志系统说明
物品发放会自动记录详细日志:
- 操作类型:
ITEM_CREATE_FROM_ABILITY_SCRIPT
- 时间戳:自动记录操作时间
-
错误处理机制
错误类型 |
错误代码 |
解决方案 |
参数错误 |
RETURNFALSE |
检查Lua参数数量和类型 |
无效物品 |
日志记录 |
验证物品ID是否存在 |
玩家状态异常 |
日志记录 |
检查玩家是否死亡/离线 |
背包已满 |
返回0 |
提示玩家清理背包空间 |
关键处理阶段
- 参数序列化:将Lua参数转换为C++数据结构
- 物品转换:使用
TSerialHelper 将物品ID转换为游戏可识别的序列化格式
- 背包管理:调用
HumanItemLogic::CreateMultiItemToBag_Bind 进行背包操作
- 日志记录:详细记录物品来源、位置等审计信息
🛠️ 最佳实践指南
场景推荐
- 任务系统奖励发放
- 活动奖励批量发放
- 商城购买物品到账
- 邮件附件领取
- 成就系统奖励发放
避坑指南
- 错误做法: 循环调用单物品发放函数
+ 正确做法: 使用本函数批量发放
- 错误做法: 在玩家离线时尝试发放
+ 正确做法: 仅在玩家在线状态发放
- 错误做法: 忽略返回值处理
+ 正确做法: 根据返回值提示玩家结果
- 错误做法: 每次发放超过255个物品
+ 正确做法: 大数量分批发放
|