Sleepless

WaypointsExports

Client Exports

Last updated on

All client-side exports for creating and managing waypoints locally on the player's client.

create

Creates a new 3D waypoint at the specified coordinates with customizable appearance and behavior.

local id = exports.sleepless_waypoints:create(data)

Parameters

ParameterTypeDescription
dataWaypointDataA table containing the waypoint configuration

Returns

TypeDescription
numberThe unique identifier for the created waypoint

Example: Small Waypoint

local id = exports.sleepless_waypoints:create({
    coords = vec3(100.0, 200.0, 30.0),
    type = 'small',
    color = '#ff6b6b',
    icon = 'hand',
    size = 0.15,
    drawDistance = 100.0,
})

print('Created waypoint:', id)

Example: Checkpoint Waypoint

local playerPos = GetEntityCoords(cache.ped)
local targetPos = vec3(200.0, 300.0, 30.0)

local id = exports.sleepless_waypoints:create({
    coords = targetPos,
    type = 'checkpoint',
    color = '#f5a623',
    label = 'DESTINATION',
    size = 1.0,
    drawDistance = 500.0,
    groundZ = playerPos.z - 1,
    minHeight = 5.0,
    maxHeight = 80.0,
})

Example: Waypoint with Image

local id = exports.sleepless_waypoints:create({
    coords = vec3(150.0, 250.0, 30.0),
    type = 'checkpoint',
    color = '#4ecdc4',
    label = 'COLLECT',
    image = 'nui://ox_inventory/web/images/copper_ore.webp',
    size = 1.0,
    drawDistance = 300.0,
    displayDistance = true,
})

The groundZ property determines where the vertical line of checkpoint-style waypoints begins. Set this to the ground level for the best visual effect.

update

Updates an existing waypoint's properties. Only the properties you specify will be changed.

exports.sleepless_waypoints:update(id, data)

Parameters

ParameterTypeDescription
idnumberThe waypoint ID returned from create
dataWaypointDataA table containing the properties to update

Updatable Properties

PropertyTypeDescription
coordsvector3New position for the waypoint
colorstringNew hex color
labelstringNew label text
iconstringNew icon
sizenumberNew size multiplier
drawDistancenumberNew maximum render distance
fadeDistancenumberNew fade distance
minHeightnumberNew minimum height
maxHeightnumberNew maximum height
groundZnumberNew ground Z coordinate

Example: Update Position

local id = exports.sleepless_waypoints:create({
    coords = vec3(100.0, 200.0, 30.0),
    type = 'checkpoint',
    label = 'TARGET',
})

-- Move the waypoint to a new position
exports.sleepless_waypoints:update(id, {
    coords = vec3(150.0, 250.0, 35.0),
})

Example: Update Appearance

-- Change the color and label
exports.sleepless_waypoints:update(id, {
    color = '#e74c3c',
    label = 'DANGER ZONE',
})

Example: Dynamic Waypoint

-- Create a waypoint that follows an entity
local targetEntity = GetClosestPed(GetEntityCoords(cache.ped), 50.0, true, true, true, true)

local id = exports.sleepless_waypoints:create({
    coords = GetEntityCoords(targetEntity),
    type = 'small',
    color = '#3498db',
    icon = 'user',
    size = 0.2,
})

-- Update the waypoint position periodically
CreateThread(function()
    while DoesEntityExist(targetEntity) do
        exports.sleepless_waypoints:update(id, {
            coords = GetEntityCoords(targetEntity),
        })
        Wait(100)
    end
    exports.sleepless_waypoints:remove(id)
end)

If you need to update multiple properties at once, pass them all in a single update call for better performance.

remove

Removes a waypoint by its ID. The waypoint will be destroyed and its DUI resources freed.

exports.sleepless_waypoints:remove(id)

Parameters

ParameterTypeDescription
idnumberThe waypoint ID returned from create

Example: Timed Removal

local id = exports.sleepless_waypoints:create({
    coords = vec3(100.0, 200.0, 30.0),
    type = 'checkpoint',
    label = 'TEMPORARY',
})

-- Remove the waypoint after 30 seconds
SetTimeout(30000, function()
    exports.sleepless_waypoints:remove(id)
    print('Removed waypoint:', id)
end)

Example: Conditional Removal

local waypointId = nil

-- Create waypoint when player starts a mission
RegisterNetEvent('mission:start', function(targetCoords)
    waypointId = exports.sleepless_waypoints:create({
        coords = targetCoords,
        type = 'checkpoint',
        color = '#2ecc71',
        label = 'OBJECTIVE',
        drawDistance = 500.0,
    })
end)

-- Remove waypoint when mission ends
RegisterNetEvent('mission:complete', function()
    if waypointId then
        exports.sleepless_waypoints:remove(waypointId)
        waypointId = nil
    end
end)

removeAll

Removes all active waypoints created by the client. Useful for cleanup operations.

exports.sleepless_waypoints:removeAll()

Example: Mission Cleanup

local waypointIds = {}

