Agency-Phone: The Smartphone Built Specifically for FiveM

Why Build Yet Another FiveM Phone?

We built Agency-Phone because every phone we tried on our own servers either looked great and performed badly, or performed well and looked dated. The market was full of compromises. We wanted something that genuinely felt like a modern smartphone the moment you opened it, and that still hit 0.00ms idle resource usage when it was sitting in someone's pocket.

A UI That Doesn't Feel Like FiveM

Most FiveM phones betray their origin within two seconds of opening them. The fonts look slightly off, animations are jerky, the home screen layout feels like a placeholder. Agency-Phone was designed by people who use real smartphones daily. Every element — from the lock screen clock to the app drawer spring physics — was iterated until it stopped feeling like a script and started feeling like a phone.

The App Architecture

Under the hood Agency-Phone uses a lazy-loading app system. Apps only initialize their UI when they're actually opened, which keeps memory usage flat even as we ship more apps. The event bus between client Lua and the NUI layer is debounced so rapid user actions don't flood the game with resmon spikes. This is the kind of engineering work nobody sees but everyone benefits from when their server is holding 128 players.

Framework-Agnostic By Default

Agency-Phone ships with adapters for QBCore and ESX but the core is framework-independent. If you run a standalone server with your own player data layer, you can wire it up in an afternoon by implementing four lookup functions. We refuse to ship scripts that lock you into one framework because frameworks churn — we've seen at least three waves of "this is the standard now" come and go in our time in the community.

The Point of a Phone in RP

A FiveM phone is ultimately a social tool. Players use it to coordinate meetups, run drug deals, message their boss's character, listen to music on the radio app. Everything we add or remove from Agency-Phone is judged against the question: does this make social interaction easier or more fun? That's why we shipped a gallery app before we shipped calendar reminders, and why the stock messaging app has rich typing indicators before it has scheduled sends. RP first, feature checklists second.

Installation & Setup

Agency-Phone requires oxmysql for contact, message, and call log persistence. Import phone.sql into your database, download the resource from Tebex, drop it into your resources directory, and add ensure agency-phone to server.cfg. Framework detection is automatic for QBCore and ESX. For standalone setups, implement the four adapter functions in config.lua — typically an hour or two of work depending on your custom player data layer.

Players open the phone by pressing the configurable keybind (default: M) or an item in their inventory. Both methods are supported simultaneously — some servers use the key shortcut, others prefer the immersive item approach where the phone can be dropped or stolen.

Configuration Options

The config.lua covers both technical and gameplay settings:

• Phone keybind — key to open/close the phone. Default: M.
• Phone as item — toggle whether a phone item is required in inventory. Default: disabled (key-only).
• Number format — how phone numbers are displayed and auto-generated for new characters.
• Call range — maximum physical distance for in-range calls vs. out-of-range (voicemail). Default: unlimited for in-character calls.
• Twitter/LifeInvader integration — connect Agency-LifeInvader if installed for the social app.
• Radio app integration — configure available radio streams for the music player app.
• Banking app — connect QBCore banking, ESX accounts, or a custom banking handler.
• GPS app — custom waypoint categories for server-specific locations (hospitals, police stations, businesses).
• Notification routing — which external scripts can push notifications to the phone and how they appear.

Framework Compatibility

Agency-Phone ships with QBCore and ESX adapters. The adapter covers money display, inventory item (if phone-as-item is enabled), job data for job-specific app visibility, and character name display. For standalone, the same four-function pattern applies. Once the adapter is written for one Agency script, subsequent scripts share the same functions.

Why This Matters for Roleplay

A phone is the most personal prop a character carries. Players interact with it every session — making calls, sending texts, checking their bank balance, looking at the map. When that interaction feels like a real phone, the RP sessions that involve phone use feel more real as well. A drug deal coordinated through Agency-Phone's SMS app, with read receipts and typing indicators, is a meaningfully different (better) scene than the same deal coordinated through a chat command.

The social coordination function is the phone's most RP-critical role. Most significant RP events start with communication: someone reaches out, arranges a meeting, provides coordinates, confirms timing. All of that communication is more immersive when it happens through in-character channels rather than Discord or OOC chat. Agency-Phone's calling and SMS apps cover 95% of that social coordination need natively.

The 0.00ms idle resource usage isn't just a technical footnote — it's what makes the phone feasible as an always-open resource. Scripts that cost 0.02ms idle on a 128-player server contribute 2.56ms of aggregate idle load across the population. Agency-Phone's idle cost contribution is zero. That matters for server performance the same way any shared resource does: proportional to player count.

The gallery app in v2 and the in-game screenshot capability have created an unexpected RP use case: in-character evidence photography. Police characters take screenshots of crime scenes with the phone's camera and share them in their department's internal chat. Journalists photograph events and post them on LifeInvader. The camera transforms the phone from a communication tool into a documentation tool with genuine RP application.

Frequently Asked Questions

Can phone numbers be persistent across server wipes?

Phone numbers are stored in oxmysql against the character identifier. As long as the character identifier is preserved across a wipe, the number persists. Most server wipes clear character progression but preserve identifiers, so numbers typically survive. For full wipes that include identifier resets, a number preservation export is available that saves/restores a character's number separately from the main wipe.

Can police trace calls and messages in real time?

Yes. Enable the trace system in config.lua. Police with the required permission flag can open the trace panel and search by number. Active call origins appear on the map. Message metadata (time, number pair) is stored in the log table and accessible through Agency-Admin. Full message content tracing is disabled by default as a privacy-by-design choice — enable it explicitly if your server's RP rules support it.

How does the phone handle calls when a player is dead or in custody?

Configure death state and handcuff state in config.lua. Dead players can be set to go straight to voicemail, have their phone disabled, or allow emergency calls only. Handcuffed players can be blocked from phone use entirely or restricted to GPS-only view (so police can see they're not calling for backup). These states are detected via exported functions from your deathscreen and handcuff scripts.

What radio stations are available in the music app?

The default station list includes eight community radio stream URLs covering common genres. Add your own by adding stream URLs to Config.RadioStations. Servers often add their own server radio station where staff broadcast in-character news. There's no DRM or streaming service integration — any publicly accessible audio stream URL works.

Requirements

• FiveM server (QBCore, ESX, or standalone)
• oxmysql
• cfx.re account with valid Agency-Phone license
• Optional: Agency-LifeInvader (for social app integration)
• Optional: Agency-Pad (for cross-device data sync)