Integration

Framework

How FX Phone detects QBCore, Qbox, ESX or standalone, and how to connect your own framework.

FX Phone talks to the framework through one bridge. Everything else (apps, bank, invoices, services) only calls the bridge, so supporting another framework means filling in one file.

#Detection

Config.Framework = 'auto' picks the first that is running, in this order:

Order Name Detected by Character identifier
1 custom Only when Config.Framework = 'custom' Whatever bridge/custom.lua returns
2 qbox qbx_core started citizenid
3 qbcore qb-core started citizenid
4 esx es_extended started identifier
5 standalone Always license: identifier

FX Phone must start after the framework. When it falls back to standalone while a framework is installed but not yet started, the console says so:

cfg[fx-phone] qb-core is installed but not started yet. Ensure fx-phone after your framework.

A named framework that is not running falls back to auto with a warning.

#What each adapter does

QBCore Qbox ESX standalone
Name charinfo.firstname/lastname Same firstName/lastName, else getName() FiveM name split at the first space
Job PlayerData.job, duty from onduty Same getJob(), on duty unless the job says onDuty = false unemployed
Boss isboss Same Grade name boss No
Money PlayerData.money.bank/cash Same Accounts bank and money In memory: 5000 bank, 500 cash, lost on restart
Offline money Offline player object, else the money JSON column Same accounts JSON column Not supported
Number sync Writes charinfo.phone Same None None
Admin admin or god permission group.admin ACE Group admin or superadmin group.admin ACE
Death metadata.isdead / inlaststand Same esx:onPlayerDeath / esx:onPlayerSpawn Game damage event

On every framework the fxphone.admin ACE also counts as admin for the console commands.

#Your own framework

  1. Set Config.Framework = 'custom'.
  2. Open bridge/custom.lua. It already runs as a standalone copy; replace the functions you need.
  3. Anything you delete falls back to the standalone behaviour.

The identifier is the primary key of every phone row. It must be stable across joins, unique per character (not per player, if you have multiple characters) and at most 80 characters.

#Server functions

Function Returns Notes
GetPlayer(src) Your player object or nil Only checked for nil
GetIdentifier(src) string The character id
GetSourceFromIdentifier(identifier) Server id or nil Online only
GetCharacterName(src) firstname, lastname
GetJob(src) Job table Shape below
GetJobs() { [name] = { name, label, grades = { { grade, label, isBoss } } } } Used by Services and the tablet
GetPlayers() List of server ids Loaded characters
GetMoney(src, account) number account is 'bank' or 'cash'
AddMoney(src, account, amount, reason) boolean
RemoveMoney(src, account, amount, reason) boolean Return false when the balance is too low
AddOfflineMoney(identifier, account, amount, reason) boolean true only when the money was stored. Without it, payments to offline players wait until their next login
IsAdmin(src) boolean
Notify(src, text, kind) Your notification resource
OnPlayerLoaded(fn) Call fn(src) when the character is ready
OnPlayerDropped(fn) Call fn(src, identifier) on disconnect and on character logout
OnJobUpdate(fn) Call fn(src, job) on job or duty changes
SetPhoneNumber(identifier, number) Keep your framework's own phone field in sync, if it has one
GetOfflineCharacterName(identifier) firstname, lastname or nil Shown in bank transfers to offline players
GetBirthdate(src), GetIdentity(src) Used by the Wallet ID card and the Medical ID
SetBloodType(src, value) Optional: only where the framework keeps a blood type

The job table is always:

lua{ name = 'police', label = 'LSPD', grade = 2, gradeLabel = 'Sergeant', onDuty = true, isBoss = false }

#Client functions

Function Notes
IsLoaded() true once the character is selected
OnLoaded(fn) Call fn() when the character is ready
OnUnloaded(fn) Call fn() on character logout
GetJob() Same job shape
OnJobUpdate(fn) Call fn(job)
IsDead() boolean
OnDeath(fn) Call fn(true) when the player goes down, fn(false) when revived
Notify(text, kind) Your notification resource
GetNeeds() Optional: { hunger, thirst, stress } from 0 to 100, shown in the Health app

#Example

A GetJob for a framework with exports:

luafunction adapter.GetJob(src)
    local job = exports['my-core']:GetJob(src)
    if not job then return Utils.Copy(CIVILIAN) end
    return {
        name = job.id, label = job.title, grade = job.rank, gradeLabel = job.rankTitle,
        onDuty = job.duty == true, isBoss = job.boss == true,
    }
end

Restart the server after editing the bridge, then check the console line framework: custom.