Features

Apps and phone setup

The app list, the home screen, bundled and custom apps, the smaller built-in apps and the phone in the player's hand.

This page covers which apps a phone has, the home screen, the bundled and custom apps, the smaller apps that have their own settings, and the phone in the player's hand.

Bigger apps have their own pages: Camera, Calls, Services, Live, Anon, Wallet, Bank, invoices and crypto, Cases and accessories, Messaging, Social apps and Health.

#1. The app list (Config.Apps)

Every core app has one line in Config.Apps. The line decides whether a new phone has the app, where it sits and who may use it.

lua{ id = 'phone', default = true, dock = true, category = 'communication', removable = false },
Field What it does
id The core app id. Do not change it
default true: installed on a new phone. false: the player installs it from the App Store
dock Placed in the dock of a new phone
category The App Store category
removable false: the player cannot uninstall it
label Optional name instead of the one in the locale
icon Optional icon id
hidden true removes the app from every phone. enabled = false does the same
jobs Optional list of job names. Only those jobs see the app, and the server refuses its requests from anyone else

Changes to default and dock only reach new phones and phones that are reset. Players who already have a phone keep their own apps.

Staff with the god role can switch any app off and on from the admin tablet while the server runs. Players' phones get the new list at once.

#2. The home screen (Config.HomeScreen)

The layout of a phone that was never arranged: a new player, or a phone after a reset. Once a player moves their own icons, their layout is kept.

Option Default What it does
Widget { 'weather', 'medium' } The widget on top of the first page: { name, size }. false: no widget
FirstPage 14 app ids The apps on the first page, in this order

Widget names: 'weather', 'calendar', 'clock', 'photos', 'bank', 'favorites', 'notes', 'alarms'. Sizes: 'small', 'medium', 'large'.

FirstPage takes core app ids and the identifiers of bundled apps (for example 'fx_music', 'fx-billing'). Under a medium widget about 16 icons fit. Apps the player does not have are skipped; every other app follows from the second page on. The dock takes the apps marked dock = true.

#3. Bundled apps (Config.BundledApps)

Fixitfy apps that come with fx-phone in their own folder ([fx-apps] in the examples below; use the folder name from your package). Each one is its own resource, with its own page under Features.

Resource App
fx-billingapp Billing: invoices
fx-casinoapps Fixitfy Play: phone games
fx-companyapp Company: employees, funds, directory
fx-fansapp Fans: creator subscriptions
fx-garageapp My Vehicles: garage and valet
fx-mapsapp Maps: friends' live locations
fx-metubeapp MeTube: videos and TV screens
fx-musicapp Music: streaming, speakers, Dynamic Island
fx-orderapp Order: businesses, menus, delivery, couriers
fx-rentalapp Rental: player-to-player car rental

Each resource has a true / false entry. Set one to false and fx-phone stops it from starting; if it is already running when fx-phone starts, fx-phone stops it. An app that is not installed is ignored.

Start fx-phone before the folder:

cfgensure fx-phone
ensure [fx-apps]

While fx-billingapp runs, the core Invoices icon leaves the home screen, so players see one invoice app. The invoice service itself keeps working: Bank still lists bills and scripts still bill through fx-phone's exports.

#4. Custom apps (Config.CustomApps)

Your own apps, shown in an iframe on the phone. Config.CustomApps registers apps without any Lua: a web page on an https:// address or a page in another resource. It takes the same fields as the AddCustomApp export.

luaConfig.CustomApps = {
    {
        identifier = 'wiki',
        name = 'City Wiki',
        description = 'Rules, laws and maps.',
        ui = 'https://wiki.example.com/phone',
        icon = 'https://wiki.example.com/icon.png',
        defaultApp = true,
        category = 'utilities',
    },
}
  • ui must be an https:// address or resource/path. An entry with a bad ui is skipped.
  • A price set here is charged as written; Config.Limits.AppPriceMax only caps apps added by another resource.
  • The admin tablet can switch these apps off like core apps.
  • They get the fx-phone:customApp:opened / closed events and SendCustomAppMessage, like apps added by a resource. The page's nuiCallback messages reach a resource (as <resource>:phoneApp:event) only when the entry names it with resource = 'my-resource'.

To build an app with Lua and messages between the page and your script, use the export: Client exports: custom apps. Storage for custom apps: Server exports: app data.

#5. Pawly (Config.Pets)

A virtual pet. The player adopts a cat, dog, bunny, panda or fox, names it and looks after it.

#How it works

  • A pet has six needs: hunger, thirst, clean, fun, energy and health. They drop over time, also while the player is offline, at half the speed while the pet sleeps. Energy comes back while it sleeps.
  • Health falls while hunger, thirst or clean is nearly empty, or while the pet is left in a mess for hours. It comes back while the basic needs are fine.
  • Actions: Feed, Water, Wash, Medicine and Toy use up a supply; Play, petting and cleaning up after it are free. Each action has a short cooldown. Actions give XP, and every 100 XP is a level.
  • Supplies are bought in packs from the shop in the app, paid from the bank. A pet holds at most 99 of each.
  • A pet can be shown in the Dynamic Island.
  • Release gives the pet up for good.

