Configuration

88. The most useful settings

All in config/config.lua unless another file is named. Restart the phone after a change.

The customer package has six configuration files:

Translations and inventory definitions stay in locales/ and items/. Search for the Config name to jump to a setting. The optional developer kit contains example apps and custom integration templates; it is not required to install the phone.

The other keys: Left Alt switches between the phone cursor and looking around (Config.Keys.cursor), Y answers a call and Backspace declines it without taking the phone out (Config.Keys.answer, Config.Keys.decline). Changing a default only affects players who have not bound that key yet.

The four handset models

The phone resource includes all four models. New phones are Pulse Titanium unless you change Config.Device.default.

Choose the models the clerk sells with Config.Device.storeModels (all four by default). Prices are Config.Store.phonePrice, and Config.Store.modelPrices for a model with its own price (flip = 1099). Each model has its own held prop and charging placement. Storage sizes are a gameplay setting; they don't use that much disk space on your server.

The Pulse Flip is two models: pulse_flip (open) and pulse_flip_closed (shut).

• It is shut in the pocket, on the ground and in its box.
• It flicks open with a snap as the phone comes up, and snaps shut as it is put away.
• It never opens or closes while held to the ear in a call.
• Other players see the same state.

A player gets a Flip in any of these ways:

• The store: they pick the Pulse Flip in the showroom. Without unique phones, a player who already has a phone gets the new handset in its place, with the same number and data.
• As the default: set Config.Device.default = 'flip', and new phones are Flips.
• Unique phones (Config.Item.unique = true): a blank phone item with the metadata phoneModel = 'flip' becomes a Flip the first time it is used.

Older records with the model pro or promax show as the Pulse Ultra handset, in their own finish. Their numbers and IMEIs are unchanged.

Colours and finishes

Every model comes in the 13 classic finishes: Natural Titanium, Desert Titanium, White Titanium, Black Titanium, Deep Blue, Sky Blue, Deep Purple, Sage Green, Sunset Orange, Crimson, Rose, Gold and Silver.

Each model also has its own exclusive finishes, sold on that model only:

How a player gets a finish. In the store showroom they pick a model, a finish and a storage size. The phone arrives in that finish, sealed in its box if boxes are on. A sealed box keeps its model and finish when given to someone else only on ox_inventory, qb-inventory and qs-inventory (section 4). The finish belongs to that handset: players can't change it in Settings. A different colour means buying another phone. On servers that use colour items, the finish comes from the item instead (Config.Item.variants, or the phone item's phoneColour metadata with unique phones).

What you control (config/config.lua):

You can't switch off a single exclusive. A model you don't sell (Config.Device.storeModels) has none of its exclusives in the store.

Accessories: Pulse Reserve, Reserve Max and the wired Pulse cable. The store previews the accessory on the selected handset. Keep existing inventory IDs such as pulse_magpack and exports such as UseMagPack: these are stable integration names, not the displayed product name.

Dead, downed, cuffed, jailed: player states (Config.Block)

Most death scripts revive the player and play a dead animation, and QBCore and Qbox cuffs don't use the game's own handcuff flag, so the phone reads the state those scripts already publish, with nothing to set up, for: qb-ambulancejob, qb-policejob, qb-prison, qb-smallresources (hands up), qbx_medical, qbx_police, qbx_prison, ESX Legacy / esx_ambulancejob, esx_policejob, esx_jail, ox_core / ox_police, ars_ambulancejob, wasabi_ambulance (v1 and v2), wasabi_police, osp_ambulance and rcore_police.

Each state in Config.Block.states has a mode:

By default dead, cuffed, head-bagged, escorted, carried, jailed, hands up, underwater, swimming, parachuting and ragdolled players are blocked, a downed player (laststand) is emergency-only, and driving is allowed (drivingKmh sets the speed above which driving counts).

• Config.Block.calls says what happens to a call already live when a state starts: 'hangup' ends every line (an emergency call is kept under 'emergency-only'), 'keep' lets it carry on, 'hold' puts every line on hold.
• A phone switched off by a script (SetPhoneDisabled / SetDisabled) is always blocked. Its calls follow calls.disabled ('keep'), so a cutscene that hides the phone doesn't end a call.
• Your own scripts (a jail, a cutscene, surgery) can add a state from the client: exports.phone:SetRestriction('surgery', 'block'), and nil to clear it. It is kept per resource and cleared when that resource stops. Add its key to calls to choose what happens to a live call.
• The server checks the same states before it accepts a request, and other scripts can read the published phone restrictions; see Exports for custom scripts.

Unique phones

Config.Item.unique = true stores the number on the item (needs ox_inventory, qb-inventory, qs-inventory, core_inventory or codem-inventory):

