课时 20 · 服务端接口（上）：人物、物品、消息、定时器

本课目标

• 熟练使用人物、物品与消息接口，掌握定时器。

知识讲解

接口是脚本主动调用的全局函数，第一个参数几乎都是 actor（玩家对象）。本节按人物、物品、消息、定时器四类讲解最常用接口。

人物货币接口

知识讲解

querymoney(actor, id) 查询人物货币，id 为货币 ID（1—100），返回对应货币值。changemoney(actor, id, opt, count, desc, send) 设置人物货币，opt 支持 +、-、= 三种操作符，desc 为描述，send 表示是否推送到客户端（true 时界面即时刷新）。

示例：查询与发放货币

local num = querymoney(actor, 3)
release_print('查询人物货币 3', num)

local ok = changemoney(actor, 3, '+', 100, '测试', false)
release_print('发放货币是否成功', ok)

来源：本地文档 接口\人物相关\查询人物货币.md、设置人物货币.md。

物品接口

知识讲解

物品操作是功能开发最高频的一类接口：checkitems 批量检测背包是否满足物品条件；takeitem 按名称拿（扣除）物品，可指定忽略极品；giveitem 按名称给物品，返回最后一个物品唯一 id（生成失败返回 nil）；DelItem 按物品 table 删除，可控制绑定与背包/身上范围。

示例：检测、扣除与发放物品

-- 检测背包是否满足：金创药(小量) 100 个
local isHave = checkitems(actor, '金创药(小量)#100', 0, 0)
release_print('批量检测背包物品，是否满足', isHave)

-- 按名称扣除 2 个木剑（0=所有都扣除，1=极品不扣除）
local isSuccess = takeitem(actor, '木剑', 2, 0, '测试')
release_print('拿走物品，是否成功', tostring(isSuccess))

-- 发放 1 把木剑
local uid = giveitem(actor, '木剑', 1)
if uid then
    release_print('你获得一把木剑')
else
    release_print('包裹已满')
end

来源：本地文档 接口\物品操作\批量检测背包物品.md、拿物品.md、给物品.md。

示例：按物品表删除

local itemtab = {
    [50014] = 1,    -- 装备
    [2] = 10000,    -- 货币
    [10036] = 3,    -- 堆叠道具
}
local isSuccess = DelItem(actor, itemtab, 1, 2, 'desc')
release_print('删除物品，是否成功', isSuccess)

来源：本地文档 接口\物品操作\删除物品.md。

消息接口

知识讲解

sendmsg(actor, type, msg) 发送聊天框消息：type 是发送范围（1 自己、2 全服、3 行会、4 当前地图、5 组队），msg 必须是 JSON 字符串，不能直接写纯文本，最小写法是 '{"Msg":"内容","Type":1}'。Msg 是消息内容，Type 是显示频道（1 系统频道、2 行会、3 组队、4 顶部跑马灯、5 屏幕跑马灯、9 systemtips，完整表见本地文档 接口\系统\发送聊天框消息.md）；FColor、BColor、Time、SendName、SendId 都可省略。sendcentermsg 发送屏幕中间大字体信息，可指定前景色/背景色、发送范围、显示时间，并支持倒计时回调。

示例：聊天消息与屏幕大字

-- 给自己发聊天框消息
sendmsg(actor, 1, '{"Msg":"你好，勇士！","Type":1}')

-- 全服公告（type=2）
sendmsg(actor, 2, '{"Msg":"服务器将于 30 分钟后维护","Type":2}')

-- 屏幕中间大字体，显示 30 秒
sendcentermsg(actor, 180, 251, '这是一个居中显示的公告.', 0, 30)

来源：本地文档 接口\系统\发送聊天框消息.md、发送屏幕中间大字体信息.md。

定时器接口

知识讲解

个人定时器：setontimer(actor, id, runTick, runTime) 给指定玩家添加定时器，id 为定时器 ID，runTick 为执行间隔，单位是秒（文档示例 setontimer(actor, 1, 5, 1) 就是每 5 秒触发一次，别按毫秒写），runTime 为执行次数，执行完由引擎自动移除。定时器到期后引擎调用全局函数 ontimer{id}(actor)（例如 id=1 时回调 ontimer1）。移除用 setofftimer(actor, id)。

示例：个人定时器

-- 给玩家添加 id=1 的定时器：每 5 秒执行一次，共执行 10 次（第三个参数是秒）
setontimer(actor, 1, 5, 10)

-- 定时器回调函数（函数名 = ontimer + 定时器ID）
function ontimer1(actor)
    release_print('个人定时器触发', actor)
end

-- 移除个人定时器
setofftimer(actor, 1)

来源：本地文档 接口\定时器\添加个人定时器.md、移除个人定时器.md。

全局定时器：setontimerex(id, tick) 添加全局定时器（不绑定玩家），id 为定时器 ID，tick 为执行间隔（秒），回调函数为 ontimerex{id}()。全局定时器适合全区活动调度，如每周活动的开关检查。

示例：全局定时器

setontimerex(23, 5)   -- 每 5 秒触发一次

-- 触发函数为 ontimerex 拼接定时器 id
function ontimerex23()
    release_print('全局定时器 23 触发')
end

来源：本地文档 接口\定时器\添加全局定时器.md。

练习任务

• 实现金币转账命令与定时提示：玩家输入转账命令后，检测余额、扣除转出方货币、给转入方加货币；同时给转出方添加一个 10 秒定时器，到期提示「转账成功」。

参考：核心逻辑

-- 检测并扣除（查询余额 + 设置货币）
local bal = querymoney(actor, 1)
if bal >= 1000 then
    changemoney(actor, 1, '-', 1000, '转账', true)
    changemoney(target, 1, '+', 1000, '收款', true)
    setontimer(actor, 2, 10, 1)   -- 10 秒后提醒一次（第三个参数是秒）
else
    sendmsg(actor, 1, '{"Msg":"余额不足","Type":1}')
end

function ontimer2(actor)
    sendmsg(actor, 1, '{"Msg":"转账成功","Type":1}')
end