Configuration

How the configuration works#

Everything a server owner can change without touching code lives in the config/ folder of the resource. The files are loaded in this order (see fxmanifest.lua):

Startup validation#

After the config files load, the resource checks the whole configuration on start. If a value is invalid, it prints a yellow warning in the server console and falls back to the default value (it never stops the resource):

[rarx_phone] config: Config.Messages.MaxLength = 'lots' no es válido (debe ser un número); se usa 1000
[rarx_phone] config: Apps 'bank': dock = 9 debe ser 1, 2, 3 o 4; se quita del dock

If no warning appears, your configuration is valid. After changing any file in config/, run ensure rarx_phone (or restart the server).

Apps (config/apps.lua)#

Everything app-related is done in Config.Apps, without editing the Apps list itself.

Disable an app#

Config.Apps.Disabled = { 'crypto', 'blackmarket' }

A disabled app:

• does not appear on the home screen, dock, app drawer, search, store, multitasking, notification settings or the admin panel;
• cannot be opened (not even from a link, notification or widget);
• has its server requests rejected (err_app_blocked). Modules shared by several apps (for example media, used by Gallery, Voice Memos, Camera and Messages) are only blocked when none of those apps is available.

settings cannot be disabled: the validator warns and keeps it enabled. The core apps (phone, messages, store, widgets) can be disabled, but think twice: without phone nobody can take calls, and without store nobody can install apps.

You can also disable an app with its feature switch (for example Config.Features.Crypto = false) or with enabled = false in Overrides.

Rename an app#

Config.Apps.Overrides = {
    dating = { name = 'Tinder' },
    music = { name = { es = 'Música RRX', en = 'RRX Music' } },
    news = { name = { default = 'Weazel', en = 'Weazel News' } },
}

• name as a string: the same name in every language.
• name as a per-language table: each language uses its own name; default is used for languages not listed. If a language is missing and there is no default, that language keeps its normal translation.

The name overrides the app_<id> translation key on the server, so it is shown everywhere: home screen, dock, drawer, search, store, multitasking, notifications (banner, notification centre, lock screen and closed-phone alerts), settings and the app title. It takes priority over the translation; Config.Locale.Overrides can still override a specific key.

The label field in the Apps list is only an internal fallback label. Use name to change the visible name.

Change the icon#

Config.Apps.Overrides = {
    dating = { icon = 'https://cdn.example.com/tinder.png' },
    bank = { icon = 'nui://my_banking/html/icon.png' },
    music = { icon = 'images/apps/my-music.png' },
    mail = { icon = { default = 'images/apps/mail.png', white = 'images/apps/mail-white.png' } },
}

• Must start with https://, http://, nui:// or images/ (a path inside the resource's ui/ folder; images/apps/x.png is ui/images/apps/x.png).
• As a table, the icon can change with the player's icon pack (realist, white, black); default is used for packs not listed.
• If the image fails to load, the placeholder with the app's initial is shown.
• Recommended: a square PNG of 180x180 or larger, without rounded corners (the phone adds them).

Position on the home screen and dock#

Config.Apps.Overrides = {
    camera = { dock = false, slot = 5 },
    bank = { dock = 4 },
}

• dock = 1, 2, 3 or 4 (dock slot). false removes it from the dock. If two apps share a slot, the validator warns.
• slot = default position on the home grid (lower = earlier). false removes the position (goes to the end).
• This is only the default order: if a player rearranges their home screen, their order wins.

Installed by default or store only#

Config.Apps.Overrides = {
    darkchat = { default = false },
    blackmarket = { default = false, store = false },
}

• default = false: new phones do not include it; the player installs it from the store. Players who already customised their apps keep what they had.
• store = false: it does not appear in the store unless already installed and cannot be installed from it (if the player already has it, they can keep using and uninstall it). Useful for apps handed out by an admin or a job.
• fija = true: always installed and cannot be uninstalled.

Restrict by job, grade, item or ACE permission#

Config.Apps.Overrides = {
    services = { requires = { jobs = { 'police', 'ambulance' } } },
    fines = { requires = { jobs = { police = 2, sheriff = 0 }, onDuty = true } },
    darkchat = { requires = { items = { 'burner_phone', 'laptop' } } },
    news = { requires = { ace = 'rarxphone.news' } },
}

• jobs: a list of jobs, or a table of job = minimum grade.
• onDuty = true: must also be on duty.
• items: the player must carry any of these items.
• ace: an ACE permission from server.cfg (add_ace group.admin rarxphone.news allow).
• When combined, all conditions must be met.
• Players who do not qualify do not see the app and the server rejects their requests. The check is cached for 5 seconds per player, so after dropping the item or changing job, access is lost within a few seconds (the icon disappears the next time the phone is opened).
• This is independent of the admin panel app locks (block for everyone or per job), which keep working as usual.

