> For the complete documentation index, see [llms.txt](https://nobit.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://nobit.gitbook.io/docs/reference/developers.md).

# For developers

Hooking your own scripts into the map. Copy-paste ready.

You do not need any of this to use the map — blips from other resources appear on their own. This page is for when you want to push your **own** blips, zones or names into it.

Every call below goes in a **client** script.

{% hint style="success" %}
**You never have to wait for the map to load.** Anything you send before the map is ready is stored and replayed the moment it is, so a script that starts before the map does not need to retry.
{% endhint %}

## Adding a blip

```lua
exports.nobit_map:UpsertMapBlip({
    id     = 'shop:1',                        -- your own unique name for it
    blipId = 52,                              -- GTA blip sprite id
    color  = 2,                               -- GTA blip colour id
    title  = 'Shop',
    coords = vector3(25.0, -1346.0, 29.5),
    scale  = 1.0,
    description = 'Open 24/7',                -- optional
})
```

Send the same `id` again to update it — only the fields you include change.

## Removing a blip

```lua
exports.nobit_map:RemoveMapBlip('shop:1')
```

## A moving blip

For something that moves — a patrol car, a delivery van — send the position on its own. It is far cheaper than re-sending the whole blip.

```lua
exports.nobit_map:UpdateDynamicMapBlipCoords('patrol:3', vector3(x, y, z))
```

## Many at once

Every call above has a batch version that sends everything in one message: `UpsertMapBlipBatch`, `UpdateDynamicMapBlipCoordsBatch`, `RemoveMapBlipBatch`. Use them when you have more than a handful.

## Zones

A zone is an area drawn on the map — a gang territory, a safe zone, a district. Give it a ring of points and it draws as a filled shape on the flat map and a solid block in 3D.

```lua
exports.nobit_map:UpsertMapZone({
    id = 'grove', title = 'Grove Street', color = 2,
    points = { vector3(...), vector3(...), vector3(...) },
})
```

To recolour or retitle it later, send just the parts that changed — the shape does not need sending again, so an update costs the same whether the zone has four points or two hundred.

```lua
exports.nobit_map:UpsertMapZone({ id = 'grove', color = 1, title = 'Ballas turf' })
exports.nobit_map:RemoveMapZone('grove')
```

## Naming other scripts' blips

Mirrored blips are named `Blip 52` because GTA will not read a blip's label back. Name your own directly:

```lua
exports.nobit_map:SetNativeBlipTitle(blip, 'Pizza This')
```

For resources you did not write, see [Blip names](/docs/setting-up/blip-names.md).

## Showing a character name

If your framework has characters, override the name in the HUD:

```lua
exports.nobit_map:SetMapPlayerName('John Doe')   -- no argument hands it back
```

## Matching the player's colour

Read the accent the player chose so your own blips and UI can match it:

```lua
local hex  = exports.nobit_map:GetMapAccentColor()
local name = exports.nobit_map:GetMapAccentName()
```

## Circles and squares on the map

If your script uses `AddBlipForRadius` or `AddBlipForArea`, the game keeps the size to itself and hands it to nobody — so the map can only draw a dot in the middle. Tell it the size and it draws the real shape:

```lua
local blip = AddBlipForRadius(coords.x, coords.y, coords.z, 150.0)
exports.nobit_map:SetNativeBlipRadius(blip, 150.0)

local area = AddBlipForArea(coords.x, coords.y, coords.z, 80.0, 40.0)
exports.nobit_map:SetNativeBlipArea(area, 80.0, 40.0)   -- full width and height
```

`ClearNativeBlipExtent(blip)` turns it back into a dot. You do not need it before removing a blip — a blip that goes away takes its shape with it.

## Routing to a blip

Use this instead of the game's `SetBlipRoute`, so the line is drawn on this map too:

```lua
exports.nobit_map:SetMapBlipRoute(blip, true)
```

The game holds one blip route at a time alongside the player's own waypoint, so routing to a new blip replaces the previous one — both here and in the game.

## Everything available

| Export                                                       | What it does                                         |
| ------------------------------------------------------------ | ---------------------------------------------------- |
| `IsMapReady()`                                               | Whether the map has finished loading                 |
| `UpsertMapBlip(update)`                                      | Add or update one blip                               |
| `UpsertMapBlipBatch(updates)`                                | The same, for many                                   |
| `UpdateDynamicMapBlipCoords(id, coords)`                     | Move a blip                                          |
| `UpdateDynamicMapBlipCoordsBatch(updates)`                   | The same, for many                                   |
| `RemoveMapBlip(id)` / `RemoveMapBlipBatch(ids)`              | Remove blips                                         |
| `SetNativeBlipTitle(blip, title)`                            | Name one of the game's own blips                     |
| `GetNativeBlipTitle(blip)`                                   | Read that name back                                  |
| `UpsertMapZone(update)` / `RemoveMapZone(id)`                | Zones                                                |
| `GetMapAccentColor()` / `GetMapAccentName()`                 | The player's chosen colour                           |
| `GetMapBlipRoute()`                                          | Which blip is currently routed to                    |
| `SetMapBlipRoute(blip, enabled)`                             | Route to one of the game's blips                     |
| `SetNativeBlipRadius(blip, radius)`                          | Draw a radius blip as a circle                       |
| `SetNativeBlipArea(blip, w, h)`                              | Draw an area blip as a rectangle                     |
| `ClearNativeBlipExtent(blip)`                                | Back to a plain dot                                  |
| `RefreshMapRoute()`                                          | Rebuild the route now                                |
| `SetMapPlayerName(name)`                                     | Override the HUD name                                |
| `RefreshMapMugshot()`                                        | Re-capture the player's face after a clothing change |
| `SetMinimapVisible(visible)`                                 | Show or hide the minimap                             |
| `OpenFullscreenMap()` / `CloseFullscreenMap()`               | The fullscreen map                                   |
| `OpenPauseMenu()` / `ClosePauseMenu()` / `IsPauseMenuOpen()` | The pause menu                                       |