Pulse Phone docs
Pulse Phone: exports, events and state bags
This is the whole surface other resources can use. The phone resource is named phone.
phone_api in the server console prints the add-on (app) API as a short summary.
To add your own app to the phone, see Custom Apps next to this file.
1. State bags
The server writes these to Player(src).state. They are replicated, so clients read them as
LocalPlayer.state.<key>, or Player(serverId).state.<key> for other players. The names match
the ones other popular phone resources use, so existing HUD, dispatch and evidence scripts read
them unchanged.
| Key | Type | Meaning | Set from |
|---|---|---|---|
phoneNumber |
string | false | number of the phone in hand (turn off with Config.Public.numberState = false) |
device load, provisioning, unique-phone switch |
phoneOpen |
boolean | phone out, screen shown | client open/close, throttled flag event |
phoneDisabled |
boolean | disabled by SetPhoneDisabled |
server export |
flashlight |
boolean | torch on | client torch toggle |
airplaneMode |
boolean | airplane mode | client toggle |
inCall |
boolean | has a live call: dialling, ringing out or connected | server call records |
callAnswered |
boolean | the call is connected | server |
onCallWith |
number | false | server id of the other party (player-to-player) | server |
speakerphone |
boolean | speaker on during a call | server (phone:call:speaker) |
mutedCall |
boolean | this player muted their microphone on the call | server (phone:call:signal) |
otherMutedCall |
boolean | the other party muted | server |
phoneItem |
boolean | carries a phone item (Config.Item.required or unique phones) |
server inventory check |
phoneBlocked |
boolean | the player's state blocks the phone (dead, cuffed, escorted ... Config.Block) |
client state check, verified by the server |
phoneEmergencyOnly |
boolean | the phone opens on the emergency screen only (for example downed, Config.Block) |
client state check, verified by the server |
phoneColour |
string | false | unique phones only: finish id of the phone in hand | item metadata / Config.Item.variants |
phoneBattery |
number | battery percent (0-100); other players' copies may lag (see below) | server battery loop |
phoneCharging |
boolean | charging now | server |
phoneDead |
boolean | battery empty: apps refused, calls ring out | server |
phone:anim, phone:anim:prop |
internal | animation mirroring for other clients | anim controller |
Limits:
- An incoming call sets
inCallon the callee only once it is answered. - The three client flags (
phoneOpen,flashlight,airplaneMode) are only accepted as booleans, through one rate-limited event. No other key can be set from a client. phoneBatteryis throttled for everyone except the phone's owner: it is written at once when charging starts or stops, when the phone dies, at 0, 20 and 100 %, and at every step below 20 %; otherwise it can lag up to 30 s. The owner'sexports.phone:GetBattery()(client) and the server'sGetBattery(src)are always exact.
2. Server events
Listen with AddEventHandler(name, fn) in a server script. Only the phone raises these. They
are not net events, so a client cannot forge them.
| Event | Arguments |
|---|---|
phone:numberChanged |
src, number \| nil, oldNumber \| nil |
phone:toggled |
src, open |
phone:callStarted |
callId, fromNumber, toNumber, fromSrc, toSrc (nil: not known yet), video |
phone:callAnswered |
fromNumber, toNumber, fromSrc, toSrc, callId |
phone:callEnded |
fromNumber, toNumber, reason, durationMs, fromSrc, toSrc, callId |
phone:emergencyCall |
src, service ('police' \| 'ems' \| 'fire' \| ...), reason \| nil, coords (vector3) \| nil (Smart 911) |
phone:emergencyText |
src, service, reason \| nil, body (Smart 911 emergency text) |
phone:messageSent |
fromNumber, toNumber, body |
phone:groupMessageSent |
fromNumber, groupId, body |
phone:mailSent |
fromAddress, toAddress, subject |
phone:wallet:transfer |
fromNumber, toNumber, amount, note |
phone:photoSaved |
ownerNumber, url, kind ('photo' \| 'portrait' \| 'video') |
phone:socialPost |
authorNumber, app, postId, caption, url |
phone:mediaStored |
url, kind: a file the phone's upload stored |
phone:mediaRefused |
src \| nil, url, where: a link the allow-list refused |
phone:calendar:saved |
ownerNumber, event |
phone:battery:died |
src |
phone:notification:action |
src, app, notificationId, actionId: the player pressed a button your Notify offered (once per notification, within 30 minutes) |
3. Client events
Listen with AddEventHandler in a client script. These are local and cannot be sent from the network.
| Event | Arguments |
|---|---|
phone:toggled |
open, reason? |
phone:openRefused |
reason: 'disabled', 'nui-focused' or 'check:<resource>' |
phone:numberChanged |
number \| nil |
phone:drive:carAudio |
resource, action, data: a button on Pulse Drive for the car stereo resource reported with SetCarAudio. action: 'play', 'pause', 'next', 'previous' or 'volume' (data.value, 0 to 1). Check resource == GetCurrentResourceName() and run your stereo's own controls; Pulse sends nothing while the state says canControl = false |
4. Server exports (exports.phone:…)
| Export | Returns | Notes |
|---|---|---|
IsReady() |
boolean | true once the phone takes requests: the database connection proved and the schema built, or the file store in use. A script that starts next to the phone waits on this instead of a guessed delay; false again while the database is down |
GetPhoneNumber(src) |
number | nil | from cache; nil until the player has loaded |
SourceOfNumber(number) |
src | nil | online players only |
FormatNumber(number) |
string | in Config.Numbers.format |
GetEmail(src) |
address | nil | |
GetEmailOfNumber(number, cb) |
cb(address \| nil) |
works for offline players too |
HasPhoneItem(src, number?) |
boolean | always true when Config.Item.required is off; with unique phones number asks for that phone |
Notify(src, { app?, title, body, sound?, actions?, deepLink?, thread? }) |
boolean | actions: up to 3 { id, title, destructive?, deepLink? }; a press raises phone:notification:action. sound: a tone name, or false for silent |
SetBadge(src, appId, count) |
boolean | registered add-ons only |
SendMessage(src, number, text) |
none | as that player |
SendMail(address, sender, subject, body) |
none | |
AddContact(ownerNumber, { name, number, avatar? }) |
boolean | owner must be online |
Call(src, number, video?) |
none | places a call |
IsInCall(src) |
boolean, callId | |
EndCall(src) |
boolean | |
SetPhoneDisabled(src, bool) / IsPhoneDisabled(src) |
boolean | closes the phone if it is open |
RecordTransaction(number, 'sent' \| 'received', amount, party, note?) |
boolean | statement line only; does not move money |
GetWalletBalance(number, cb) |
cb(balance \| nil) |
|
UploadMedia(dataUrl, kind, cb) |
cb(url, reason) |
through the configured provider |
IsMediaAllowed(url) |
boolean | the server allow-list (Config.Media.allow) |
Log(action, title, fields, src?) |
none | writes to the phone's Discord/Fivemanage log |
GetBattery(src) / SetBattery(src, percent) |
number | server-authoritative level |
IsCharging(src) / IsPhoneDead(src) |
boolean | |
ToggleCharging(src, on?, ratePerMin?) |
boolean | an external charger (a cable item, a station script) |
UsePowerbank(src) |
boolean | single-use (reusable = false, the default): removes one Config.Battery.powerbank.item and charges amount % over time; reusable bank (reusable = true): plugs the phone in or out, charging to 100% |
SaveBattery(src) / SaveAllBatteries() |
none | levels also save every minute and on leave |
RegisterApp / UnregisterApp / EmitApp / BroadcastApp / GetApps / Set / Get |
add-on apps (phone_api, CUSTOM_APPS.md): SDK v3 declarations add names and icons per language and OS, job grades, item gating, the web / media capabilities the owner reviews (Config.AppStore.capabilities), defaultInstalled and a dev-server devUrl (used only with set pulse_dev_apps true). An app id belongs to the resource that registered it while that resource runs. GetApps(src) is the list this player is offered |
|
HasAppPermission(src, appId, perm) / GetAppContacts / GetAppPhotos / GetAppLocation(src, appId, cb) / GetAppRating(appId, cb) |
true / false / nil; cb(data, reason) | creator apps (SDK v2): what the player allowed an app, the data it opens, the App Hub rating (CUSTOM_APPS.md sections 3 and 5) |
RegisterProvider / UnregisterProvider / GetProvider / HasCapability / BridgeReport / GetCharacterId |
providers (custom_provider_template.lua in this folder) |
|
RegisterFrameworkBridge, RegisterSite, RegisterMarketsEconomy, AddDirectoryEntry |
server exports, documented in the sections below | |
PhoneTaken / PhoneReturned / PhoneLocked / PhoneBypass / PhoneCustody / PhoneImei |
stolen phones | |
DropPhone / DroppedPhones, PairAccessory / UnpairAccessory / SetAccessoryBattery / RegisterAccessoryKind, IsBlocked, MarketsQuotes / MarketsShock |
as named | |
ClearNotifications(src, app?) |
boolean | empties the notification list on that player's phone (all, or one app id) |
StartActivity(src, def) |
id | false, reason |
an Island activity on the Island and Lock Screen (section 14) |
UpdateActivity(src, id, patch) / EndActivity(src, id) / EndAllActivities(src?) |
boolean / count | your own resource's activities only (section 14) |
PlaceScriptCall(target, opts) |
callId | false, reason |
ring a player from a script identity: "Unknown", "Dispatch" (section 15) |
EndScriptCall(callId) / GetScriptCallState(callId) |
boolean / 'ringing' | 'connected' | nil |
your own script calls only (section 15) |
PlayerCall(src, number, video?, cb?) |
boolean | the player places the call themselves, through every check the dialler makes (their own phone, Config.Block, the app being allowed, battery, carrier, rate limits). false only for a missing or over-long number. cb(result): the call's answer, or { ok = false, reason } when refused |
PlayerSaveContact(src, { name?, number, avatar?, firstname?, lastname? }, cb?) |
boolean | the player saves a contact into their own phone, checked as the Contacts app's save is. name falls back to firstname lastname, then to the number. false for a missing table or number. cb(contact) once saved, cb(nil) when the number is not valid, or cb({ ok = false, reason }) when refused |
UnregisterSite(id) |
boolean | removes a Browser site added with RegisterSite (section 9). Sites are removed by themselves when the resource that registered them stops |
MapsAddPin(id, { label, x, y, category?, description?, colour? }) |
boolean | a public Maps pin while the server runs (a business opening, an event venue). id: letters, digits and _, up to 32. coords = { x, y } works in place of x, y. category: hospital, police, garage, store, airport, bank, dealership, clothing, food, gas, job or other (the default). colour: '#RRGGBB'. Adding an id again replaces that pin; an id Config.Maps.locations already uses is refused, as is a 501st pin. Phones see the change within a few seconds |
MapsRemovePin(id) |
boolean | removes a pin added with MapsAddPin; false when there is none |
MapsReportIncident(kind, x, y) |
id | nil | a Maps report from your script (a crash your dispatch knows about). kind: a type in Config.Maps.incidents.types (crash, police, roadworks, hazard by default). A report of the same kind within mergeRadius keeps that one up instead and returns its id. nil when reports are off, the kind is unknown, the position is not usable or max reports are up |
5. Client exports (exports.phone:…)
| Export | Notes |
|---|---|
Open() / Close() / IsOpen() |
Open respects every veto below |
AddOpenCheck(fn) → id / RemoveOpenCheck(id) |
fn() returning false refuses the open. Checks are removed when their resource stops |
SetDisabled(bool) / ToggleDisabled() / IsDisabled() |
a local switch; the server's SetPhoneDisabled drives the same one |
GetPhoneNumber() |
from the state bag |
FormatNumber(number) |
|
IsInCall() |
|
Notify({ app?, title, body, icon?, colour?, sticky? }) |
shown by this player's phone only |
SetFlashlight(bool) / GetFlashlight() / GetAirplaneMode() |
|
GetSignalBars() / SetAirplaneMode(bool) |
|
RegisterCaptureProvider(p) / CaptureAvailable() |
camera capture backends: { name, Available, Take, Video = { Start(opts, cb), Stop(cb), Available?, Modes? } }. The Camera's Slo-mo and Time-lapse tabs appear only when Video.Modes lists them ({ 'SLO-MO', 'TIME-LAPSE' }, or Video.Supports(mode) answers true); Start then gets opts.mode and must record at that speed |
Rpc(name, data) |
the phone's own request channel; internal |
useItem(data, slot) |
ox_inventory item hook for unique phones (client = { export = 'phone.useItem' }) |
usePowerbank() |
ox_inventory item hook for the power bank (client = { export = 'phone.usePowerbank' }) |
GetBattery() / IsCharging() / IsPhoneDead() |
this player's own level, exact; setting the level is server-only |
SetRestriction(key, mode \| nil) |
a player state of your own for Config.Block (a jail, a cutscene, surgery): 'block', 'emergency-only' or nil to clear it. Kept per calling resource and cleared when that resource stops. Add key to Config.Block.calls to choose what happens to a live call (unlisted: the call is kept) |
StartActivity(def) / UpdateActivity(id, patch) / EndActivity(id) / EndAllActivities() |
an Island activity on this player's phone, from a client script (section 14) |
SetCarAudio(state \| nil) → boolean |
a car audio script's stereo on Pulse Drive, the car screen: its Home card and Music view show it before the phone's music, labelled "Car stereo · label". state: { title?, artist?, art?, label?, colour?, playing, position, duration?, volume?, canControl, app?, vehicle? }; position and duration in seconds (no duration = a live stream), volume 0 to 1 (shows a volume slider), art an https:// or nui:// image, colour '#RRGGBB', app the id of your registered phone app (an Open button), vehicle the car's entity handle (shown only while the player sits in it). No title = the stereo is on but idle. Send it on every change and about once a second while playing; nil clears it. One state per calling resource, forgotten when that resource stops. false when Config.Drive.enabled = false. Buttons arrive as the client event phone:drive:carAudio (section 3) |
PhoneAudioRoute() |
where this player's call audio goes: 'speaker' (the default), 'earpiece' or 'bluetooth' |
NearestDroppedPhone() |
the id of the dropped handset within reach (Config.Dropped.pickupRange), or nil. For a server with its own interaction system |
IsTabletOpen() |
true while this player has the Pulse Tablet open |
LocaleStrings(prefix) → { code, strings } |
text in the language this player picked on the phone (the server's Config.Locale until the phone has booted): every key starting with prefix, with English where that language lacks one. Add your own keys in a config/locales/<name>_<code>.lua file per language (Locale.Register('<code>', { ['myscript.key'] = '...' })) |
OpenDeptStore(storeId?) |
opens a department store (Config.DeptStores) when the player stands at one of its locations, as the prompt there does; without storeId, whichever store they are at. Returns false anywhere else. The server checks access and distance again |
AppCompatAdd / AppCompatRemove / AppCompatMessage / AppCompatPopUp / AppCompatContextMenu / AppCompatComponent / AppCompatOpenApp / AppCompatCloseApp / AppCompatIsOpen / AppCompatIdOf |
used by the app compatibility resource (pulse-phone-app-compat, CUSTOM_APPS.md section 11); not an API of their own |
Open vetoes, in order: disabled, then another resource holding NUI focus
(Config.Open.blockWhenNuiFocused), then each AddOpenCheck. A refusal raises
phone:openRefused with the reason. Checks made before this one still apply: the player's state
(Config.Block: dead, downed, cuffed, escorted, carried, jailed, under water, in the pause menu,
or a SetRestriction of another script) and the phone item.
6. Compatibility with other phones
Many scripts (police, ambulance, boss menus, garages, deliveries) send mail, texts, notifications and job alerts using the event names other phone resources use. The phone answers those events itself (mail, texts, notifications and job alerts), so those scripts work without edits.
A script that calls another phone's exports by that phone's resource name needs one change:
call exports.phone instead. These seven server exports cover what such scripts do, and any
script may use them directly:
| Export | What it does |
|---|---|
ResolvePhone(target[, cb]) |
target is { source }, { number }, { email }, { identifier } or { imei }. Returns { number, email, name, identifier, imei, source }: with cb, online or offline; without it, online only, immediately. |
DeliverMailTo(target, mail[, cb]) |
mail = { sender, subject, body, attachments? }. Calls cb(true, mailId) or cb(false, reason). |
SendText(from, to, body[, opts][, cb]) |
From an online phone, a stored message. From anything else, a live service message named opts.name. |
DispatchAlert(jobs, { title, body, coords? }) |
Notifies every on-duty member of the jobs; tapping the alert opens Maps at coords. Returns how many it reached. |
CompanyMessage(src \| nil, jobOrCompany, body[, opts][, cb]) |
From a player, a message to the company's Services inbox, or an alert when anonymous. From a script, an alert. |
PayBill(src, billId[, cb]) |
Pays one of the player's bills, as the Wallet does. |
IsOnDuty(src[, job]) |
Whether the player is on duty in job, or in their own job when job is omitted. |
7. Housing providers (Home app)
These are built in and chosen automatically when one of the scripts is running.
- Scripts:
qb-houses,qbx_properties,qs-housing,loaf_housing,vms_housing,rtx_housing,ps-housing,bcs_housing,nolag_properties,esx_property(bridge/server/housing.lua+bridge/client/housing.lua). - Priority: 6, so a provider you register at 10 wins.
- Pinning:
Config.Providers.housing = '<name>'pins one;'none'turns housing off. - Client relay: some scripts only expose client exports, or only accept their own menu's net
events. For those, the phone asks the owner's client to call that export or fire that event, and
the housing script's server validates it as usual. The relay (
phone:housing:ask/phone:housing:answer) is token-bound to the player it asked.
Vendor API each adapter uses (from each script's published source or documentation, cited in the adapter). "Owner's client" means the phone asks the owner's client to fire the event the housing script's own menu fires.
| Script | List | Lock | Keys |
|---|---|---|---|
qb-houses |
its tables player_houses, houselocations (read only) |
its own lock event, from the owner's client | its own give/remove events, from the owner's client |
qbx_properties |
its properties table (read only) |
none (shells) | list only (its key events need the owner inside) |
qs-housing |
server export GetPlayerHouses |
none exposed | none exposed |
loaf_housing |
client export GetOwnedHouses |
server exports IsDoorLocked / SetDoorLocked |
client exports GiveKey, RemoveKeyHolder, GetKeyHolders |
vms_housing |
server exports GetPlayerProperties / GetProperty |
none exposed | its give/remove key events, from the owner's client |
rtx_housing |
client export GetPlayerOwnedProperties |
its lock event + GlobalState | its permission events, from the owner's client |
ps-housing |
its properties table (read only) |
none (door lock script) | its addAccess / removeAccess events, from the owner's client |
bcs_housing |
server export GetOwnedHomeKeys |
server exports isLocked / LockHome (toggle) |
server exports GetKeyHolders, RemoveKeyHolder (giving a key stays in its menu) |
nolag_properties |
server export GetAllProperties |
server export ToggleDoorlock (sets the state) |
server exports GetKeyHolders, AddKey, RemoveKey, as the player |
esx_property |
server export GetProperties (with lock state) |
none exposed | list from GetProperties |
The loaf_housing calls could not be re-checked: its current version publishes no exports page.
CurrentHome(src[, cb]) (optional). Pulse Home Wi-Fi asks a housing provider which home the
player is standing in when they place a router (Config.Wifi.placement 'housing', or 'auto'
with a housing script). Return the home's id - one of the ids your ListOwned gives that player -
or nil, or answer through cb(id) when your script has to look it up. Without it the phone
goes by the homes' positions (within Config.Wifi.homeRadius) and by instanced homes (a routing
bucket other than 0). None of the built-in adapters above has it: none of those scripts publishes
such a call. Add it to your own provider (custom_provider_template.lua in this folder).
8. Unique phones
Set Config.Item.unique = true. The number lives in the item's metadata:
| Key | Meaning |
|---|---|
phoneNumber |
the number |
phoneColour |
the finish |
description |
tooltip text |
Device rows for item phones are keyed item:<id>. Face Unlock enrols the character, not the
handset. The item's finish reaches the interface as bootstrap.device.colour and the
phoneColour state bag, and the handset in the player's hand is drawn in that finish.
9. Browser sites (RegisterSite)
The Browser app cannot reach the internet. A site is registered by a resource on the server, and a page is data (a title and a list of blocks) that the phone draws in its own style. A site cannot carry script, a stylesheet or a URL outside the game. The add-on page kinds (list, detail, board, form) are accepted too and converted.
exports.phone:RegisterSite({
id = 'pdm', -- [a-z0-9_], also the event namespace
name = 'Premium Deluxe', -- shown on the start page tile
host = 'pdm.ls', -- optional; default '<id>.<Config.Browser.tld>'
colour = '#B8322F', glyph = 'car', -- tile art (built-in glyph set)
keywords = { 'cars', 'dealer' }, -- optional, for the search box
pages = { ['/'] = { title = 'Showroom', blocks = { ... } } },
resolve = function(src, path, cb) cb(page) end, -- optional, dynamic pages
submit = function(src, path, form, values, reply) end, -- optional, forms
})Blocks: heading, text, stats, list, cards, links, form, directory, hero (a
branded banner with an optional picture), posts (short posts with author and time) and empty
(a designed "nothing here" panel). A list row, card or post may carry app + route to open a
phone app (Services, Wallet, Echo...) instead of a page.
Built-in sites. Eight ship by default, each drawn from data the server really has or
labelled as a brochure. Three are generated: the server's front page (name, players online,
phones issued, the apps on the phone), the phone directory, and a help site built from
Config. Five are in-world (<tld> is Config.Browser.tld):
| Site | Host | Content |
|---|---|---|
| City Services | city.<tld> |
Config.Services, live: who is on duty, call the line, message the company (opens Services) |
| City Wire | citywire.<tld> |
public Echo posts and LS Pages adverts from the server's own tables; a designed empty page otherwise |
| Harbor Trust | harbortrust.<tld> |
the caller's real balance from the bank provider, and the way into Wallet |
| Redline Motors | redline.<tld> |
a showroom brochure (Config.Browser.showroom): class, seats and list price per model, a page per car |
| Chromeworks | chromeworks.<tld> |
a customs price list (Config.Browser.customs) and the mechanic's line from Config.Services |
Replace the brochure data in config, or turn a site off with
Config.Browser.builtin = { redline = false, ... }.
10. Player data controls (requests for the interface)
Server requests the interface calls through the normal request bridge (fetchNui('phone:<name>', data)
on the page, phone:rpc on the wire). Each acts on the caller's own phone only, is rate limited by
the security layer, and answers { ok, reason? }.
| Request | Data | Effect |
|---|---|---|
calls:history:delete |
{ id } (a Recents row's id from bootstrap) |
hides that call from this phone's Recents; the other party keeps theirs. reason = 'not-found' for an id that is not this phone's |
calls:history:clear |
{} |
hides every call from this phone's Recents |
messages:thread:delete |
{ number } or { group } |
"Delete Conversation" for this phone only (same as messages:conversation:delete) |
messages:threads:delete |
{ threads = [ { number } \| { group }, ... ] } (at most 50) |
the same for several at once; answers { ok, deleted, failed } |
notifications:clear |
{ app? } |
empties the notification list (all, or one app id); the server relays it to the page as the NUI message notifications:clear { app? }, which the page must handle by calling clearNotifications(app) |
A call row stays in the database until both sides have deleted it. Recents from bootstrap no longer include deleted calls.
11. Owner tools (console, or ace phone.admin)
<id|number> is an online server id (up to five digits) or any phone number, online or offline.
Every command writes a security-log row and an activity-log entry.
| Command | Does |
|---|---|
phone:resetpin <id\|number> |
removes the passcode and Face Unlock; the lockout clears |
phone:wipe <id\|number> confirm |
erases the phone's own data (contacts, photos, notes, reminders, calendar, voicemail, memos, saved places, playlists, albums, blocks, mail) and hides its calls and conversations for that phone, then factory resets it. Without confirm it only says what it would erase |
phone:number <id\|number> <newnumber> |
a new number: must fit Config.Numbers.format and be unused; the phone's own data, conversations and call history move to the new number. phone:number with no arguments shows your own number. Refused with unique phones on (the number is on the item) |
phone:inspect <id\|number> |
a summary: number, mail, IMEI, created, online, setup, power, passcode, counts |
phone:retention [now] |
runs Config.Retention pruning now (now is required while retention is off) |
phone:health |
prints the start-up panel again, including voice conflicts and config problems |
12. Clock and retention settings
Config.Clock.mode = 'server' (the default) publishes the server's clock in the global state bag
phone:clock ({ hour, minute }), so every phone shows the same time; utcOffset pins a zone.
'game' follows the game's time of day (and so any weather/time sync script), 'real' is each
player's own computer clock, 'custom' a function in config.
Config.Retention (off by default) prunes messages, social DMs, Dark Chat, call history, social
activity and optionally mail older than the configured days, once a day at hour, in batches.
13. Bills, carrier, charging, store, Home Wi-Fi, burners, taps and payphones
All server side unless marked.
Server exports
| Export | Returns | Notes |
|---|---|---|
SendBill(sender, targetSrc, amount, reason, society?, cb?) |
id | false, reason |
sender: a player's server id, or a name for a script ('police', 'city_hall'). targetSrc must be online. society: optional job name ('police' or 'society_police'); payment then goes to that company's account. A script name with no society bills for the account of that name. cb(ok, idOrReason) runs once the bill is stored. Reasons: disabled, target, amount (not a whole number from 1 to Config.Bills.maxAmount), society, sender, self, rate (Config.Bills.perMinute), no-device |
GetBills(src, cb?) |
{ unpaid = {...}, paid = {...} } |
the phone's own bills plus esx_billing / okokBilling / qb-core phone_invoices rows, newest first; the paid list is capped at Config.Bills.paidHistory. Without cb it waits for the answer, so call it from a thread. Each bill: { id, source, from, company, number, reason, amount, at, status, paidAt } |
IsWalletCardLocked(src) |
boolean | true while that player has locked their phone's card in Wallet > Cards. A script that charges "the phone" (a shop's tap to pay) should refuse while it is locked, as the phone's own payments do |
CreateInvoice(fromSrc, toSrc, { amount, reason?, kind?, job?, due? }) |
id | nil, reason |
an invoice, fine or medical bill (Config.Invoices). fromSrc: the issuing player's server id, or a name for a script ('city'). toSrc must be online. kind: 'invoice' (default), 'fine' (needs job) or 'medical'. job: the company the money goes to; a player must hold that job. due: epoch ms or seconds, or a number of days from now; left out, Config.Invoices.dueDays; 0, no due date. Called from a thread it waits until the invoice is stored; outside one it returns the id at once, or nil, 'pending' while it is being forwarded (issueTo = 'forward'). Reasons: disabled, data, kind, amount, job, not-employee, sender, target, self, due, rate, plus SendBill's |
PayInvoice(src, id, cb?) |
ok, reason | pays the invoice from that player's bank, as the Wallet's Pay does. id: 'bill:phone:<id>' (or the bare id) or another billing resource's 'bill:<source>:<id>'. Without cb it waits, so call it from a thread |
GetInvoices(src \| { job }, cb?) |
{ unpaid, paid } | { invoices, totals } |
a player's bills, as GetBills; or with { job = 'mechanic' } that company's phone invoices, newest first (up to 100), with totals = { paid, unpaid, unpaidCount, overdue, overdueCount }. Each invoice: { id, to, number, from, reason, amount, kind, status, at, due?, paidAt?, dispute?, disputedAt? }. Without cb it waits |
CancelInvoice(id, cb?) |
ok | voids an unpaid phone invoice; the payer is told. cb(ok, row \| reason), reasons id and gone (paid, cancelled or unknown). Without cb, from a thread it waits for the answer; outside one it returns true once the request is made |
HasService(src, service?) |
boolean | may this phone make a call / send a text / use data now ('call' default, 'text', 'data'). Always true while Config.Carrier.enabled is false |
GetCarrierStatus(src) |
table | nil | nil while the carrier is off or the line is not loaded. { service ('ok' \| 'no-plan' \| 'suspended' \| 'no-service'), bars, roaming, carrier, plan, job, line = { number, iccid, eid, status, autorenew, renewsAt, graceUntil, ... }, usage = { talkSeconds, texts, dataKB } } |
UseMagPack(src, slot?, name?) |
boolean | as if the player used a Reserve item (ak47_inventory's onUse); name is the item name used (pulse_magpack or pulse_magpack_max) |
UseChargingCable(src, slot?) |
boolean | as if the player used the cable item |
DetachChargers(src) |
takes the Reserve and cable off the phone | |
GetChargingState(src) |
{ pack, cable, source?, mode?, packLevel? } |
what is attached, and where the cable is plugged in |
SetPowerSource(src, name \| false) |
boolean | a power source your script provides (a house, a charging station): while set, the cable can be plugged in anywhere. false clears it and unplugs a cable using it |
UseBox(src, slot?, name?) |
boolean | as if the player used the sealed phone box (Config.Store.boxItem, or a per-finish box name) |
IsOnWifi(src) |
boolean | true while that player's phone is online over Pulse Home Wi-Fi: a router, or a Personal Hotspot whose own phone has service. Decided on the server from where the character stands; false while Config.Wifi.enabled is false |
SetRouterPlacementCheck(fn \| nil) |
boolean | your own rule for where a router may go, replacing Config.Wifi.placement: fn(src, coords, bucket) -> ok, reason. coords is { x, y, z } of the spot, bucket the player's routing bucket. A false answer refuses, and reason (a string) is what the player is told. maxPerPlayer and minSpacing still apply. nil goes back to the config rule. A function that errors refuses |
UseRouter(src) |
boolean | as if the player used the router item (Config.Wifi.item): starts placing it (ak47_inventory's onUse) |
UseBurner(src, slot?) |
boolean | as if the player used the burner item (Config.Burner.item): the burner comes out (ak47_inventory's onUse) |
IsBurnerNumber(number) |
boolean | true for a Pulse Burner's number, live or destroyed |
TapNumber(number, reason, hours, officerSrc?) |
id | nil, reason |
a police tap from an MDT (Config.Taps). With officerSrc that player must be allowed (job, grade, duty) and their maxActive applies; without it the tap is placed by your resource. Call it from a thread or an event handler: it waits for the number's database lookup. Reasons: disabled, number, emergency, reason (8-200 characters), hours (1 to maxHours, whole), unknown-number, exists, untappable (a burner with Config.Burner.allowTaps = false), not-in-service, limit-officer, limit-server, not-police, grade, off-duty, busy |
EndTap(id) |
boolean | ends an active tap |
UseBudsItem(src) |
boolean | as if the player used the Pulse Buds item (Config.Accessories.buds.item): the case comes up in their hand to pick Left, Right or Both (ak47_inventory's onUse). With Config.Accessories.buds.caseInHand = false it is UseBuds |
UseBuds(src) |
boolean | the Pulse Buds straight in if they are out, out if they are in, without the case |
AreBudsIn(src) |
boolean | true while that player's Pulse Buds are in: their calls are private and their phone's sounds stay in their ears |
UseRingLight(src) |
boolean | as if the player used the Pulse Ring Light item: starts placing it (ak47_inventory's onUse) |
UseCardWallet(src) |
boolean | as if the player used the Pulse Card Wallet item: on the phone if it is off, off if it is on (ak47_inventory's onUse) |
IsCardWalletOn(src) |
boolean | true while the card wallet is on that player's phone |
Client exports (ox_inventory item hooks)
| Export | Item entry |
|---|---|
usePack |
client = { export = 'phone.usePack' } on pulse_magpack |
useCable |
client = { export = 'phone.useCable' } on pulse_cable |
useBox |
client = { export = 'phone.useBox' } on pulse_phone_box (and the per-finish boxes) |
useRouter |
client = { export = 'phone.useRouter' } on pulse_router (Pulse Home Wi-Fi) |
useBurner |
client = { export = 'phone.useBurner' } on pulse_burner (the Pulse Burner) |
useBuds |
client = { export = 'phone.useBuds' } on pulse_buds |
useRingLight |
client = { export = 'phone.useRingLight' } on pulse_ringlight |
useCardWallet |
client = { export = 'phone.useCardWallet' } on pulse_wallet |
The server re-reads the slot and the item for each of these; nothing the client sends is trusted.
Ready-made item entries are in config/items/.
Client export: opening the store from your own script
| Export | Returns | Notes |
|---|---|---|
OpenStore() |
boolean | opens the store counter when the player stands at a store (Config.Store.locations, within Config.Store.range), exactly as pressing E there does; with no counter there, the Pulse machine they stand at (as OpenVendingMachine()). false anywhere else. For a server with its own menu, NPC or target script. The server still checks the distance at checkout |
Server events
| Event | Arguments |
|---|---|
phone:bills:sent |
billId, ownerNumber, amount, reason, job \| nil |
phone:bills:paid |
fullId ('bill:<source>:<id>'), payerNumber, amount, job \| nil |
phone:tap:intercept |
{ id, tap, number, at, kind ('sms' \| 'group' \| 'call'), from, to, body, duration (s), status }: one intercepted event on a tapped number. Never call audio |
State bags
| Key | Type | Meaning |
|---|---|---|
phoneCharger |
'pack' | 'cable' | 'both' | nil |
the accessories on the phone in this player's hand; written only by the server |
phone:unbox |
internal | the unboxing scene other players see; written only by the server |
Payphone calls
A payphone call is an ordinary call of the phone's call system, so phone:callStarted,
phone:callAnswered and phone:callEnded fire for it. The caller's "number" is what
Config.Payphone.callerId shows: Config.Payphone.callerLabel (default Payphone), Unknown,
or the booth's own number. The payphone itself has no exports.
14. Island activities (Island and Lock Screen)
Another resource can show an Island activity on a player's phone: the same Island and Lock Screen card the phone's own timers and calls use, drawn by the same code. A delivery route, a heist countdown, a tow truck on its way.
Server (exports.phone:…)
local id, why = exports.phone:StartActivity(src, {
id = 'delivery', -- optional, your own key (1-32 of A-Z a-z 0-9 _ -); starting it again replaces it
title = 'Delivery route', -- required, 1-40 characters
detail = '3 stops left', -- optional, up to 60
compact = '1/4', -- optional, up to 12: the short text beside the camera
progress = 0.25, -- optional, 0 to 1: a bar
-- or a countdown the phone runs itself (no update per second needed):
-- countdown = 90, -- seconds (1 s to 24 h), or endsAt = os.time() + 90
-- endOnZero = true, -- remove it when it reaches zero (else it stays at 0:00)
glyph = 'truck', -- a glyph (list below), or appIcon = 'my_app' (an app's icon)
colour = '#FF9F0A', -- #rrggbb, must reach 3:1 contrast on black
link = 'my_app/route/42', -- optional: where a tap goes ('messages', 'my_app', 'my_app/<route>')
})
if not id then print('not shown: ' .. why) end
exports.phone:UpdateActivity(src, id, { detail = '2 stops left', progress = 0.5 })
exports.phone:UpdateActivity(src, id, { detail = false }) -- false (or '') clears a field
exports.phone:EndActivity(src, id)
exports.phone:EndAllActivities(src) -- every activity YOUR resource shows on that player (nil = on everyone)UpdateActivity takes any of the same fields except id; countdown = false stops a countdown,
link = false removes the link. It returns true, or false, reason.
Client (exports.phone:…, this player's phone only)
local id = exports.phone:StartActivity({ title = 'Fuel', glyph = 'fuel', progress = 0.6 })
exports.phone:UpdateActivity(id, { progress = 0.55, compact = '55%' })
exports.phone:EndActivity(id)Same definition and limits. endsAt is read against GetCloudTimeAsInt() on the client. A
link or appIcon naming an add-on works once the phone has received this player's add-on list.
What the player sees
| Where | What |
|---|---|
| Island, one activity | the glyph or app icon leading; compact trailing (else the countdown, else detail) |
| Island, two or three | small pills either side of the camera. The phone's own call, timer and music always stay in front of yours |
| Island, held | title, detail and the progress bar |
| Lock Screen | the card: title, detail, progress bar and a stripe in your colour |
| Tap | opens link (an app of the phone, or a registered add-on at the route). No link: the tap expands it |
A countdown shows as m:ss (h:mm:ss over an hour) after your detail ("Drill running · 1:24")
and fills the bar as it runs.
Glyphs: the Island's call, music, timer, navigation, record, camera, download,
job, delivery, event, emergency, and the add-on set shield, cross, wrench, cart,
bank, key, car, house, briefcase, radio, pin, bolt, book, chart, dice, fuel,
gavel, heart, lock, note, plane, tag, truck. Default: event.
Limits (config/apps.lua, Config.Api.activities)
| Setting | Default | Meaning |
|---|---|---|
perResource |
2 | activities one resource may show on one phone at once ('limit-resource') |
perPlayer |
4 | from every script together ('limit-player'); the interface also never holds more than 6 |
updateMs |
500 | one activity updates at most this often. Faster updates are merged and the newest state is sent when the interval ends, so the last one always arrives |
startsPerMinute |
20 | starts per resource per player per minute ('rate-limited') |
enabled |
true | false refuses every start ('disabled') |
Text lengths are fixed by the screen: title 40, detail 60, compact 12 characters. Longer text is
refused, not cut, with a reason such as 'title is longer than 40 characters'; an unknown
field (detial = …) is refused too. Each refusal also prints one console line naming your
resource (at most once a minute per reason).
Other reasons: 'player-offline', 'no-phone' (the player's phone has not loaded),
'unknown-activity' (not yours, or already ended), 'id cannot change'.
Cleanup
Your activities end when you end them, when your resource stops (the server and client halves
each clear their own), when the player leaves, and - with endOnZero - when the countdown runs
out. One resource can never update or end another's: activities are keyed by the calling resource.
15. Script calls (a custom or hidden caller id)
A server script can ring a player from an identity that is not a phone - a mission's
"Unknown" caller, a dispatcher - through the phone's own call system: the ringtone, the call
screen, answer and decline, call waiting when they are already talking, Recents, and the public
call events (phone:callStarted, phone:callAnswered, phone:callEnded).
local callId, why = exports.phone:PlaceScriptCall(target, { -- target: server id, or a phone number held by someone online
label = 'Unknown', -- required, 1-32 characters: what the call screen and Recents show
number = '555-0142', -- optional, 3-15 digits (+ - ( ) and spaces allowed)
hidden = false, -- default: true without a number, false with one
speaker = dispatcherSrc, -- optional: a player whose voice carries the call
ringSeconds = 30, -- 5 to 60 (default Config.Api.scriptCalls.ringSeconds)
onAnswer = function(callId, src) end,
onDigit = function(callId, src, digit) end, -- a key on the in-call keypad: '0'-'9', '*', '#'
onEnd = function(callId, reason, durationMs) end, -- 'ended' | 'missed' | 'declined' | 'dropped' | 'busy'
})
exports.phone:EndScriptCall(callId) -- hang up from your side
exports.phone:GetScriptCallState(callId) -- 'ringing' | 'connected' | nilAudio. With speaker, that player is the calling end - their own phone shows the call - and
the phone's existing voice routing puts both in one call channel (pma-voice, mumble-voip,
SaltyChat, TokoVOIP, YACA), exactly as for a phone-to-phone call. Without speaker nobody is on
the far end: the line connects and is silent, and your script supplies what the player hears or
reads (onAnswer is where to start it).
Phone menus. The in-call keypad sends each digit the player presses: onDigit gets it on a
script call, so a script can run a menu ("press 1 for parts, 2 for service"). On any call, every
other player listening hears the touch tone, and the server event phone:callDigit
(callId, src, digit) fires for scripts. Digits come only from a connected, unheld call and are
rate-limited.
Security
Server only. These are server exports and no net event leads to them, so a client can never
place a script call. EndScriptCall and GetScriptCallState only answer the resource that placed
the call, and a player's own call can never be ended through them.
Logged. Every script call writes Script call placed and Script call ended to the phone's
activity log (calls: the resource, the label, the number or withheld, the callee, the reason)
and a call-history row, whose caller column is the number shown, or the label when the number is
withheld. A script call never offers voicemail (there is no one to offer it to).
Refusals (false, reason): 'unavailable' (target offline, phone not loaded, dead battery or
no service), 'busy' (already ringing or dialling), 'speaker-busy', 'speaker-is-target',
'limit-resource' (Config.Api.scriptCalls.perResource, default 8 at once), 'disabled', and a
sentence for a bad option ('label is required', 'number must have 3 to 15 digits',
'unknown field "video"'). Your resource stopping hangs up its calls; the callbacks are not called
then, because the resource is gone.
A working example of sections 14 and 15: pulse-phone-devapi-demo/ (in this folder) (/devkit_delivery,
/devkit_heist, /devkit_call, /devkit_dispatch <id>, /devkit_fuel).
16. Phone damage, protection and repairs (Config.Damage, config/apps.lua)
The server decides every crack and every drop of water (server/damage.lua); the condition belongs to the handset (the phone item with unique phones, otherwise the character's phone).
Server exports
| Export | Returns | Notes |
|---|---|---|
GetPhoneDamage(src) |
table | nil | the handset in that player's hand: { screen ('intact' \| 'cracked' \| 'badly'), water (nil \| 'flicker' \| 'dead'), case (protection id \| nil), protector, pouch }. nil while its record is not loaded yet |
RepairPhone(src, what?, cb?) |
true | repairs the handset in that player's hand for free - for a mechanic or electronics job that charges in its own way. what: 'screen', 'water' or 'all' (default). cb(changed): false when there was nothing to repair. A screen repair takes a screen protector with the old glass |
DamagePhone(src, what) |
boolean | 'crack', 'shatter' (badly cracked) or 'water' from your own script. A screen protector still takes a crack, and the waterproof pouch still keeps water out |
FitPhoneProtection(src, item) |
boolean | as if the player used that protection item (pulse_case, pulse_case_clear, pulse_pouch, pulse_protector): the item is taken from their inventory |
A job script repairing phones:
RegisterNetEvent('myjob:repairPhone', function(target)
local src = source
-- your own checks: job, distance, the price
exports.phone:RepairPhone(target, 'all', function(changed)
if changed then --[[ charge, log, notify ]] end
end)
end)Client export (ox_inventory item hook)
| Export | Item entry |
|---|---|
useProtection |
client = { export = 'phone.useProtection' } on pulse_case, pulse_case_clear, pulse_pouch, pulse_protector |
Inventories that cannot make items usable fit protection with /phoneprotect <id>
(Config.Damage.protection.command) or at the Pulse Store's Repairs counter.
State bags
| Key | Type | Meaning |
|---|---|---|
phone:damage |
{ s, k, x, y, w, c, t } | nil |
the handset in this player's hand: screen 0-2, the crack's seed and impact point, water 0-2, the case style ('rugged' | 'clear') and its tint row. Written only by the server; the screen on the prop and the case on the handset are drawn from it |
Owner tool
phone:damage <playerId> <crack|shatter|water|repair|clear> from the console, or a player with the
phone.admin ACE. clear also takes off everything fitted.
17. Groups and group jobs (Config.Groups)
Players make groups in the Groups app (create, invite a contact, join with a code). A job script
reads and drives the group through these server exports. Group ids are numbers; an unknown or
disbanded group answers nil, false, 0 or {} - never an error.
The names and argument order are the ones group-job scripts are commonly written against, so a
script that calls these functions on another resource needs one change: call exports.phone.
| Export | Returns | Notes |
|---|---|---|
GetGroupByMembers(src) |
id | nil | the player's group |
FindGroupByMember(src) |
id | 0 | the same, 0 when none |
GetPlayerGroup(src) |
id | nil | |
getGroupMembers(id) |
{ src, ... } |
in join order |
GetGroupMembers(id) |
{ { source, name }, ... } |
with character names |
getGroupSize(id) / GetGroupMembersCount(id) |
number | |
GetGroupLeader(id) |
src | nil | |
isGroupLeader(src, id) / IsGroupLeader(id, src) |
boolean | both argument orders exist |
GetGroup(id) |
{ id, name, leader, members, status, stages, temp } | nil |
|
CreateGroup(src, name?) |
id | nil | a group made by a script (isGroupTemp is true) |
AddGroupMember(id, src) / RemoveGroupMember(id, src) |
boolean | |
DestroyGroup(id) |
boolean | members are told it was disbanded |
isGroupTemp(id) |
boolean | |
setJobStatus(id, status, stages?) / SetJobStatus(id, status, stages?) |
boolean | stages = { { name, isDone }, ... }; 'WAITING' with no stages takes the job card down |
getJobStatus(id) / GetJobStatus(id) |
string | |
resetJobStatus(id) |
boolean | back to 'WAITING', card removed |
SetGroupJob(id, { label, stage?, stages?, countdown? \| endsAt? }) |
boolean | the job card with a timer (countdown seconds, or a UNIX endsAt) |
SetGroupStage(id, index) |
boolean | stages before index are done |
SetGroupWaypoint(id, coords, label?) / ClearGroupWaypoint(id) |
boolean | sets every member's GPS waypoint; the app offers Route to it |
pNotifyGroup(id, title, body) / NotifyGroup(id, body) |
boolean | a phone notification to every member |
CreateBlipForGroup(id, name, data) |
boolean | data = { label, coords, sprite, colour \| color, scale, alpha, route, routeColour \| routeColor, radius?, netId? \| entity? } |
CreateBlipForGroup(id, name, label, coords, sprite, colour, scale, route) |
boolean | the same, positional |
RemoveBlipForGroup(id, name) |
boolean | |
GroupEvent(id, event, args) / SendGroupEvent(id, event, args) |
boolean | TriggerClientEvent(event, member, args) for each member |
SetGroupData(id, key, value) / GetGroupData(id, key) / DestroyGroupData(id, key) |
script data kept with the group |
Client exports: GetGroupID() (0 when none), IsGroupLeader(), GetJobStage() (the status),
GetGroup() (the group as the app sees it).
The job card. While a group has a job (a status other than 'WAITING', stages, or
SetGroupJob), every member's Island and Lock Screen show it: the job, the current stage,
done/total and the timer. Tapping it opens Groups. It is the phone's own activity, so it never
counts against your resource's activity limit (section 14).
Server events (AddEventHandler): phone:groups:created (id, src), phone:groups:joined
(id, src), phone:groups:left (id, src, reason: 'left', 'kicked', 'dropped', 'unloaded',
'script'), phone:groups:disbanded (id, members).
Members leave a group when they leave the server or log out of the character; a leader who leaves hands it to the longest-standing member.
18. Dispatch lines, online status, Jobs and the trap phone
- Dispatch lines (
config/apps.lua). A company line with a dispatcher on duty queues its callers for the dispatcher, with hold music and the caller's place in line; the dispatcher works the line from Services > My Work > Dispatch Console and can transfer a caller to a unit. With nobody dispatching, the line rings everyone on duty exactly as before. The public call events fire for every leg; a transferred call ends the dispatcher's leg with reason'transferred', and a transfer nobody answered with'transfer-failed'. - Online status (
config/apps.lua). The dot on a contact; each player chooses who sees it in Settings > Privacy & Security. Nothing is exported. - Jobs (
config/apps.lua). The job board and business directory. Admins remove reviews and postings withphone:jobs(acephone.admin). - Trap phone (
Config.Burner.trapinconfig/apps.lua, off by default). Buyers text a carried Pulse Burner; the hand-off pays through the framework's money functions and can raise a police alert through the dispatch script.
19. Hail: trip offers from your own job script
An NPC taxi job (or any job that needs a driver) can send a trip to Hail drivers who are online. The driver sees it on the normal request card with its countdown and taps Accept or Decline. Hail only shows the offer and tells you the answer. Your script does everything after that: the NPC, the pickup, the destination, the fare, the payment and any XP. Hail moves no money for these offers and does not list them in the driver's Hail earnings.
Once a driver accepts, Hail holds them for your job. They get no Hail trips and the app shows
"On a job". The hold ends when you call EndHailJob, when the driver goes offline or leaves the
server, or after holdMinutes.
Server exports (exports.phone:…)
| Export | Returns | Notes |
|---|---|---|
GetHailDrivers(coords?, radius?) |
array of drivers | Every online driver, nearest first when coords is given. Each entry has source, number, name, state ('free', 'offer', 'trip', 'job'), free, coords, distance and vehicle (label, plate, net, model). |
IsHailDriverFree(source) |
free, state |
false, 'offline' when the player is not online in Hail. |
SendHailOffer(source, offer, cb?) |
offerId or nil, reason |
Offers to one driver. Reasons: 'not-online', 'busy', 'bad-offer', 'bad-coords'. |
SendHailOfferNear(offer, cb?) |
offerId, driverSource or nil, reason |
Offers to the nearest free driver in the service area within offer.radius (default Config.Rides.trip.offerRadius) of the pickup. Skips the sources in offer.exclude. Adds the reason 'no-driver'. |
CancelHailOffer(offerId) |
boolean | Withdraws an offer your resource sent that is still waiting. |
EndHailJob(source) |
boolean | Releases a driver from your job so Hail offers them trips again. Only the resource that sent the offer can release it. |
The offer table:
| Field | Required | Meaning |
|---|---|---|
pickup |
yes | vector3 or { x, y, z } |
dest |
yes | vector3 or { x, y, z } |
pickupLabel, destLabel |
no | Place names shown on the card (up to 60 characters) |
riderName |
no | Shown on the card. Default "Local passenger". |
label |
no | A tag on the card, for example 'NPC fare' (up to 24 characters) |
fare |
no | The amount shown to the driver. Display only: your script pays it. |
pay |
no | 'cash' (default) or 'bank', the chip on the card |
seconds |
no | Time to answer, 5 to 120. Default Config.Rides.trip.offerSeconds. |
holdMinutes |
no | How long an accepted job holds the driver, 1 to 240. Default 30. |
radius, exclude |
no | SendHailOfferNear only |
cb(accepted, reason, offerId) is called once. reason is 'accepted', 'declined',
'expired' or 'offline'. To accept, the driver must still be in the driver seat of the car
they went online with.
Server events (listen with AddEventHandler)
phone:hail:offerAnswered(offerId, driverSource, accepted, reason, resourceName)phone:hail:jobEnded(offerId, driverSource, reason, resourceName). Reasons:'ended'(you calledEndHailJob),'offline'and'timeout'.phone:hail:driverOnline(source, number)phone:hail:driverOffline(source, number, reason)
If your resource stops, its waiting offers and held jobs are cleared. Nothing is called back into it.
Example: an NPC fare
local function offerNpcFare(pickup, dest, fare)
local exclude = {}
local function try()
local id, driver = exports.phone:SendHailOfferNear({
pickup = pickup, dest = dest, fare = fare, label = 'NPC fare',
pickupLabel = 'Legion Square', destLabel = 'Vespucci Beach', exclude = exclude,
}, function(accepted, reason)
if accepted then
StartNpcFare(driver, pickup, dest, fare) -- your job: spawn the NPC, pay at drop-off
elseif reason == 'declined' or reason == 'expired' then
exclude[#exclude + 1] = driver
try() -- offer it to the next nearest driver
end
end)
if not id then print('no Hail driver for this fare: ' .. tostring(driver)) end
end
try()
end
-- When your fare is finished or cancelled:
exports.phone:EndHailJob(driverSource)