Sleepless Waypoints

A 3D DUI waypoint and marker system for FiveM. Create customizable waypoints with support for different styles, icons, labels, and distance tracking.

Github

Releases

Features

Two Waypoint Types: Small markers and checkpoint-style beacons
Customizable Appearance: Colors, icons, labels, and sizes
Distance Display: Automatic distance tracking to waypoints
Map Waypoint Sync: Automatically creates a 3D marker at the player's map waypoint
Server-side Support: Create waypoints for specific players or globally from the server
Performance Optimized: Efficient rendering with distance-based culling

Installation

Download a release (opens in a new tab) or build the source code.

git clone https://github.com/Sleepless-Development/sleepless_waypoints.git
cd sleepless_waypoints/web
pnpm i
pnpm build

Usage

Add to your resource folder and ensure sleepless_waypoints in your server.cfg

ensure sleepless_waypoints

You can now use the waypoints exports inside of your resources.

Configuration

Configure the resource in config.lua:

local config = {}
 
-------------------------------------------------
-- Map Waypoint Sync
-------------------------------------------------
-- When enabled, a waypoint marker will be created at the player's map waypoint
config.syncToWayPoint = true
 
-- Settings for the auto-created map waypoint marker
config.mapWaypoint = {
    type = 'checkpoint',
    label = 'WAYPOINT',
    color = '#f500fc',
    size = 1.0,
    drawDistance = 1000.0,
}
 
-------------------------------------------------
-- Default Waypoint Settings
-------------------------------------------------
config.defaults = {
    drawDistance = 500.0,     -- Maximum distance to render the waypoint
    fadeDistance = 400.0,     -- Distance at which waypoint starts fading
    size = 1.0,               -- Base size multiplier
    minHeight = 0.5,          -- Minimum marker height (checkpoint type)
    maxHeight = 50.0,         -- Maximum marker height (checkpoint type)
    groundZOffset = -2.0,     -- Offset from coords.z for ground position
    color = '#f5a623',        -- Default marker color (hex)
    label = 'CHECKPOINT',     -- Default label text
    displayDistance = true,   -- Show distance on marker by default
}
 
-------------------------------------------------
-- DUI Settings
-------------------------------------------------
config.dui = {
    width = 512,     -- DUI texture width in pixels
    height = 1024,   -- DUI texture height in pixels
}
 
-------------------------------------------------
-- Rendering Settings
-------------------------------------------------
config.rendering = {
    updateInterval = 100,           -- Main loop update interval (ms)
    perspectiveDivisor = 20.0,      -- Camera distance divisor for perspective scale
    checkpointBaseMultiplier = 4.0, -- Multiplier for checkpoint base size
    checkpointMinScale = 0.1,       -- Minimum perspective scale for checkpoints
    checkpointAspectRatio = 2.0,    -- Height to width ratio for checkpoint quads
    smallMinScale = 1.0,            -- Minimum perspective scale for small markers
    smallAspectRatio = 2.0,         -- Height to width ratio for small marker quads
}
 
-------------------------------------------------
-- Server Settings
-------------------------------------------------
config.server = {
    cleanupInterval = 60000,  -- Cleanup interval for disconnected players (ms)
}

Waypoint Data

All waypoint creation functions accept a WaypointData table with the following properties:

Property	Type	Default	Description
`coords`	`vector3`	required	The 3D position of the waypoint
`type`	`'small'` \| `'checkpoint'`	`'small'`	Waypoint style type
`color`	`string`	`'#f5a623'`	Hex color for the waypoint
`label`	`string`	`'CHECKPOINT'`	Text label (mainly for checkpoint type)
`icon`	`string`	`nil`	Icon name for the waypoint
`image`	`string`	`nil`	Image URL for the waypoint
`size`	`number`	`1.0`	Size multiplier
`displayDistance`	`boolean`	`true`	Whether to show distance text
`drawDistance`	`number`	`500.0`	Maximum distance to render
`fadeDistance`	`number`	`400.0`	Distance to start fading
`minHeight`	`number`	`0.5`	Minimum height for checkpoint line
`maxHeight`	`number`	`50.0`	Maximum height for checkpoint line
`groundZ`	`number`	`coords.z - 2`	Ground Z coordinate for the line

Waypoint Types

Small

A compact marker suitable for nearby points of interest. Displays an icon or image at the specified coordinates.

Checkpoint

A tall beacon-style marker visible from far distances. Features a vertical line extending from the ground with a label and distance display at the top.

addPed create