> For the complete documentation index, see [llms.txt](https://cylexdev.gitbook.io/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cylexdev.gitbook.io/docs/cylex_mdt/features/live-map.md).

# Live Map

Monitor all on-duty officers across the city in real time, click officer dots to view unit info, set in-game waypoints, and switch between map view modes.

The Live Map gives supervisors and commanders a real-time overhead view of every on-duty officer across the city. Officer positions update automatically at a configurable interval, each dot colored by the officer's current unit status. You can click any dot to view officer details, set an in-game waypoint for that officer, and switch between view modes to see different layers of information. The map costs nothing when nobody has the page open — the snapshot loop only runs while at least one officer is viewing it.

### Opening the live map <a href="#id-704cad90-6ac1-4fe1-895b-c01134e68f7f" id="id-704cad90-6ac1-4fe1-895b-c01134e68f7f"></a>

Navigate to **Live Map** in the MDT sidebar. The map loads automatically with all on-duty officers shown as colored dots moving in real time.

{% hint style="info" %}
By default, `showOffDuty = false`, so only officers currently on duty appear on the map. Set this to `true` in `config.lua` if you want to track all players in allowed jobs regardless of duty status.
{% endhint %}

### Officer dots and status colors <a href="#id-2279e26c-67cd-414d-813a-a3e801d67ba9" id="id-2279e26c-67cd-414d-813a-a3e801d67ba9"></a>

Each dot on the map represents a single on-duty officer. The dot color reflects the officer's current unit status, which is set from their MDT topbar or the Units page. Statuses include **Patrol**, **On Scene**, **Traffic**, **Assistance**, and **Resting** — each unit's color is determined by how your department has configured the unit, making it easy to distinguish patrol units from units already engaged at a scene.

Click any dot to open a small info card showing the officer's name, callsign, and unit assignment.

### Setting a waypoint <a href="#a1648e9a-89cb-4c7a-a3c2-85ccb28041fd" id="a1648e9a-89cb-4c7a-a3c2-85ccb28041fd"></a>

With an officer info card open, click **Set Waypoint**. This places an in-game GPS waypoint on the actual map for that officer's current position. Use this to direct patrol units to a scene or to coordinate a response without switching to radio.

### View modes <a href="#b89475ac-e8cf-495a-af21-32315a710727" id="b89475ac-e8cf-495a-af21-32315a710727"></a>

Three view modes are available from the controls in the top-right of the map:

{% tabs %}
{% tab title="Units" %}
The default view. Each officer is shown as an individual dot colored by their unit. This mode is best for tracking specific officers and understanding patrol distribution across the city.
{% endtab %}

{% tab title="Clusters" %}
Officers that are close together are grouped into a single cluster dot with a count badge. Useful when many units are staged in a small area and individual dots overlap.
{% endtab %}

{% tab title="Heatmap" %}
Overlays a density heatmap showing where incidents are clustering across the city. Use this during high-activity periods to identify hotspots and direct units preemptively. Officer dots remain visible underneath the heatmap layer.

### Map tile styles <a href="#id-7ea2a949-6a32-43fc-95b2-aed439a0e279" id="id-7ea2a949-6a32-43fc-95b2-aed439a0e279"></a>

The map background can be changed to match your server's visual preferences. Three styles are available:
{% endtab %}
{% endtabs %}

### Map tile styles <a href="#id-7ea2a949-6a32-43fc-95b2-aed439a0e279" id="id-7ea2a949-6a32-43fc-95b2-aed439a0e279"></a>

The map background can be changed to match your server's visual preferences. Three styles are available:

| Style key       | Description                          |
| --------------- | ------------------------------------ |
| `styleAtlas`    | Standard street atlas view — default |
| `styleSatelite` | Satellite imagery                    |
| `styleGrid`     | Minimal grid overlay                 |

Set the style in `config.lua`:

```lua
Config.LiveMap = {
    tileStyle = 'styleAtlas',    -- styleSatelite | styleAtlas | styleGrid
    tileExt   = 'jpg',           -- jpg for satellite, png for atlas/grid
}
```

### Update interval <a href="#id-5bcaa11f-7e72-496e-99f6-11b26cbd51ca" id="id-5bcaa11f-7e72-496e-99f6-11b26cbd51ca"></a>

The map snapshot runs on a timer. The default is 5000 milliseconds (5 seconds), which balances responsiveness against server overhead. Lower values feel more fluid but increase the frequency of position updates sent to all watching clients.

```lua
Config.LiveMap = {
    updateInterval = 5000,   -- milliseconds between position snapshots
}
```

{% hint style="warning" %}
Values between 1500 and 3000 ms give a noticeably smoother experience on busy servers without meaningful performance impact. Going below 1000 ms is not recommended.
{% endhint %}

### Department scoping <a href="#id-338a1bb6-f4d7-4582-9d2c-8957449b1de5" id="id-338a1bb6-f4d7-4582-9d2c-8957449b1de5"></a>

By default all departments can see each other's officers on the map. Enable department scoping to restrict each department to seeing only their own officers:

```lua
Config.LiveMap = {
    departmentScoped = false,  -- true = each dept sees only their own officers
}
```

When `departmentScoped = true`, an MRPD officer will only see MRPD dots. A State Police supervisor will only see State Police dots. This is useful on servers where departments operate independently and cross-departmental visibility would be a spoiler.

### Performance <a href="#id-30f820e2-d183-4cfc-a7ad-f66a7ab2deb5" id="id-30f820e2-d183-4cfc-a7ad-f66a7ab2deb5"></a>

The snapshot loop that broadcasts officer positions to the client is idle when no officer has the Live Map page open. It activates the moment any officer navigates to the page and pauses again when the last viewer navigates away. You do not need to disable the feature during low-population periods — it handles this automatically.

```lua
Config.LiveMap = {
    enabled = true,  -- set false to disable the page entirely
}
```

### Full configuration reference <a href="#id-85b4ab40-e14f-4fe5-9ef7-0aea11a3aebf" id="id-85b4ab40-e14f-4fe5-9ef7-0aea11a3aebf"></a>

```lua
Config.LiveMap = {
    enabled        = true,
    updateInterval = 5000,    -- ms between snapshots
    showOffDuty    = false,   -- false: on-duty only; true: all allowed-job players

    tileBaseUrl = 'https://assets.cylexdev.com/cylex_mdt/mapStyles',
    tileStyle   = 'styleAtlas',     -- styleSatelite | styleAtlas | styleGrid
    tileExt     = 'jpg',            -- jpg for satellite, png for atlas/grid
    tileMinZoom = 1,
    tileMaxZoom = 5,                -- 8 for satellite, 5 for atlas/grid

    departmentScoped = false,       -- true = each dept sees only their own officers
}
```

<details>

<summary>Enabling the live map page for specific ranks only</summary>

The Live Map page respects the MDT permissions system. Navigate to **Permissions** in the MDT, select the rank you want to restrict, and toggle the **Live Map → View** permission off. Officers at that rank will not see the Live Map entry in the sidebar.

</details>

<details>

<summary>Using satellite tiles</summary>

Switch `tileStyle` to `'styleSatelite'` and set `tileExt` to `'jpg'`. Satellite tiles support up to zoom level 8 (`tileMaxZoom = 8`), giving you a much closer view of the terrain.

```lua
Config.LiveMap = {
    tileStyle   = 'styleSatelite',
    tileExt     = 'jpg',
    tileMaxZoom = 8,
}
```

</details>