Opening the Phone#

Players open the phone with a key or by using the phone item. Every key is a FiveM key binding, so players can change it in Settings → Key Bindings → FiveM; the values below are only the defaults.

Key	Does	Config
F1	Open or close the phone.	`Config.Phone.openKey`
Q / E	Answer or decline an incoming call while the phone is closed.	Key bindings
B (hold)	Talk to Aura, the voice assistant (DLC).	`Config.Aura.pushToTalkKey`
T	Fold or unfold a foldable phone.	`Config.Fold.key`

lua

Config.Phone = {
    openKey = 'F1',
    openByKeyPress = true,      -- false = only the item opens the phone
    requireItem = true,         -- false = everyone has a phone, no item needed
    itemName = 'phone',
    blockWhenRestricted = true, -- no phone while handcuffed
}

With blockWhenRestricted, the phone cannot be opened or used for calls while the player is restrained. The check reads the usual handcuff flags; to match your police script, edit framework:isPhoneRestricted() in custom/<framework>/client.lua and server.lua.

Pear, Nova and Foldables#

The phone has two system skins: Pear and Nova. Each one changes the device frame, the system screens and the look of the apps. In the config, Pear is 'ios' and Nova is 'android'. Config.Platform.mode decides how a player gets one:

Mode	How it works
`'item'`	The item decides. `phone` opens Pear and `phone_android` opens Nova. Sell them at different prices in your shops. The switch in Settings is hidden.
`'settings'`	Every phone can switch between Pear and Nova in Settings → Display. The choice is saved per phone.

Config.Platform.default is the skin for phones that never chose one.

Foldable phones#

Two foldable models, each its own item: phone_duo (Pear, short wide cover screen, landscape inner screen) and phone_fold (Nova, tall narrow cover screen, almost square inner screen). They always open their own skin, in both modes. Press T with the phone open to fold or unfold; it is ignored while typing or playing a game.

lua

Config.Fold = {
    iosItemName = 'phone_duo',      -- false = disabled
    androidItemName = 'phone_fold', -- false = disabled
    key = 'T',
    disableControl = 245,           -- the GTA control on the same key (245 = chat); false = none
}

Phone Numbers and SIM Cards#

With Config.MetaSystem.enabled = true (the default) every phone item is its own device: its own number, contacts, messages, photos and settings. Give the phone to someone else and they have your phone, protected only by your passcode and Face Unlock.

With it set to false, the data belongs to the character instead, and any phone item shows the same data.

lua

Config.MetaSystem = {
    enabled = true,
    phoneNumberPrefix = '555',          -- always a string: use '06', not 06
    phoneNumberLength = 7,              -- digits after the prefix
    phoneNumberMask = '(XXX) XXX-XXXX', -- X = digit; must add up to prefix + length
}

For a French-style number use prefix '06', length 8 and mask 'XX XX XX XX XX'.

Feature	What it does
SIM card	Using `phone_sim` gives the phone a new number. Consumed on use by default (`Config.SimCard.consumeOnUse`).
Backup and transfer	Players back up a phone and restore it on a new one. Up to `Config.Backup.maxPerPlayer` (10) backups. Only works with the metadata system on.
Hidden number	A privacy switch in Settings that hides the caller's number. Streamer mode hides personal details on screen.

Service numbers#

Fixed numbers that ring every online player with the right job at once. The first one to answer takes the call. They appear in every player's contacts and favourites, and nobody needs to own them.

lua

Config.ServiceNumbers = {
    enabled = true,
    lines = {
        { number = '911', label = 'Emergency Services', avatar = '', jobs = { 'police', 'ambulance' }, minGrade = 0 },
        { number = '912', label = 'Police',             avatar = '', jobs = { 'police' },              minGrade = 0 },
        { number = '913', label = 'EMS',                avatar = '', jobs = { 'ambulance' },           minGrade = 0 },
    },
}

Calls#

Voice calls go through your voice script; video calls need the TURN server from Installation. Incoming calls show in the Dynamic Island, and players can answer with Q without opening the phone.