#Sharing

The owner offers a pet to another player by phone number. Once they accept, both look after it and see what the other did in the pet's diary. The owner can take a carer off; a carer can leave. Only the owner can rename or release it.

#Families

Two grown pets, a girl and a boy, can be brought together from the Nest. They can both be the player's own, or one shared with them.

  1. A pet is a baby for BabyDays days, a youngster until AdultDays days, then grown.
  2. Both pets must be awake and well. Each meeting fills one heart; the same pair can meet again after DateCooldown seconds.
  3. With Hearts hearts full, the mother lays an egg. It goes to the mother's owner and waits in the Nest.
  4. After HatchHours hours the egg can be hatched into a baby, if its owner has room for another pet.

A pet's gender is fixed when it is adopted and cannot be chosen.

#Options

Option Default What it does
Enabled true Switches adopting and families off when false
MaxPets 3 Own pets per player. Hatching needs a free place too
AdoptPrice 500 Price of adopting, from the bank
MaxMembers 1 Other players one pet can be shared with. 0 turns sharing off
MaxShared 3 Shared pets one player can look after besides their own
Family.Enabled true Switches families on
Family.BabyDays 2 Days a pet is a baby
Family.AdultDays 5 Age in days from which a pet is grown
Family.Hearts 3 Meetings needed for an egg (1 to 9)
Family.DateCooldown 3600 Seconds between two meetings of the same pair
Family.HatchHours 6 Hours until an egg can be hatched
Family.SameSpecies true false: any two kinds can have a baby, which takes after one of them
Shop 5 supplies food, water, soap, medicine, toy, each { price, amount }: price of one pack and how many are in it

Default shop: food 60 for 5, water 30 for 5, soap 45 for 3, medicine 180 for 1, toy 90 for 3.

#6. Arcade (Config.Arcade)

Seven phone games: Hop, Merge, Mines, Serpent, Stack, Drop Four and Tic Tac.

  • The first five are played alone. Each game keeps the player's best score, a city record and a leaderboard. A score that could not be reached in the time the round took is refused.
  • Drop Four and Tic Tac are played on the server, against the phone or against a friend. A friend is invited by phone number and must be online; the invite runs out after 60 seconds, and each turn has 45 seconds. Wins, losses and draws have their own leaderboard.
Option Default What it does
Enabled true false: no new rounds can be started
Leaderboard 20 Players shown per game (5 to 50)
AiSlip 0.2 How often the phone misses a block or plays a loose move. 0: never

#7. Calendar (Config.Calendar)

Personal events and public events everyone can see.

  • Personal events (personal, work, gym, gaming, music, family) are only seen by their owner.
  • Public events (event, meetup, party, car meet, race, business) appear in everyone's calendar. Others can mark themselves as going.
  • An event can last up to 31 days and can have a place on the map.
  • A reminder can be set: at the start, or 5, 15, 30, 60 minutes or one day before. The owner, and everyone going to a public event, get a notification.

With PublicApproval = true a new public event waits in the Approvals list until phone staff accept it. Staff are players with any admin tablet role; their own public events need no approval, and they can edit or delete any public event. The owner gets a notification when their event is accepted or refused. Editing a public event sends it back for approval.

Option Default What it does
PublicApproval true Public events wait for staff approval
MaxEvents 200 Upcoming events one character may keep
MaxPublicPerDay 3 Public events one character may announce per day

Events that ended more than 60 days ago are deleted a minute after the server starts.

#8. Voice Memos (Config.VoiceMemos)

Records audio with the player's microphone and keeps it on the phone, in folders. Recordings are uploaded to your upload provider like photos.

Option Default What it does
MaxMemos 100 Recordings one character keeps
MaxSeconds 600 Longest recording, in seconds

A 10 minute recording is about 2.4 MB. Your upload host must accept files that size, and Config.Limits.UploadBytes (default 6 MB) must be above it.

#9. Clock

World clock, alarms, stopwatch and timer. A character can keep 20 alarms, each with a time, a label and the weekdays it repeats on (no days: it rings once). There are no options.

#10. Weather (Config.Weather)

Shows the current weather, an hourly forecast for 24 hours and a 10 day forecast.

Only the current weather type is read from the game or your weather resource. The temperature, wind, humidity and forecast are worked out from that type, the time and the date, so every player sees the same forecast. The forecast is made up, not what your weather resource will really do next.

