Handset (beta)

Handset is the in-game phone for FiveM servers, made by CursedTech. It is free with CAdmin and currently in beta.

What it does:

• contacts and a phone number for every character;
• one-to-one messages, including shared locations;
• calls over pma-voice;
• a camera and a gallery;
• a CAdmin staff app for alerts assigned to you.

The phone is in English, Spanish and Brazilian Portuguese.

Your game server stays in charge of everything: phone numbers, messages, calls and photos live on your server and in your database, not with CursedTech.

Beta. Handset works, but it is new. Try it on a test server before you turn it on for your players, and tell us what you find (see "Getting help" below).

What you need

• CAdmin connected to your network, with the CursedTech installer (version 0.3.0 or later). See Getting started.

• For in-place mode, FXServer build 35245 or later. On an older build the installer only stages releases for you to copy by hand.

• oxmysql with MariaDB or MySQL.

• pma-voice 7.x, for calls. Without it the phone works, and calls show as unavailable.

• Optional, for the camera:

  • screenshot-basic. You install it yourself; the installer does not.
  • The public https:// address of your game server, for photos (handset_photo_origin below).

  Without both, the camera and the gallery stay off and everything else works.

Install

Handset installs and updates through the CursedTech installer, the same way CAdmin does. You don't copy files by hand.

Available with installer 0.3.0. Handset delivery needs the CursedTech installer 0.3.0 or later, which is being published now. Until your installer reports 0.3.0, the steps below do not apply yet.

1. Turn Handset on for the server in the dashboard

The dashboard first shows what it found on the server:

• any other phone;
• whether screenshot-basic is there;
• whether pma-voice is running.

Confirm there.

2. Allow the install in server.cfg

The installer only installs Handset when your own server.cfg allows it. The dashboard can ask, but it cannot install anything by itself:

set handset_install 1

set handset_install 0, or no line at all, means the installer never downloads or touches Handset.

3. In-place mode: create the folder once

Most servers use the installer's in-place mode. FXServer does not let the installer create a resource folder, so you create it once, by hand (with the txAdmin file manager, or on disk).

Create the folder:

resources/[cursedtech]/cursedtech_handset/

Add a placeholder file. The folder must contain a file named fxmanifest.lua when the server starts, with exactly this content:

fx_version 'cerulean'
game 'gta5'
version '0.0.0'

Version 0.0.0 marks it as a placeholder, and the installer replaces it with the signed release.

Add the permission line. In the CursedTech block of server.cfg, before ensure cursedtech, add the Handset line next to the CAdmin one:

add_filesystem_permission cursedtech write cadmin
add_filesystem_permission cursedtech write cursedtech_handset
add_ace resource.cursedtech command.refresh allow
add_ace resource.cursedtech command.ensure allow
add_ace resource.cursedtech command.stop allow
add_ace resource.cursedtech command.start allow
set cursedtech_mode "inplace"
set handset_install 1
ensure cursedtech

Do not add ensure cadmin or ensure cursedtech_handset: the installer starts what it installs. Make sure oxmysql and pma-voice are started earlier in server.cfg than ensure cursedtech.

Restart the server. The installer then verifies the signed Handset release and installs it. To update it by hand later, run cursedtech update cursedtech_handset in the server console.

4. Turn the phone on

set handset_enabled 1

Any other value, or no line at all, keeps the phone fully off.

5. Start the server

On first start, Handset creates its database tables, all named handset_.... It never changes, drops or rewrites other tables. If a handset_ table already exists with a different layout, the affected app stays off, and the server console says why.

Updates arrive the same way and never downgrade. Your photos and settings are kept, and players keep their own key bindings.

Keys

Players open and close the phone with F1. That is the only key Handset uses while the phone is closed.

While the phone is open:

• players move through it with the arrow keys or the numpad;
• Enter selects, and Backspace goes back;
• Home goes to the home screen;
• walking and driving keep working.

Answering and hanging up, the camera shutter and the mouse cursor all work inside the phone. Players who want a key for one of them bind it themselves in the game settings, under the FiveM key bindings. All keys appear in the phone under Settings > Shortcuts.

Running next to another phone

If your server already runs another phone (for example lb-phone, qb-phone, npwd or gksphone), Handset never touches it. You choose what happens with handset_coexist:

Value	What happens
unbound (default)	Handset runs next to the other phone. Its open key has no default, so players bind their own
ignore	Handset runs normally with its default keys. Use this when you are switching to Handset only
off	Handset stays off while the other phone runs, and turns on by itself once it is gone

Handset registers no phone item and no /phone command. To keep only Handset, stop or remove the other phone yourself.

Configuration

Setting	Default	What it does
handset_enabled	0	1 turns the phone on
handset_install	not set	1 lets the installer install and update Handset
handset_coexist	unbound	behaviour next to another phone (see above)
handset_photo_origin	not set	the public address of your game server, as https://host only (no port, path or login), which the phone loads photos from. Without it the camera and gallery stay off
handset_photo_bytes_max	2 GB	total photo storage on this server. New photos are refused at the cap; nothing is deleted
handset_number_format	###-####	phone number pattern, where # is one digit
handset_call_channel_base	4000	first pma-voice call channel Handset uses. Keep this range free
handset_key_toggle	F1	default open and close key. Empty means unbound; players can always rebind it

Choose the number format before your first player opens the phone. Numbers already given out are never rewritten, and a number that no longer fits the pattern can't be typed in anymore.

Limits in this version:

• 200 contacts and 200 photos per character, at 600 KB a photo;
• messages up to 500 characters;
• 20 messages and 6 outgoing calls a minute per character;
• calls ring for 30 seconds.

What players should know

You can show this text to your players, or adapt it:

Your phone's contacts, messages, call history and photos are stored on this game server. Staff don't read phone content. You can delete your own photos in the Gallery.

Staff see no messages, call lists, contacts or photos in CAdmin. This version has no report button for messages or photos.

Not in this version

• group messages;
• photos in messages;
• a maps app;
• reporting a message or photo;
• streamer mode;
• photo hosting by CursedTech;
• linking a real phone;
• the dispatch app.

A shared location shows as "Shared location", without a street name.

Known limits in this beta

• Camera and gallery: they need your own screenshot-basic and handset_photo_origin. They have not yet been checked on a live server with a real https address.
• Interrupted photo saves: if the server stops while a photo is being saved, the gallery can show an entry without its picture. Delete that entry in the Gallery.
• Frameworks: in game, Handset has been tested with ESX. QBCore, Qbox and CLRPV2 are supported and tested automatically, but not yet played.
• Performance: client performance has not been measured in a real game client yet. Server-side load tests pass.
• Installer: in-place updates on Windows hosts are not tested yet. Big updates take about a minute.
• Calls and messages between players: tested with automated test players, not yet between two real game clients.
• Other apps: no third-party phone app is approved by default. Approval applies to the whole server.
• Phone screen check: the stricter check of where phone screen messages come from is rolling out. In this version it only logs.

Getting help

Run the phone's own check. In the Phone app, dial *#0*#. Handset runs its diagnostics (display, keys, server round trip, storage, notifications, messages, calls and clock) and shows a summary. Dial *#06# to see the phone's version and device id.

Contact support. Use your usual CAdmin support channel and include:

• the Handset version (from *#06#);
• the diagnostics summary;
• what you did;
• any line from the F8 console or the server console.

Never send licence keys, tokens or passwords.