Setting	Default	What it does
`PhoneCall.ringTimeoutMs`	10000	How long a call rings before it is missed.
`PhoneCall.playVoicemailOnTimeout`	true	The caller hears a voicemail message when nobody answers.
`CallAudio.speakerDistance`	6.0 m	With the speaker on, players this close hear the other side.
`CallAudio.ambientBleed`	true	pma-voice only: the microphone also picks up people standing right next to each caller (`ambientDistance`, 3 m).
`PhoneSpeaker.distance`	24.0 m	How far others hear music, videos, ringtones and notifications from the phone.

Emergency SOS#

When a player dies, the phone counts down for 10 seconds with an alarm and then texts the player's location to every on-duty medic. The player can cancel during the countdown, or send it by hand with /sos. It uses your ambulance script automatically (see Integrations).

lua

Config.SOS = {
    enabled = true,
    jobs = { 'ambulance' }, -- who receives the SOS
    minGrade = 0,
    healthThreshold = 0,    -- 0 = only on death; > 0 = also below this health
    cooldownSeconds = 90,
    countdownSeconds = 10,
    alertSound = 'alarm',
}

Battery and Charging#

The battery drains slowly with the phone closed, faster with it open, and faster still in heavy apps. At 0% the phone has no signal, so calls and online apps stop working until it is charged. The level is saved with the phone.

Drain	% per minute
Phone closed	0.08
Phone open	0.30 plus the app below
Video call · Maps · Beatzy · Camera · Pictagram	1.40 · 1.05 · 1.05 · 0.95 · 0.92
Music · Chirpy · Zapp · Marketplace	0.58 · 0.44 · 0.42 · 0.38
Notes · Wallet · Settings	0.08 · 0.10 · 0.12

Change any app's drain in Config.Battery.apps, or turn the whole system off with Config.Battery.enabled = false. Players charge in three ways:

Charger	Rate	How
Powerbank	18% / min	Use the `powerbank` item anywhere. Consumed on use; `returnItemWhenDone` gives it back.
Charging station	60% / min	A marker at four 24/7 and LTD stores by default. Walking more than 5 m away stops charging. Add your own in `Config.Battery.chargingStations.points`.
House charger	48% / min	Chargers placed inside qs-housing houses.

Signal#

The map has coverage zones with four signal levels: full, mid, low and none. Outside every zone the signal is full. The default zones cover Mount Chiliad, Raton Canyon, the Tongva hills, the Humane Labs tunnel, the sea around Cayo Perico and other remote places.

Rule	Default
Make or answer a call	low or better
Video calls	mid or better
An active call drops	below low
Online apps (Messages, Mail, social, Wallet…)	mid or better
Offline apps	Always: Settings, Notes, Clock, Calculator, Camera, Gallery, Reminders, Calendar

Add a zone (for example a basement MLO) in Config.Signal.zones with coordinates, a radius and a level. Set Config.Signal.debug = true to see the zones in game, and Config.Signal.enabled = false to turn signal off.

Wireless earbuds#

Using wireless_earbuds shows a pairing card, then music, videos and calls play only for the owner. The buds drain while in use (about 4.5 hours from full) and refill from their case; the case charges with the phone. At 0% audio goes back to the speaker. Settings are in Config.Earbuds.

A share sheet sends contacts, photos (up to 20 at a time) and more to players within 10 m, who accept or decline. Change it in Config.ShareSheet.

Storage#

Each phone has 8 GB. Apps take their size when installed, a photo about 4 MB and a video about 32 MB. When it is full, players delete apps or media, or buy 64 GB and 128 GB upgrades in the Peach Store. Set it in config/appstorage.lua; enabled = false removes the limit.

The Apps#

These apps are installed on every new phone. Add, remove or restrict them to a job in Config.PhoneApplications.