-- Create multiple waypoints for a mission route
local checkpoints = {
    { coords = vec3(100, 200, 30), label = 'CHECKPOINT 1' },
    { coords = vec3(150, 250, 30), label = 'CHECKPOINT 2' },
    { coords = vec3(200, 300, 30), label = 'CHECKPOINT 3' },
}

for i, checkpoint in ipairs(checkpoints) do
    waypointIds[i] = exports.sleepless_waypoints:create({
        coords = checkpoint.coords,
        type = 'checkpoint',
        color = '#f5a623',
        label = checkpoint.label,
    })
end

-- Clean up all waypoints when player cancels mission
RegisterNetEvent('mission:cancel', function()
    exports.sleepless_waypoints:removeAll()
    waypointIds = {}
end)

Example: Resource Cleanup

-- Clean up waypoints when resource stops
AddEventHandler('onResourceStop', function(resourceName)
    if resourceName == GetCurrentResourceName() then
        exports.sleepless_waypoints:removeAll()
    end
end)

get

Retrieves a waypoint instance by its ID. Returns the waypoint data and DUI reference if the waypoint exists.

local waypoint = exports.sleepless_waypoints:get(id)

Parameters

ParameterTypeDescription
idnumberThe waypoint ID returned from create

Returns

TypeDescription
WaypointInstance?The waypoint instance, or nil if not found

WaypointInstance Properties

PropertyTypeDescription
idnumberThe waypoint's unique identifier
dataWaypointDataThe waypoint's configuration data
duiDuiThe DUI instance used for rendering
activebooleanWhether the waypoint is currently active

Example: Check Waypoint Exists

local id = exports.sleepless_waypoints:create({
    coords = vec3(100.0, 200.0, 30.0),
    type = 'checkpoint',
    label = 'TARGET',
})

-- Check if waypoint still exists
local waypoint = exports.sleepless_waypoints:get(id)

if waypoint then
    print('Waypoint exists at:', waypoint.data.coords)
    print('Active:', waypoint.active)
else
    print('Waypoint not found')
end

Example: Calculate Distance to Waypoint

local waypoint = exports.sleepless_waypoints:get(waypointId)

if waypoint then
    local playerPos = GetEntityCoords(cache.ped)
    local distance = #(playerPos - waypoint.data.coords)
    print('Distance to waypoint:', distance)
end

Example: Get Waypoint Properties

local waypoint = exports.sleepless_waypoints:get(waypointId)

if waypoint and waypoint.active then
    local data = waypoint.data
    print('Type:', data.type)
    print('Color:', data.color)
    print('Label:', data.label)
    print('Draw Distance:', data.drawDistance)
end

createTimer

Creates a world-space DUI timer on this client. The plate is centered on coords.

local id = exports.sleepless_waypoints:createTimer(data)

Parameters

ParameterTypeDescription
dataTimerDataTimer fields. See Timers.

Returns

TypeDescription
numberClient timer id

Pass duration in milliseconds to run a countdown. Omit it and set progress from 0.0 to 1.0 when your script should move the fill.

local id = exports.sleepless_waypoints:createTimer({
    coords = vec3(100.0, 200.0, 30.4),
    style = 'pill',
    label = 'Cooking',
    duration = 8000,
    color = '#31a4fc',
    drawDistance = 12.0,
    onEnd = function(id)
        print('Timer finished', id)
    end,
})

onEnd runs when a duration timer hits zero, before the plate is removed. updateTimer can replace it. Script timers never call it.

updateTimer

Changes the fields you pass. Anything you leave out stays as it is.

exports.sleepless_waypoints:updateTimer(id, data)

Passing duration starts that countdown over. Passing progress on a duration timer jumps the fill. paused = true freezes a countdown, and paused = false resumes it.

exports.sleepless_waypoints:updateTimer(id, {
    paused = true,
    label = 'Resting',
})

removeTimer

Removes one timer and releases its DUI back to the pool.

exports.sleepless_waypoints:removeTimer(id)

removeAllTimers

Removes every timer on this client, including timers the server created for this player.

exports.sleepless_waypoints:removeAllTimers()

getTimer

Returns the timer table for a client id, or nil when it is already gone.

local timer = exports.sleepless_waypoints:getTimer(id)

timerEnded

A duration timer fires this local event when it reaches zero. onEnd, when you passed one to createTimer, runs first. Then this event fires. Then removeOnComplete removes the plate.

AddEventHandler('sleepless_waypoints:client:timerEnded', function(id)
    print('Timer finished', id)
end)

Script timers do not fire this event.

Configuration

Previous Page

Server Exports

Next Page

On this page

createParametersReturnsExample: Small WaypointExample: Checkpoint WaypointExample: Waypoint with ImageupdateParametersUpdatable PropertiesExample: Update PositionExample: Update AppearanceExample: Dynamic WaypointremoveParametersExample: Timed RemovalExample: Conditional RemovalremoveAllExample: Mission CleanupExample: Resource CleanupgetParametersReturnsWaypointInstance PropertiesExample: Check Waypoint ExistsExample: Calculate Distance to WaypointExample: Get Waypoint PropertiescreateTimerParametersReturnsupdateTimerremoveTimerremoveAllTimersgetTimertimerEnded
Edit on GitHub