Start
Installation
Install FX Phone in six steps, from copying the files to granting admin roles.
Steps 1 to 6 are required. Expect about 15 minutes on a server that already runs a framework, an inventory and a voice resource.
#1. Install the files
Copy the fx-phone folder into resources/. Keep the folder name: the export namespace (exports['fx-phone']), the event names and the page address all use it.
Copy fx-phone-assets and the [fx-apps] folder next to it if you want the phone models and the bundled apps.
Add the resources to server.cfg. FX Phone must start after everything it talks to. The full order is on Start order.
cfgensure oxmysql
ensure qb-core
ensure ox_inventory
ensure pma-voice
ensure fx-phone
#2. Database
Nothing to do by default. All tables are in one file, setup/install.sql. With Config.AutoSchema = true FX Phone runs it on every start, then applies the column changes newer versions need. Every statement is CREATE TABLE IF NOT EXISTS or a checked ALTER TABLE, and only statements on fx_phone_* tables are run.
The database user oxmysql connects with needs the CREATE, ALTER and INDEX rights on the database.
If your database user cannot create tables, import the file yourself and switch the automatic run off:
bashmysql -u user -p yourdb < setup/install.sql
luaConfig.AutoSchema = false
With AutoSchema = false the column changes of an update do not run either. See Updating.
#3. The phone item
By default a player needs an item called phone to use the phone.
luaConfig.Item = 'phone' -- false: everyone has a phone, no item needed
Config.Inventory = 'auto' -- 'auto' | 'ox_inventory' | 'qb-inventory' | 'standalone'
The item code for each inventory and the item images are on Item setup. How the inventory is detected is on Inventory.
#4. Uploads
Photos, videos, voice messages and profile pictures are stored by an upload provider, never in the database. Pick one in config_server.lua and set its key there:
luaServerConfig.Upload = {
Provider = 'fivemanage', -- 'fivemanage' | 'fmapi' | 'relay' | 'custom' | 'none'
Fivemanage = {
Image = 'your-v3-api-key',
},
}
The player's game uploads the file straight to the provider with a single-use URL. The key never leaves the server.
With Provider = 'none' the camera still works but nothing can be saved or sent.
config_server.lua holds your keys and webhooks. Never share it, never paste it in a support ticket, never put it in a public repository.
Every provider is described on Upload.
#5. Language and currency
luaConfig.Locale = 'tr' -- language of new phones; the shipped config uses Turkish
Config.Locales = { 'en', 'tr' } -- what players can pick in Settings
Config.Currency = { Code = 'USD', Symbol = '$', Locale = 'en-US' }
An English server sets Config.Locale = 'en' and keeps the USD line. A server that uses Turkish lira:
luaConfig.Locale = 'tr'
Config.Currency = { Code = 'TRY', Symbol = '₺', Locale = 'tr-TR' }
Config.Crypto.Currency = 'try'
Currency.Locale controls how amounts are formatted in the phone (thousands separator, decimal mark, symbol position). Crypto.Currency is the CoinGecko quote currency, lower case.
#Adding a language
Copy locales/en.json to locales/<code>.json, translate it, and add the code to Config.Locales. Codes are two letters or xx-XX. Keys you leave out fall back to English. The same file holds the console and Discord log text (logs.), the admin tablet (tablet.) and every app.
Useful keys to change without translating everything:
| Key | What it is |
|---|---|
apps.<id> |
App names under the icons |
phone.no_item, phone.dead, phone.disabled |
Why the phone did not open |
phone.keys.open, phone.keys.look |
Key binding names in the GTA settings |
mail.system_sender |
Sender name of script mails without one |
admin.command., admin.backup. |
Command replies |
logs.<event>.title, logs.<event>.summary |
Discord embed title and line per event |
#6. Admin roles
The admin tablet and the admin commands use ACE permissions. Add to server.cfg:
cfgadd_ace group.admin fxphone.admin allow
add_ace group.moderator fxphone.mod allow
add_ace group.owner fxphone.god allow
add_ace group.owner fxphone.admin allow
The last line lets owners also run the fxphone:number, fxphone:wipe and fxphone:mail commands in game. Those check fxphone.admin (or the framework's own admin check), not the tablet role.
Roles are described on Admin and Admin tablet.
Start the server, load a character and press F1.
#Console output to expect
The framework, inventory, voice, sound and bank resources are looked for when FX Phone starts. The server console prints what it found:
cfg[fx-phone:main] framework: qbcore
[fx-phone:bank] bank adapter: tgiann-bank
[fx-phone:schema] database ready: 39 statements, 0 migrations applied, 12 recorded, 0 skipped, 0 failed
The numbers in the last line depend on the version. If the first line says standalone on a framework server, fix the start order.
#Server console commands
| Command | Who | What it does |
|---|---|---|
fxphone:number <identifier> <number> |
Console, fxphone.admin, framework admins |
Gives a character a new number |
fxphone:wipe <identifier> |
Same | Deletes every phone row of a character |
fxphone:mail <id or identifier or -1> <sender> <subject> <message> |
Same | Sends a mail. -1 is everyone. Put words with spaces in double quotes |
fxphone:backup |
Console, god role | Starts a snapshot now |
fxphone:admin <id> |
Console | Opens the tablet for that player with their role, or reports that they have none |
fxphone:migrate cylex dry / run / resume |
Console | Copies cylex_phone data. See Migration |
The identifier is the framework's character id: citizenid on QBCore and Qbox, the ESX identifier, the license: identifier on standalone.
fxphone:number, fxphone:wipe and fxphone:mail are defined at the bottom of config_server.lua, so you can change or remove them.
#Backups and trash
Every day at 04:30 server time FX Phone writes every fx_phone_* table to backups/<yyyy-mm-dd>/<table>.json with a manifest.json. Tables are read 500 rows at a time with a pause between pages. Folders older than Config.Admin.BackupDays are deleted. Start one by hand with fxphone:backup or from the tablet (god role).
Snapshots are not a replacement for database backups. They exist so a deleted account can be recovered without restoring the whole database.
setup/tools/restore.py turns a snapshot folder into SQL (Python 3, no packages):
bashpython setup/tools/restore.py backups/<date> -o restore.sql
python setup/tools/restore.py backups/<date> -o users.sql -t fx_phone_users -t fx_phone_contacts
Every row becomes INSERT ... ON DUPLICATE KEY UPDATE, so importing the file puts the snapshot's values back without deleting rows created later. Read the file before you import it.
Deleting a social account, post, comment, story, listing or news story only marks it deleted. For Config.Admin.TrashDays days it can be restored from the tablet. After that the daily clean-up removes it.
#Content Security Policy
html/index.html carries a Content-Security-Policy that limits what the phone's page may load:
| Kind | Allowed |
|---|---|
| Scripts | Files of the phone itself, plus the inline import map by its hash |
| Styles, fonts | Files of the phone itself |
| Images, audio, video, network requests | https:, nui:, data:, blob: |
| Frames (custom apps) | The phone itself, nui:, https: |
| Workers, plugins, base element | None |
A custom app's ui must end up as https://: an https:// site, or a resource page (my-app/html/index.html and nui://my-app/... become https://cfx-nui-my-app/...). Any other address opens as a blank page.
Which hosts the phone accepts for player media is decided on the server by ServerConfig.Upload.AllowedHosts. See Upload.
To check in game, open the phone, Photos, Camera and a custom app, then look at the F8 console. There should be no line mentioning Content Security Policy. If one appears, it names the directive and the blocked address.