Apps for specific phone models#

Config.Apps.Overrides = {
    fans = { models = { 'ifruit26', 'ifruitzfold' } },
}

Models: phone, ifruitduo, ifruit26, ifruitzfold or any item from Config.Item.Names. It is compared with the item used to open the phone. If the model is unknown (for example with Config.Item.Require = false), the app is shown.

App fields reference#

These fields can be set in Config.Apps.Overrides.<id> or directly on the entry in the Apps list.

Full example:

Config.Apps.Disabled = { 'crypto' }

Config.Apps.Overrides = {
    dating = { name = { es = 'Tinder', en = 'Tinder' }, icon = 'https://cdn.example.com/tinder.png', slot = 3 },
    fines = { requires = { jobs = { police = 0 } }, default = false },
    blackmarket = { default = false, store = false, requires = { items = { 'burner_phone' } } },
    fans = { models = { 'ifruit26', 'ifruitzfold' } },
}

App IDs#

phone, messages, rrx (Lenz), camera, store, widgets, gallery, settings, notes, calendar, map, weather, music, news, bank, ads, services, vehicles (Garage), mail, taxi, go, invoices, fines, clock, findmy (Find Device), dating (Flechazo), calculator, properties, browser, voicememo, crypto, darkchat, blackmarket, fans (Privé), birdy, shortcuts, health.

AppDomains (also in config/apps.lua) maps each RPC module to its app (bank to bank, rides to taxi and go, and so on). You do not need to touch it unless you add new apps.

Feature switches (config/funciones.lua)#

Each switch in Config.Features set to false turns that feature off on the server (requests are rejected with err_feature_off, or the related apps are disabled) and hides it in the interface. true leaves the feature as is.

Some switches are linked to older keys in config/config.lua (for example Crypto = Config.Crypto.Enabled == true), so you can change either one. On start, the value in Config.Features wins and is copied back to the old key.

Other switches that live elsewhere: Config.ServerNotifications.Enabled, Config.Filter.Enabled, Config.Notifications.Outside, Config.Animation.Enabled, Config.Music.AllowCustomUrl, Config.Bank.Offline, Config.Crypto.Transfer, Config.Messages.AllowDelete.

When a switch is off, its controls are also hidden in the interface, for example: Pin and FaceId hide the passcode and face sections in Settings and the setup wizard (a phone that already has a code keeps "Turn off passcode"); Flashlight and Camera hide their buttons in Control Centre and on the lock screen; Video hides the Video mode in Camera; VideoCalls hides every video call button; Voicemail hides the Voicemail tab; Battery and Coverage hide the status-bar indicators; CustomNumbers hides the custom number entry in Settings.

Keys and commands (config/funciones.lua)#

Config.Keys is linked to the older keys (Config.Command, Config.Keybind, Config.Calls.KeyAnswer, Config.Calls.KeyHangup, Config.Admin.Command); changing a value here copies it to the old one.

Key names are FiveM key names (F1 to F12, M, RETURN, BACK, PAGEUP, and so on). FiveM remembers the key each player already bound, so changing the default only affects players who never changed it.

Config.Keys = {
    Command = Config.Command,
    Open = Config.Keybind,
    Answer = Config.Calls.KeyAnswer,
    Hangup = Config.Calls.KeyHangup,
    Preview = 'F3',
    AdminCommand = Config.Admin.Command,
}

The camera keys (Config.Camera.Keys) are documented under Camera.

Branding and texts (config/marca.lua)#

Brand#

Icon packs#

Config.IconPacks = { 'realist', 'white', 'black' } lists the icon packs players can choose. realist gives each app its own colours. If you remove one, it disappears from Settings and players using it switch to the first pack in the list.

New-phone defaults#

Config.Defaults applies to phones that never saved settings and to any setting the player has not changed. It never overrides what a player already chose.

The default language is Config.DefaultLanguage in config/config.lua. The phone clock follows the in-game (GTA) clock; there is no separate time zone.

Overriding any text#

Config.Locale.Overrides overrides any key from locales/<language>.json. It is applied on the server before the language is sent to the client, so it changes both the interface and server-generated texts (notifications, errors).

Config.Locale.Overrides = {
    ['*'] = { ui_set_carrier = 'Carrier' },
    es = { app_dating = 'Ligoteo', err_feature_off = 'Esto no está disponible en este servidor.' },
    en = { app_dating = 'Hookup' },
}

