Waypoint

Waypoints as 3D markers in the world. The GTA map waypoint is shown automatically, other scripts set their own waypoints via exports on the client or the server. The script needs no framework.

Requirements

OneSync, only if server scripts use onArrive (the server then checks the distance)

Features

GTA waypoint as a 3D marker with distance. The waypoint is removed on arrival.
Two types: checkpoint with a line down to the ground and small as a floating marker.
Configurable per waypoint: color, icon or image, text, distance, blip with GPS route, expiry time and a function on arrival.
Exports for client and server.
Lightweight: Only the nearest waypoints are drawn (maxVisible), the browser instances are reused and cleaned up when they are no longer needed.

Installation

Put the off_waypoint folder into your resources folder.
Add to your server.cfg:

cfg

ensure off_waypoint

Configuration

`config/settings/config.lua`

Option	Default	Description
`serverInfo.name`	`'OFF SCRIPTS'`	Server name, shown in the UI instead of "OFF SCRIPTS"
`serverInfo.locale`	`'de'`	Language: `de`, `en`, `pl`, `fr`, `es` or `it`
`serverInfo.color`	`{ 155, 89, 255 }`	Server color (RGB), also used for waypoints without their own `color`
`serverInfo.design`	`3`	UI design: `1` = Classic, `2` = Receipt, `3` = Storefront
`type`	`'checkpoint'`	Default type: `'checkpoint'` or `'small'`
`drawDistance`	`500.0`	Default view distance in meters
`displayDistance`	`true`	Show distance by default
`maxVisible`	`6`	How many waypoints are shown at the same time, nearest first
`blip`	`{ sprite = 162, color = 17, scale = 0.8 }`	Default for waypoint blips
`mapWaypoint.enabled`	`true`	Show the GTA waypoint as a 3D marker
`mapWaypoint.type`	`'checkpoint'`	Type of the GTA waypoint
`mapWaypoint.drawDistance`	`10000.0`	View distance of the GTA waypoint
`mapWaypoint.arriveDistance`	`25.0`	The GTA waypoint is removed within this distance, `0` = never

Languages

The default waypoint text and the console messages are in config/locales/ (one file per language).

Waypoint options

You can pass these fields when creating and updating. Only coords is required.

Field	Description
`coords`	`vector3`, `vector4` or `{ x, y, z }`
`type`	`'checkpoint'` or `'small'`
`label`	Text below the distance, `false` = no text
`color`	`'#9b59ff'` or `{ 155, 89, 255 }`
`icon` / `iconColor`	Phosphor icon (e.g. `'ph-flag'`, default `'ph-map-pin'`) and a custom icon color
`image`	Image URL instead of an icon
`displayDistance`	Show distance
`size`	Size, default `1.0`
`drawDistance` / `fadeDistance`	View distance and the distance from which the waypoint fades out
`dynamicScaling`	Gets bigger and higher with distance, like the GTA waypoint
`arriveDistance`	Arrival radius in meters, default `5.0`
`onArrive`	Function on arrival: on the client `(id, metadata)`, on the server `(source, id)`
`removeDistance`	Removed as soon as you are this close
`duration`	Milliseconds until the waypoint is removed
`blip`	`true` or `{ sprite, color, scale, name, shortRange }`
`route` / `routeColor`	GPS route to the waypoint (sets a blip automatically) and its color
`groundZ` / `minHeight` / `maxHeight`	`checkpoint` only: ground height of the line and limits of its height
`metadata`	Any data, returned in `onArrive` and `GetWaypoint`

For developers

lua

-- Client
local id = exports.off_waypoint:AddWaypoint({
  coords = vector3(215.0, -810.0, 30.7),
  label = 'Pickup',
  icon = 'ph-package',
  color = '#3B9EFF',
  route = true,
  onArrive = function(id)
    exports.off_waypoint:RemoveWaypoint(id)
  end,
})

exports.off_waypoint:UpdateWaypoint(id, { label = 'Abgabe', coords = vector3(300.0, -900.0, 29.3) })
exports.off_waypoint:RemoveWaypoint(id)          -- with fade-out, RemoveWaypoint(id, true) instantly
exports.off_waypoint:RemoveAllWaypoints()        -- all waypoints of your script
local waypoint = exports.off_waypoint:GetWaypoint(id)
local exists = exports.off_waypoint:HasWaypoint(id)

-- Server
local id = exports.off_waypoint:AddWaypoint(source, {
  coords = vector3(215.0, -810.0, 30.7),
  label = 'Lieferung',
  onArrive = function(source, id)
    exports.off_waypoint:RemoveWaypoint(source, id)
  end,
})

exports.off_waypoint:UpdateWaypoint(source, id, { label = 'Neue Adresse' })
exports.off_waypoint:RemoveWaypoint(source, id)
exports.off_waypoint:RemoveAllWaypoints(source)  -- all waypoints of your script for this player
local exists = exports.off_waypoint:HasWaypoint(source, id)

When a script stops, its waypoints are removed automatically.
onArrive on the server only fires if the player is really nearby according to the server.

Common issues

Problem	Solution
Waypoints are invisible	`web/dist` is missing – run `npm install` and `npm run build` in the `web` folder.
Not all waypoints are visible	Only the nearest `maxVisible` are shown, increase the value in the config.
Icon is missing	Check the name on phosphoricons.com, e.g. `ph-flag`.
`onArrive` on the server does not fire	OneSync must be on and `arriveDistance` must fit the location.

Not bought yet?

View Waypoint in the shop