Option Default What it does
Sync 'auto' Where the current weather comes from: 'auto', 'native', 'Renewed-Weathersync', 'qb-weathersync', 'cd_easytime'
Units 'metric' 'metric' (°C, km/h, km, hPa) or 'imperial' (°F, mph, mi, inHg)

'auto' uses the first of Renewed-Weathersync, qb-weathersync and cd_easytime that is running, otherwise the game's own weather. A named resource that is not running also falls back to the game.

#11. AirDrop (Config.Airdrop)

Sends a photo or video, a contact card or a location to a player standing close by.

  1. The sender picks AirDrop. Players within Range metres show up as devices, nearest first, at most 20.
  2. The sender picks a device. The receiver gets an offer with a preview.
  3. The receiver accepts or declines. An offer nobody answers is withdrawn after OfferSeconds seconds.

A photo that is accepted goes into the receiver's Photos. A sender can have 3 offers open at once.

Who can find a player is set in their Settings: Everyone, Contacts Only (the default) or Off. Airplane mode and Bluetooth off hide the player too, and a blocked number never finds them.

Option Default What it does
Enabled true Switches AirDrop on
Range 12.0 Metres. Only players this close show up
OfferSeconds 30 Seconds before an unanswered offer is withdrawn

Scripts can send a photo to a player with AirShare: Server exports: media.

#12. Phone-wide settings

Option Default What it does
Config.NameChange true Players may change the owner name on their phone. false: the character name is always used
Config.Scale 0.8 Size of the phone on screen. Players adjust it in Settings
Config.Variation 'burgundy' The colour a new phone starts in (one of the 14 phone colours). Existing phones keep theirs; phones moved over with fxphone:migrate start in it
Config.Time.Format 24 24 or 12 hour clock
Config.Time.RealTime true true: the real server time. false: the in-game clock
Config.Number.Length 7 Digits generated after the prefix for a new number
Config.Number.Prefix '' Digits put in front of every new number, e.g. '555'
Config.Wallpapers the 30 files shipped, '01-concept-18-burgundy.webp' to '30-zumrut.webp' Files in html/assets/wallpapers/ offered in Settings and on the lock screen, in this order; the first is a new phone's wallpaper. A small copy of the same name in thumbs/ (.webp) is used in the lists when it is there
Config.Ringtones 4 tones { id, label }. Plays html/assets/sounds/<id>.wav
Config.NotificationSounds 6 sounds Same for notification sounds

To add your own tone, put <id>.ogg in html/assets/sounds/, add the id to html/assets/sounds/overrides.json (a JSON list of ids) and add a line to Config.Ringtones or Config.NotificationSounds.

Number only affects new numbers. Raise Length if the console reports that no free number is left.

#13. The phone in the hand (Config.Prop, Config.Animation)

#The prop

With fx-phone-assets running, the phone in the player's hand is the 3D model of their phone colour, with the case and accessories they put on it. Without it, the game prop in Model is used.

Option Default What it does
Model ` prop_npc_phone_02 ` The prop used without the assets resource, or while a model cannot load
Assets 'fx-phone-assets' The resource with the phone models
Bone 28422 The hand bone the prop is attached to
Offset vector3(0.0, 0.0, 0.0) Position on the bone
Rotation vector3(0.0, 0.0, 0.0) Rotation on the bone

If a model is listed but does not load in 3 seconds (for example the assets resource was started while the player was already connected), the game prop is used for a minute and the console says so. Reconnecting fixes it.

#The animation

Style What the character does
'ambient' (default) The game's own street phone clips, with gestures while talking. Male and female clips differ
'classic' The standard phone clips
'custom' Your own clips from Custom

Custom takes text, call, walkText, walkCall, camera and selfie, each { dict = '...', anim = '...' }. Anything left out falls back to the built-in clip. Custom is only read with Style = 'custom'.

Some clips are always the same, whatever the style:

  • In a vehicle the classic clips are used.
  • Walking during a call uses the classic call clip with the 'ambient' style.
  • With the camera open, the pose comes from Config.Camera.Pose (see Camera), unless 'custom' gives a camera or selfie clip.

A clip that does not load falls back to the classic clip, with a warning in the F8 console.

#Good to know

  • A new app does not appear for existing players. default = true only installs it on new or reset phones. Players install it from the App Store.
  • An app is gone for some players. It has a jobs list, or staff switched it off on the admin tablet.
  • Two invoice apps. Not possible while fx-billingapp runs; if you see both, the bundled app is not started.
  • A bundled app will not start. Check Config.BundledApps and that fx-phone starts before [fx-apps].
  • Pets lose health while the player is away. Needs keep dropping offline (at most a week is counted). Supplies and a shared carer help.
  • The weather app disagrees with the sky. Check Config.Weather.Sync and that your weather resource starts before fx-phone. Only the current weather is real; the forecast is made up.
  • The hand is empty or holds the old prop. fx-phone-assets is not running, or was started after the player connected.