• '*' = all languages; the specific language is applied afterwards.
• Look up key names in locales/es.json (or any other locale file). Keep any %s placeholders the original text has.
• Languages not listed in Config.Languages, or values that are not strings, are ignored with a warning.

Core options (config/config.lua)#

All of these are validated on start (type and range); out-of-range values print a warning and fall back to the default.

General#

Animation and prop#

Item and phone numbers#

Shop, line recovery and custom numbers#

Notifications and storage#

Calls#

Video calls and WebRTC#

Config.Calls.Video.* is the frame-streaming video used as a fallback without WebRTC and for group calls. Higher values mean better image and more server bandwidth.

Ringtone heard by others (Ringer3D)#

Messages, mail and content#

Uploads, Face Unlock and rate limits#

Battery#

Social and entertainment#

Browser#

Money, jobs and transport#

Valet#

Wallpapers, accents, sounds and stickers#

Config.Wallpapers = {
    { id = 'default', label = 'Cloud 8', url = 'images/wallpapers/cloud8.jpg' },
    { id = 'light',   label = 'Claro',   url = 'images/wallpapers/light.svg', light = true },
    -- add your own: a path inside ui/ or an https:// URL
    { id = 'city',    label = 'City',    url = 'https://cdn.example.com/city.jpg' },
}

Admin and moderation#

Database#

The convar set rarx_phone_auto_sql 0 also disables it, and set rarx_phone_migrate 1 forces migrations even when it is false.

Integrations (config/integraciones.lua)#

Banking#

Garage#

If the detected framework (or the one forced in Config.Framework) has a profile and the garage still uses the Qbox/QBCore values (player_vehicles + citizenid), the profile is used. If you changed table or columns.owner, your values are respected.

Housing#

Resource requirements#

• ox_lib and oxmysql: required.
• Optional (features that depend on them switch off on their own if missing): rarx_banking, rarx_garages, rarx_housing, rarx_inventory / ox_inventory, rarx_uploader, rarx_business, rarx_map (map tiles), pma-voice, qbx_vehiclekeys.

Widgets (config/widgets.lua)#

Widgets.Catalogo lists the widgets players can add. Each entry is { id, label, fuente }, where fuente = 'propio' means the phone fills it and fuente = 'fuera' means another resource fills it with SetWidgetData (hidden when Config.Features.ExternalWidgets = false).

Shipped widgets: servidor (server status), weather (clock and weather), bank, trabajo (job and shift, external), emergencias (emergency call), multas (fines and invoices), garaje (garage), negocio (business, external), facciones (factions on duty), ruta (GPS route), radio (external), anuncios (ads), battery, activity (pending items). config/extra/atajos.lua adds atajos (shortcuts) and salud (health).

lb-phone compatibility (config/compat.lua)#

rarx_phone provides lb-phone, so resources written for lb-phone keep working.

Set any command to '' (or false) to not register it. All three commands require phone admin rights (or the server console).

Coverage (config/cobertura.lua)#

Config.Coverage simulates cell towers. Far from towers, in tunnels or in dead spots, players can lose signal and cannot call or send messages.

Bars (0-4) are calculated on the client every Interval ms, only if the player moved more than MoveDistance metres (and at least every 5 checks even when standing still). The status bar of every model shows this value.

Calculation order:

1. Config.Features.Coverage = false: always 4.
2. Admin panel zones: mode on = signal only inside the zones; off = no signal inside the zones; none or no zones = no effect. If the zones say "no signal", it is 0 bars regardless.
3. Towers: 2D distance to the nearest tower in TowerList, using Range. With Towers = false (or an empty list) it stays at 4.
4. Client modifiers: inside an interior, subtract Interior bars; underground (not in an interior and with ground more than Underground.Depth metres above), subtract Underground.Bars.
5. MinBars raises the result to that minimum.
6. Hard limits that beat MinBars: BelowZ (below that height, 0 bars) and DeadSpots.

Config.Coverage = {
    Towers = true,
    MinBars = 1,       -- never fully lose signal by distance
    Interior = 1,      -- lose one bar inside interiors
    Underground = { Enabled = true, Depth = 8.0, Bars = 2 },
    DeadSpots = {
        { x = 1000.0, y = -2000.0, z = 30.0, radius = 80.0, bars = 0 },
    },
    -- ...
}

The server recalculates the bars for every blocked action using the ped position on the server (towers, zones, DeadSpots, BelowZ) and keeps the minimum of that and what the client reported (the client can only lower it: interiors and tunnels). Players without signal cannot be called (err_call_unreachable, as with airplane mode); messages sent to them are still delivered. Everything else (notes, gallery, map and other apps) works without signal.

