Features
Maps (fx-mapsapp)
The bundled maps app with saved pins, navigation and live location sharing, how it installs into the phone and its main settings.
#What it is
fx-mapsapp is a maps app. It shows on the phone as "Maps" by default; the name is Config.Phone.AppName.
- The map, two ways. A drawn atlas or a satellite image, with pinch, drag, double-tap and rotate. The player's own position is live, with a heading cone and the street name.
- Fast Nav. One tap on a category (fuel, hospital, bank and so on) marks the nearest one with a GPS route. Every location in the catalogue is searchable by name, by category or by pasting coordinates.
- Pins. Double-click the map to drop a pin, name it, pick a category and leave a note. One pin can be Home and one Work.
- Sharing pins. Publish a pin under a short code, or send it to a nearby player or a friend. A sent pin waits in their inbox until accepted and becomes their own copy. Codes can expire or be limited to a number of uses.
- Live friend locations. Add a friend standing next to you or by friend code, then share your location for a set time or until switched off. Sharing is per friend and per direction.
- Navigation. A route draws a line on the map, sets the in-game waypoint and keeps a live distance and ETA. Arrival is sent as a phone notification.
- Per player. Pins, friends, sharing, theme, language, units and display toggles are saved per player.
This is a separate app from the phone's own map features described in Map integration.
#Requirements
| Resource | Required |
|---|---|
fx-phone |
Yes (the app also installs into lb-phone or cylex_phone) |
oxmysql |
Yes |
| MySQL 5.7+ or MariaDB 10.2+ | Yes |
Works with ESX, QBCore, Qbox or standalone, detected automatically. For anything else, fill in bridge/custom.lua. No API key is needed.
#Installation
cfgensure oxmysql
ensure fx-phone
ensure fx-mapsapp
Run setup/sql/install.sql once against your database. It creates eight tables prefixed maps_ and is safe to run twice. When upgrading an older install, also run setup/sql/migrations/003_pin_details_and_sharing.sql.
fx-mapsapp must start after the phone. If it starts first it waits 30 seconds for a phone to appear, then prints what it looked for.
#How it registers into the phone
With Config.Phone.Resource = 'auto' the app installs into whichever supported phone is running. Its FX Phone adapter (client/phone/fxphone.lua) calls exports['fx-phone']:AddCustomApp with Config.Phone.AppIdentifier (default fx_maps), AppName, Developer, Icon, DefaultApp and Size. On the server it reads the player's number with exports['fx-phone']:GetPhoneNumber.
To keep the app from starting at all, set ['fx-mapsapp'] = false in Config.BundledApps. See Apps.
#Config highlights
config.lua:
| Setting | Meaning |
|---|---|
Config.Framework |
auto or a fixed framework |
Config.Locale, Config.Locales |
Default language and the languages players may choose |
Config.Theme |
Default theme and the themes on offer |
Config.Phone |
Phone choice, AppIdentifier, AppName, Icon, DefaultApp |
Config.Map |
Map calibration |
Config.Position |
The self-position loop: how often it wakes while still and while moving |
Config.Route |
Route drawing and arrival |
Config.Places |
Pin limits |
Config.PinShare |
Share codes: length, expiry, use limits |
Config.Friends |
Friend limits, friend codes and sharing durations |
Config.Pois |
The location catalogue: categories and the list of places. Add, remove or replace them freely |
Config.Avatars |
Friend avatars |
Config.Notifications, Config.Sound |
Phone notifications and interface sounds |
Config.RateLimits, Config.Cache |
Rate limits and cache lifetimes |
config_server.lua is server only and holds the Discord webhook settings.
#Performance and security
From the resource's README:
- The map is the only thing that polls, and only while it is on screen. Closing the app, putting the phone away or switching to Settings stops the position loop.
- The position loop paces itself: slower while standing still, faster while moving. A position is only published once the player has moved.
- Friend positions are sent from one server tick, only to players with the map open, and only for friends that moved.
- Search never reaches the server; the catalogue is config and already on the client.
- Live positions are read on the server from the player's ped. A client does not report where it is.
- Sharing is checked against the database on every tick, so revoking a share takes effect on the next tick.
- Every client request is rate limited, then validated.
#Exports
| Export | Side | Purpose |
|---|---|---|
GetVersionStatus() |
Server | Result of the update check: { state, current, latest, behind } |
The app has no other exports.