App	What it does
Phone · Contacts · Video Call	Calls, favourites, recents, voicemail, blocked numbers and video calls.
Messages	Texts, group chats, photos, GIFs, locations, reactions and money transfers.
Mail	An in-game email account; scripts can send mail to it.
Camera · Gallery	Photos, selfies and videos up to 60 s with nearby voices; albums and sharing.
Wallet · Crypto	Bank transfers by phone number, bills, and a simulated coin market.
Maps	The GTA map with GPS routes, shops, garages and your own markers.
Music	Quasar playlists, favourites and a player in the Control Center and Dynamic Island.
Home	Your houses from qs-housing or qb-houses: keys, doors and locations.
Health	Steps walked, and warnings for low health, hunger and thirst.
News	Articles written by the jobs in `Config.Weazel.publishJobs`.
App Store · Peach Store	Download more apps; buy powerbanks, earbuds, SIM cards and storage.
Settings · Clock · Calendar · Notes · Reminders · Calculator · Weather · Tips	The everyday system apps.

These are downloaded from the App Store, listed in config/store.lua. An app with a price costs money to download.

App	What it does
Pictagram	Photos, stories, direct messages and live streams.
Chirpy	Short posts, replies, reposts and trends.
Beatzy	Short vertical videos with likes and comments.
Whispr	A chat app with groups, statuses and SMS verification.
Pairly	Dating: swipe, match and chat.
Findly	Classified listings.
Marketplace	Chat with businesses (police, EMS, mechanics, taxi…) whose staff are on duty.
Garages	Your vehicles from your garage script, GPS to them and valet delivery.
Aventon	Rent cars, motorcycles and bicycles at the airport.
Zapp · Zapp Eats	Ride hailing between players, and a food delivery job.
Job Center	Take a job from `Config.JobCenter` and get a GPS route to it.
Onion Browser ($550) · Dark Chat ($250)	An anonymous black market with dead drops, and anonymous chat channels.
Games	Slice Rush, Chick Blast, Turbo Kart, Street Fight, Void Drift ($300), Rescue Fleet and Drift Track ($190).

Any app in either list accepts job (a name or a list), minGrade or grades to limit who can use it. Config.HomeScreenDefaults sets the dock, folders and first page of a new phone, and Config.StoreDownload.secondsPerMb sets how long downloads take.

App Settings#

Every app with a server-side rule has its own block in config/main.lua.

Wallet, Messages payments and Mail

lua

Config.Wallet = {
    account = 'bank',   -- account used for transfers
    minAmount = 1,
    maxAmount = 999999,
}

Config.Messages = {
    PaymentAccount = 'money', -- account used for money sent in a chat
    PaymentMin = 1,
    PaymentMax = 999999,
    PaymentCurrencySymbol = '$',
}

Config.Mail = {
    emailSuffix = '@cloud.com',                   -- must start with @
    systemFromEmail = '[email protected]', -- sender of script mail
    systemFromName = 'Mail',
}

Transfers need the recipient online.

Bills

Unpaid bills appear in Wallet → Bills, read from your billing script. Without one, the phone uses its own billing and the jobs in Config.BillJobs can use /sendbill.

lua

Config.BillJobs = { 'police', 'ambulance' }

Config.BillingJobs = { -- icon shown next to a bill from that job
    police = { label = 'LSPD', icon = 'f7:shield_fill' },
    ambulance = { label = 'EMS', icon = 'f7:cross_case_fill' },
}

Config.BillingFallbackAvatar = 'f7:doc_text_fill'

Marketplace

Shops are listed in config/marketplace.lua. Staff with a matching job press Enter service in the Profile tab to receive customer chats. Keep each shop's id the same once the server is live; chats and ratings are saved against it.

lua

{
    id = 5003,
    name = 'Bennys Motorworks',
    description = 'Performance tuning, repairs, and custom work.',
    job = { 'mechanic' },
    coords = vec3(-205.7, -1310.7, 31.3),
    image = 'https://...',
},

Zapp and Zapp Eats

Config.Zapp sets the penalty for cancelling an accepted ride (50% of the fare) and how close the driver must be to pick up and drop off.

Config.Zappeats sets the delivery points, the menu, tips and payouts. With givePhysicalItem = true, the courier gets the real item and must hand it over; the items must exist in your inventory.