Exports: client exports.rarx_phone:SetServiceBars(n | false) (also exports['lb-phone']:SetServiceBars) forces the displayed bars (the server still calculates its own, so forcing 4 does not allow calls in a dead zone; forcing 0 does cut them) and GetServiceBars(); server exports.rarx_phone:GetServiceBars(src).

AirShare (config/airshare.lua)#

Share with the player next to you (AirShare on iFruitOS, nearby share on Andromeda). The share button appears in Gallery (photos and videos, several at once), Notes, Voice Memos, Map (saved place, marked point or your location) and Contacts (a contact or your own card). A sheet lists nearby people (contact name if saved, otherwise their phone name) and "Share with apps" (Messages) below. The receiver gets a card to accept or decline; if their phone is closed they get an outside alert and the card appears when they open it (until it expires). Accepted items are saved in their Gallery, Notes, Voice Memos, Map places or Contacts.

Config.AirShare = {
    Range = 7.5,
    Expire = 60,
    Cooldown = 2500,
    MaxPending = 3,
    MaxPhotos = 10,
    Types = { photos = true, note = true, memo = true, place = true, contact = true },
}

Security: distance and routing bucket are checked with server coordinates; the receiver must have the phone on; content is loaded from the sender's own data by id, never from the client; URLs are re-checked against allowed hosts; a contact can only be shared if it is your number or in your contacts; if the receiver has blocked you, the send stays pending without notifying them. The receiver's limits (Config.Notes.Max, Config.VoiceMemos.Max, Config.Maps.MaxPlaces, full gallery) are respected. Pending sends live in memory and are cleared when they expire, are answered or cancelled, or either player disconnects.

Music (config/music.lua)#

Config.Music.Songs = {
    { title = 'Night Drive', artist = 'Example Artist', album = 'Example Album',
      url = 'https://cdn.example.com/night-drive.mp3', cover = 'https://cdn.example.com/cover.jpg' },
}

Config.Music.Albums = {
    { title = 'Example Album', artist = 'Example Artist', cover = 'https://cdn.example.com/cover.jpg', year = 2026 },
}

GIFs in Messages (config/gifs.lua)#

Server-only file: the API key never reaches the client. The interface asks the server for GIFs and the server makes the HTTP request with the key.

set rarxphone_gifs_key "YOUR_GIF_API_KEY"

• Without a provider or key, the GIF button does not appear in Messages.
• The server only returns results from Hosts, and the gif message type is checked against the general media host allowlist or Config.Gifs.Hosts. The GIF host list only applies to the gif type: photos, videos or voice notes with Tenor/Giphy links are still rejected.
• Keys: Tenor from Google Cloud Console ("Tenor API", free); Giphy from developers.giphy.com (the beta key has an hourly limit, so raise CacheSeconds).

Logs and Discord channels (config/logs.lua)#

config/logs.lua is loaded only on the server, so webhooks and keys never reach the client. It has its own validator that prints warnings the same way ([rarx_phone] config: Config.Logs...).

As shipped, nothing is sent (no webhooks). Filling Default is enough to get every log in one channel.

Options#

Config.Logs.Service = 'discord'
Config.Logs.Default = 'YOUR_WEBHOOK_URL'

Config.Logs.Categories = {
    money = { Enabled = true, Webhook = 'YOUR_MONEY_WEBHOOK_URL' },
    darkchat = { Enabled = false, Webhook = '' },
    -- other categories use Default
}

Webhook selection order for a category: category convar, Categories.<cat>.Webhook, rarx_phone_logs_webhook convar, Default, legacy Config.Logs.Webhook.

Categories#

Each Discord log is an embed with the action title, player (name and ID), character, CID, number, target, amount, action-specific fields, content in a code block, media links (the first image is shown), identifiers, category colour and time.

Discord limits and safety#

• Requests go through a queue per webhook with a sliding window (5 every 2 s by default). Up to 10 embeds are grouped per message (max 6000 characters).
• On 429, the retry_after from Discord is honoured and the same batch is resent first.
• 5xx or network errors: retried with increasing delay (RateLimit.Retries times). 401/403/404 (deleted webhook): that webhook is skipped until restart and a warning is printed once.
• If the queue fills up, the oldest logs are dropped with a warning.
• No pings: allowed_mentions is empty and @everyone, @here and <@...> in player text are neutralised.
• The console never prints webhook URLs or keys.

Feed channels#

