X3D Phone

Installation

1. Extract the zip and put the x3d_phone folder in resources/. Do not rename the folder: every export and event uses this name.
2. Run install.sql on your server database. It is safe to run again and keeps existing data.
3. If your server has no phone item, run optional/phone_item.sql. With ox_inventory, add the item to ox_inventory/data/items.lua instead; the file has an example.
4. If your server has no screenshot-basic, move optional/screenshot-basic/ into resources/. You can skip this; only the camera needs it.
5. Add these lines to server.cfg, in this order:

ensure oxmysql
ensure es_extended
ensure pma-voice
ensure screenshot-basic
ensure x3d_phone

Players open the phone with F1, the /openphone command, or by using the phone item. While the phone is open, Alt switches to game controls; press it again to get the cursor back.

Requirements

No image host, no API key, and no other software to install.

---

All settings: config/config.lua

General

Phone item

With UseItem on:

• No item: the phone does not open, and every server callback refuses. Triggering events by hand does not get past this.
• A player without the item cannot be called. The caller sees "unavailable" and the call is logged as missed.
• SMS are still stored, but no alert shows until the player has the item.
• If the item leaves the inventory while the phone is open (dropped or taken), the phone closes and any call ends.

Calls

Config.Ringtones, Config.NotificationSounds and Config.Wallpapers are what the server checks a player's choice against. You can remove an option in the config. Adding a new option also needs a change to the phone's web UI.

Messages

Emoji work in every text box (SMS, Buzz, Dark Chat), with a picker holding all 3,600+ emoji in 9 groups plus search. Lengths are counted in real characters, so Thai text and emoji are not over-counted.

Buzz and post card skins

Example: lock the whole server to Halloween for the event:

Config.Buzz = {
    ToChat = true,
    Themes = { 'halloween' },
    DefaultTheme = 'halloween',
    PlayerTheme = false,
}

Post cards use FiveM's standard chat resource. x3d_phone adds its own styles through chat_theme and leaves your chat theme alone. Post text is always escaped, so players cannot inject HTML into chat.

Service numbers (police / EMS / mechanic) and job scripts

• Service numbers appear as special contacts for everyone and cannot be edited or deleted.
• Texting police delivers [Police] ... to every online player with a job in jobs who has a phone. It arrives from the sender's own number with their location, so a tap sets a GPS waypoint and a reply goes straight back to the sender.
• The location comes from the character's position on the server, so it cannot be faked. One message per service every 20 seconds.
• If nobody from the service is online, the sender is told.

Hooking up job scripts: the police, ambulance and mechanic numbers already ship in the config, and your job scripts can add or remove numbers with these events.

Job scripts that call the old esx_phone:* event names do not work with x3d_phone; point them at the events above.

Dispatch app

Responders (players with a job in jobs) get a Dispatch app. Each call shows a title, message, distance, age and the caller's number, plus a flashing map blip, a notification and a sound.

• Respond sets a GPS waypoint, tells the caller "X accepted and is on the way", and shows the other responders that someone has it.
• Close call removes it from every phone and map. Calls nobody closes expire after AlertSeconds.
• Calls come from texts to a service number, or from other scripts requesting a service.

Requesting a service from other scripts (e.g. a "call EMS" button on the death screen):

-- client
exports['x3d_phone']:RequestService('ambulance', 'Unconscious in the street')
-- or
TriggerServerEvent('x3d_phone:requestService', 'ambulance', 'Unconscious in the street')

-- server (set your own title / coords)
exports['x3d_phone']:SendAlert('police', { source = src, title = 'Bank robbery', message = 'Pacific Standard' })
exports['x3d_phone']:SendAlert('police', { coords = vector3(x, y, z), title = 'Alarm triggered' })

RequestService reads the location from the caller's character on the server, so it cannot be faked, and a player can call the same service once every 60 seconds.

Bills app

Locked bills can only be cancelled in x3d_adminpanel → Phone → Unpaid bills (search by number or description, hold to cancel, with a cancel log).

Business bills: by default there is no society account (Billing.PaySociety returns false), so the payer is not charged and the bill stays unpaid. Wire your server's society account (for example esx_addonaccount) in addons/billing/server.lua before you use business bills.

• The recipient gets an alert at once if online. If offline, the bill waits in the app.
• A bill can be paid once; tapping repeatedly never charges twice.
• One bill every 5 seconds per player, and descriptions go through FilterMessage like other messages.

Billing from other scripts (server):

local ok, idOrError = exports['x3d_phone']:CreateBill(source, '48213', 500, 'Parking fine', 'police')
-- issuer: 'personal', a job name in Config.Billing.Jobs (the biller must actually have that job) or 'admin' (the biller must be in Config.Billing.Admin.groups)

Images: camera, uploads and external links

Where images are stored: in x3d_phone/data/uploads/ on your server. They are served through FXServer's own game port (30120), with no outside service. Worst-case disk use is Keep × MaxBytes, about 3 GB by default, but a camera photo is normally under 400 KB.

BaseUrl: when empty, image links are stored as /i/<token>.jpg. Each player's client adds the address of the server it is connected to, so this works with no setup. Set BaseUrl only when:

• you have an https domain pointing at the server (for example through a reverse proxy), and you want photos to show inside post cards in chat.
• Example: BaseUrl = 'https://img.myserver.com/x3d_phone'

Why cdn.discordapp.com is not a default host: Discord file links expire after about 24 hours when opened outside Discord, so the image would be gone the next day.

⚠️ AnyImageHost = true: the image host sees the IP address of every player who views the image, and you do not control what the image shows. Prefer listing the hosts you trust in ImageHosts.

Mobile banking

Transfers go to the phone number of an online player. They use the ESX bank account and are logged in the x3d_phone_bank_history table. A transfer cannot start while another one is still running, and a player can transfer once every 3 seconds.

---

Copies to Discord

Add these to server.cfg. The webhook URLs stay on the server; players never see them.

set x3d_phone_upload_webhook "https://discord.com/api/webhooks/..."
set x3d_phone_log_webhook    "https://discord.com/api/webhooks/..."

• Mentions are off in every post, so a player named @everyone pings nobody.
• Posts are queued, one every 1.5 seconds, to stay under Discord's rate limit. When more than 20 are waiting, new ones are skipped.
• The photo itself stays on your server, so in-game links never expire.
• Only URLs that look like real Discord webhooks are accepted.

---

Fitting your server: addons/

Edit these files freely. Each one works out of the box.

Example: to use your own banking system, change Banking.Transfer to call it and return true, or false, 'error message'. The server has already checked the amount, the recipient and the rate limit.

Example: banned words:

Config.BannedWords = { 'badword1', 'badword2' }

---

Exports (client)

exports['x3d_phone']:OpenPhone()
exports['x3d_phone']:ClosePhone()
exports['x3d_phone']:IsPhoneOpen()     --> boolean
exports['x3d_phone']:GetPhoneNumber()  --> string | nil
exports['x3d_phone']:IsInCall()        --> boolean
exports['x3d_phone']:GetCallData()     --> { phoneNumber, displayName, isOutgoing } | nil

Commands

Troubleshooting