Pulse Phone docs
Creator apps for Pulse Phone
Any resource can add a full app to Pulse Phone: an icon on the Home Screen, a listing in the App Hub with screenshots, ratings and reviews, a page of its own (plain HTML or React, Vue, anything that builds to a web page) shown inside the phone, and a message channel between that page and the resource's own Lua. The phone draws the frame, the status bar, notifications, badges, the permission prompts and the Home / back gestures, and hands the page its own look - colours, fonts, Dark Mode, the handset's OS and the Pulse Duo's two screens - so a creator's app looks and behaves like a built-in one on every handset.
What you build is yours: Pulse never maintains your app. A dispatch board, a bank, a game, a page that plays video from a site you choose - the SDK gives you the phone, you decide what the app does.
This guide is for creators (SDK v3, rspulse.js 3.0.0). Every v1 and v2 app keeps working
unchanged: nothing below is required, and a page on an older rspulse.js runs as before.
The examples are not in the phone download. They ship in the optional
Pulse Developer Kit: unzip it
anywhere outside resources. Every example below is a folder inside the kit's
optional-developer-kit/ folder; copy only the one you want into resources/.
Example (in the kit's optional-developer-kit/ folder) |
What it shows |
|---|---|
pulse-phone-template-vanilla/ |
Start here (no build step). Plain HTML/JS: the phone's look, a server request, a client request |
pulse-phone-template-react/ |
Start here (React). React + TypeScript + Vite, typed hooks (src/pulse.ts), hot reload inside the phone |
pulse-phone-app-notes/ |
"Jot": notes in page storage, the back swipe, a draft saved when the app leaves, the Duo's two screens, names and icons per language and Dark Mode |
pulse-phone-app-dispatch/ |
"Dispatch": job gating with grades, server pushes and requests, notifications that open the call, badge, Island activity, a client-side waypoint |
pulse-phone-app-webview/ |
"Web View": a web page from your own config, with sound, video and full screen (capabilities), stopped when the player leaves |
pulse-phone-sdk/ |
rspulse.js, its TypeScript types rspulse.d.ts, and pulse.css (optional base styles drawn from the phone's own theme) |
pulse-phone-app-starter/ |
"Tally": the smallest SDK v2 app |
pulse-phone-app-arcade/ |
"Lane Rush": a landscape game with a store listing, permissions and a server-checked leaderboard |
pulse-phone-app-template/ |
"Field Notes": list, location, server storage, a deep-linking notification |
pulse-phone-devapi-demo/ |
"Dev Kit": every native sheet, an Island activity, a script call |
pulse-phone-app-compat/ |
Runs apps written for another phone's custom-app API (section 11) |
Scripts written for another phone keep working without edits: Pulse answers lb-phone:getPhoneNumber, lb-phone:sendMail, lb-phone:sendMessage and lb-phone:notification; qb-phone:server:GetPhoneNumber, qb-phone:server:sendNewMail, qb-phone:server:sendNewMessage and qb-phone:server:sendNotification; npwd:getPhoneNumber, npwd:sendMail, npwd:sendMessage and npwd:notification; and the matching qs-smartphone, gcphone, esx_phone, high_phone and roadphone names, all server-side and built in. Apps built for the lb-phone custom-app API run unedited through the compatibility resource in the kit (section 11).
In the server console, phone_api prints a short summary of the whole API.
Quick start (5 minutes)
- Copy
pulse-phone-template-vanilla/(orpulse-phone-template-react/) out of the kit'soptional-developer-kit/folder into yourresources/folder (a resource inside another resource is not started) and rename the folder, e.g.my-app. - Name it. In
server.luachangeAPP_ID(letters, digits and_, unique on the server),name,developerandcolour. - Start it after the phone, in
server.cfg:
cfg
ensure phone
ensure my-app
The console prints registered app "my_app" from my-app. A mistake in the declaration is
printed there too, naming the field.
4. Open it. It is already on every phone's Home Screen and in App Hub > Creators. No
reconnect is needed: an app appears the moment its resource starts.
5. Build your page in ui/ (React: web/, npm install, npm run dev). Open the page in a
desktop browser: rspulse.js notices it is not inside the phone, keeps storage in the browser,
answers your requests from RSPulse.devHandlers and plays the phone's events with
RSPulse.devSimulate, so you work with live reload and test in game at the end (section 15).
Everything else in this guide is optional and added one field at a time.
1. Register the app (server)
exports.phone:RegisterApp({
-- v1: what every app has
id = 'lane_rush', -- unique, letters/digits/_ (max 32); the event namespace
name = 'Lane Rush', -- Home Screen label (max 24)
colour = '#FF375F', -- icon tile, #rrggbb
icon = 'ui/icon.svg', -- see "Icons" below; or glyph = 'car'
description = 'Weave through traffic.', -- App Hub (max 160)
developer = 'Your Studio', -- App Hub: "by Your Studio" and the developer page (max 32)
version = '1.2.0', -- App Hub "Updates" shows version changes
job = { 'police' }, -- optional: only these jobs see the app (v3: grades, below)
badge = true, -- may set a count on its icon
notify = true, -- may raise notifications (default true)
page = { kind = 'frame', url = 'ui/index.html' },
-- SDK v2: the App Hub listing and what the app may ask for (all optional)
category = 'games', -- the shelf (list below)
tagline = 'Three lanes. No brakes.',-- the line under the name (max 40)
whatsNew = 'Friend challenges.', -- "What's New" for this version (max 300)
screenshots = { -- up to 6: paths in your resource or https URLs
'ui/shot-1.jpg',
{ url = 'ui/shot-2.jpg', landscape = true, caption = 'Night traffic' },
},
permissions = { -- the player is asked once, the server enforces (section 3)
contacts = 'To pick a friend to challenge.',
notifications = 'To tell you when a friend challenges you.',
},
orientation = 'landscape', -- 'portrait' (default), 'landscape' or 'any' (section 2)
paid = { url = 'https://you.tebex.io/package/123', price = '9.99 USD' }, -- section 6
-- SDK v3 (all optional)
names = { fr = 'Course', de = 'Spurwechsel' }, -- the label per phone language (24)
descriptions = { fr = 'Slalom dans le trafic.' }, -- the App Hub text per language (160)
icons = { -- per OS and Dark Mode (Icons, below)
default = 'ui/icon.svg', dark = 'ui/icon-dark.svg',
duo = { light = 'ui/icon-duo.svg', dark = 'ui/icon-duo-dark.svg' },
},
job = { police = 2, sheriff = 0 }, -- these jobs, from this grade up
items = { 'police_badge' }, -- and carrying one of these items
capabilities = { web = 'Why', media = 'Why' }, -- reviewed by the server owner (section 3)
defaultInstalled = false, -- players tap Get in the App Hub first
devUrl = 'http://127.0.0.1:5173/', -- your dev server, dev servers only (section 15)
})- Register from the server. Re-registering the same id from the same resource replaces the
declaration (use it to bump
version). Another running resource cannot take an id over: it is refused while the first owner runs.exports.phone:UnregisterApp(id)removes it. When your resource stops, its apps are removed automatically; when the phone restarts it forgets add-ons, so register again ononResourceStartfor the phone (every example does both). - A rejected declaration prints the exact field and reason in the server console - an unknown
category, a misspelt orientation, a seventh screenshot, an unknown permission or capability, a
language code that is not one, a store link that is not https, a
devUrloff this machine. - Players already online get the app immediately; no reconnect.
Categories: games, entertainment, social, productivity, utilities, finance,
business, lifestyle, music, photo, travel, news, health, education, sports,
services.
Screenshots are drawn at the handset's proportions (0.46 : 1, portrait, or 1 : 0.46 with
landscape = true): capture your page at 440 x 956 (or 956 x 440). JPEG or PNG, listed under
files { }. No data: or http: addresses. An app without screenshots shows a live preview of
its page instead.
Who sees the app. job takes names ({ 'police', 'sheriff' }) or names with the lowest grade
({ police = 2 }, 0 = every grade). items takes item names ({ 'badge', 'mdt' }) or names with
a count ({ badge = 1 }): the player must carry at least one, read through the phone's inventory
adapter (every supported inventory) and checked again within a few seconds of a change. A player
who is not offered the app does not see it anywhere, and every message, request and storage call
they send as it is refused on the server.
Page
page.url |
served from |
|---|---|
'ui/index.html' (recommended) |
your resource: https://cfx-nui-<your_resource>/ui/index.html |
'nui://my_res/ui/index.html' |
rewritten to the address above |
'https://…' |
an external page you host (still sandboxed; web keeps its own origin, section 13) |
Nothing else is accepted for a page, an icon or a screenshot: no http:, data:, javascript: or file: address (the console names the field).
List the files under files { } in your fxmanifest. Do not set ui_page for it: the
phone shows it inside its app frame. Load your scripts as classic <script src> tags (the React
template's build does this): a page without web has no origin of its own, and a browser refuses
module scripts from another origin unless the server sends CORS headers, which a resource's files
do not.
No HTML at all? page.kind may instead be list, form, detail or board - declarative
pages the phone renders in its own style; send SendAppMessage(src, id, 'page', {...}) to
replace the page live. (Frame apps are what this document is about.)
Icons
icon may be a path in your resource ('ui/icon.png', 'ui/icon.svg'), a URL, or an
inline SVG string ('<svg xmlns=… viewBox=…>…</svg>', under 16 KB). Draw it full-bleed and
square; the phone applies its own rounded mask. Or use a built-in glyph (shield, cross,
wrench, cart, bank, key, car, house, briefcase, radio, camera, pin, bolt,
book, chart, dice, fuel, gavel, heart, lock, note, plane, tag, truck) on
colour.
One icon per OS and per appearance (v3). The handsets run different OS looks - ultra,
titanium, clear, flip and duo - and each has a light and a Dark Mode Home Screen. icons
lets you draw for each: default, dark, and any OS as a path or as { light = …, dark = … }.
The phone picks, in order: the OS's own (its dark one in Dark Mode), then dark in Dark Mode,
then default, then icon. All variants together stay under 48 KB when inline; prefer files.
The phone's own icons are rendered objects with one soft light from above (a lens, a paper note,
a card): an icon drawn the same way sits naturally beside them.
Installing and removing
Registered apps are installed by default (an MDT must be there when the shift starts).
With defaultInstalled = false an app starts under Available in the App Hub and the player
taps Get. Players can remove any app from the App Hub (it stays removed across reconnects)
and get it back there. Removing an app also forgets the permissions the player gave it.
2. The page (HTML/CSS/JS)
Load the SDK before your own script. Either ship the copy from the kit in your resource (recommended: it also runs in a desktop browser), or load the phone's own, always-current copy:
<script src="rspulse.js"></script>
<!-- or: <script src="https://cfx-nui-phone/web/build/sdk/rspulse.js"></script> (if the phone's folder is named phone) -->
<script src="app.js"></script>Pages on the SDK get sharp text automatically at any screen size and phone size: the phone gives them their real pixels and they lay out at 440 pt themselves. A page without the SDK keeps its 440 pt viewport and is scaled to fit, as before.
await RSPulse.ready // the first context (v3)
RSPulse.on('context', ctx => { /* ctx.theme, ctx.safeArea, ctx.os, ctx.device, ctx.tokens … (ctx.number: below) */ })
const notes = await RSPulse.request('notes:list') // your SERVER Lua answers
const where = await RSPulse.request('where', null, { side: 'client' }) // your CLIENT Lua answers
RSPulse.send('shared', { id }) // fire-and-forget to your Lua (client + server)
RSPulse.on('message:notes:added', note => …) // pushed by your Lua
RSPulse.on('deeplink', route => …) // opened from a notification: 'note/abc'
RSPulse.notify({ title: 'Saved', body: '…', deepLink: 'note/abc' })
RSPulse.badge(0)
RSPulse.open('messages') // another app (the player taps Open first); or '<yourId>/route'
RSPulse.home() // leave the app
RSPulse.haptic('success') // selection, impactLight/Medium/Heavy/Rigid/Soft, success, warning, error
RSPulse.sound('tap') // the phone's own sounds (below)
// SDK v2
const state = await RSPulse.permissions.request('contacts') // 'granted' | 'denied' (section 3)
const people = await RSPulse.contacts.list({ limit: 50 }) // [{ name, number }]
const shots = await RSPulse.photos.list({ limit: 30 }) // [{ url, taken }]
const here = await RSPulse.location.get() // { x, y, z, heading }
await RSPulse.storage.set('best', 1215) // section 4
await RSPulse.setOrientation('landscape') // apps declared orientation = 'any'
// SDK v3 (sections 12-14)
RSPulse.on('pause', save); RSPulse.on('resume', refresh) // the app left / came back
RSPulse.on('volume', v => player.setVolume(v * 100)) // the phone's media volume, 0..1
await RSPulse.back.enable(true); RSPulse.on('back', closeDetail) // the phone's back swipe
await RSPulse.call('555-0142') // the player confirms first
await RSPulse.messages.compose({ to: '555-0142' }) // the player presses Send
await RSPulse.fullscreen(true) // turns the phone sidewaysRSPulse.api is 3 on a phone with SDK v3, 2 or 1 on older ones; calls a phone does not have
reject with 'unknown-method', so a page can fall back.
Sounds (RSPulse.sound(name)): tap, success, error, warning, notify, send,
receive, complete, start, stop, shutter, lap - the phone's own, at the player's
volume and Silent Mode; at most 6 a second.
Landscape apps
orientation = 'landscape' turns the phone sideways as the app opens - the handset itself
turns, with the status bar out of the way - and stands it up again when the player leaves.
Use it for games and video. orientation = 'any' opens upright and turns when the page asks:
RSPulse.on('orientation', o => layout(o)) // 'landscape' | 'portrait'
await RSPulse.setOrientation('landscape') // e.g. a video going full screenWhile turned, the context says orientation: 'landscape', size is 956 x 440 and the safe area
keeps 48 px clear on both short sides (the Island's side and its mirror) and the Home band at
the bottom. <html data-orientation> follows it, so CSS can switch layout. A portrait app is
refused ('orientation-locked').
Native UI: pickers, alerts and sheets the phone draws
Your page can ask the phone to draw its own contact picker, photo picker, alert, confirm, action sheet, text prompt (with the phone's own keyboard) and camera. They look and move exactly like the phone's, and they are the only way a page gets a contact or a photo: nothing is read silently, the page receives just the one thing the player taps, and the Camera opens only after the player agrees.
Every call returns a Promise. It rejects with an Error whose message is the reason:
'cancelled' (the player said no), 'busy' (a sheet is already open), 'rate-limited',
'not-visible' (your app is not the one on screen), 'unknown-method', or
'bad-params: <what is wrong>'.
const who = await RSPulse.pickContact({ title: 'Send To' }) // { name, number }
const pic = await RSPulse.pickPhoto({ title: 'Evidence' }) // { url, taken } (url: show it in an <img>)
await RSPulse.alert({ title: 'Shift Started', message: 'On duty until 18:00.', button: 'Got It' })
const yes = await RSPulse.confirm({ title: 'Delete Report?', message: 'This cannot be undone.',
confirm: 'Delete', cancel: 'Keep', destructive: true }) // true | false
const pick = await RSPulse.actionSheet({ title: 'Share Location', actions: [
{ id: 'pin', label: 'Drop a Pin' }, { id: 'stop', label: 'Stop Sharing', destructive: true },
] }) // 'pin' | 'stop'
const plate = await RSPulse.prompt({ title: 'Plate Number', placeholder: 'e.g. 46EEK572',
maxLength: 8, keyboard: 'text' }) // the text typed| Call | Parameters (all text is trimmed; longer text is refused, not cut) | Answers |
|---|---|---|
pickContact |
title? (40) |
{ name, number } of the contact tapped |
pickPhoto |
title? (40) |
{ url, taken } of the photo tapped (videos and deleted photos are not offered) |
alert |
title (80), message? (300), button? (20) |
nothing, once dismissed |
confirm |
title (80), message? (300), confirm? (20), cancel? (20), destructive? |
true / false |
actionSheet |
title? (80), actions: 1-6 of { id (1-32 of A-Z a-z 0-9 _ -, unique), label (40), destructive? } |
the id tapped |
prompt |
title (80), message? (200), placeholder? (60), value?, maxLength? (1-500, default 120), keyboard? ('text', 'number', 'decimal', 'phone'), secure?, confirm? (20) |
the text |
capturePhoto |
state? (any plain data, up to 2048 characters as JSON) |
see below |
Unknown parameters are refused (bad-params: unknown parameter "…"), so a typo shows up at once.
Taking a photo. The phone runs one app at a time, so the Camera replaces your page while
the player takes the photo, and your page loads again when they come back. The answer therefore
arrives as a capture event after your page's ready, carrying the state you passed in so you
can put the page back where it was:
RSPulse.on('capture', ({ ok, url, error, state }) => {
if (ok) attachPhoto(state.reportId, url) // url: the saved photo, as pickPhoto returns it
else showNotice(error) // 'cancelled' | 'timeout'
})
await RSPulse.capturePhoto({ reportId: 42 }) // resolves { opened: true } once the Camera is openingThe player first sees "“Your App” Would Like to Use the Camera" with Don't Allow / Open Camera
(Don't Allow rejects 'cancelled'). While the Camera is open the Island shows Photo for
Your App with Cancel. The first photo saved sends the player straight back to your app; leaving
the Camera without one, Cancel, or five minutes, answers ok: false. The photo is also in the
player's Photos, like any photo they take.
An Island activity from your page
One Island activity per add-on, on the Island and the Lock Screen, leading back into your app:
await RSPulse.activity.start({ title: 'Tow truck', detail: 'On its way', countdown: 240,
glyph: 'truck', colour: '#FF9F0A', route: 'job/42' })
await RSPulse.activity.update({ detail: 'Arriving', compact: '1 min' })
await RSPulse.activity.end()Fields as in EXPORTS.md section 14 (title 40, detail 60, compact 12, progress 0-1 or
countdown seconds with endOnZero, glyph, colour), with two differences: a tap always opens
your app, at route (there is no link), and without a glyph it shows your app's icon.
Updates faster than one per 500 ms are merged (the last one wins). A second activity is refused
('limit-resource'); start again with the same id replaces it. It stays when your page closes -
that is what it is for - and ends when you end it or when your resource stops.
For server- and client-side activities (no page needed) see EXPORTS.md section 14.
Look like the phone
rspulse.js sets, from the first paint (the phone puts them in the page address) and
again whenever the player changes them:
<html data-theme="light|dark">- follow it; the phone switches automatically at dusk if the player chose Automatic.<html dir="ltr|rtl">- the phone's language direction; use logical CSS (margin-inline-start) and right-to-left languages lay out correctly.<html data-orientation="portrait|landscape">.--rsp-accent- the phone's accent colour (it follows the handset), for your small controls.--rsp-safe-top(status bar),--rsp-safe-bottom(the Home swipe band),--rsp-safe-left(the back-swipe edge),--rsp-safe-right.--rsp-text-scale(Settings › Display › Text Size), classrsp-reduce-motion.- SDK v3: the handset's whole look -
data-os,data-device,--rsp-bg,--rsp-label,--rsp-tint, the fonts, the Duo's hinge and more. Section 12.
Keep tappable controls out of the bottom and left bands: those strips belong to the phone (Home swipe/tap and back swipe work over your page) and do not reach it.
The phone's browser is Chromium 103: no CSS :has(), container queries, CSS nesting or
color-mix(), and backdrop-filter is best avoided in a page.
Developing in a browser
Open your page directly in a browser: rspulse.js detects it is not inside the phone, sends a
stand-in context (with the Ultra look's theme values), keeps RSPulse.storage in the browser's own
storage, simulates a turn for setOrientation and fullscreen, answers every permission
'granted', and answers request from RSPulse.devHandlers[event]. There are no native sheets or
player data in a plain browser: those calls reject 'not-in-phone' unless you give a stand-in,
RSPulse.devSdk.pickContact = () => ({ name: 'Ava', number: '555-0142' }) (the same for
'contacts.list', 'photos.list', 'location.get'). RSPulse.devSimulate(…) plays the phone's
events: ('lifecycle', { state: 'background' }), ('volume', { volume: 0.3 }), ('back'),
('theme', 'dark'), ('device', { form: 'duo-spread', hinge: { x: 601, width: 22 } }).
3. Permissions
Declare what your app may ask for in RegisterApp (permissions), with a sentence saying why:
it is shown in the prompt, on your App Hub page and in Settings.
| Permission | Opens | Without it |
|---|---|---|
notifications |
your notifications (page and server) reach the player | they are dropped |
contacts |
RSPulse.contacts.list, exports.phone:GetAppContacts |
refused |
photos |
RSPulse.photos.list, exports.phone:GetAppPhotos |
refused |
location |
RSPulse.location.get, exports.phone:GetAppLocation |
refused |
camera |
RSPulse.capturePhoto opens the Camera without asking each time |
refused |
The player is asked once. The first call that needs a permission the player has not answered shows the phone's own prompt - "Lane Rush" Would Like to Access Your Contacts, your reason, Don't Allow / Allow - and the call continues with the answer. Ask at the moment it makes sense (the dispatch example offers it as a row the player taps, never as a prompt on launch):
const p = await RSPulse.permissions.query() // { contacts: 'prompt' | 'granted' | 'denied', ... }
if (p.notifications === 'prompt') await RSPulse.permissions.request('notifications')
RSPulse.on('permission', ({ permission, state }) => …) // changed in Settings while openA permission the player refused is not asked again: the call rejects 'denied' and the player
changes it in Settings › Apps › your app (where every answer can be switched, or reset with
Ask Next Time). A permission you did not declare rejects 'not-declared'.
The server decides. The answers are stored on the server per phone, and the server checks
them before it hands your app any data - whatever your page or client script sends. An app that
declares notifications has its notifications delivered only once the player allowed them;
an app that declares no permissions at all keeps the v1 rules (notify = true). The one-off
pickers (pickContact, pickPhoto) need no permission: the player picks the one thing you get.
Your Lua:
exports.phone:HasAppPermission(src, 'lane_rush', 'contacts') -- true / false, nil if not asked yet
exports.phone:GetAppContacts(src, 'lane_rush', function(list, reason) end) -- reason: 'denied', 'not-asked', 'not-declared'
exports.phone:GetAppPhotos(src, 'lane_rush', function(list, reason) end)
exports.phone:GetAppLocation(src, 'lane_rush', function(pos, reason) end)
AddEventHandler('phone:app:lane_rush:permission', function(src, permission, state) end) -- 'granted' | 'denied' | 'ask'A contact is { name, number } and a photo { url, taken } - never more of the player's data.
Capabilities the server owner reviews (v3)
Two things a page may do beyond a plain sandboxed page are not the player's to answer but the server owner's, because they are about what the city allows, not about the player's data:
| Capability | What the page gets | Typical app |
|---|---|---|
web |
it keeps its own web origin, so pages and players it embeds from other sites (a video site's embed, a map, your own web app) keep their storage and work as in a browser | a web view, an embedded player, a hosted web app |
media |
sound and video may start without a tap, go full screen, play protected streams and picture-in-picture; the phone stops it when the player leaves the app | a music or video app, a stream |
capabilities = {
web = 'Shows the page this city chose, with what it embeds.',
media = 'Plays the page’s sound and video, and full screen.',
},The console prints what each app asks for and whether it is allowed. The owner decides in
config/apps.lua (Config.AppStore.capabilities, section 6); players see both, with your
reasons, in Settings › Apps › your app under Set by This City. Neither opens any player data,
another app, or any of the phone's own events. A page reads what it got from
context.capabilities ({ web: true, media: false }) and should say so when one is off - the
Web View example does.
4. Storage
A page's own key/value storage, kept on the server per phone (it follows the player to any machine), no database work:
await RSPulse.storage.set('best', 1215) // any JSON value up to 8 KB; keys: 1-64 of A-Z a-z 0-9 _ . : -
const best = await RSPulse.storage.get('best')
await RSPulse.storage.remove('best')
const keys = await RSPulse.storage.keys()It is the same store as exports.phone:Set / Get: your Lua reads a page's key as
'page:<key>' with the phone number as owner (exports.phone:Get(APP_ID, number, 'page:best', cb)).
A page can never overwrite a key your server code keeps, never read another app's keys and never
read another phone's. At most 200 keys per app per phone. Like anything from the page it is
player input: keep scores and money on the server. The notes example shows a layout that scales
(an index key and one key per note).
5. Ratings, reviews and the App Hub
Under App Hub › Discover › Creators players see the featured apps (the server owner's
picks, else the best rated with screenshots), Top Rated, New in This City (first run here in
the last three weeks), every app from the city, and a page per developer. An app's page has
its screenshots, rating and reviews, install count, What's New with the version history, the
permissions and what the player answered, and an Updated badge when your version changes.
Every number is real: a rating is the mean of players' stars, installs are the phones that have
the app. Players rate 1-5 stars with an optional title and review, one per phone per app
(writing again edits it), and can delete their own. Anyone can report a review; moderators
remove, restore and ban from reviewing in Settings › Moderation, exactly as for social posts.
Your server hears new ratings: AddEventHandler('phone:appReviewed', function(src, appId, rating) end),
and can read them: exports.phone:GetAppRating(appId, function(r) end) (r.rating, r.count, r.installs).
6. Paid apps and what the server owner controls
The phone never handles money. If you sell your app, declare where:
paid = { url = 'https://you.tebex.io/package/123', price = '9.99 USD' }. Server owners buy it
from you and install your resource as usual. Players always see Get and Open - they
never pay - and staff (ace phone.admin) see your store link on your app and developer pages.
The server owner decides what is offered in config/apps.lua (Config.AppStore):
| Setting | Effect |
|---|---|
allow = { ... } |
only these apps (ids or resource names); empty = all |
deny = { ... } |
never offered; wins over everything |
jobs = { app = { 'mechanic' } } or { app = { police = 2 } } |
per-job access, with a lowest grade, on top of the app's own job |
freeHere = true or { 'app_id' } |
paid apps offered free to players: all, or only those listed (the rest are visible to staff only, with a note) |
storeLinks = 'staff' |
who sees a paid app's store link: 'staff', 'everyone', 'nobody' |
featured = { ... } |
the Featured shelf, in order |
reviews = { enabled, maxLength, perHour } |
ratings and reviews |
capabilities = { web = true, media = true } |
v3: true every app that declares it, false none, { 'app_id', 'resource' } only these |
An app that is not offered to a player is missing from their phone and refused on the server for
every message, request and data call. Config.Addons.allowCustomPages = false (config/config.lua)
restricts every add-on to the declarative pages.
7. Your Lua
Server
-- fire-and-forget from the page (and 'open' / 'close' when the app is shown / left)
AddEventHandler('phone:app:rsp_notes', function(src, event, payload) end)
-- requests: call reply(result) - now or later (after a DB read). 10 s timeout.
AddEventHandler('phone:app:rsp_notes:request', function(src, event, payload, reply)
if event == 'notes:list' then return reply(loadNotes(src)) end
reply(nil) -- always answer unknown events
end)
exports.phone:SendAppMessage(src, 'rsp_notes', 'notes:added', note) -- to one player's page
exports.phone:BroadcastApp('rsp_notes', 'dispatch', data, 'police') -- to every player (job filter optional)
exports.phone:Notify(src, { app = 'rsp_notes', title = '…', body = '…', deepLink = 'note/abc' })
exports.phone:SetBadge(src, 'rsp_notes', 3)
exports.phone:GetApps(src) -- the apps this player is offered (job, grade, items, owner rules)
exports.phone:GetPhoneNumber(src) -- '481-2097' or nil
exports.phone:SourceOfNumber('481-2097') -- src or nil
exports.phone:Set('rsp_notes', owner, 'key', value) -- per-app key/value storage
exports.phone:Get('rsp_notes', owner, 'key', function(value) end)A notification's deepLink is the route inside your app: tapping it opens your app and
your page receives deeplink with that route (also when it is already open). For an app that
declares notifications, Notify returns false (and nothing is shown) until the player allowed it.
To push to everyone who may see an app (grades and items included), loop GetPlayers() and
check GetApps(src) - the dispatch example does.
Client (optional)
For what only the game client knows (position, vehicle, inventory UI):
AddEventHandler('phone:app:rsp_notes', function(event, payload) end) -- incl. 'open'/'close'
AddEventHandler('phone:app:rsp_notes:request', function(event, payload, reply) end) -- side = 'client'
exports.phone:SendAppMessage('rsp_notes', 'env', { inVehicle = true }) -- to the page, no server trip
exports.phone:IsAppOpen('rsp_notes')8. Security model (read this)
- The phone's own callbacks are the phone's. Any page in the game's browser can send a
request to
https://phone/<callback>, a page inside the phone included. Every one of the phone's NUI callbacks refuses a request without the phone page's own key (a random key per session, sent only to the phone's page by the game, never to a frame inside it), so an app's page cannot call them itself - not the owner panel, not the permissions, not another app's storage. The phone acts for your page only through the messages below, and always as YOUR app: the app id comes from the frame that sent the message, never from what the page wrote. - The phone number is personal.
context.numberisnullunless the player allowed your appcontacts; your server can always askexports.phone:GetPhoneNumber(src). - Every page runs in its own frame. The page runs in an
<iframe sandbox="allow-scripts allow-forms">withoutallow-same-origin: it cannot read the phone's document, storage or NUI callbacks, cannot navigate the top window, cannot open popups. An app the server grantedwebkeeps its own origin - its resource's (https://cfx-nui-<resource>) or its site's - and never the phone's or another resource's: a page whose address is on the phone's origin or on another resource's gets no origin, whatever it declared. Its messages are then checked against that exact origin both ways, so a frame that navigated elsewhere stops hearing the phone. - Never delegated: camera, microphone, location, screen capture, USB, serial, HID, Bluetooth,
payment and clipboard reading are switched off in every app's frame (
allow="… 'none'"). The player's data reaches a page only through the SDK calls above.mediadelegates autoplay, full screen, protected media and picture-in-picture, and only to the app it was granted to. - The phone accepts a message only from your iframe's window, and scopes every action to
your app id: a page cannot notify, badge or message as another app. Game (NUI) messages
are only accepted from the phone's own window, so a page cannot forge them.
rspulse.jsin turn accepts messages only from the phone (never from a frame your page embeds). - An app id belongs to the resource that registered it while that resource runs: another resource registering the same id is refused.
- Messages reach only the resource that registered the app, and only for players who can see it (job, grade and items are re-checked on every message and request on the server).
- Each page is rate-limited (60 messages/second; excess is dropped with a console warning).
- Contacts, photos and the camera only by consent. The page never gets a list unless the
player allowed it: the phone draws the picker and the page receives the one contact or photo the
player taps. The Camera opens only after the player answers the phone's own prompt. The native
sheets answer only while your app is the one on screen (
'not-visible'otherwise), one at a time ('busy'), and at most 8 in 20 seconds ('rate-limited'); call prompts at most 3 in 30 seconds. - Calls, messages and other apps are the player's.
RSPulse.callplaces nothing until the player taps Call;RSPulse.messages.composeopens Messages and the player presses Send;RSPulse.opentakes the player to another app only after they tap Open. - Sound stops with the app. An app with
webormediais unloaded shortly after it leaves the screen (section 13); every page's own<audio>/<video>is paused byrspulse.js. - Every parameter crossing the frame is checked by type and length on the phone side; anything
else is refused with
bad-params, never passed through. Theme values handed to a page are plain colours, lengths and font names only. - Treat every payload as client input. It came from a player's machine. Validate and
clamp it, and never take an identity from it - use
srcandGetPhoneNumber(src). - Permissions are enforced on the server (section 3): the player's answer is checked for every data request, and a page never receives a list it was not allowed.
- Reviews and ratings are players' own: one per phone per app, rate limited, filtered by the server's word list and moderated like posts.
Config.Addons.allowCustomPages = false(phone config) restricts add-ons to the declarative pages;Config.AppStoredecides which apps are offered at all and which capabilities they get (section 6). AdevUrlis used only withset pulse_dev_apps true.
9. Protocol reference (for pages not using rspulse.js)
Page → phone: parent.postMessage({ rspulse: 1, type, ... }, '*')
| type | fields | effect |
|---|---|---|
ready |
zoom? |
phone replies context, then delivers anything queued, then a pending deeplink |
send |
event, payload |
client phone:app:<id> + server phone:app:<id> |
request |
id, event, payload, side? |
answered by response with the same id |
notify |
title, body, deepLink? |
notification (if notify ~= false) |
badge |
count |
icon badge (if badge = true) |
open |
link |
'<app>' or '<app>/<route>'; your own id → deeplink; another app opens after the player taps Open in the phone's alert (4 in 30 s, only while your app is on screen) |
home |
- | leave the app |
haptic |
kind |
system haptic |
typing |
active |
a text field has focus: the character stops walking while typing |
sdk |
id, method, params |
a native sheet or Island activity (methods: pickContact, pickPhoto, alert, confirm, actionSheet, prompt, capturePhoto, activity.start, activity.update, activity.end; SDK v2: permissions.query, permissions.request, contacts.list, photos.list, location.get, storage.get, storage.set, storage.remove, storage.keys, orientation.set, orientation.get, sound.play; SDK v3: call, messages.compose, back.set, fullscreen.set, volume.get); answered by response with the same id |
Phone → page: { rspulse: 1, app, type, ... } (to '*', or to the page's own origin when it kept one)
| type | fields |
|---|---|
context |
version, number (only for an app the player allowed contacts, else null), theme, textScale, reduceMotion, safeArea{top,bottom,left,right}, size{width,height}, locale; SDK v2 adds api, orientation, dir, accent, permissions (declared ones: granted, denied or prompt); SDK v3 (api: 3) adds os{look,style}, device{model,form,hinge,fold}, tokens, volume, inCall, lifecycle, capabilities, restored, preview |
message |
event, payload |
response |
id, ok, data or error (timeout, unknown-app, failed; for sdk: cancelled, busy, rate-limited, not-visible, unknown-method, bad-params: …, and SDK v2: denied, not-asked, not-declared, orientation-locked, too-large, full; SDK v3: in-call) |
deeplink |
route |
orientation |
orientation: the phone turned |
permission |
permission, state: an answer changed (prompt or Settings) |
capture |
requestId, ok, url or error (cancelled, timeout), state: the photo a capturePhoto asked for, sent after ready |
lifecycle |
v3: state (active, inactive, background), reason (open, controlCentre, notificationCentre, switcher, home, other-app, locked, display-off, put-away, folded) |
volume |
v3: volume 0..1, the phone's media volume |
call |
v3: active: a phone call started or ended |
back |
v3: the player swiped back (only while the page enabled it with back.set) |
Page address parameters: rsp_app, rsp_theme, rsp_safe_top, rsp_safe_bottom, and SDK v2: rsp_dir, rsp_accent, rsp_orientation.
The wire marker stays rspulse: 1 for every version, so a v1, v2 and v3 page talk to the same phone; a page tells the difference from context.api.
10. Not supported
- Registering from the client (apps are server-registered so job gating, permissions and the App Hub stay authoritative). Apps written for another phone's API do add themselves from the client; section 11.
- Selling inside the phone: there are no prices, purchases or in-app payments, by design (section 6).
- A page reading the phone's own data beyond the permissions above (messages, call history, the whole photo library at once). Anything more, ask your Lua, which can use the phone's server exports.
- Microphone, camera stream or screen capture from a page (the Camera is the phone's, section 2).
- Background playback: an app's sound stops when the player leaves it (section 13). Music that should keep playing belongs in the phone's Music app or your own resource's sound system.
- A page drawn over other apps, or on the Pulse Flip's small cover screen: the cover shows the time and notifications, and your app is in the background while the Flip is shut.
11. Apps written for another phone's API
Many servers already run custom apps (dispatch, banking, job boards, taxis) written for the
custom-app API of the phone resource named lb-phone. Those apps run on Pulse Phone without
being edited, through the app compatibility resource in the developer kit,
pulse-phone-app-compat/. The app opens in the phone's own app
frame, follows the player's light/dark setting, and its popups, menus, pickers and
notifications are drawn by Pulse in Pulse's style.
Installing
- Copy
pulse-phone-app-compat/out of the kit'soptional-developer-kit/folder into yourresources/folder, next to the app resources you already have. - Remove the old phone and its
ensureline, if it is still there. The compatibility resource answers in that phone's place (fxmanifestprovide 'lb-phone'), so the two can't run together. While a resource namedlb-phoneis running, the compatibility resource stands aside (and says so in the console when it starts). - In
server.cfg, start it after the phone and before the apps:
cfg
ensure phone
ensure pulse-phone-app-compat
ensure my-dispatch-app
ensure my-bank-app
Nothing else changes: the apps keep their own folders, scripts and pages. A renamed phone is
found by its pulse_phone 'yes' manifest line, or name it with
setr pulse_phone_resource "my_phone". When the phone or the compatibility resource restarts,
every app is added again by itself.
What players see
- The app is on the Home Screen and in the App Hub like any add-on, installed by default.
Players can remove it in the App Hub and get it back there; its
onDelete/onInstallrun when they do. - Opening it shows its page inside the phone, with the phone's status bar, Home gesture and
back swipe.
data-themeon the page isdarkorlight, andsettings/onSettingsChangefollow the player's appearance. - An app without a page runs its
onUsewhen opened, and the phone returns to where it was. - A page that does not load within 15 seconds shows "App Didn't Load" with Try Again.
Supported calls
Client exports, called as the apps already do (exports["lb-phone"]:AddCustomApp(...)):
| Export | On Pulse Phone |
|---|---|
AddCustomApp(app) |
identifier, name, description, developer, ui, icon, onUse, onOpen, onClose, onInstall, onDelete. Returns true or false, reason; a refusal also prints the reason in the client console |
RemoveCustomApp(identifier) |
only the resource that added the app can remove it |
SendCustomAppMessage(identifier, data) |
data arrives as the page's own message event (onNuiEvent / useNuiEvent match data.action) |
SetPopUp(data) |
title, description, picture, one text field, up to 6 buttons (blue, red, green, yellow); the pressed button's cb runs |
SetContextMenu(data) |
the phone's action sheet with Cancel; up to 8 entries |
ShowComponent(options, cb) |
contactselector and gallery, while one of the calling resource's apps is open |
SendNotification(data) |
app (the app's identifier), title, content |
OpenApp(app) / CloseApp(options?) |
the phone's own apps by plain name (Messages, Maps, Clock ...) and compat apps by identifier |
IsOpen, ToggleOpen(open?), IsDisabled, ToggleDisabled(disabled), GetEquippedPhoneNumber, FormatNumber, HasPhoneItem, IsInCall, GetAirplaneMode, GetFlashlight, ToggleFlashlight(on), GetBattery, IsCharging, IsPhoneDead |
forwarded to Pulse Phone's own client exports |
RegisterClientCallback, AwaitCallback, TriggerCallback |
callbacks between the app's client and server scripts (15 s timeout) |
Server exports:
| Export | On Pulse Phone |
|---|---|
RegisterCallback(event, handler, options?), BaseCallback(event, handler, options?) |
options: preventSpam, rateLimit (per player per minute; 60 when not set), defaultReturn. BaseCallback passes the player's phone number after the source, and answers defaultReturn to a player without one |
AwaitClientCallback(event, source, ...), TriggerClientCallback(event, source, cb, ...) |
only the asked player can answer |
SendNotification(target, data) |
to a server ID, or to a phone number while its player is online |
GetEquippedPhoneNumber(source or identifier), GetSourceFromNumber, FormatNumber, HasPhoneItem, IsPhoneDead, IsInCall, EndCall |
forwarded to Pulse Phone's own server exports |
Events raised under that phone's names: client lb-phone:phoneToggled and
lb-phone:numberChanged, server lb-phone:numberChanged.
The page gets, after componentsLoaded: fetchNui(event, data) (to the app's own
resource only), onNuiEvent / useNuiEvent, settings, getSettings, onSettingsChange,
sendNotification, setApp, createCall (the player confirms first), formatPhoneNumber,
resourceName, appName, appIdentifier, and in components: setPopUp,
setContextMenu, setContactSelector, setGallery (photos), setFullscreenImage,
saveToGallery, setHomeIndicatorVisible. The older globals setPopUp, setContextMenu
and selectGallery work too.
Not supported
Each of these is refused openly: the player sees "Not Available" when they tap something that needs it, and the console names it once.
createGameRenderandGameMap(the in-app camera view and map),uploadMedia,fetchPhone,useCamera/SetCameraComponent, and the GIF, emoji, colour and music pickers and the share sheet.price(apps are free here),landscape(their pages open upright),game,imagesandsizeare accepted and ignored.fixBlurchanges nothing: pages are drawn sharp anyway.defaultApp = false: the app is installed like any other; players remove it in the App Hub.fetchNui(event, data, otherResource): a page reaches only its own resource.- Calling a company with
createCall, video pickers, and more than one text field in a popup (the first is shown). - Every export not listed above. A script calling one gets FiveM's own
No such exporterror. Only start the compatibility resource if you use such apps: while it runs, other scripts that look for that phone find it too, and only the calls above answer.
Security
- A page is served from its own resource (
uimust name the resource that adds the app), so its storage is its own, and it cannot navigate the phone, open windows or raise browser dialogs. - The popups, menus and pickers a page asks for appear only while its app is on screen, one at a time and at most 8 in 20 seconds. A page gets a contact or photo only when the player picks one, and its call starts only after the player taps Call. A page's notifications are capped at 10 in 10 seconds, its saved photos at 5 a minute and its requests at 60 a second.
- Treat these apps like any other resource that runs on players' machines: whatever their page or client script sends to the server is client input, and money or items must be checked on the server.
Tested
Three test apps written from the public documentation (a page with a popup and notifications, a board with server callbacks, menus, the contact picker and removal, and an app with no page) run through the compatibility resource and Pulse Phone in automated tests. Apps you run that do not behave: send their name and the client console output to support.
12. Look native on every OS and the Duo
Pulse handsets do not share one look. The Ultra, Titanium, Clear and Flip each run their own OS look, the player can choose a style for it, every look has a light and a Dark Mode, and the Pulse Duo runs its own OS on a cover screen and, open, across two screens with a fold between them. A page on SDK v3 gets all of it, live:
On <html> / in the context |
Values |
|---|---|
data-os / context.os.look |
ultra, titanium, clear, flip, duo |
data-os-style / context.os.style |
the style the player chose for that look (default, or a style's id) |
data-device / context.device.form |
phone, duo-cover (the Duo shut), duo-spread (open across both screens), tablet |
data-model / context.device.model |
ultra, titanium, clear, flip, book (the Duo) |
data-theme |
light, dark |
data-lifecycle |
active, inactive, background |
The phone's own values, as CSS variables, for the current look, style and appearance:
| Variable | Use |
|---|---|
--rsp-bg, --rsp-bg-2 |
a plain screen's background |
--rsp-grouped-bg, --rsp-grouped-bg-2 |
a grouped list's background and its rows |
--rsp-label, --rsp-label-2, --rsp-label-3 |
text: primary, secondary, tertiary |
--rsp-separator, --rsp-fill-3 |
hairlines, fields and pressed rows |
--rsp-tint, --rsp-link |
the look's tint: buttons, links, the selection |
--rsp-blue, --rsp-red, --rsp-green, --rsp-orange, --rsp-yellow, --rsp-destructive |
system colours, adjusted per look and appearance |
--rsp-model-accent |
the handset's own accent |
--rsp-r-card, --rsp-r-button, --rsp-r-sheet, --rsp-screen-radius |
corner radii |
--rsp-font-ui, --rsp-font-display, --rsp-font-rounded, --rsp-font-mono |
the look's font families (see the note below) |
--rsp-hinge-x, --rsp-hinge-width |
the Duo open: where the fold is, in page pixels (0 elsewhere) |
--rsp-volume |
the media volume, 0..1 |
RSPulse.tokens holds the same values for script. pulse.css (developer kit) is an optional
stylesheet built only on these: an inset grouped list (.group, .row), a large title, buttons,
fields, empty states, a navigation bar with the back chevron, and .split for the Duo. Every
example uses it, so each one takes the look of the handset it runs on with no code of its own.
Fonts. The variables name the look's font families. A page cannot load the phone's own font
files (they belong to the phone's origin): ship the font files you want in your resource and list
them under files { }, or let the family list fall back to the system font.
The Pulse Duo.
- Shut (
duo-cover). A single tall screen. Its camera sits in the top corner below the status bar; the context's top safe area keeps your page under it - use--rsp-safe-top. - Open (
duo-spread). Your page spans both screens (context.sizeis the whole spread) with the fold atcontext.device.hinge({ x, width }). Never put text or a control across it: lay out two panes, one each side.pulse.cssdoes it for you:
```html
```
On a phone .split is a plain block (show one pane at a time); on the Duo open it becomes two
columns, one each side of the fold. The notes and dispatch examples show list and detail side by
side; the web view gives a web page the right screen to itself.
- The context changes when the Duo is opened or shut while your app is open: listen to context.
The Pulse Flip. context.device.fold is open or shut. Shut, your app is in the background
(section 13): the cover shows the time and notifications.
Text size and motion. --rsp-text-scale follows Settings › Display › Text Size; multiply your
font sizes by it. rsp-reduce-motion on <html> means the player asked for less motion.
13. Lifecycle, sound and web content
Lifecycle. The page always knows whether it is on screen:
| State | When | Your page |
|---|---|---|
active |
on screen, taking input | run |
inactive |
on screen under something the phone draws: Control Centre, notifications, the app switcher | keep running; do not start sound |
background |
not on screen: Home, another app, locked, the display off, the phone put away, a Flip folded shut | save what you need, stop sound |
RSPulse.on('lifecycle', ({ state, reason }) => …)
RSPulse.on('pause', () => saveDraft()) // to background
RSPulse.on('resume', () => refresh()) // back from background
RSPulse.lifecycle // the state nowThe server hears open and close as before (section 7).
Sound follows the phone. RSPulse.volume (0..1) is the phone's media volume, and the volume
event fires when the player presses the volume buttons. rspulse.js applies it to your page's own
<audio> and <video> elements (turn off with RSPulse.autoVolume = false if you mix sound
yourself), pauses them in the background and resumes the ones it paused when the player comes back
(RSPulse.autoPause = false to do it yourself). During a phone call (RSPulse.inCall, the call
event) duck or pause your sound. A page's sound is heard by the player only - it is not world audio.
A player embedded from another site (an <iframe> in your page) is outside your page: neither
rspulse.js nor the phone can reach into it. So:
- forward the volume to it in the way that site's player offers (most embeddable players take
commands by
postMessageor have an iframe API with a volume and a pause call); the web view example posts{ type: 'pulse:volume', volume }to the page it shows, which your own pages can listen for; - the phone unloads every app with
webormediaabout a second after it goes to the background - that is what guarantees an embedded player falls silent. When the player returns, the page loads again and its context saysrestored: true: put it back fromRSPulse.storage(save onpause).
Web content (web) keeps your page's own origin, so a page or player it embeds keeps its own
origin too and runs as in a browser. Without web your page and everything it embeds has no
origin: most embeddable players and web apps refuse to start then. Many sites refuse to be shown
inside another page at all (X-Frame-Options, frame-ancestors); nothing in a phone can change
that - choose pages that allow embedding, or host your own. Popups and navigating the phone are
never allowed; links that open a new window do nothing.
Media (media) lets your page and what it embeds start sound without a tap, go full screen,
play protected streams (where the game's browser supports them) and picture-in-picture. When a
player in your page goes full screen, rspulse.js turns the phone sideways for it (apps declared
orientation = 'any' or 'landscape'); RSPulse.fullscreen(true) does it on demand.
14. Calls, messages, back and full screen
await RSPulse.call('555-0142', { video: false }) // "Call 555-0142?" - only the player's tap places it
// rejects 'cancelled', 'in-call', 'busy', 'rate-limited' (3 in 30 s), or the call's own reason
await RSPulse.messages.compose({ to: '555-0142' }) // opens that conversation in Messages
await RSPulse.messages.compose({ body: 'On my way' }) // a new message with this text; the player picks the recipient
// the player always presses Send; your app is left (it goes to the background)
await RSPulse.back.enable(true) // while your page has somewhere to go back to
RSPulse.on('back', () => closeDetail()) // the edge swipe and Backspace come here
await RSPulse.back.enable(false) // at your root: the swipe does nothing, as in the phone's apps
await RSPulse.fullscreen(true) // turns the phone sideways (orientation 'any' / 'landscape')Turn back on only while it means something (a detail screen open), and turn it off at your root: the phone's own apps behave the same way, and players expect the swipe to do nothing at the top level of an app.
15. Templates, TypeScript and hot reload
Vanilla (pulse-phone-template-vanilla/): HTML, CSS and JavaScript, no build step. Edit ui/,
ensure the resource again, reopen the app.
React (pulse-phone-template-react/): React, TypeScript and Vite. The source is in web/, the
built page in ui/ (already built, so ensure works as shipped).
cd web
npm install
npm run dev # http://127.0.0.1:5173 in a desktop browser, with hot reload
npm run build # writes ../ui for the phonepulse-phone-template-react/src/pulse.ts has typed hooks over rspulse.js: usePulseContext, useLifecycle,
useVolume, useForm (phone / Duo cover / Duo spread), usePulseEvent, useServerMessage,
useBack(handler | null) and useStorage(key, initial). The template's Vite settings matter:
base: './', target: 'chrome103', and one classic script (not a module) - see the comment in
vite.config.ts. Vue, Svelte or anything else works the same way: load rspulse.js with a
classic <script> first, build with relative paths for Chromium 103.
TypeScript types: rspulse.d.ts (in pulse-phone-sdk/ and in every example) declares
window.RSPulse and every event, call and context field. In TypeScript, include it in your
project; in plain JavaScript, put // @ts-check and /// <reference path="rspulse.d.ts" /> at the
top of your script for editor hints (every example does).
Hot reload inside the phone. On your development server only:
- keep
npm run devrunning (the React template serves onhttp://127.0.0.1:5173/); - register with
devUrl = 'http://127.0.0.1:5173/'(the React template already does); - add
set pulse_dev_apps trueto that server'sserver.cfgand restart the phone.
The phone then loads your app from the dev server, and every save shows in game at once. The
console says so for each app; without the convar devUrl is ignored, so leaving it in your
resource is harmless on a live server. devUrl must be http(s)://127.0.0.1 or localhost.
16. Troubleshooting
| What you see | Why, and the fix |
|---|---|
| The app is not on the phone | The console says why at registration (add-on "x" rejected: …). No line at all: your resource started before the phone, or did not register on the phone's onResourceStart. Also check the app's job / items and Config.AppStore (allow, deny, jobs, paid apps). |
refused: the id belongs to … |
Another running resource registered that id first. Pick your own id. |
| "App Didn't Load" | The page did not load in 15 s: a wrong page.url, the file missing from files { }, or an external page that is down. Open the address in a browser. |
| A blank page, scripts not running | A <script type="module"> (or a crossorigin stylesheet) without web: use classic scripts (the React template's build does), or declare web. |
| An embedded site stays blank | The site forbids being shown inside other pages (X-Frame-Options / frame-ancestors), or you have no web capability, or the owner turned it off (context.capabilities). |
| Sound starts only after a tap, or full screen does nothing | No media capability, or the owner turned it off. Check context.capabilities.media. |
| Sound keeps playing after leaving the app | Only possible for sound outside the SDK's reach in an app without web / media (a player in an iframe): declare media, which makes the phone unload the app in the background. |
| The page loses its place when the player comes back | Apps with web / media are unloaded in the background: save on pause, restore when context.restored is true. |
A call rejects not-visible |
Your app is not the one on screen (it was closed, or the phone is locked). |
Rejects not-declared / denied |
Declare the permission in RegisterApp; the player refused it - they change it in Settings › Apps. |
Rejects unknown-app |
This player is not offered the app (job, grade, items, owner rules), or the app was unregistered. |
| Text or buttons under the camera on the Duo, or across the fold | Use --rsp-safe-top and, open, the .split panes or --rsp-hinge-x / --rsp-hinge-width. |
| Colours look wrong on one handset | Use the --rsp-* variables instead of fixed colours; check light and dark. |
devUrl is ignored |
set pulse_dev_apps true is missing from server.cfg, or the address is not on this machine. |
| The page works in a browser but not in game | The game's browser is Chromium 103: newer CSS or JavaScript does not run there. Build for chrome103. |
phone_api in the server console prints the whole API. The client console (F8) shows a page's
script errors.
17. API reference at a glance
Page (window.RSPulse)
| Member | Returns / does |
|---|---|
ready, context, api, version, app |
the first context (Promise), the latest context, SDK level (1-3), rspulse.js version, your app id |
on(name, fn) / off(name, fn) |
events: context, lifecycle, pause, resume, volume, call, back, deeplink, orientation, permission, capture, message, message:<event>, resize; on returns an unsubscribe function |
lifecycle, volume, inCall, orientation, os, device, tokens |
the phone's state now |
autoVolume, autoPause |
your own media follows the phone (default true) |
send(event, payload), request(event, payload, { side }) |
your Lua (section 7) |
notify, badge, open, home, haptic, sound |
section 2 |
pickContact, pickPhoto, alert, confirm, actionSheet, prompt, capturePhoto |
the phone's sheets (section 2) |
activity.start / update / end |
one Island activity (section 2) |
permissions.query / request, contacts.list, photos.list, location.get |
section 3 |
storage.get / set / remove / keys |
section 4 |
setOrientation(mode), fullscreen(on) |
turn the phone (orientation any / landscape) |
back.enable(on), call(number, { video }), messages.compose({ to } \| { body }) |
section 14 |
devHandlers, devSdk, devSimulate(type, data) |
a plain browser only (section 2) |
Server (exports.phone:…): RegisterApp, UnregisterApp, SendAppMessage / EmitApp,
BroadcastApp, Notify, SetBadge, GetApps, Set, Get, GetPhoneNumber, SourceOfNumber,
HasAppPermission, GetAppContacts, GetAppPhotos, GetAppLocation, GetAppRating, and the
Island activity exports (EXPORTS.md section 14). Events: phone:app:<id>, phone:app:<id>:request,
phone:app:<id>:permission, phone:appReviewed, phone:notification:action.
Client (exports.phone:…): SendAppMessage(appId, event, payload), IsAppOpen(appId);
events phone:app:<id> (incl. open / close) and phone:app:<id>:request.