Config.Logs.Feeds copies public posts to Discord as a feed:

Each channel is { Enabled, Webhook, Name, Avatar, Color }. Feeds.Enabled = false turns them all off. Feeds work even if Logs.Enabled is false or Service is not discord.

Testing#

In the server console: rarxphone_logs shows the service, active categories, channels and queue state; rarxphone_logs test sends a test log to every active category and channel.

Extra modules (config/extra/)#

Every .lua file in config/extra/ is loaded automatically on both client and server.

Software update check (actualizacion.lua)#

The server checks on start and every CheckMinutes, and shows the result in Settings > General > Software Update (only admins see the download link). The installed version is the one in fxmanifest.lua.

Shortcuts and Health (atajos.lua)#

Birdy (birdy.lua)#

Promoted posts are inserted every EveryPosts posts in the feed.

Camera (camara.lua)#

Car mode (coche.lua)#

Shared music and walkie-talkie (compartir.lua)#

Config.Compartir.Musica (play music out loud for nearby players and in vehicles):

Config.Compartir.Walkie: Enabled true, Tecla 'J' (push-to-talk key), InvitacionSegundos 30, MaxHablaSegundos 30, MaxMinutos 0 (0 = no session limit), Volumen 0.9.

Mail and breaking news (correo.lua)#

App accounts (cuentas.lua)#

Password-protected accounts for social apps.

Gallery (galeria.lua)#

Garage and company (garaje.lua)#

Map points of interest (mapa.lua)#

Config.MapPois.Enabled = true. Config.MapPois.Categories defines categories (police, medical, mechanic, gas, shop, food, bank, gov) as { id, icon, color, label } (label can be per language). Config.MapPois.Points lists places as { name, category, x, y, icon? }.

Config.MapPois.Points = {
    { name = 'Mission Row Police Station', category = 'police', x = 428.2, y = -981.5 },
    { name = 'International Airport', category = 'gov', x = -1037.0, y = -2737.0, icon = 'plane' },
}

Find Device, SOS, location sharing and low power (sistema2.lua)#

Social extras (social.lua)#

Voice (tecnico.lua)#

-- Change these only if your voice resource uses a different name
Config.Calls.VoiceResources = {
    pma = 'pma-voice',
    mumble = 'mumble-voip',
    salty = 'saltychat',
    toko = 'tokovoip_script',
}

The phone's call volume setting only applies with pma-voice. The console command rarxphone_voz <id> prints the detected system.

Uploads (tecnico.lua)#

Config.Uploader.Custom:

Config.Uploader.Method = 'custom'
Config.Uploader.Custom = {
    Url = 'https://upload.example.com/api/upload',
    Field = 'file',
    Body = 'multipart',
    Headers = {
        -- never put the key in plain text: config files are downloaded by every client
        Authorization = 'convar:rarx_phone_upload_key',
    },
    ResponsePath = 'data.url',
    Timeout = 45,
    MediaHosts = {},
}

Service numbers and transfer (tecnico.lua)#

Config.ServiceNumbers = { Enabled = true, Speech = true, AnswerDelay = 1200, MaxDuration = 600 }. Config.Transfer.Enabled = true enables Settings > General > "Transfer to another phone".

Utilities (utilidades.lua)#

Convars#

Set these in server.cfg with set (never setr, so they stay on the server). Convars take priority over the config files.

set rarx_phone_fivemanage_key "YOUR_FIVEMANAGE_KEY"
set rarx_phone_logs_webhook "YOUR_WEBHOOK_URL"
set rarx_phone_turn_token_id "YOUR_TURN_TOKEN_ID"
set rarx_phone_turn_api_token "YOUR_TURN_API_TOKEN"
set rarxphone_gifs_key "YOUR_GIF_API_KEY"

Languages#

Translations live in locales/<code>.json. Shipped languages: es, en, fr, de, pt, pt-BR, it, nl, pl, tr, ar.

• Config.Languages lists which languages players can pick; each needs its JSON file.
• Config.DefaultLanguage must be one of them (otherwise the first in the list is used).
• Config.DateLocales sets the date format per language.
• To change individual texts without editing the JSON files, use Config.Locale.Overrides.

Validated values reference#

Values checked on start. Anything missing or invalid falls back to the default shown.

Lists that must not be empty: Config.Item.Names, Config.PhoneNumber.Prefixes, Config.Languages. The validator also warns when a prefix length plus Config.PhoneNumber.Length does not match the digits in Config.PhoneNumber.Format, when UsernameMin is greater than UsernameMax, and when a Privé minimum is greater than its maximum.