Pulse Phone: install guide

Installing takes about two minutes. Sections 1 and 2 are all most servers need. The rest of this page is there when you want it: find your framework in section 3, and if something is wrong, go straight to Troubleshooting (section 11).

1. Quick install

Step 1: Copy

Put the phone folder into your server's resources folder. Keep the name phone.

Step 2: Add one line to server.cfg

Put it after your database, framework, inventory and voice scripts:

ensure phone

Step 3: Restart the server

That's it. In game, press F1 (or type /phone).

• The database tables are created by themselves. You don't need to import anything.
• Your framework is found by itself: ESX, QBCore, Qbox, ox_core, vRP or standalone.
• Popular inventory, voice, banking, garage, housing, dispatch and vehicle-key scripts are also found by themselves.
• At start-up the server console prints a short check that lists anything missing, with the fix on the line below it.

What is in the folder

2. Requirements

A complete server.cfg block:

set onesync on
set sv_enforceGameBuild 2699        # or newer

ensure oxmysql
ensure screenshot-basic
ensure pma-voice
# ... your framework, then your inventory, banking, garage and housing scripts ...
ensure phone
# ... scripts that use the phone ...

The database. With oxmysql running, the phone creates its tables on first start and adds new ones by itself after every update. It tests the connection with a real query first and gives a database that is still starting 30 seconds. If the database never answers, the phone stores nothing, says so in the console, and keeps retrying. On a test server you can let it use the key/value store instead with set phone_db_fallback "kvp" (that data is never copied into SQL later).

Another phone's tables. If an old phone left tables with the same names (for example phone_messages), they are renamed to old_<name> at first start. Nothing is deleted.

3. Step by step for your framework

The phone finds your framework by its resource name: es_extended, qb-core, qbx_core, ox_core or vrp. You only need Config.Framework in config/config.lua if more than one is running, or for a custom framework.

Multicharacter works on every framework. Config.IdentityScope = 'character' (the default) gives each character its own phone. 'player' gives one phone per account. Pick once: changing it on a live server leaves every existing phone behind.

Company management (duty, staff, hiring, the company account in the Services app) uses the companies in Config.Services in config/apps.lua. If your job names differ from the defaults (police, ambulance, mechanic, taxi, fire ...), add yours to that company's job list. To choose the boss grades yourself, add bossGrade = <n> to the company.

ESX Legacy

ensure oxmysql
ensure es_extended
# ... your ESX scripts, inventory, banking ...
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: with the default ESX inventory, run config/items/esx.sql on your database. With another inventory, see section 4.
• Money: the bank is the ESX bank account, cash is the money account.
• Character: the phone follows ESX's player identifier, so esx_multicharacter works.
• Boss: the grade named boss manages the company, unless you set bossGrade.
• Company accounts: esx_addonaccount / esx_society, or a banking script from section 7.

QBCore

ensure oxmysql
ensure qb-core
# ... qb-inventory and your other qb scripts ...
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: paste config/items/qb-core.lua into qb-core/shared/items.lua. Pictures go to qb-inventory/html/images/.
• Money: bank and cash.
• Character: the citizenid, so qb-multicharacter works.
• Boss: grades with isboss = true in your jobs, unless you set bossGrade.
• Company accounts: Renewed-Banking, qb-banking, or older qb-management.
• Multijob: with ps-multijob running, the player's other jobs show in Services and one tap makes a job active.

Qbox

ensure oxmysql
ensure qbx_core
ensure ox_inventory
# ... your other Qbox scripts, in Qbox's own order ...
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: Qbox uses ox_inventory. Paste config/items/ox_inventory.lua into ox_inventory/data/items.lua. Pictures go to ox_inventory/web/images/.
• Money: bank and cash, through qbx_core.
• Character: the citizenid.
• Boss: grades with isboss = true, unless you set bossGrade.
• Multijob: built in. A player's other jobs show in Services.
• qbx_core also answers as qb-core. That is normal: the phone treats the two as one framework.

ox_core