• Each phone item is its own handset with its own number, messages and photos. Handing it over, dropping it or having it stolen hands over the phone. A player carrying two can switch between them.
• A new item gets its number the first time it is used, written to its phoneNumber metadata and shown in its tooltip.
• Config.Item.variants = { phone_black = 'black' } adds phone items in other finishes.
• Face Unlock belongs to the person, so a stolen phone doesn't unlock. Wrong-passcode attempts and the lockout belong to the phone, so dropping and picking it up again keeps the lockout.
• A player who leaves while holding someone else's phone drops it where they stood.
• Keeping a number on a new handset. A player whose phone was lost or stolen marks it lost in Locate, then on their new phone opens Settings > General > Backups > Phone Number and moves the old number over with the old phone's passcode. Messages, calls, voicemail and contacts come with the number; the old handset gets a fresh number, and the new phone's own number is retired. Only the owner can do it, once per Config.Backups.numberTransferCooldown minutes (30). Turn it off with Config.Backups.numberTransfer = false.

Battery and charging

The server keeps the charge and saves it per phone (per item, with unique phones). Idle, screen on, calls, camera, music and GPS each add to the drain. At 20 % the phone offers Low Power Mode. At 0 % apps and calls stop except the emergency numbers, and incoming calls ring out. Config.Battery.enabled = false turns the battery off.

The Reserve and the cable (Config.Charging, on by default) are items that work like the real things, and everyone nearby sees them on the phone in the player's hand:

• Use the item to put it on, and again to take it off. Settings > Battery shows what is attached, the pack's level, and Remove / Unplug. /phonepack and /phonecable do the same as using the item (the item is still needed when an inventory runs). Rename or remove them in Config.Charging.commands.
• A full Reserve fills 70 % of a phone, a Reserve Max 120 % (magpack.variants). Plugging the cable in at a real power source while a pack is on charges both. magpack.unlimited = true makes packs never run down; consumeWhenEmpty = true (the default) removes a spent pack.
• Config.Charging.requireCable = false lets vehicles and charging spots charge on their own.
• Charging spots: Config.Charging.cable.spots, plus every Config.Battery.charge.zones entry, checked on the server. Charger props rely on what the player's game reports, so they stay off unless you set trustClientProps = true. Another script (a house, a charging station) can declare a source with exports.phone:SetPowerSource(source, 'my_house'), and clear it with false.
• Standalone (no inventory): every player carries both, unless standaloneOwnsAccessories = false.
• Config.Charging.enabled = false removes the accessories and brings back the old power bank.
• Exports: UseMagPack, UseChargingCable, DetachChargers, GetChargingState, SetPowerSource, SetBattery, GetBattery, IsCharging, ToggleCharging, UsePowerbank (Exports).

The Pulse Store

A clerk at Legion Square (Config.Store.locations: add as many counters as you like) opens the store: every model turning in every finish, an accessories aisle, a bag with quantities, checkout by card or cash, a receipt, and a Sell & Trade-in counter. Walk up and press E, or use ox_target / qb-target on the clerk.

Everything is decided on the server: the store screen only sends product ids and quantities, and prices come from Config.Store. The whole bag is charged once. If any item can't be handed over (inventory full, item missing), everything already handed over is taken back and the full amount refunded, and the player is told which item didn't fit.

The box and the unboxing. With Config.Store.box = true a phone is handed over sealed in its box. Using the box plays a short scene (about 7 seconds): the lid lifts, the phone comes out of its tray into the hand, and only then does the server swap the box for the phone. Space or Backspace skips it (the phone is still handed over). Damage, a fall, getting into a vehicle, water or death before that moment stops it, and the box stays in the inventory. Nearby players see it too. Config.Store.cinematic = false keeps the animation without the close camera. With no inventory at all (standalone), the phone changes at the counter and the scene plays straight after checkout.

What the box turns into: with unique phones, a new phone item in that finish; with Config.Item.required, the phone item (a Config.Item.variants item when the finish has one); otherwise the character's phone takes the new model and finish, and keeps its number, apps and data.

Sell & Trade-in (Config.Store.sell): the store buys back used phones and accessories for percent (40) of its own price, and sealed boxes for sealedPercent (70), paid to payTo ('cash'). The server removes the item first and pays second; if the payment fails, the item is given back.

• The player's only phone is never bought, and neither is the phone in use.
• With unique phones, a traded-in handset is factory reset and its line switched off. Its row stays in the database, and its number is never handed out again. This needs ox_inventory, qb-inventory or qs-inventory to tell handsets apart; on other inventories phones are listed but not bought.
• A Reserve or cable that is the player's last one is taken off the phone before it is sold.

The other settings (pay, maxQuantity, maxPhones, accessories, storage, specs) are explained beside them in Config.Store.

The Wallet's bank

Nothing to install. Every option is in config/apps.lua, and the defaults work as they are.

• Sign-in. The Wallet opens behind Face Unlock or the passcode, checked on the server. Five wrong passcodes lock it for two minutes (session.attempts, session.lockoutSecs); five idle minutes sign it out (session.idleMinutes). A phone with no passcode opens straight away.
• Moving money between the player's own accounts is debited first and refunded if the second step fails, and never counts toward dailyLimit. Cash in and out is an ATM action: only at an ATM (atms, the base-game positions; add your map's) or inside a branch (branches, plus every Config.Maps pin in the bank category).
• Card controls. Locking the card stops every payment from the phone and ATM withdrawals, on the server. Scheduled payments wait until it is unlocked. Other scripts can ask exports.phone:IsWalletCardLocked(src).
• Scheduled payments (once, weekly, monthly) are paid by the server when due, so a restart loses nothing. With a framework, a payment due while the owner is away runs when they return.
• Pay by code: a short single-use code another player types in to pay them. Neither sees the other's number.
• The weekly limit (Config.Wallet.weeklyLimit) and sending to offline players (Config.Wallet.transferOffline, on) are in config/apps.lua.

