Waypoints

Overview

Waypoints are 3D markers drawn in the world from DUI textures. Each one has its own label, icon, distance counter and theme. ML scripts use them for objectives and points of interest, and any other resource can call the same exports.

Two visual types are available:

• checkpoint: tall marker with a line to the ground, for objectives and destinations
• small: low diamond marker, for loot spots and interaction points

A marker takes a DUI from a shared pool only while it is on screen and gives it back when it leaves the view, so the cost depends on visible markers, not on how many exist.

Themes

• default: orange
• 'cyberpunk': magenta with a glow pulse
• 'wasteland': rust tones, dashed borders
• 'noir': red, minimal
• 'fantasy': gold, double border

Client Exports

Create

1local id = exports.ml_bridge:WaypointCreate(data)

Creates a waypoint for the local player and returns its ID.

Update

1exports.ml_bridge:WaypointUpdate(id, { label = 'New Label', color = '#ff0000' })

Send only the fields that change.

Remove

1exports.ml_bridge:WaypointRemove(id)

Remove All

1exports.ml_bridge:WaypointRemoveAll()

Get

1local wp = exports.ml_bridge:WaypointGet(id)

Returns the waypoint data table or nil.

Server Exports

Create for Specific Player

1local id = exports.ml_bridge:WaypointCreate(source, data)

Create for All Players

1local id = exports.ml_bridge:WaypointCreate(-1, data)

Create for Multiple Players

1local id = exports.ml_bridge:WaypointCreate({src1, src2, src3}, data)

Update

1exports.ml_bridge:WaypointUpdate(id, { label = 'Updated' })

Remove

1exports.ml_bridge:WaypointRemove(id)

Remove All for a Player

1exports.ml_bridge:WaypointRemoveForPlayer(source)

Remove All Globally

1exports.ml_bridge:WaypointRemoveAll()

Query

1local wp = exports.ml_bridge:WaypointGet(id)
2local all = exports.ml_bridge:WaypointGetAll()
3local playerWps = exports.ml_bridge:WaypointGetForPlayer(source)

Waypoint Parameters

Fields of the data table passed to WaypointCreate:

• coords (vec3): world position. Required
• type (string): 'checkpoint' or 'small'. Default 'small'
• label (string): display text. Default 'CHECKPOINT'
• icon (string): FontAwesome icon name without fa-, such as 'store', 'flag', 'skull'
• image (string): URL of an image, used instead of an icon
• color (string): hex color. Default '#f5a623'
• theme (string): theme name from the list above
• size (number): scale. Default 1.0
• drawDistance (number): maximum render distance. Default 10000.0
• fadeDistance (number): distance where the fade starts. Default 400.0
• displayDistance (boolean): shows the distance counter. Default true
• groundZ (number): height of the ground line, checkpoint only. Default coords.z - 2.0
• heightOffset (number): vertical offset, small only. Default 0
• removeDistance (number): removes the waypoint when the player gets this close, after a 5 second fade
• activateDistance (number): hides the waypoint until the player is this close

Behaviors

Always Visible (Default)

Shown whenever the player is within drawDistance.

1exports.ml_bridge:WaypointCreate({
2    coords = vec3(200, 300, 30),
3    type = 'checkpoint',
4    label = 'Shop',
5    icon = 'store',
6})

Auto-Remove on Approach

Fades out over 5 seconds and removes itself when the player reaches removeDistance.

1exports.ml_bridge:WaypointCreate({
2    coords = vec3(200, 300, 30),
3    type = 'checkpoint',
4    label = 'Pickup',
5    icon = 'hand',
6    removeDistance = 2.0,
7})

Proximity Activation

Hidden until the player is within activateDistance.

1exports.ml_bridge:WaypointCreate({
2    coords = vec3(200, 300, 30),
3    type = 'small',
4    label = 'Hidden',
5    icon = 'eye',
6    activateDistance = 30.0,
7})

Combo: Activate + Remove

Appears when the player gets close and removes itself on arrival.

1exports.ml_bridge:WaypointCreate({
2    coords = vec3(200, 300, 30),
3    type = 'checkpoint',
4    label = 'Objective',
5    icon = 'bullseye',
6    theme = 'cyberpunk',
7    activateDistance = 50.0,
8    removeDistance = 3.0,
9})

Examples

1local checkpoints = {
2    vec3(100, 200, 30),
3    vec3(150, 250, 32),
4    vec3(200, 300, 28),
5}
6
7local wpIds = {}
8
9for i, pos in ipairs(checkpoints) do
10    wpIds[i] = exports.ml_bridge:WaypointCreate({
11        coords = pos,
12        type = 'checkpoint',
13        label = ('Checkpoint %d'):format(i),
14        icon = 'flag',
15        color = '#4ecdc4',
16        removeDistance = 3.0,
17    })
18end
19
20
21for _, id in ipairs(wpIds) do
22    exports.ml_bridge:WaypointRemove(id)
23end

1local lootSpots = {
2    { pos = vec3(100, 200, 30), item = 'Crate' },
3    { pos = vec3(120, 210, 30), item = 'Backpack' },
4}
5
6for _, spot in ipairs(lootSpots) do
7    exports.ml_bridge:WaypointCreate({
8        coords = spot.pos,
9        type = 'small',
10        label = spot.item,
11        icon = 'box',
12        theme = 'wasteland',
13        activateDistance = 20.0,
14        removeDistance = 2.0,
15    })
16end

1RegisterCommand('event', function(source)
2    exports.ml_bridge:WaypointCreate(-1, {
3        coords = vec3(300, 400, 30),
4        type = 'checkpoint',
5        label = 'Event',
6        icon = 'star',
7        color = '#ff6600',
8        theme = 'fantasy',
9        drawDistance = 999.0,
10    })
11end, true)

Performance

• Creating or removing a waypoint reuses pooled DUI textures instead of creating new ones
• Visibility checks run every Config.Waypoints.rendering.updateInterval ms (default 100)
• Distance text updates run on their own interval
• The server removes waypoints of disconnected players every Config.Waypoints.server.cleanupInterval ms
• Config.Waypoints.enabled = false turns the whole system off