ensure oxmysql
ensure ox_core
ensure ox_inventory
# ... your other scripts ...
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: paste config/items/ox_inventory.lua into ox_inventory/data/items.lua. Pictures go to ox_inventory/web/images/.
• Money: the bank is the character's ox_core account. Cash is the money item in ox_inventory.
• Character: the charId.
• Jobs: ox_core groups have no duty flag, so the phone keeps duty itself. Company management (staff, hiring, grades) and valet are not available on ox_core.

vRP

Only vRP 2 is supported (not vRP 1 or community forks). The phone loads a small extension into vRP from bridge/frameworks/vrp/. Nothing to copy.

ensure oxmysql
ensure vrp
# ... your other scripts ...
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: there is no item file for vRP, and vRP 2 cannot make items usable for the phone. Keep Config.Item.required = false (the default), and set Config.Store.box = false so the store hands phones over directly. Players use the charging items with /phonepack and /phonecable.
• Money: vRP's bank and wallet.
• Character: vRP's character id.
• Jobs: company management and valet are not available on vRP. The Garage app stays empty unless you connect a garage script.

Standalone (no framework)

ensure oxmysql
ensure pma-voice
ensure screenshot-basic
ensure phone

• Items: none needed. Every player has a phone, a MagPack and a cable.
• Money: the phone keeps its own bank. A new player starts with 5000 (Config.Providers.standalone.startingBank).
• Character: the player's Rockstar licence.
• Jobs, cars and homes: the phone keeps its own. Fill them with the test commands in section 9.

Custom or in-house framework

