Pulse Phone 文档

Pulse Phone 开发者 API

Pulse Phone 为其他资源提供服务端和客户端 API:读取玩家的号码,发送短信、邮件和通知,拨打电话,响应手机上发生的事,以及添加你自己的应用。本页内容全部取自 Pulse Phone 1.5.0 的 phone 资源。包含所有参数的完整列表见导出函数和事件。

适用于 Pulse Phone 1.5.2阅读约 4 分钟更新于

API 在哪里

资源名为 phone,所以每次调用都是 exports.phone:...。使用前先等待手机就绪:数据库响应、手机开始接收请求后,IsReady() 会变为 true。

Lua
CreateThread(function()
    while GetResourceState('phone') ~= 'started' or not exports.phone:IsReady() do Wait(500) end
    print('Pulse Phone is ready')
end)

在服务器控制台运行 phone_api,会打印应用 API 的简要摘要。

最常用的服务端导出函数

导出函数 作用
GetPhoneNumber(src) 玩家持有的手机的号码,加载完成前为 nil
SourceOfNumber(number) 拥有该号码的在线玩家,没有则为 nil
Notify(src, { title, body, app?, actions? }) 发送到该玩家手机的通知,最多 3 个按钮
SendMessage(src, number, text) 该玩家发给某个号码的短信
SendMail(address, sender, subject, body) 发给某个地址的邮件
Call(src, number, video?) 替该玩家拨打电话
SetPhoneDisabled(src, bool) 开关玩家的手机(监狱、过场动画)
RecordTransaction(number, 'sent' or 'received', amount, party, note?) 钱包中的一条账单记录,不会转移资金

为其他手机编写的脚本,调用下面这些,而不是那款手机的导出函数:

导出函数 作用
ResolvePhone(target[, cb]) 按 { source }、{ number }、{ email }、{ identifier } 或 { imei } 查找手机
DeliverMailTo(target, mail[, cb]) 发给该手机的邮件:{ sender, subject, body }
SendText(from, to, body[, opts][, cb]) 来自某部手机或某个命名服务的短信
DispatchAlert(jobs, { title, body, coords? }) 向这些职业的所有在岗成员发送提醒,返回送达的人数

示例:抢劫脚本带着地图标记向警方发出提醒。

Lua
local reached = exports.phone:DispatchAlert({ 'police', 'sheriff' }, {
    title = 'Store robbery',
    body = 'Alarm at the 24/7 on Innocence Blvd.',
    coords = vector3(25.7, -1345.6, 29.5),
})

服务端事件

在服务端脚本中用 AddEventHandler 监听。这些事件只由手机触发,客户端无法伪造。

事件 参数
phone:numberChanged src, number, oldNumber
phone:callStarted callId, fromNumber, toNumber, fromSrc, toSrc, video
phone:callEnded fromNumber, toNumber, reason, durationMs, fromSrc, toSrc, callId
phone:messageSent fromNumber, toNumber, body
phone:emergencyCall src, service, reason, coords
phone:wallet:transfer fromNumber, toNumber, amount, note
phone:notification:action src, app, notificationId, actionId:你的 Notify 提供的按钮被按下

客户端导出函数

导出函数 作用
Open(), Close(), IsOpen() 打开或关闭手机;Open 遵守下面所有的限制
AddOpenCheck(fn) fn() 返回 false 会阻止手机打开;你的资源停止时会被移除
SetRestriction(key, mode) 你自己的玩家状态:'block'、'emergency-only',或用 nil 清除
SetCarAudio(state) 在车机屏幕 Pulse Drive 上显示你的车载音响
GetPhoneNumber(), IsInCall(), GetBattery() 该玩家自己的手机

示例:玩家在你的监狱里时不能用手机。

Lua
exports.phone:SetRestriction('myjail', 'block')   -- on entering the cell
exports.phone:SetRestriction('myjail', nil)       -- on release

State bag

服务端用其他手机资源所用的名称,把这些写入 Player(src).state,所以 HUD 和调度脚本无需修改即可读取:phoneNumber、phoneOpen、inCall、onCallWith、phoneBattery、phoneDead。客户端用 LocalPlayer.state.phoneOpen 读取自己的状态。

config 示例

手机的设置在 phone/config/ 中。其他脚本依赖其中三项:

Lua
Config.Item = {
    required = false,    -- true: the player needs the phone item
    name     = 'phone',
}
Config.Public = {
    numberState = true,  -- publish Player(src).state.phoneNumber
}
Config.Open = {
    blockWhenNuiFocused = true,   -- no phone while another menu holds the cursor
}

你自己的应用

exports.phone:RegisterApp({ id, name, colour, icon, page = { kind = 'frame', url = 'ui/index.html' } }) 会把应用添加到主屏幕和 App Hub。页面在自己的框架中运行,并通过手机与你的服务器通信。权限、通知、语言和 App Hub 上架信息都是可选字段。完整指南见自定义应用。

集成说明

  • Pulse Phone 自己应答 lb-phone、qb-phone 和 NPWD 的事件名,所以用这些方式发送邮件、短信和提醒的脚本继续可用。调用其他手机导出函数的脚本需要改一处:exports.phone。参见切换手机。
  • 从你自己的服务端事件传入真实的 source。永远不要从客户端消息里取玩家 ID。
  • 银行、车库、住房和调度通过手机的桥接对接,在启动时选定。你自己的脚本也可以作为提供方加入:高级集成。

常见问题

Pulse Phone 的资源叫什么名字?

phone。每个导出函数都是 exports.phone:Name(...)。请保持文件夹名不变,因为其他脚本和背包物品钩子都用这个名称调用它。

为 lb-phone 或 qb-phone 编写的脚本能用于 Pulse Phone 吗?

使用那些手机的事件(邮件、短信、通知、手机号码)的脚本无需修改即可运行。调用它们导出函数的脚本需要改用 exports.phone。

我可以给 Pulse Phone 添加自己的应用吗?

可以。在你的资源里用 RegisterApp 注册即可。它会出现在 App Hub 中,指南涵盖页面、权限和通知。

译自英文。如有任何内容与英文页面不一致,以英文页面为准。 English