Aventon rentals and Garages valet

Config.Aventon holds the pickup point at the airport, the return point, the categories and the vehicles with their price. Players return the rental by driving to the return marker and pressing E.

lua

Config.Valet = true                  -- valet in the Garages app
Config.ValetPrice = 1000
Config.IcarValetPaymentAccount = 'bank'

Crypto

Three coins ship (Quasar Coin, Los Santos Token, Vinewood Digital). Each has a base price and a volatility; prices move every minute. global sets the trade fee (0.45%), the transfer fee and the trade limits. Set Config.Crypto.enabled = false to remove it.

News and Job Center

lua

Config.Weazel.publishJobs = { -- who can write articles
    { name = 'police', grades = { 0, 1, 2, 3, 4 } },
}

Config.JobCenter = {
    { job = 'taxi', label = 'Taxi Driver', description = 'Pick up riders and earn fares.', Coords = vec2(909.49, -177.24) },
}

Every Job Center job must exist in your framework.

Onion Browser

Two kinds of listings: vendor items from List, and items players sell themselves. A player sale is held by the market until the buyer picks it up, then the seller is paid minus a 5% fee. Every order is collected from a courier at a random dead drop.

lua

Config.OnionBrowser.Payment = {
    method = 'crypto', -- 'crypto' or 'bank'
    coin = 'qsc',
    account = 'bank',
}
Config.OnionBrowser.Market.blockedItems = { 'money', 'black_money', 'id_card' }
Config.OnionBrowser.Delivery.collectMinutes = 30

Camera, Map and Radio

lua

Config.Camera = {
    AllowWalking = true,                 -- walk while the camera is open
    Recording = { MaxDurationSeconds = 60 },
}

Config.ProximityCapture = { enabled = true, radius = 12.0 } -- nearby voices in videos

Config.Map.maxCustomMarkers = 200

Config.RadioPrivateChannels = { -- private channels for the Radio DLC
    { label = 'Police Channel', frequency = 113, password = '3983221' },
}

Map blips for shops, garages and stations are in Config.Map.defaultBlips.

Appearance and performance defaults

Config.DefaultSettings is what a brand-new phone starts with: dark mode, brightness, wallpaper, frame colours, lock screen font. Config.Wallpapers lists the wallpapers and Config.Ringtones the ringtones.

lua

Config.DefaultOptimization = { -- set all to false for low-end PCs
    blur = true,
    filterAnimations = true,
    motionAnimations = true,
}

Once a player changes an option in Settings → Optimization, their own choice wins.

Restart qs-smartphone after any config change. Settings players choose on their phone (wallpaper, language, theme) are saved per phone and are not reset by a restart.

Opening the Phone#

Pear, Nova and Foldables#

Foldable phones#

Phone Numbers and SIM Cards#

Service numbers#

Calls#

Emergency SOS#

Battery and Charging#

Signal#

Earbuds, Sharing and Storage#

Wireless earbuds#

Sharing with nearby players#

Storage#

The Apps#

App Settings#

Opening the Phone#

Pear, Nova and Foldables#

Foldable phones#

Phone Numbers and SIM Cards#

Service numbers#

Calls#

Emergency SOS#

Battery and Charging#

Signal#

Earbuds, Sharing and Storage#

Wireless earbuds#

Sharing with nearby players#

Storage#

The Apps#

App Settings#

Opening the Phone#

Pear, Nova and Foldables#

Foldable phones#

Phone Numbers and SIM Cards#

Service numbers#

Calls#

Emergency SOS#

Battery and Charging#

Signal#

Earbuds, Sharing and Storage#

Wireless earbuds#

Sharing with nearby players#

Storage#

The Apps#

App Settings#

Opening the Phone#

Pear, Nova and Foldables#

Foldable phones#

Phone Numbers and SIM Cards#

Service numbers#

Calls#

Emergency SOS#

Battery and Charging#

Signal#

Earbuds, Sharing and Storage#

Wireless earbuds#

Sharing with nearby players#

Storage#

The Apps#

App Settings#