QF 触发函数收到的 actor 是字符串（玩家名字），大量学员拿到就直接当对象用：调接口、拼字段、存进表里当键再去点属性，轻则接口静默无效，重则脚本报错中断，整段攻城战报逻辑停摆。典型错误写法：
local function onGuildWar(actor)
giveitem(actor, "裁决之杖", 1)
end
传进去的是字符串名字，后续一切对象级操作全部落空。
先判断类型，是字符串就用 getplayerbyname 转成玩家对象，再交给接口使用。下面是沙巴克战报的正确写法：拿下沙巴克时向全服发屏幕公告并记录功臣。示例代码如下：
local function onSabukWin(actor, guildName)
if type(actor) == "string" then
actor = getplayerbyname(actor)
end
giveitem(actor, "裁决之杖", 1)
sendcentermsg(actor, 255, 215, "【" .. guildName .. "】攻占沙巴克！功臣：" .. tostring(actor), 0, 10)
setsysvarex("SabukOwner", guildName, 1)
end
getplayerbyname 是引擎真名接口：入参玩家名字符串，返回玩家对象。转一次，处处可用。
三步验证：一，把脚本放进 QF 触发目录，M2 控制台执行重载脚本命令；二，用测试小号触发对应事件（这里可用 triggerchat 聊天触发临时改绑），观察控制台是否打印出对象而非字符串；三，故意删掉转换行再触发一次，复现报错，记住报错行号——以后线上见到同款报错，三秒内定位到没转对象。
离线玩家拿不到对象怎么办？getplayerbyname 只对在线玩家有效，按唯一 ID 找人要用 getplayerbyid，配合 sendmail 可以给离线玩家发奖励——邮件接口收 "#名字" 格式，离线也照发不误。示例代码如下：
local function rewardById(makeindex, name)
local target = getplayerbyid(makeindex)
if target ~= nil and target ~= "" then
giveitem(target, "金条", 2)
else
sendmail("#" .. name, 9001, "沙巴克军饷",
"攻城奖励已随邮件补发。", "金条#2#1")
end
end
全站技术干货持续更新：996 引擎 / Lua 实战帖，语法、参数与示例一篇讲透。进入文章地图 · 查看全部 →
学员常见误区 Lua函数可返回多个值，学员用固定变量数接收时如果变量少于返回值，多余返回值被静默丢弃；如果变量多于返回值，多…
设计初衷 行会建筑的死穴是一次全解锁：会员没有逐步建设的过程感。梯度设计让每栋建筑都有前置条件和资源门槛。 数值模型 建筑分…
设计初衷 婚姻系统的属性加成是社交玩法的经济锚点：加成太弱没人结婚，太强则"为了属性被迫结婚"扭曲了社交本质。婚姻边界的设计…
设计初衷 宝箱类玩法的信任危机都源于同一句话："概率是不是骗人的。"期望公示把概率从事后争议变成事前契约：奖池概率表全量公示…
设计初衷 流拍物（拍卖未成交的退回物品）堆积在卖家背包里成为死资产：低价值物流拍后无人问津，高价值物流拍后卖家不愿降价重拍。…
业务场景 沙巴克战功榜每周结算，玩家提交战功前不知道"再打多少能进前 10、前 10 的奖励是什么"。名次预览：输入自己的战…