Features

Calls

Voice calls, conference calls, the speaker, voicemail and video calls.

Players call each other by phone number from the Phone app. The voice travels over your voice resource (pma-voice, mumble-voip or SaltyChat); fx-phone decides who is in which call. On top of that come conference calls, the speaker, voicemail and video calls.

Part Config What it is
Voice calls Config.Voice, Config.Calls One-to-one calls, and conference calls with more people
Speaker Config.SpeakerBystanders, SpeakerRange, SpeakerFalloff Players standing next to a phone on speaker hear the call
Voicemail Config.Voicemail A caller who is not answered can leave a voice message
Video calls Config.Video The picture goes from phone to phone through a relay; the voice stays on the voice resource

Calls to companies (police, mechanics, taxis) ring a company line instead of one person. They are explained in Services.

#1. Voice calls

#How a player makes a call

The Phone app has five tabs: Favorites, Recents, Contacts, Keypad and Voicemail. A call can be started from the first four, and from the call button on a contact card.

  1. The caller sees Calling….
  2. The other phone rings for 30 seconds. The ringtone is the one the owner picked in Settings.
  3. The other player taps Accept and both are put in the same voice channel. The Dynamic Island shows the call and a microphone dot.
  4. Either side taps End.

If nobody answers within 30 seconds the call ends as No Answer. The owner gets a "Missed Call" notification and the call is listed under Missed in Recents.

When a call ends, the Dynamic Island shows for a moment how it ended, for example "Call Ended · 1:24", "No Answer" or "Line Busy".

#Two lines

A phone with two SIMs has two numbers, and both ring in it (see SIM cards).

  • Recents lists the calls of both lines together, each tagged with its slot number (1 or 2). Calling back from Recents uses the line the call was on.
  • The call screen shows which line a call is on: the slot and that line's number.
  • A call goes out on the primary line. With Calls: Ask Every Time in Settings > SIM the phone asks which line first. The keypad has a switch to pick the line.
  • Emergency numbers never ask; they go straight through.

#The ring screen

When the phone is open on the lock screen, an incoming call fills the screen. Otherwise it shows on the Dynamic Island, unless the caller has a Contact Poster (below).

Button What it does
Accept Answers. A video call opens the Video app
Decline Ends the call at once. The caller can leave a voicemail
Remind Me Declines, and puts a "Call {name} back" notification on the phone an hour later (real time, kept only until the player reconnects)
Message Declines, and sends the caller one of three short replies in Messages

#Contact Posters

A contact can have a Contact Poster: a picture that fills the screen when that contact calls. The player sets it in Contacts, on the contact's edit screen (Add Poster), from the camera, from Photos or from a link.

A caller with a poster rings full screen even while the phone is open and in use, with Accept and Decline on the poster, the way a locked phone rings. The Dynamic Island steps back for that call. The poster is stored with the contact, so only the player who saved it sees it.

The picture must come from your upload provider or a host in ServerConfig.Upload.AllowedHosts, like any other image (see Camera).

#During a call

Button What it does
Mute Stops the player's microphone reaching the call until they tap it again or the call ends. Not shown with SaltyChat
Keypad Plays dial tones
Speaker Puts the call on speaker, see section 2
Add Call Rings one more number into the call, see Conference calls below
Video Asks the other side to switch to video, see section 4
Location Sends where you stand to everyone else in the call. It is set as their GPS waypoint
Add to Contacts Shown when the caller is not saved yet: saves the number with a name

#Hidden numbers, blocking and Do Not Disturb

  • Hide Number in the Control Centre calls without showing your number. The other side sees Unknown on the ring screen and No Caller ID in Recents. Company lines and emergency numbers always see the number.
  • A blocked caller gets "This call can't be completed."
  • With Silent Mode or Do Not Disturb on, the call still arrives and can be answered; it just does not ring. Wisp's "silence unknown callers" works the same way for numbers not in Contacts.
  • With Airplane Mode on, the phone can neither call nor be called.

#When a call cannot be made

What the caller sees Why
"The number you called is unavailable." Nobody has that number, the owner is offline, has no service, has a flat battery or is in Airplane Mode
"The number you called is busy." The other player is already in a call
"No service. Move into coverage to make calls." The caller has no signal bars (see Signal below)
"Insert a SIM card to make calls." Config.Sim.Enabled = true and there is no working SIM in the phone (see SIM cards)
"You can't call your own number." The number is one of the phone's own lines, the other line included

Signal. With Config.Signal.BlockCalls = true (the default) a phone with no signal bars can neither call nor be called. Emergency numbers still go through. A phone with a flat battery can do neither. With BlockCalls = false the signal only shows in the status bar. How the bars and the battery work is on Battery and signal.

A player who dies, goes down or leaves the server drops out of the call.

#Conference calls

Add Call rings another number into an active call. That player joins when they answer; until then the others keep talking. The status line then reads "Conference · 3 people".

  • Config.Calls.MaxParticipants counts everyone in the call, the two first parties included. The default 4 allows two guests. 2 turns Add Call off.
  • A guest who does not answer within 30 seconds is dropped, and whoever added them gets a notice.
  • When one of the two first parties hangs up while guests remain, the first guest takes their place and the call goes on.
  • A video call cannot become a conference.

