# Waypoints

> 3D DUI-based waypoints and markers system for ML Bridge

Category: BRIDGE · Source: https://miciomods.it/docs/ml-bridge-waypoints · Last updated: 2026-07-09

## 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

```lua
local id = exports.ml_bridge:WaypointCreate(data)
```

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

### Update

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

Partial update, only send the fields you want to change.

### Remove

```lua
exports.ml_bridge:WaypointRemove(id)
```

### Remove All

```lua
exports.ml_bridge:WaypointRemoveAll()
```

### Get

```lua
local wp = exports.ml_bridge:WaypointGet(id)
```

Returns the waypoint data table or `nil`.

## Server Exports

### Create for Specific Player

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

### Create for All Players

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

### Create for Multiple Players

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

### Update

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

### Remove

```lua
exports.ml_bridge:WaypointRemove(id)
```

### Remove All for a Player

```lua
exports.ml_bridge:WaypointRemoveForPlayer(source)
```

### Remove All Globally

```lua
exports.ml_bridge:WaypointRemoveAll()
```

### Query

```lua
local wp = exports.ml_bridge:WaypointGet(id)
local all = exports.ml_bridge:WaypointGetAll()
local 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`.

```lua
exports.ml_bridge:WaypointCreate({
    coords = vec3(200, 300, 30),
    type = 'checkpoint',
    label = 'Shop',
    icon = 'store',
})
```

### Auto-Remove on Approach

The waypoint fades out over 5 seconds and removes itself when the player reaches `removeDistance`.

```lua
exports.ml_bridge:WaypointCreate({
    coords = vec3(200, 300, 30),
    type = 'checkpoint',
    label = 'Pickup',
    icon = 'hand',
    removeDistance = 2.0,
})
```

### Proximity Activation

The waypoint is invisible until the player is within `activateDistance`.

```lua
exports.ml_bridge:WaypointCreate({
    coords = vec3(200, 300, 30),
    type = 'small',
    label = 'Hidden',
    icon = 'eye',
    activateDistance = 30.0,
})
```

### Combo: Activate + Remove

The waypoint appears when nearby and removes itself on arrival.

```lua
exports.ml_bridge:WaypointCreate({
    coords = vec3(200, 300, 30),
    type = 'checkpoint',
    label = 'Objective',
    icon = 'bullseye',
    theme = 'cyberpunk',
    activateDistance = 50.0,
    removeDistance = 3.0,
})
```

## Examples

**Mission Checkpoints**

```lua
local checkpoints = {
    vec3(100, 200, 30),
    vec3(150, 250, 32),
    vec3(200, 300, 28),
}

local wpIds = {}

for i, pos in ipairs(checkpoints) do
    wpIds[i] = exports.ml_bridge:WaypointCreate({
        coords = pos,
        type = 'checkpoint',
        label = ('Checkpoint %d'):format(i),
        icon = 'flag',
        color = '#4ecdc4',
        removeDistance = 3.0,
    })
end

-- cleanup
for _, id in ipairs(wpIds) do
    exports.ml_bridge:WaypointRemove(id)
end
```

**Loot Spots on Ground**

```lua
local lootSpots = {
    { pos = vec3(100, 200, 30), item = 'Crate' },
    { pos = vec3(120, 210, 30), item = 'Backpack' },
}

for _, spot in ipairs(lootSpots) do
    exports.ml_bridge:WaypointCreate({
        coords = spot.pos,
        type = 'small',
        label = spot.item,
        icon = 'box',
        theme = 'wasteland',
        activateDistance = 20.0,
        removeDistance = 2.0,
    })
end
```

**Server-Side Global Event Marker**

```lua
RegisterCommand('event', function(source)
    exports.ml_bridge:WaypointCreate(-1, {
        coords = vec3(300, 400, 30),
        type = 'checkpoint',
        label = 'Event',
        icon = 'star',
        color = '#ff6600',
        theme = 'fantasy',
        drawDistance = 999.0,
    })
end, true)
```

**Map Waypoint Sync**

When `Config.Waypoints.syncToWayPoint = true`, `ml_bridge` automatically creates a 3D checkpoint marker whenever the player sets a GTA map waypoint. The marker follows the blip position and is removed when the waypoint is cleared.

No code is needed, this is automatic.

## 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