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.