#Ringtones

Players pick their ringtone in Settings > Sounds from Config.Ringtones.

luaConfig.Ringtones = {
    { id = 'reflection', label = 'Reflection' },
    { id = 'beacon',     label = 'Beacon' },
    { id = 'chimes',     label = 'Chimes' },
    { id = 'radar',      label = 'Radar' },
}

Each id plays html/assets/sounds/<id>.wav, or your own <id>.ogg when the id is listed in html/assets/sounds/overrides.json. How to add your own sounds is in Apps and phone setup.

Nearby players hear a phone ring when all three are true: fx-sound or xsound is running (Config.Sound.Resource), Config.Sound.Enable3D = true, and the owner has 3D Sounds on in Settings > Sounds. They hear it within Config.Sound.Range metres. Without a 3D sound resource only the owner hears it.

#2. Speaker

Tapping Speaker lets the people around the phone take part.

Voice resource What happens
pma-voice, mumble-voip Every player within Config.SpeakerRange metres of the phone, who is not in a call of their own, is put in the call. They hear it, and the other side hears them too: these voice resources have no listen-only mode
SaltyChat SaltyChat's own phone speaker is switched on. fx-phone does not pull anyone in, and SpeakerBystanders is ignored

A bystander follows the nearest phone on speaker only, so nobody is in two calls at once. Walking out of range takes them out of the call again.

With Config.SpeakerFalloff = true (pma-voice and mumble-voip only), the further a bystander stands from the phone, the quieter the call is for them, and the quieter they are for the other side. At the edge of the range they are at 5 % of the call volume, so leaving is not a hard cut. Players standing next to each other still hear each other through normal proximity voice. With false, the call plays at full call volume anywhere inside the range.

Set Config.SpeakerBystanders = false to keep the speaker to the phone owner.

#3. Voicemail

A caller who is not answered can leave a voice message.

  1. The call ends because nobody answered, the other player declined, was busy or could not be reached.
  2. The caller's phone offers Leave a Voicemail, with the owner's greeting.
  3. The caller taps Record, speaks for up to MaxSeconds seconds and taps Send. The offer lasts OfferSeconds seconds after the call.
  4. The owner gets a "Voicemail" notification. The message is in Phone > Voicemail, with Call Back and delete.

In Phone > Voicemail the owner can switch voicemail off for their own number, and write a Greeting: a short text the caller reads before recording. Left empty, the default text is "{name} can't take your call right now. Leave a message after the beep."

  • Only calls between players get voicemail. Company lines do not.
  • A character keeps the newest MaxMessages messages. Older ones are also deleted after Config.Retention.voicemail days (default 30).
  • The recording is uploaded like a photo, so voicemail needs an upload provider (see Camera).
Option Default What it changes
Enabled true Voicemail on the server. false removes it for everyone
MaxSeconds 60 Longest message
MaxMessages 50 Messages kept per character; the oldest go first
OfferSeconds 90 How long after the missed call the caller may still record

#4. Video calls

A video call is a voice call with a picture. The voice stays on your voice resource. The picture goes straight from one player's game to the other's (WebRTC) through a TURN relay: a server that passes the video along, so neither player sees the other's IP address. Frames never pass through your game server.

#How a player uses it

  • The Video app lists recent video calls. New Call picks a contact. A card's camera button calls again.
  • A contact card has a video button.
  • During a voice call, Video asks the other side to switch. They get "{name} wants to switch to video" with Switch to Video and Not Now, wherever they are in the phone; with the phone away, a notification tells them. The request lapses after 30 seconds. If both press Video, the call switches at once.
  • An incoming video call rings with "Incoming video call". Accepting opens the Video app.

In the call the player can turn their camera off. What the camera sends depends on Config.Video.TakeOverView:

TakeOverView The caller's own screen What the other side sees
false Left alone. The player keeps playing with their normal game camera; the character holds the phone up as for a photo. There is no lens to flip or zoom The caller's normal game view: the character from behind, or wherever the caller turns their camera. Not a close-up of the face
true (shipped) The phone's lens takes over the screen for the length of the call, front lens on the face first. The player can flip between the front and rear lens and zoom with the mouse wheel The face (front lens) or what the rear lens points at

The reason for the difference: the game draws one picture per player, and that picture is what a video call sends. With true, the front lens stands Config.Camera.SelfieDistance.Video metres from the face, and Config.Camera.SelfieNearClip keeps the hand holding the phone out of the picture (see Camera).

The picture is only sent while the player looks at the call, in the Phone or Video app with the phone open and unlocked. Anywhere else the other side sees "Video paused"; the voice goes on.

If the picture cannot connect within 25 seconds, the player sees "Video couldn't connect. The call goes on with voice." and the call carries on without a picture.

Video is person to person only: company lines and conference calls have no video button.

#Setting it up

Nothing is needed for a start. By default the picture goes through the Fixitfy relay, and the server signs up with it by itself on the first video call.

To use your own TURN server instead (for example coturn), fill these in config_server.lua, under ServerConfig.Video:

