Documentation
Using Waypoint for FiveM: the in-game creator, profiles and shareable style codes, every icon, route arrow, 3D marker, ring and beam option, the GPS route, performance mode and translations.
A waypoint in this script is not one thing but several, each with its own switch, so a player can keep only the parts they like:
Part | Where it is drawn | Seen from |
|---|---|---|
Icon | On screen, over the destination. | Any distance — this is the waypoint you see from across the map. |
Distance label | Under the icon. | Any distance. |
Off-screen indicator | At the edge of the screen, when the destination is behind you. | Any distance. |
Route | Arrows on the streets ahead of you. | While the destination is 40 m to 4 km away. |
World marker, ring and beam | In the world, standing at the destination. | A few hundred metres — the game does not draw 3D markers further out. |
It draws for the map waypoint the player sets on the pause map — or that any phone, dispatch or job script sets for them — and for every point other scripts add through the exports.
Action | How |
|---|---|
Open |
|
Open with a key | The key in |
Close |
|
There is no Save button. Every change is applied to the waypoint in the world as it is made and saved straight away. The window can be dragged by its header, and it reopens where it was left.
Where | What is there |
|---|---|
Left column | Profiles: the player's saved styles, how many of the limit are used, and New, Duplicate, Rename and Delete. |
Top right | Preview: the active style shown three ways — On screen, Off-screen at the edge, and In world with the route and the marker. |
Right | The editor: every option of the active profile, in sections. The Waypoint, Arrows and Marker buttons at its top jump to the matching section. |
Footer | Share (export and import a style), Reset and Close. |
Colours are picked from eight presets, from a colour picker, or by typing a hex code such as #00A3FF.
With Config.Preview = true, opening the creator also puts a stand-in waypoint on the ground Config.PreviewDistance metres (22 by default) in front of the player, so a style can be judged in the real world without setting a waypoint first. It appears only when there is nothing real to show, and disappears when the creator closes.
A profile is one complete style with a name. A player can keep up to Config.MaxProfiles of them (ten by default) — one for driving, one for walking, one for work — and only the active one is drawn. Clicking a profile makes it active.
Button | What it does |
|---|---|
New | Adds a profile called New style, starting from the server's factory style, and makes it active. |
Duplicate | Copies the active profile as <name> 2 — the quickest way to try a variation without losing the original. |
Rename | Up to 24 characters. |
Delete | Asks first, and cannot be undone. The last profile can never be deleted. |
Reset | In the footer. Deletes every profile and goes back to a single Default profile with the server's factory style, the waypoint switched on and the server's default units. |
Share in the footer opens a window with two boxes:
Export holds the active profile as a code starting with QSWP1:. Click it to select it all, copy it, and send it to a friend or post it in your Discord.
Import takes a code pasted by the player. Pressing Import adds it as a new profile called Import and makes it active.
A code carries the look only, not the profile's name. A damaged or incomplete code is refused with That code could not be read, and a player at the profile limit has to delete one first. Values from a code are checked like any other, so a hand-edited code cannot push anything past its allowed range.
Server owners can use this too: design a style in game, export it, and post the code as your server's "official" waypoint for players to import.
Every option below is a control in the creator and a field of Config.DefaultStyle in config.lua, with the same name. The default is the value that ships. A value outside its range is pulled back to the nearest limit, and an unknown icon or shape falls back to the factory style, so a mistake in the config can never stop the waypoint drawing. Colours are { red, green, blue }, each 0 to 255.
Field | Default | Range | What it does |
|---|---|---|---|
|
| see below | The drawing shown over the destination. |
|
| RGB | Icon colour. Also used by the off-screen indicator. |
| 235 | 10 – 255 | How solid the icon is drawn. |
| 1.0 | 0.2 – 4.0 | Scale of the icon on screen. |
| true | on / off | A dark edge, so it reads over bright skies and scenery. |
| true | on / off | A soft aura behind the icon, in the same colour. |
| true | on / off | The icon's own motion: pinging rings, drifting chevrons, a turning reticle. Costs nothing extra. |
The twelve icons, with the key used in config.lua:
Key | Name in the creator | Key | Name in the creator |
|---|---|---|---|
| Pin |
| Shield |
| Round pin |
| Star |
| Navigator |
| Flag |
| Beacon |
| Hex badge |
| Gem |
| Chevrons |
| Reticle |
| Alert |
Field | Default | Range | What it does |
|---|---|---|---|
| true | on / off | The remaining distance under the icon. |
| 0.35 | 0.15 – 1.0 | Text size. Also used for a script waypoint's label. |
|
| RGB | Text colour. |
In kilometres the label reads 850 m up to a kilometre and 1.4 km after; in miles it reads 420 ft up to a tenth of a mile and 0.85 mi after.
Field | Default | Range | What it does |
|---|---|---|---|
| true | on / off | Pins the icon to the edge of the screen when the destination is out of view. |
| 0.8 | 0.3 – 2.0 | Its size, relative to the icon's. |
The indicator is the same drawing as the icon, on purpose: turning the camera moves the waypoint rather than swapping it for something else. It appears once the destination is more than 45° away from where the camera is looking, with the distance under it.
Field | Default | Range | What it does |
|---|---|---|---|
| true | on / off | Arrows along the streets to the destination. |
|
|
| A solid chevron, two smaller ones in a row, or an open outline. |
|
| RGB | Trail colour. |
| 190 | 10 – 255 | Trail opacity. |
| 1.0 | 0.2 – 3.0 | Arrow size. At 1.0 an arrow is about 1.8 m long. |
| 6.0 | 2 – 20 m | Metres between one arrow and the next. |
| 90.0 | 20 – 300 m | How far ahead of the player the trail is drawn. The far end fades out instead of stopping dead. |
| true | on / off | A wave of brightness running along the trail towards the destination. |
Field | Default | Range | What it does |
|---|---|---|---|
| true | on / off | A 3D shape standing at the destination. |
|
|
| Upside-down cone, thick chevron, double chevron, cylinder, thin ring, thick ring, sphere or checkered flag. |
|
| RGB | Marker colour. The ground ring uses it too. |
| 200 | 10 – 255 | Marker opacity. The ring and the beam are drawn fainter, relative to it. |
| 1.0 | 0.2 – 4.0 | Marker size. |
| 1.0 | 0 – 10 m | How far above the ground it floats. |
| true | on / off | Keeps the same size on screen at any distance. Off, it is a fixed size in metres and shrinks into the distance like any object. |
| true | on / off | Drifts gently up and down. |
| false | on / off | Spins on the spot. |
| true | on / off | Always turns to face the player. |
The game only draws 3D markers from a few hundred metres away, whatever their size. That is why the world marker is an extra and not the waypoint itself: from across the map, the icon is what shows the way.
Field | Default | Range | What it does |
|---|---|---|---|
| true | on / off | A circle on the ground under the marker, in the marker's colour. |
| 1.0 | 0.2 – 5.0 | Ring size. |
| false | on / off | A pillar of light going up from the destination, visible over rooftops. |
| 8.0 | 1 – 60 m | Beam height. |
| 1.0 | 0.2 – 6.0 | Beam width. |
|
| RGB | Beam colour. |
Field | Default | Range | What it does |
|---|---|---|---|
| 0 | 0 – 200 m | Stops drawing the icon and marker once the player is this close. |
| 0 | 0 – 5000 m | Does not draw the icon and marker past this distance. |
The last section of the editor holds two choices that belong to the player, not to a profile, so they stay put when switching styles:
Waypoint marker — switches the whole waypoint off for that player, for those who prefer the plain game map.
Distance units — KM or MILES. A new player starts with Config.DefaultUnits.
The arrows are built from the game's own road network: starting from the player, the script repeatedly takes the next road point that brings it closer to the destination, so every arrow sits on a real road and the trail never cuts through a block. Where an arrow would land on a roof, a bridge deck or a tunnel ceiling instead of the road, it is dropped.
Rule | Value |
|---|---|
Drawn while the destination is | Between 40 m and 4 km away (3 km in performance mode). Closer, the destination is in sight; further, the walk would never finish. |
Rebuilt when | The destination moves more than 15 m, the player strays 40 m from the trail, the player is 60% of the way along it, or every 20 seconds (30 in performance mode). |
Which destination | The map waypoint when one is set. Otherwise one of the points added by scripts. There is one trail at a time. |
Which style | Always the player's active profile — the trail belongs to the player, not to a waypoint. |
The route is a guide along the streets, not a turn-by-turn sat-nav. At a complicated motorway interchange it can take a longer way round or end early — it corrects itself as the player drives and the trail is rebuilt. Turning performance mode off gives the best choices at junctions.
Config.OnlyInVehicles = true hides the map waypoint and every script waypoint while the player is on foot, and brings them back the moment they sit in any vehicle. Useful on servers where on-foot navigation should stay realistic. The preview marker in the creator still shows.
Waypoint is built to cost nothing when there is nothing to show:
A light background check asks a few times a second whether there is anything to mark.
Drawing runs every frame only while something is actually on screen, and sleeps otherwise.
The route is built on its own, a few road points per frame, and reused until it needs rebuilding.
Nothing runs on the server.
Config.PerformanceMode switches between two presets:
| Off (accurate) | On (light) |
|---|---|---|
Background checks | Every 200 ms | Every 400 ms |
Longest route | 4 km | 3 km |
Road points per route | Up to 600 | Up to 300 |
Junctions | Asks the game for real driving distances to pick the right turning | Picks the turning that points closest to the destination |
Route refresh | Every 20 s | Every 30 s |
Leave it off unless many of your players are on low-end computers. The icon, the marker and the arrows look exactly the same in both.
translations.lua holds one Locale table with every text in the creator: section titles, option names, hints, icon and shape names, buttons and dialogs.
English is active out of the box.
Spanish ships complete at the bottom of the same file, commented out. Replace the English table with it to switch.
Any other language: translate the values and keep the keys. %s marks where a number or a name is inserted — keep it in the sentence.
A key you delete falls back to the English text built into the interface, so a partial table is safe. Restart the resource after editing the file.
