Waypoints

Overview

The Waypoints system renders 3D markers using DUI (Direct UI) textures. Each marker has its own HTML-rendered label, icon, distance counter, and theming, all drawn as a billboard in the game world.

Two visual types are available:

• checkpoint: Tall vertical marker with a line-to-ground. Used for mission objectives and destinations
• small: Ground-level diamond marker. Used for loot spots, interaction points, hidden areas

DUI instances are pooled and reused: markers only acquire a DUI when they enter the player's view, and release it when offscreen. This keeps performance flat regardless of total waypoint count.

Themes

• Default. Industrial Orange
• 'cyberpunk': Neon Magenta, glow pulse
• 'wasteland': Rust tones, dashed borders
• 'noir': Blood Red, minimal
• 'fantasy': Gold, double border
• survival: Earth tones, retro

Client Exports

Create

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

Creates a client-side waypoint. Returns the waypoint ID.

Update

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

Partial update, only send the fields you want to 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

All parameters for the data table passed to WaypointCreate:

• coords (vec3), Required. World position of the waypoint
• type (string), 'checkpoint' or 'small'. Default: 'small'
• label (string). Display text. Default: 'CHECKPOINT'
• icon (string). FontAwesome icon name (without fa-). Example: 'store', 'flag', 'skull'
• image (string). URL to an image (alternative to icon)
• color (string). Hex color. Default: '#f5a623'
• theme (string). Theme name (see list above). Default: none
• size (number). Scale multiplier. Default: 1.0
• drawDistance (number). Max camera distance for rendering. Default: 500.0
• fadeDistance (number). Distance where fade-out begins. Default: 400.0
• displayDistance (boolean). Show distance counter. Default: true
• groundZ (number). Z position of the ground line (checkpoint type only). Default: coords.z - 2.0
• heightOffset (number). Vertical offset from ground (small type only). Default: 0
• removeDistance (number). Auto-remove when the player reaches this distance. Fades out over 5 seconds before removal
• activateDistance (number). Waypoint is invisible until the player is within this distance

Behaviors

Always Visible (Default)

The waypoint appears 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

The waypoint 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

The waypoint is invisible 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

The waypoint appears when nearby 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-- cleanup
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

• DUI textures are pooled and reused. Creating/removing waypoints does not allocate/deallocate GPU resources
• Offscreen waypoints release their DUI back to the pool automatically
• Visibility checks run every Config.Waypoints.rendering.updateInterval ms (default 100)
• Distance updates to the DUI are throttled independently
• Server-side cleanup prunes waypoints for disconnected players every Config.Waypoints.server.cleanupInterval ms