Before You Begin#
Waypoint is a client-only resource. There is no server script, no database and no dependency to install first — the whole list of requirements is short:
Requirement | Status | Notes |
|---|---|---|
Framework | Not required | Works the same on ESX, QBCore, Qbox or a standalone server. Nothing in the script talks to a framework. |
Database | Not required | No SQL to import. Each player's styles are saved on their own computer. |
oxmysql · ox_lib | Not required | Not used. The resource depends on nothing else. |
Streamed textures | None | The icon is drawn from a small web page rendered into a texture at runtime, and the 3D markers use the game's own shapes. Nothing is added to your stream folder. |
Because everything runs on each player's own client, the server pays nothing for it: no threads, no events, no network traffic.
Downloading Waypoint#
After purchasing Waypoint, the resource is automatically linked to your CFX Portal account, the same account you used to sign in during checkout.
Sign in to the CFX Portal using the same account used during checkout, open Granted Assets, find Waypoint and download the latest version.
After extracting the download, you should have the following folder:
qs-waypoint/
├── config.lua -- every setting, and the default style (editable)
├── translations.lua -- every text in the creator (editable)
├── client.lua -- the resource itself
├── fxmanifest.lua
└── web/build/ -- the creator window and the icon, ready to useKeep the folder named
qs-waypoint. Other scripts call its exports by that name, and every player's saved styles are stored under it — rename the folder and every player starts again from the default style.
Installing the Resource#
Move the qs-waypoint folder into your server's resources directory. It can live in any category folder:
resources/
└── [qs]/
└── qs-waypoint/Then add it to your server.cfg:
ensure qs-waypoint
# Scripts that call Waypoint's exports go after it
ensure my-delivery-jobWaypoint itself has no loading order to respect. The only rule is for your own resources: a script that calls exports['qs-waypoint'] the moment it starts should be ensured after it.
Where Player Data Is Saved#
There is no SQL file to import and nothing is written to your database. Each player's choices are saved on their own computer, in FiveM's client storage (KVP) under the key qs-waypoint:state:
Saved | What it is |
|---|---|
Profiles | Every style the player made, with its name. |
Active profile | Which of them is drawn. |
On / off | Whether the player wants the waypoint drawn at all. |
Units | Kilometres or miles. |
This means styles survive server restarts and updates, cost the server nothing, and belong to the player's computer rather than to a character: switching characters keeps the same style, and joining from another computer starts from the default.
Configuring the Resource#
Two files are open for editing. Everything else ships protected.
File | Contents |
|---|---|
| How players open the creator, units, profile limit, performance mode, the preview marker and the factory style every new profile starts from. |
| Every text shown in the creator. See Usage → Translations. |
The general settings at the top of config.lua:
Config.Command = "waypoint" -- /waypoint opens the creator. "" turns the command off
Config.Keybind = "" -- e.g. "F7". Empty: each player binds their own key
Config.OnlyInVehicles = false -- true: the waypoint is only drawn while driving
Config.MaxProfiles = 10 -- how many styles one player may save
Config.DefaultUnits = "km" -- "km" or "miles" for a new player
Config.PerformanceMode = false -- lighter checks, simpler routes
Config.Preview = true -- stand-in marker while the creator is open
Config.PreviewDistance = 22.0 -- metres in front of the playerBelow them, Config.DefaultStyle is the factory style: what a brand-new profile looks like and what Reset brings back. Every value in it is something players can change for themselves in the creator — it is only the starting point. Each field is explained in Usage → Styling Reference.
Changing the factory style does not repaint existing players. Their profiles are saved on their computers. A new style in
config.luareaches new players, new profiles, and anybody who presses Reset. LoweringConfig.MaxProfilesdrops the profiles above the new limit the next time a player joins.
Updating From an Older Version#
Version 3 replaces the old folder directly — there is nothing to uninstall and no data to move by hand.
Note your settings
Write down the values you changed in your old
config.lua— the command word, the units, your colour. The new file has more options and a different layout, so copy the values across rather than the file.Replace the folder
Stop the server, delete the old
qs-waypointfolder and put the new one in its place, under the same name.Start the server
Each player's settings are carried over the first time they join. Nothing else needs doing.
What carries over:
From 2.x — every profile, as it was. Options that did not exist yet take the values of your factory style.
From before 2.0 — the old single colour, size, on/off, edge indicator and units are folded into one profile called Default. The colour is applied to the icon, the marker and the beam, and the size to both the icon and the marker. The old keys are then removed.
Your scripts —
AddWaypointstill accepts the old{ color = { r, g, b, a } }options. See Commands and Exports.
Verifying the Installation#
Restart your server, join, and work through this short loop:
Set a waypoint on the map
Pick a spot a few streets away. A blue pin appears over the destination with the distance under it, and blue arrows appear on the road leading to it. The arrows are drawn while the destination is between 40 m and 4 km away.
Turn around
With the destination behind you, the pin moves to the edge of the screen on the side you need to turn to.
Open the creator
bash /waypointThe Waypoint Creator opens. Change the icon colour and the waypoint in the world changes with it, immediately.
If the creator opens and the pin shows, Waypoint is installed correctly. Changes made by players apply live; changes you make to
config.luaneed a restart of the resource.