# 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 pushing your **own** blips, zones and names into it. Every call below goes in a **client** script. > [!TIP] > **You never have to wait for the map to load.** Anything you send before it is ready is stored and replayed the moment it is. `IsReady()` tells you if you want to know. Calls that can fail return `false, reason` — print the reason while you develop. ## Adding a blip ```lua exports.nobit_map:AddBlip({ id = 'shop:1', -- your own unique name for it blipId = 52, -- GTA blip sprite id color = 2, -- GTA blip colour id, or a CSS colour like '#ff8800' title = 'Shop', coords = vector3(25.0, -1346.0, 29.5), scale = 1.0, -- 0.05 - 10 description = 'Open 24/7', -- optional }) ``` `id`, `blipId`, `color`, `title`, `coords` and `scale` are required for a new blip. Send the same `id` again to update it — only the fields you include change. Optional fields: | Field | Type | | ------------------------------------------------------------------------- | ------------------------------------------------ | | `description` | Text, up to 256 characters | | `dynamic` | `true` if you will move it with `MoveBlip` | | `alpha` | `0`–`1` | | `rotation` | Radians, clockwise from north | | `display` | `'both'`, `'map'` or `'minimap'` | | `number` | A number on the blip, or `false` | | `category` | Legend group name (up to 64 characters), or `false` | | `secondary` | Second colour like `'#ffcc00'`, or `false` | | `pulse` | A game time (`GetGameTimer()`) to pulse from, or `false` | | `tick`, `outline`, `friendly`, `heading`, `cone`, `flashes`, `hiddenOnLegend` | `true` / `false` | Pass a list of blips instead of one to add them all in one message. ## Moving and removing ```lua exports.nobit_map:MoveBlip('patrol:3', vector3(x, y, z)) -- needs dynamic = true exports.nobit_map:RemoveBlip('shop:1') ``` For many at once, pass a table: `MoveBlip({ { id = 'a', coords = ... }, ... })` and `RemoveBlip({ 'a', 'b' })`. ## Zones A zone is an area drawn on the map — a gang territory, a safe zone, a district. Give it a ring of 3 to 256 points. It draws as a filled shape on the flat map and sits on the terrain in 3D. ```lua exports.nobit_map:AddZone({ id = 'grove', title = 'Grove Street', color = 2, -- GTA colour id or '#rrggbb' opacity = 0.35, -- 0 - 1, optional description = 'Families turf', -- optional points = { vector2(...), vector2(...), vector2(...) }, }) ``` To recolour or retitle it later, send only what changed — the shape does not need sending again: ```lua exports.nobit_map:AddZone({ id = 'grove', color = 1, title = 'Ballas turf' }) exports.nobit_map:RemoveZone('grove') ``` `hiddenOnLegend = true` keeps a zone off the legend. ## The game's own blips If you create blips with natives, link your resource with `shared_script '@nobit_map/blips.lua'` (see [Blip names](/docs/3d-map/blip-names)) and everything is picked up. Without it, you can fill in what the game won't tell the map: ```lua exports.nobit_map:SetBlipTitle(blip, 'Pizza This') local name = exports.nobit_map:GetBlipTitle(blip) ``` ### Circles and rectangles The game keeps the size of `AddBlipForRadius` and `AddBlipForArea` blips to itself. Tell the map and it draws the real shape: ```lua local blip = AddBlipForRadius(coords.x, coords.y, coords.z, 150.0) exports.nobit_map:SetBlipRadius(blip, 150.0) local area = AddBlipForArea(coords.x, coords.y, coords.z, 80.0, 40.0) exports.nobit_map:SetBlipArea(area, 80.0, 40.0) -- full width and height ``` `ClearBlipSize(blip)` turns it back into a dot, `GetBlipSize(blip)` reads it. ## Routes and waypoints ```lua exports.nobit_map:SetWaypoint(x, y) -- or SetWaypoint(vector2(x, y)) exports.nobit_map:ClearWaypoint() local metres = exports.nobit_map:GetRouteDistance() ``` To route to one of the game's blips, use this instead of `SetBlipRoute`, so the line is drawn on this map too: ```lua exports.nobit_map:SetBlipRoute(blip, true) exports.nobit_map:SetBlipRouteColor(5) -- GTA colour id local routed = exports.nobit_map:GetBlipRoute() ``` The game holds one blip route at a time, so routing to a new blip replaces the previous one. `RefreshRoute()` rebuilds the route now. ## Opening things ```lua exports.nobit_map:OpenMap() -- fullscreen map exports.nobit_map:OpenMap('shop:1') -- ...focused on one of your blips exports.nobit_map:OpenMap(blip) -- ...on a game blip handle exports.nobit_map:OpenMap(vector2(x, y)) -- ...on a position exports.nobit_map:CloseMap() exports.nobit_map:IsMapOpen() exports.nobit_map:OpenPauseMenu() exports.nobit_map:ClosePauseMenu() exports.nobit_map:IsPauseMenuOpen() exports.nobit_map:ShowMinimap(false) -- hide it, e.g. for a cutscene exports.nobit_map:IsMinimapVisible() ``` ## Showing a character name If your framework has characters, override the name in the pause menu: ```lua exports.nobit_map:SetPlayerName('John Doe') -- SetPlayerName() hands it back ``` After a clothing change, `RefreshMugshot()` re-captures the player's face. ## Matching the player's colour ```lua local hex = exports.nobit_map:GetThemeColor() -- '#rrggbb' local name = exports.nobit_map:GetTheme() -- 'orange', 'blue', ... exports.nobit_map:SetTheme('blue') -- changes the player's saved theme ``` ## Switching features at runtime ```lua exports.nobit_map:SetCayoPerico(false) exports.nobit_map:SetPostals(true) ``` ## Everything available | Export | What it does | | ---------------------------------------------------------- | -------------------------------------------------- | | `IsReady()` | Whether the map has finished loading | | `AddBlip(blip \| list)` | Add or update blips | | `MoveBlip(id, coords)` / `MoveBlip(list)` | Move dynamic blips | | `RemoveBlip(id \| ids)` | Remove blips | | `AddZone(zone)` / `RemoveZone(id)` | Zones | | `SetBlipTitle(blip, title)` / `GetBlipTitle(blip)` | Name a game blip | | `SetBlipRadius(blip, r)` / `SetBlipArea(blip, w, h)` | Give a game blip its real size | | `ClearBlipSize(blip)` / `GetBlipSize(blip)` | Back to a dot / read the size | | `SetWaypoint(x, y)` / `ClearWaypoint()` | The player's waypoint | | `GetRouteDistance()` / `RefreshRoute()` | Route distance / rebuild now | | `SetBlipRoute(blip, on)` / `GetBlipRoute()` | Route to a game blip | | `SetBlipRouteColor(color)` | Colour of that route | | `OpenMap(target?)` / `CloseMap()` / `IsMapOpen()` | The fullscreen map | | `OpenPauseMenu()` / `ClosePauseMenu()` / `IsPauseMenuOpen()` | The pause menu | | `ShowMinimap(visible)` / `IsMinimapVisible()` | The minimap | | `SetPlayerName(name?)` / `RefreshMugshot()` | The player card | | `GetThemeColor()` / `GetTheme()` / `SetTheme(name)` | The player's theme colour | | `SetCayoPerico(on)` / `SetPostals(on)` | Features at runtime |