Bills

Wallet > Bills lists what a player owes and what they have paid. A bill can be paid, never declined. Bills come from the phone's own list (sent by any script with SendBill) and from the billing script you already run, read from its own table (readExternal = true, needs oxmysql):

Paying takes the money from the player's bank, then gives it to the company's account (through the company-account script) or to the player who sent it. If that credit fails, the payer gets the money back and the bill stays unpaid. A bill nobody can receive is refused before anything is taken, unless payToCity = true (then it is paid as a city fine).

Sending a bill from your script (server side):

-- sender: a player's server id, or a name ('police', 'city_hall'). society: optional job name.
exports.phone:SendBill(senderSrc, targetSrc, 250, 'Speeding on Route 68', 'police', function(ok, idOrReason)
    if not ok then print('bill refused: ' .. idOrReason) end
end)
local bills = exports.phone:GetBills(src)      -- { unpaid = { ... }, paid = { ... } }

targetSrc must be online. A zero, negative or fractional amount, one over maxAmount, billing yourself, and a sender over perMinute are refused. The settings are Config.Bills in config/config.lua.

Carrier plans and eSIM (off by default)

With Config.Carrier.enabled = false (the default) every phone has service and nothing is billed. To switch it on without editing the config, add setr phone_carrier 1 to server.cfg. Then:

• A phone has no service until its owner buys a plan in the Carrier app. No plan means no calls, no texts and no internet apps (the full list is Config.Carrier.services). Emergency numbers always work, with no plan, no signal and no charge. Payphones work too.
• Signal. With requireSignal = true, zero bars is no service. Each carrier has its own coverage by GTA zone: stronger towers (boost), dead zones (dead) and roaming zones (only on plans with roaming = true).
• Plans are weekly or monthly with talk minutes, texts and data (numbers or 'unlimited'). When an allowance runs out, the player is told and that service stops until the plan renews.
• Billing is from the character's bank. A plan renews by itself; the player can cancel. A renewal that fails starts graceDays of grace, then the line is suspended until paid. Renewals only charge a player who is online.
• eSIM only: there is no SIM item. Transfer eSIM moves a plan to another handset of the same character.
• Department plans: jobPlans gives members of a job a free plan (police, sheriff, ambulance and ems by default).

Three example carriers ship (Badger, Tinkle, Whiz Wireless); keep carrier names fictional. Other scripts can use exports.phone:HasService(src, 'call' | 'text' | 'data') and exports.phone:GetCarrierStatus(src).

Dead zones (Config.Coverage, off by default)

Places where phones lose signal: tunnels, bunkers, an island, high altitude. Works with or without the Carrier.

• The server decides. Every 2 seconds it works out the bars allowed where each player stands. A modified game can lower its own bars, never raise them.
• Zones: sphere, box or poly (up to 256). mode = 'cap' means at most bars; mode = 'floor' is a repeater. Also altitude, depth and interiors.
• With enforce = true, zero bars works like "No Service", and a call in progress ends after dropGraceSecs. Emergency calls and texts always work and are never ended by a zone.

In game, with the phone.admin ace (zones placed this way are saved and apply at once):

Other scripts: exports.phone:GetCoverage(src).

Maps: your public places

