Configuration

Appearance and sound

The phone prop, animations, size, colour, wallpapers, ringtones and the sounds other players hear.

Files: configs/config_appearance.lua and configs/config_sound.lua.

#Config.Prop

Setting Type Default What it does
Prop.Model model hash prop_npc_phone_02 Fallback prop in the hand
Prop.Assets string 'fx-phone-assets' Resource with the phone models. While it is started, the phone in the hand is fx_phone_<finish>, in the player's colour
Prop.Bone number 28422 Ped bone the prop is attached to
Prop.Offset vector3 0, 0, 0 Position offset from the bone
Prop.Rotation vector3 0, 0, 0 Rotation in degrees

The way the phone sits in the hand can be adjusted in game with /phonecam > Phone hold. See Camera.

#Config.Animation

Setting Type Default What it does
Animation.Style string 'ambient' 'ambient' uses the game's street phone animations, 'classic' the standard phone clips, 'custom' the clips in Custom
Animation.WalkClips boolean or string 'onehand' false: the phone is held the same way standing and walking. true: taking a step switches to the game's walking phone clips. 'onehand': on the move the phone is read with one hand; standing keeps the two-handed pose
Animation.Foot.Look boolean true On foot, the head turns to the phone while it is read
Animation.Bike table see below How the phone is held on a motorbike or bicycle
Animation.Custom table empty For 'custom': text, call, walkText, walkCall, camera (rear camera), selfie (front camera), each { dict, anim }. Anything left out falls back to the ambient clip

#Animation.Bike

On a bike the game keeps the rider's hands on the handlebar grips, so a phone pose does not show unless that is switched off.

Field Default What it does
Free true true: the arm IK is off while the phone is out, so the arms follow the phone clip. false: as the game does it, hand on the grip
Dict 'ambient' The clips used on a bike. 'ambient' is the same pose as standing with the phone. Other values name an animation dictionary, for example 'cellphone@' or 'anim@cellphone@in_car@ds'
Anim not set With a Dict other than 'ambient': the clip of that set used while the phone is looked at. Left out: the reading pose
Torso true The lean the game adds to a rider's body is off too, so the body follows the clip
Look true Head and neck turn to the phone (not during a call at the ear)
Way not set Left out: 'free', the arms follow the clip. 'measure' tries the arm IK variants one after the other and prints what it finds to the F8 console; 'reach', 'split' or 'left' force one. Hand = vector3(right, forward, up) is where 'reach' sends the phone hand
Moving 'onehand' While the bike moves faster than a walk, the phone is read with one hand and the other stays forward on the bar. MovingDict and MovingAnim name another clip. Left out: the same pose moving or not

#Size and colour

Setting Type Default What it does
Config.Scale number 0.8 Default size of the phone on screen. Players adjust it in Settings
Config.Variation string 'burgundy' The colour a new phone starts in: burgundy, black, silver, white, glacier, light_gold, cosmic_orange, pink, lavender, purple, deep_blue, mist_blue, sage or forest

Players change the colour with a case from the phone shop. A phone that already exists keeps its colour. A phone moved over with fxphone:migrate is new and starts in this colour, with the first wallpaper of Config.Wallpapers.

#Config.Wallpapers

A list of file names in html/assets/wallpapers/, in the order they are offered in Settings and on the lock screen. The first one is what a new phone starts with. 30 wallpapers are shipped (.webp).

To add your own:

  1. Drop a portrait picture (.webp, .jpg or .png) into html/assets/wallpapers/.
  2. Add its file name to Config.Wallpapers.
  3. Optional: put a small copy with the same name (.webp, about 450 pixels wide) in the thumbs/ folder next to it. It makes the wallpaper lists open faster.

A player whose wallpaper is taken off the list gets the first one.

#Config.Sound

Setting Type Default What it does
Sound.Resource string 'auto' 'auto', 'fx-sound', 'xsound' or 'none'. The engine for sounds other players hear
Sound.Enable3D boolean true Ringtones and notification sounds are heard by nearby players. Needs fx-sound or xsound
Sound.Range number 10.0 Metres at which someone else's phone fades to silence
Sound.BystanderVolume number 0.35 The loudest another player's ringtone or notification can be for you (0 to 1), whatever volume its owner set

Without fx-sound or xsound every sound plays for the owner only.

#Ringtones and notification sounds

Setting Shipped ids
Config.Ringtones reflection, beacon, chimes, radar
Config.NotificationSounds note, tri-tone, chord, bloom, aurora, glass

Each entry is { id, label }. The sound ships as <id>.wav in html/assets/sounds/.

To use your own sound:

  1. Put <id>.ogg in html/assets/sounds/.
  2. Add the id to html/assets/sounds/overrides.json, a JSON array of tone ids (shipped empty):
json["reflection", "tri-tone", "shutter"]

The phone only asks for an .ogg when its id is in that list, and falls back to the .wav if the file is missing. A new ringtone or notification sound is a new file plus an entry in Config.Ringtones or Config.NotificationSounds, and in overrides.json when it is an .ogg. The camera shutter is the id shutter.

More: Notifications and Dynamic Island and Sound.