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.md 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.

Two limits:

• An incoming call sets inCall on 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.
• phoneBattery is 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's exports.phone:GetBattery() (client) and the server's GetBattery(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.

3. Client events

Listen with AddEventHandler in a client script. These are local and cannot be sent from the network.

4. Server exports (exports.phone:…)

5. Client exports (exports.phone:…)

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, so those scripts work without edits. phone_api in the server console lists every event it answers.

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:

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; not verified against live servers). "Owner's client" means the phone asks the owner's client to fire the event the housing script's own menu fires.

The loaf_housing calls could not be re-checked: its current version publishes no exports page.

8. Unique phones

Set Config.Item.unique = true. The number lives in the item's metadata:

Device rows for item phones are keyed item:<id>. Face Unlock enrols the character (Identity.CharacterKey), not the handset. The item's finish reaches the interface as bootstrap.device.colour and the phoneColour state bag. Drawing the handset in that finish (Device3D finishId) belongs to the OS layer and is not wired yet.

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. Add-on pages in the The add-on page kinds (list, detail, board, form) are accepted 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):

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? }.

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.

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 and payphones

All server side unless marked.

Server exports

Client exports (ox_inventory item hooks)

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/.

Server events

State bags

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

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/api.lua, Config.Api.activities)

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,
    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' | nil

Audio. 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).

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).