Config.Maps in config/config.lua lists the pins every player sees: your hospital, police stations, garages, shops. Each is a pin, a row under its category and a search result, with Directions (the game's GPS) and Set Waypoint. Ten examples ship; replace them with yours, then restart the phone.

Config.Maps.enabled = false hides every public pin (players' own saved places still work). The map art is Zslash's GTA V World Map; keep the credit line the Maps app shows.

Pulse Drive (the car screen)

In the driver's seat, players open Pulse Drive with F10 (Config.Keys.drive, or /pulsedrive): a car screen low in the middle of the view with the map and turn cards, what is playing (the phone's music and the car radio's station), favourites and recent calls, and incoming messages. Calls run hands-free with the phone in the pocket. Players drag the bar above the screen to put it anywhere, and pick its size and whether it comes up by itself in Settings > Pulse Drive.

Config.Drive in config/config.lua: enabled (false removes it for everyone), passengers (also offer it in the front passenger seat), autoShow (the default for players who have not chosen) and ignoreClasses (vehicle classes with no screen, such as bicycles and trains).

Music and Videos (a free YouTube key, optional)

Radio stations in Music are Config.Music.stations in config/music.lua, as YouTube video ids. Long mixes work best.

Without a key the Videos app plays any link a player pastes in. With a YouTube Data API key it also has search, trending, view and like counts, channel videos and comments.

1. In Google Cloud Console (console.cloud.google.com), create a project.
2. APIs & Services > Library: enable YouTube Data API v3.
3. APIs & Services > Credentials > Create credentials > API key. Restrict it to that API.
4. Put it in server.cfg:

set phone_youtube_key    "<your key>"   # `set`, never `setr`: the key never leaves the server
set phone_youtube_region "US"           # trending country, a two-letter code
set phone_youtube_safe   "moderate"     # none | moderate | strict
set phone_youtube_quota  10000          # your project's daily units

Google gives 10,000 units a day free, with no card. A search costs 100 units, most other calls 1 or 2. The phone caches every answer on the server and shares it between players, limits each player, and keeps the last 300 units of the day for trending and details. When searches run out, the app says search is resting and pasted links still play. bad-key means the key is wrong; api-off means the API isn't enabled on its project.

Web search in the Browser (optional)

Out of the box the Browser searches only the in-world sites. With a key it also lists real web results beneath them. Set one provider's key in server.cfg:

# Brave Search API: one key
set phone_search_key "<your Brave Search key>"

# or Google Programmable Search: an API key and the search engine id
set phone_search_key "<your Google API key>"
set phone_search_cx  "<your search engine id>"

Then set Config.Browser.webSearch.provider in config/apps.lua to 'brave' or 'google' (also resultCount, safeSearch, perMinute and cacheSeconds). The key stays on the server: players only receive titles, addresses and short snippets. A result opens inside the phone when the site allows it; most large sites don't, and then the phone offers Copy Link.

The assistant (Aria)

Aria is built in: nothing to install, no account, no API key and no outside service. She understands typed requests on the phone itself and acts through the phone's own apps. Players open her with the side button (hold) or the Action Button. She places calls, drafts texts (sent only on Send), reads messages and calls, sets timers, alarms and reminders, uses the calendar and notes, routes to places (including your Config.Maps pins), tells the weather, flips switches such as Do Not Disturb, plays Music stations, and answers sums and conversions. Anything else gets a plain answer saying what she can do instead; she never makes up a fact.

She is typed, not spoken to (the game's browser has no microphone input), replies on screen, and works in English. Config.Assistant.enabled = false switches her off.

Your own ringtones, alert tones and wallpapers

Put the files in ownermedia/ (its README has the formats and sizes), then list each one in Config.OwnerMedia in config/config.lua with the name players see. They appear in a Server group above the built-in ones. Restart: the console checks every entry and prints one line per problem with the fix. phone:ownermedia prints the check again.

Config.OwnerMedia.defaults is what a new phone starts with. A value is one of your files, or a built-in one by name:

• ringtones: solstice meridian cascade ember waypoint quartz halo onyx lantern tidal relay atrium drift belfry ridgeline filament ascend nocturne skip harbour
• tones: glint droplet pebble lumen arc triad ivory stepwise milestone umbra charm swell zephyr ticker patter refresh
• wallpapers: aurora ribbon bloom tide sierra ember iris mint slate vinewood chiliad pier graphite obsidian

A default that is neither prints a warning, and new phones get the built-in default. Changing a default later only reaches phones still on the built-in one. If you remove a file, phones that chose it fall back to a built-in one by themselves.

Server music (the Server Library)

Your own songs, in the Music app under Server Library (on For You, in Library and in search). Players can play them, shuffle them, add them to playlists and play them out loud.

1. Put .mp3, .ogg (Vorbis or Opus) or .flac files in ownermedia/music/. Nothing goes in the config.
2. Restart the server, or type phone:musiclibrary in the server console to read the folder again without a restart. The console prints one line per file it skipped, with the reason and the fix, then the total.

Where each song's details come from, first match wins:

Limits: 25 MB a song (Config.MusicLibrary.maxFileMb) and 500 songs (maxTracks), in config/music.lua. File names may use letters, numbers, spaces and - _ . ( ) ' , & !, with a lower-case extension. The file's contents are checked, so a renamed .wav or .m4a is refused with a message rather than failing silently in the phone. (.m4a and .wav are not accepted: convert them to MP3 or Ogg, for example with Audacity.)

Players do not download these when they join. A song is streamed from your server only to the phone playing it, a slice at a time, the same way the phone's photos and videos load. If photos load in game, songs will; servers behind a proxy that set phone_media_origin for photos need nothing else.

Hosts that cannot list a folder. The phone reads ownermedia/music/ itself at start. A few managed hosts do not allow that; the console then says so. List your songs by hand in ownermedia/music/library.json instead:

["Artist - Title.mp3", { "file": "other.ogg", "title": "Other Song", "artist": "Someone" }]

Songs are your responsibility: only add music you have the right to play on your server.

Playing out loud and parties

In Music's full player, Output > Play Out Loud lets the people around a phone hear what it plays. Each listener's own phone plays the same song quietly from where the host stands: it gets quieter with distance and through walls and closed cars. A Server Library song is also panned to the side the phone is on and muffled the further away and the more is in the way; a YouTube station gets the right loudness only (the game's browser does not let a page reshape another site's sound). Nothing is streamed between players; the server only passes on what is playing and where.

With Party on, phones nearby see a card at the top of Music with Join. A guest's phone plays the host's song in step with the host, follows pauses, seeks and song changes, and drops out when the guest leaves, plays something else, or walks out of partyRange.

Out loud stops for everyone, at once, when the host turns it off, puts the phone away, drops it, dies or is restrained (Config.Block), runs out of battery, moves the sound to the earpiece or an accessory, or leaves the server. A listener who walks out of earshot stops hearing it. The phone only plays out loud from its speaker, and never in another routing bucket.

Config.MusicSpeaker in config/music.lua:

Listeners are worked out on the server once a second, only while someone plays out loud. Each listener's client measures distance and direction five times a second, only while a phone nearby is playing, and nothing runs at all otherwise.

Microphone and recordings

Settings > Privacy & Security > Microphone lets a player check their microphone: whether the phone gets one, a live level meter, and a five-second test they can play back. When there is no microphone it says why (refused, not found, no answer, not available in this client) and what to do. The first time, FiveM asks at the top of the screen; the player presses Y to allow it.

What carries the player's voice: video clips from the Camera, and Voice Memos and voice messages (Config.AudioRecording). The game's own sound and other players' voice chat are played by the game itself and cannot be recorded by any phone script; the page says so to players.

Home Wi-Fi

Settings are in config/apps.lua. Players buy Pulse Home Wi-Fi (item pulse_router, $350) at the Pulse Store and use it from their inventory. A see-through router follows where they look: the scroll wheel or Q / E turns it, ENTER or left click places it, BACKSPACE or right click cancels. It stays in the world, through restarts, until its owner picks it up in Settings > Wi-Fi > Manage Router while standing next to it. The item goes back into their inventory.

On a router's Wi-Fi a phone's data is free (it does not count against a Carrier plan) and works in dead zones. Calls and texts use Wi-Fi Calling and work with no signal, but a Carrier plan is still needed for them when the Carrier is on. Owners rename the network, change or remove its password, restart it, and remove or unblock devices. Phones can also share their mobile data with Personal Hotspot; with the Carrier on, this needs a plan that includes hotspot data.

Where a router may go (placement):

maxPerPlayer (2) and minSpacing (8 m) always apply. The housing scripts in section 7 are read for this through their home lists. To use your own rule instead, call exports.phone:SetRouterPlacementCheck (Exports). On a standalone server with no inventory, players place a router with /phonerouter and need no item.

Burner phones

Settings are in config/apps.lua. Players buy a Pulse Burner (item pulse_burner, $150) at the Pulse Store and use it from their inventory. It comes out of their pocket instead of their Pulse and works as a phone of its own: its own number, contacts, texts and calls. It has no apps, no internet, no camera, no Wallet and no Wi-Fi (its calls and texts always use the mobile network). Nothing a player can see links it to the character. Closing the phone puts it back in the pocket.

• Two phones, one hand. While the burner is in the hand, the main phone is in the pocket: a call to it rings there (people nearby hear it) and ends as a missed call, unless the player puts the burner away while it rings - then the main phone comes out and the call rings on it. Its texts wait until the main phone comes out again. While the main phone is in use, a call to the burner makes it buzz and shows "Incoming call on your burner"; it rings out as a missed call on the burner, unless the player closes the main phone while it rings - then the burner comes out.
• Calls and texts to a burner reach whoever carries it. A call makes them take it out; a text buzzes it in the pocket. If nobody carries it, or its carrier is dead, cuffed or otherwise blocked (Config.Block), callers hear "not available".
• On ox_inventory, qb-inventory and qs-inventory the burner is the item itself: hand it over, drop it or lose it, and its number goes with it. On other inventories each character has one burner (maxPerPlayer).
• Destroy Burner (in its settings, or /burner destroy) snaps it in half. The item is removed and the number is dead for good. A police tap on it ends, and its texts are deleted after purgeHours (default: at once).
• With the Carrier on, a burner's plan is paid in cash, never from the bank, so no statement links it to the character. It has its own battery, which lasts longer (batteryDrainMultiplier).
• Selling a burner back at the Pulse Store retires it, the same as destroying it.
• On a standalone server with no inventory, /burner takes out the character's burner and no item is needed.

Phone damage, protection and repairs

Settings are in config/apps.lua. A hard fall, a heavy crash or a hit taken with the phone in hand can crack the screen, and a second crack makes it badly cracked: the cracks show on the screen and on the phone in the player's hand, and a tap on the damaged glass can now and then miss. Swimming or diving with the phone lets water in: the screen flickers for a while, then the phone stops until it is repaired. Nothing on the phone is ever lost. The server rolls every outcome; the chances, the times and the prices are all in the file.

• Protection is sold at the Pulse Store and fitted by using the item: the Pulse Case (rugged, far fewer cracks), the Pulse Case Clear, the Pulse Waterproof Pouch (no water damage at all) and the Pulse Screen Protector (takes one crack, then breaks). Settings > General > About > Protection shows what is fitted; a case or the pouch comes off there and goes back in the inventory. An inventory that cannot make items usable fits them with /phoneprotect <id> or at the store counter.
• Repairs are done at the store's Repairs counter, paid like a purchase. Your own job script can repair phones with exports.phone:RepairPhone (docs/EXPORTS.md, section 16).
• The fitted case shows on the handset in the hand when its model is streamed (Config.Damage.cases.models). The Pulse Flip takes no case.
• Test it with phone:damage <id> crack | shatter | water | repair | clear (section 9).

enabled = false turns all of it off.

Police phone taps (Intercept)

Settings are in config/apps.lua. Players with a job in jobs (police, sheriff and state by default), at minGrade or higher and on duty, get the Intercept app. An officer taps a phone number for 1 to 72 hours, with a reason. From then on, every text to or from that number (group texts too) and every call's details (who called whom, answered or not, how long) appear live for every officer on duty, with a silent notification. Officers who were off duty read the log later.

• No live call audio. Nobody can listen in on a call: the voice scripts have no listen-only channel the phone could rely on. A tap shows who called whom and for how long, never what was said. Texts from before the tap started are never shown.
• A tap is on a number, not a person. A burner is caught only once the police learn its number (turn that off with Config.Burner.allowTaps = false). The tapped player is never told.
• Limits: maxActive taps per officer (5), maxServer on the server (50), and no emergency numbers. Every tap added or ended is in the security log with the officer's identifier.
• MDT scripts can use exports.phone:TapNumber, exports.phone:EndTap and the event phone:tap:intercept (Exports).

Hail: city rides

Players get Hail from App Hub. It has both sides: Ride (request a car to a place on the map, see the driver, car and plate, give them your PIN) and Drive (go online in a road car, accept a request, check the rider's PIN, drive, get paid). Every value is explained in config/apps.lua.

• Money uses the Wallet's bank. A bank ride's price is taken when it is booked, and whatever isn't charged comes back (Config.Rides.cancel). Cash rides need a framework with cash. Drivers collect earnings on a Hail balance and cash out to their bank (Config.Rides.payout).
• Drivers must sit in the driver's seat of an allowed vehicle class (Config.Rides.driver.classes, plus models), and optionally hold a job (jobs), carry a licence item (licenceItem) or be inside serviceArea. Anything missing is shown to them.
• Bonus hours (Config.Rides.bonusHours) pay drivers extra for trips starting in a zone at set days and hours. To stop two friends farming it, you can require a minimum trip distance (limits.bonusMinDistance) and cap bonuses per driver and rider per day (limits.bonusPerPairPerDay); both are commented out in config/apps.lua.
• Fares are recorded before the rider is charged, so a restart never loses one. Refunds that can't be paid at once are paid the next time that player is in the city. A restart closes every open trip and gives back everything held for it.
• Safety reports go to the security log; Config.Rides.safety.notifyJobs = { 'police' } also notifies those jobs.

News: the city's newspaper

Players get News from App Hub. Everyone reads; members of your news jobs write. Settings are in config/apps.lua:

• publish lists the jobs and the lowest grade that may write and publish. manage sets the grade from which a member may also edit and unpublish other people's articles. Players with the phone.admin ace count as editors. requireDuty = true limits publishing to on-duty members.
• masthead is the paper's name; categories are its sections, in order.
• A reporter can mark an article Breaking: every phone with News gets a notification, once per article. breaking.cooldownSeconds and breaking.perAuthorSeconds keep it from being a spam button; breaking.enabled = false turns alerts off.
• Text goes through the word filter. Markets shows Business articles, and an asset's page shows the articles that name its ticker.

Emergency SOS after a crash or going down

Settings are Config.Safety in config/apps.lua. When a player goes down (dead or in last stand, read from your death script the same way Config.Block reads it) or has a hard crash in a vehicle, a countdown appears over the game: Calling emergency services in 10... with Cancel and Call Now. Backspace or Esc cancels too. If nobody cancels, the alert goes to service ('ems', a Config.Emergency service): its Services inbox with the player's location, a notification to everyone on duty there, and your dispatch script.

• crashDetect and deathSOS switch each trigger off for the whole server. Players switch them off for themselves in Settings > Emergency SOS.
• countdown is the seconds before the alert goes (5 to 30). The server runs the clock, so a client cannot hurry an alert or hold one back.
• crash = { minKmh = 70, dropKmh = 55 }: the speed the vehicle had, and the speed it lost between two looks half a second apart, that count as a crash rather than braking.
• The server checks the player really is down (death script state, or no health left) or really is in or just out of a damaged vehicle, and allows one alert per cooldown seconds. A player who is revived during the countdown sends nothing.
• jobs adds jobs to the dispatch alert (default: the service's own jobs). notifyContacts texts the player's Medical ID emergency contacts with their location.
• Every alert, sent or cancelled, is kept in phone_sos_log. Other scripts can listen for phone:emergencySOS (source, cause, coords) on the server.

Medical ID

Config.MedicalId in config/apps.lua. Players fill in Settings > Emergency SOS > Medical ID: blood type, allergies, conditions, medications, notes, organ donor and up to maxContacts emergency contacts from their Contacts. It is kept on the server per character (phone_medical_ids).

• Show When Locked: anyone holding the phone can open it from Emergency on the passcode screen (the Medical ID button in the corner), without the passcode. Read only.
• Share During Emergency SOS: the Medical ID goes with an automatic SOS, so responders read it in their Services inbox and dispatch alert.

Reports, blocking and moderation

Config.Moderation in config/apps.lua. In Vibe, Loop, Glint, Echo, Circle, Marketplace and LS Pages, players can Report a post, a story, a comment, a listing or an account (spam, harassment, hate, violence, nudity, scam, pretending to be someone, something else), and Block its author. A block uses the phone's block list: their posts leave the player's feeds, and they cannot message or call them.

• Moderators get Settings > Moderation: open reports, most reported first, with the words and picture reported, then Remove, Restore, Dismiss and Ban (1, 7 or 30 days, or until lifted, from banDays). Removing keeps a copy, so anything can be restored as it was.
• A ban is per app and per phone: no posting, commenting, direct messages, stories or listings in that app, whichever account the phone uses. The player is told.
• autoHide = 5 hides a post from everyone once five different players report it, until a moderator decides. 0 turns that off. reportsPerHour limits reports per player.
• Moderators: the ace phone.moderate (or phone.admin), or a framework admin group listed in groups (ESX groups, QBCore permissions):

add_ace group.admin phone.moderate allow

• Every action is written to phone_moderation_log, the security log and the activity log. phone:modlog [n] prints the newest in the console.

Hide Caller ID

In Config.Calls (config/config.lua): allowHiddenId = true lets players hide their number. Settings > Apps > Phone > Show My Caller ID is each player's default; the Caller ID switch on the keypad changes it for one call, and so does dialling #31# (hide) or *31# (show) before a number. The person called sees No Caller ID, also in Recents, missed calls and voicemail.

• The call log on the server always keeps the real number.
• Players with a job in jobsCanSeeHidden (police by default) see the number anyway.
• Emergency calls are never hidden by this; Config.Emergency.anonymous decides those.

Editing messages and polls

In Config.Messages (config/apps.lua):

• editSeconds = 900: the sender can edit a text message for 15 minutes (up to five times) by holding it and choosing Edit. Everyone sees the new words marked Edited. 0 turns it off. Unsend works as before (unsendSeconds).
• polls = true: Poll in the + drawer of any conversation, one-to-one or group. A question, 2 to 10 answers, one answer or several. Everyone in the conversation sees results live and who voted for what; whoever asked can close it. The server checks every vote.

Shade: the anonymous market (off by default)

Settings are in config/apps.lua; set enabled = true to use it. Shade is in App Hub only for players who meet access: carrying one of access.items (the Pulse VPN Dongle, pulse_vpn, by default), holding one of access.jobs, or access.everyone = true. Lose the item and the app leaves the phone; the server refuses every Shade request from anyone without access, whatever their phone shows.

• Buying. Players see the house catalogue (catalog: item, price, stock per restock, the most per order) and, with playerListings.enabled, other players' listings, all under generated handles ("ashen-cipher-14") - never a name or a number. Prices are always the server's.
• Escrow and the dead drop. Paying takes the money (account: cash by default) and holds it on the order. The server picks a free drop from drops and marks it on the buyer's map; only the buyer sees the small package there (ox_target / qb-target option, else the interact key, E by default, rebindable). Picking it up checks the server's own view of where the buyer stands, hands over the item and releases the money - to the seller, less playerListings.fee, for a player listing. Not collected within pickupMinutes, or cancelled: the buyer is refunded and the stock returns. Nothing is ever charged or handed over twice - not on a double press, a reconnect or a restart. Money owed to someone who has left is paid the next time they are on.
• Selling. Players can list items from playerListings.items. The items leave their bag when they list and come back if they end the listing or it runs out (days); unsold items wait in the app under Collect Items.
• Police heat. heat.chance (0 to 1) tips off heat.jobs through your dispatch script (or phone notifications), somewhere within heat.radius of the drop - at pickup, or at payment with heat.when = 'order'. A catalogue line can set its own heat (0 = never).
• Other scripts can open Shade for a player without an item: exports.phone:SetDarkMarketAccess(src, 'my_script', true), or exports.phone:RegisterDarkMarketAccess(function(src) return ... end) for a rule checked on every request. exports.phone:HasDarkMarketAccess(src) gives the phone's own answer.
• Staff: phone:darkmarket review lists orders a restart or a failing inventory left undecided; phone:darkmarket resolve <order> delivered|refund settles one.

Slipstream: street races

Settings are in config/apps.lua. Players get Slipstream from App Hub.

• Building a track. Tap Build a Track and drive the route, dropping a checkpoint at the start and at each corner - from the app, or with J (rebindable) without taking the phone out. The server records where the player really is each time; nothing is taken from the phone. editor.minSpacing / maxSpacing keep checkpoints sensible. Save it as a circuit (laps back over the start line) or a sprint, with a vehicle class.
• Racing. At a track's start (joinRadius), in the driver's seat, a player hosts a race with an entry fee (minFee..maxFee, from account). Others join from the app at the start line; the host starts a countdown. Everyone sees the next checkpoint in the world, all of them on the map with a GPS route, and a race card on screen with their position, lap and times.
• Prizes. The pool (every fee, less houseCut) is split by payout (60/30/10 by default); shares nobody finished to claim are spread over the finishers. Leaving before the start, the host closing the lobby, a lobby that times out (lobbyMinutes) or a race nobody finishes gives every fee back.
• Fair play. Every checkpoint is checked on the server: the right one, the car really there (checks.slack; three misses disqualify) and not faster than checks.maxSpeed allows over the distance (a disqualification at once, logged). There is no ghost mode: normal collisions apply. Dying in a race takes the racer out (forfeitOnDeath); leaving the server counts as leaving.
• Leaderboards keep each driver's best lap and best race per track, and recent results.

SIM cards and prepaid credit (off by default)

Settings are in config/apps.lua. With both switches off (the default) nothing changes: every phone keeps its own number and calls and texts are free.

• SIM cards (enabled = true). A number lives on a SIM card (item pulse_sim). Every phone holds one; a spare card carries its number on the item, so it can be bought (Pulse Store), traded or stolen. Settings > Cellular > Spare SIM Cards > Insert (or using the item) swaps it with the card in the phone: the phone takes that number, with everything kept under it - conversations, contacts, calls, voicemail, notes and photos - and the card that was in it comes out into the inventory. Settings, passcode and mail stay with the phone. A new card from the store gets a fresh number when first inserted. A number on a spare card is never given to anyone else. Needs ox_inventory, qb-inventory or qs-inventory (item metadata).
• Prepaid (prepaid = true). Each SIM carries credit (startingCredit for a phone's own line). Outgoing calls cost perMinute per started minute and texts perText; incoming calls and texts are free, and emergency numbers always work. Without credit, calls and texts are refused with a clear No Credit alert and a Top Up button; a call is ended when the credit runs out. Top up in Settings (topups, paid from account) or with a Prepaid Top-Up card (pulse_topup, worth topupValue). Prepaid works on every inventory.
• Staff: phone:sim give <player id> [credit] hands out a SIM card; phone:sim credit <number> <amount> adds credit.
• With the Carrier (Config.Carrier) on as well, both apply. Most servers use one or the other.

Pulse Beacons: item trackers

Settings are in config/apps.lua. A Pulse Beacon (item pulse_tracker, sold at the Pulse Store) is paired to whoever uses it first. Keep it in a bag or give it to someone, or use it beside a vehicle to stick it on (attachRange). The owner sees each beacon in Locate > Items: where it was last read and when, who has it (with you, with someone, on a vehicle), with Directions, Rename and, at the car, Take It Off the Vehicle.

• Positions are read by the server every interval seconds, and only while beacons are in use. A vehicle stored and taken out again is found by its plate.
• Safety. A beacon travelling with someone who is not its owner (and whose owner is not with them) for alert.alertAfter seconds warns that person - "Unknown Beacon Found" - and shows it at the top of their Locate, with Switch Off when they are close enough. Turn this off only if your server's rules allow covert tracking.
• Without item metadata (ESX's default inventory and others) a beacon can only be stuck to a vehicle; using it does that straight away.

Activity log

set phone_discord_log          "https://discord.com/api/webhooks/..."
set phone_fivemanage_log_token "<your Fivemanage token>"
set phone_fivemanage_dataset   "phone"

The log records calls and messages, mail, Wallet transfers, bill payments and company money, photos and social posts, job offers, hires and fires, carrier plans, refused media links and the admin commands in section 9. Turn each kind on or off in Config.Logs.actions; a kind not listed there is on. Entries go out in batches, at most one request per destination every 4 seconds. With neither convar set, nothing is logged.

Keys

Players rebind them in Settings > Key Bindings > FiveM. Changing a default only reaches players who have not bound that key yet. Side + Volume Up takes a screenshot; holding Side + Volume Down opens the power menu. While a call rings with the phone put away, the handset rises just far enough to show the caller, and the player keeps full control of their character. The decline key only ever declines a ringing call, never a call in progress, so it is safe to share with menus.

Emergency alerts

Admins, and the jobs you choose, send an alert to every phone in the city or to everyone inside a circle on the map. Settings > Notifications > Emergency Alerts has the history, and a New Alert button for those allowed to send. The settings are in config/apps.lua (Config.Broadcast).

• Who may send: admins (ace phone.admin) always, every level. Add jobs with senders = { 'police:3', 'ambulance:4' } (job, or job:lowest grade) and choose the highest level they may send with jobMax. With requireDuty = true (the default) they must be on duty.
• Limits: one alert per cooldownSeconds (60) and at most perHour (10) per sender, admins included. An area is minRadius to maxRadius metres (50 to 6000).
• From the server console: phone:alert severe Road closed | The bridge on Route 68 is closed.
• Alerts are kept for historyDays (14). Every alert is written to the security log.

Everything else you can switch on

Invoices, the handset lock, Lost Mode and other quiet defaults

Payroll (Wallet > Business): on ESX, QBCore and Qbox it lists every employee and pays offline ones the next time they join. On TMC and custom frameworks only employees who are online right now are listed and paid, because those frameworks give the phone no list of offline staff. On ox_core, ND and vRP company payroll is not available; invoices and fines still work there.

These work out of the box. Each block is written out with its default values, so you can see and change them:

Leaving a block out, or any key in it, uses the value shown.