Option What it is
Hosted Use the Fixitfy relay when no TURN server of your own is set. false turns that off
TurnSecret The shared secret of your TURN server, for short-lived logins. Set your secret in config_server.lua
IceServers Your STUN and TURN addresses
AllowDirect Lets the picture go directly between players when possible. Off, it always goes through the relay and players' addresses are filtered out of the connection data
CredentialSeconds How long one relay login lasts, between 60 and 3600 seconds

Setting up your own relay is covered in Video relay.

If no relay is available, the camera button is hidden and the server console says video calls are off: ServerConfig.Video has no TURN server, Hosted is false and AllowDirect is false.

#Options (Config.Video)

Option Default What it changes
Enabled true The camera button in calls and the Video app. false turns video calls off
Fps 24 Frames per second, between 5 and 30
Size { 960, 540 } Picture size, long side and short side. At most 1280 by 720. The phone sends it upright
MaxBitrate 1500 Upper limit per direction in kbit/s, between 100 and 2500. Every call uses up to this much of your relay in each direction
RequireItem false An item needed to turn your own camera on, e.g. 'phone_camera'. Without it the player still sees the other side, and gets "You need a camera to turn on video."
TakeOverView true false: the call leaves the player's own view alone and sends their normal game view. true: the phone's lens takes over the screen and the other side sees the face. See above

On a weak relay or slow connections, go down to Fps = 15, Size = { 640, 360 } and MaxBitrate = 600.

Live streams use the same relay and the same picture size; see Live.

#When the in-phone capture fails

If the phone cannot capture the game picture on a player's client, it sends about two still frames a second instead, taken with screenshot-basic or utk_render (Config.Screenshot, see Camera). Without either resource that player's picture stays off.

#5. Voice resources (Config.Voice)

Value Result
'auto' (default) pma-voice if it is installed, otherwise mumble-voip, otherwise SaltyChat
'pma-voice' Calls use pma-voice call channels
'mumble-voip' Calls use mumble-voip call channels
'saltychat' Calls use SaltyChat calls, and SaltyChat's own phone speaker

The server picks a random channel for every call and puts the players in it; the channel number is never shown to a client, so knowing a call id does not let anyone listen in. Start your voice resource before fx-phone in server.cfg. With none found, the phone still rings and connects, but nobody hears anything.

#All options

Option Default What it changes
Config.Voice 'auto' Voice resource, see section 5
Config.Calls.MaxParticipants 4 People in one call, the two parties included. 2 turns Add Call off
Config.SpeakerBystanders true Players next to a phone on speaker join the call
Config.SpeakerRange 3.0 Metres from a phone on speaker within which bystanders hear the call
Config.SpeakerFalloff true The call gets quieter with distance from the phone (pma-voice, mumble-voip)
Config.Voicemail.* see section 3 Voicemail
Config.Video.* see section 4 Video calls
Config.Signal.BlockCalls true No signal bars, no calls (emergency numbers excepted)
Config.Ringtones four tones Ringtones players can pick
Config.Sound.Resource 'auto' 'auto', 'fx-sound', 'xsound' or 'none': the engine for sounds other players hear
Config.Sound.Enable3D true Ringtones can be heard by nearby players
Config.Sound.Range 12.0 Metres within which a ringtone is heard

#For developers

  • Start, end or check calls from a script: CreateCall, StartVideoCall, EndCall, IsInCall on the client (Client exports: calls) and the server, which also has GetCall (Server exports: calls).
  • Stop a player from calling, for example while cuffed: the server AddCheck with the createCall check, see Server exports: other.
  • Client events: fx-phone:callStarted (a call became active) and fx-phone:callEnded with { id, reason, duration }.

#Good to know

  • Mute works with pma-voice and mumble-voip. The player's microphone stops reaching the call, for every other party and speaker bystander; players standing next to them still hear them as usual. The mute ends with the call. SaltyChat offers no way to mute a call from outside, so with SaltyChat the Mute button is not shown.
  • A personal call always rings for 30 seconds. Config.Services.CallTimeout only changes company lines.
  • Nobody hears anything in a call. The voice resource is missing, was started after fx-phone, or Config.Voice names one that is not installed.
  • Players far away hear a speaker call. Lower Config.SpeakerRange. On pma-voice and mumble-voip those bystanders are also heard by the other side; set SpeakerBystanders = false if that is a problem.
  • Nearby players do not hear the ringtone. No fx-sound or xsound, or the owner switched 3D Sounds off in Settings.
  • "Video calls are off on this server." Config.Video.Enabled = false, or no relay is available (see the console line above). A relay that refused this server is tried again later.
  • The other side sees the caller's back, not their face. Config.Video.TakeOverView was set to false: the call sends the caller's normal game view. Set it back to true to have the front lens take over the caller's screen.
  • The picture is choppy or blocky. Lower Fps, Size and MaxBitrate. Every call uses up to MaxBitrate of your relay in each direction.
  • A missed call has no voicemail offer. The owner switched voicemail off in Phone > Voicemail, the call was to a company line, or Config.Voicemail.Enabled = false.