1. Set Config.Framework = 'custom' in config/config.lua.
2. Give the phone a bridge table shaped like developers/custom_framework_bridge.lua: either as Config.Providers.custom in config/config.lua, or from your own resource with exports.phone:RegisterFrameworkBridge(MyBridge).
3. Only GetCharacterId is required. Anything you leave out falls back to standalone (licence identity, the phone's own bank).

bridge/frameworks/custom.lua shows how the phone uses your table. To connect other in-house scripts (a banking or garage script), see developers/custom_provider_template.lua and developers/EXPORTS.md.

4. Items and inventories

Items are only needed on framework servers. The files are in config/items/ and the pictures in config/items/images/.

If an item is missing, the phone still starts. The store turns boxes off or takes that item off sale, and the console names the item to add.

What to do for your inventory

For the other inventories in this table, the phone makes the items usable by itself. ox_inventory uses the client = { export = 'phone....' } lines already in its file.

ox_inventory: if you used another phone before, also remove its Item('phone', ...) hook from ox_inventory/modules/items/client.lua.

ak47_inventory keeps item use in each item's own entry. Add these:

-- powerbank
server = { onUse = function(source) exports.phone:UsePowerbank(source) end },
-- pulse_magpack and pulse_magpack_max
server = { onUse = function(source, item) exports.phone:UseMagPack(source, item and item.slot, item and item.name) end },
-- pulse_cable
server = { onUse = function(source) exports.phone:UseChargingCable(source) end },
-- pulse_phone_box
server = { onUse = function(source, item) exports.phone:UseBox(source, item and item.slot) end },

Unique phones (Config.Item.unique = true) put the phone number on the item, so handing over the item hands over the phone. They need ox_inventory, qb-inventory, qs-inventory, core_inventory or codem-inventory.

5. Voice and calls

Start one voice script before the phone. It is found by itself:

• To pin one, set Config.Voice.backend in config/voice.lua to 'pma', 'mumble', 'salty', 'toko' or 'yaca'. The default 'auto' is right for almost everyone.
• Run exactly one voice script. Two at once (or esx_voice / mumble-voice next to one) is the usual cause of calls with no sound. The start-up check flags it.
• A company phone line: give a company in Config.Services a number. Calling it rings every on-duty member.
• The Radio app does not work with YACA.

Video calls go phone to phone. If a video call only shows the caller's picture, the two players' networks can't connect directly. Add a TURN relay in server.cfg:

set phone_turn_urls       "turn:turn.example.com:3478"
set phone_turn_username   "your-username"
set phone_turn_credential "your-password"

6. Photos and videos

The camera needs screenshot-basic running before the phone.

Out of the box, photos are saved in the phone's media/ folder and served by your server. Photo links must be https. With no phone_media_origin set, the phone uses your server's own https://<name>.users.cfx.re address, which is right for almost everyone. If you set phone_media_origin yourself, it must start with https://.

To keep photos on a CDN instead, add one of these to server.cfg:

# Fivemanage (recommended)
set phone_media_provider   "fivemanage"
set phone_fivemanage_token "YOUR_TOKEN"

# or a Discord webhook (free, but Discord links can expire)
set phone_media_provider  "discord"
set phone_discord_webhook "https://discord.com/api/webhooks/..."

# or your own endpoint (multipart POST that answers with a url)
set phone_media_provider    "custom"
set phone_media_endpoint    "https://cdn.example.com/upload"
set phone_media_field       "file"
set phone_media_auth_header "Authorization"
set phone_media_auth_value  "Bearer xxx"

Uploads go through the server, so players never see your token. With the built-in store, back up media/ along with your database.

7. Other scripts it connects to automatically

Nothing to set up. The start-up line lists what was found. phone:diag shows every script the phone considered and why it used or skipped each one. To force one, set Config.Providers.<area> in config/config.lua to the resource name, or 'none' to switch that area off.

Scripts written for other phones (police, EMS, job and boss-menu scripts) keep working when they send mail, texts or notifications through events: the phone answers the common event names other phones use. A script that calls another phone's exports needs one change (see "No such export" in section 11).

8. The most useful settings

All in config/config.lua unless another file is named. Restart the phone after a change.

The other keys: Left Alt switches between the phone cursor and looking around (Config.Keys.cursor), Y answers a call and Backspace declines it without taking the phone out (Config.Keys.answer, Config.Keys.decline). Changing a default only affects players who have not bound that key yet.

9. Admin and testing commands

Give your admins the ace first:

add_ace group.admin phone.admin allow
add_principal identifier.license:YOUR_LICENSE group.admin

Run these in the server console, or in game (F8 or chat) with the ace. <id|number> is an online server ID or any phone number.

Testing on a standalone server. These only work with no framework, where the phone keeps its own jobs, money, cars and homes. [id] defaults to yourself.

Quick test: phonesetjob police 4, then open Services to see Your Company. Dial 911 from a second player and choose Police: your phone rings.

10. Updating from an older version

1. Keep a copy of your old phone folder, and back up your database. Move the old folder out of resources: two phone folders start two phones.
2. Put the new phone folder in its place.
3. Copy your old settings files (config/*.lua) over the new ones, but not the config/locales/ folder. Don't delete the new config/ folder first: it may have files yours doesn't.
4. Copy your files in ownermedia/ back, and your media/ folder if you use the built-in photo store.
5. Don't copy old bridge/ files back (or server/custom/, client/custom/ from older versions). If you changed one, make the same change in the new file.
6. Add any new items from config/items/ to your inventory (section 4).
7. Restart. The database updates itself. Read the start-up check in the console.

Settings your older config.lua doesn't have run on their defaults. To change one, copy that section from the new config/config.lua into yours.

11. Troubleshooting

Start here: read the start-up check in the server console. It is the box that starts with PULSE PHONE by ZeroDev. Every [FAIL] or [WARN] line has its fix on the line below it (-> ...). Type phone:health to print it again and phone:diag for the details.

The phone won't open

Framework, money and jobs

Database

Calls, photos and the handset

Store and items

Other scripts, language and service

Install and version problems

12. Still stuck?

Join our Discord: https://discord.gg/RAjfwbXCqe

• Urgent (server down, players can't use the phone): open a ticket in #open-a-ticket.
• Everything else: post in the #pulse-issues forum. We go through it every week.

Please include the version from the first line of the start-up check (PULSE PHONE by ZeroDev v...), every console line that starts with [phone], any red lines, and the output of phone:diag.