Exports

Element 3D Pause Menu can be driven from your own resources. Everything on this page is called on the client.

Calling an export

exports.element_3d_pausemenu:<Name>(...)

Opening and closing

Export	Signature
`Toggle`	`(view?: string, params?: any) => void`
`Open`	`(view?: string, params?: any) => void`
`SwitchView`	`(view: string, params?: any) => void`
`Close`	`() => void`
`IsOpen`	`() => boolean`
`SetEnabled`	`(enabled: boolean) => void`
`IsEnabled`	`() => boolean`
`SetMapMode`	`(mode: "3d" \| "vanilla") => boolean`
`GetMapMode`	`() => "3d" \| "vanilla"`
`FocusMap`	`(coords: vector3, height?: number, seconds?: number) => boolean`

The legend

Export	Signature
`SetLegendMode`	`(mode: "default" \| "advanced") => boolean`
`GetLegendMode`	`() => "default" \| "advanced"`
`RegisterLegendCategory`	`(id: string, label: string, order?: number) => boolean`
`RemoveLegendCategory`	`(id: string) => boolean`
`SetBlipLegendCategory`	`(blip: number, category?: string) => boolean`
`SetSpriteLegendCategory`	`(sprite: number, category?: string) => boolean`
`SetNameLegendCategory`	`(name: string, category?: string) => boolean`
`SetLegendCategoryHidden`	`(category: string, hidden: boolean) => boolean`
`IsLegendCategoryHidden`	`(category: string) => boolean`

Markers

Export	Signature
`AddBlip`	`(options: BlipOptions) => number`
`UpdateBlip`	`(id: number, patch: BlipOptions) => boolean`
`RemoveBlip`	`(id: number) => void`
`ClearBlips`	`() => void`
`SetBlipMeta`	`(handle: number, meta: BlipMeta) => void`

Postal numbers

Export	Signature
`SetPostalsEnabled`	`(enabled: boolean) => void`
`SetPostalDataset`	`(dataset: string) => void`

The player card and tabs

Export	Signature
`SetProfile`	`(profile: { name?: string, avatar?: string, tags?: string[] }) => void`
`RegisterPage`	`(page: MapPage) => boolean`
`UpdatePage`	`(id: string, patch: table) => boolean`
`SetPageContent`	`(id: string, content: table) => boolean`
`RemovePage`	`(id: string) => boolean`
`OpenPage`	`(id: string, camera?: boolean) => void`
`ClosePage`	`() => boolean`
`CurrentPage`	`() => string \| nil`
`OpenSettings`	`(category?: string) => void`
`SetStartTab`	`(id?: string, camera?: boolean) => void`
`StartTab`	`() => string`

The page exports are described separately in Pages.

Views

Export	Signature
`RegisterView`	`(view: MapView) => boolean`
`UpdateView`	`(id: string, patch: table) => boolean`
`RemoveView`	`(id: string) => boolean`
`HasView`	`(id: string) => boolean`
`ListViews`	`() => string[]`
`SetDefaultView`	`(id: string) => void`
`CurrentView`	`() => string \| nil`
`SetViewParams`	`(params: any) => boolean`
`PatchView`	`(patch: table) => boolean`
`RefreshView`	`(layerId?: string) => void`

Described separately in Views.

Custom settings

Export	Signature
`RegisterSettings`	`(category: table) => boolean`
`UpdateSettings`	`(id: string, patch: table) => boolean`
`RemoveSettings`	`(id: string) => boolean`
`SetSettingValue`	`(id: string, setting: string, value: any) => boolean`
`GetSettingValue`	`(id: string, setting: string) => any`

Described separately in Custom settings.

World exceptions

Export	Signature
`AddWorldException`	`(target: WorldTarget) => string \| nil`
`RemoveWorldException`	`(id: string) => boolean`
`ClearWorldExceptions`	`() => void`
`ListWorldExceptions`	`() => (WorldTarget & { id: string, owner: string })[]`

See Keeping entities in sight.

The world under the map

Export	Signature
`SetWorldConfig`	`(patch: table) => boolean`
`GetWorldConfig`	`() => table`
`ResetWorldConfig`	`() => void`

See Changing the world while the server runs.

Opening

Open and Toggle take an optional view id, registered beforehand with RegisterView, and the parameters that view is to be shown with. Omitting the id uses the default view, which is the standard map unless SetDefaultView said otherwise. An id that was never registered opens nothing and says so in the console. SwitchView puts another view on the open map. When the map is up, or a page is open over it, the map stays open: the camera flies from where it is to where the new view opens, and only el:pausemenu:view:leave and el:pausemenu:view:enter are raised. Over the settings, or on the game’s own map, it closes the map and opens it again on the new view. When that view is not registered, refuses the parameters or refuses to open, the map on screen stays as it is. Open on an open map does nothing, because the two views are two maps and one’s camera flight and markers are not the other’s. UpdateView and RemoveView act only on a view the calling resource registered. SetViewParams, PatchView and RefreshView act on the view that is on screen and do nothing when the map is closed. Another resource follows a view through the el:pausemenu:view:* events, and can stop one from opening with the beforeOpen hook, registered with RegisterHook. See Following a view from another resource. Open does nothing when the map is already open, while it is opening or closing, or when the player cannot see it: during the pause menu, while the screen is faded, and when the player is not loaded or is dead. Without a framework, “loaded” and “dead” are read from the game itself: the map opens for a connected player whose character is spawned and alive. A map that is open when the player dies closes, together with any page or settings screen on it. SetEnabled turns the map on and off. While disabled, Toggle, Open and the toggle command do nothing, and a map that is open closes. IsEnabled reports the current state; the map starts enabled. While the map is disabled the game’s own pause menu works again, so a player is never left without one.

Choosing the map

SetMapMode chooses which map the Map tab is for this player: "3d" for this menu’s own, or "vanilla" for the game’s full-screen map, with the settings screen and pages unchanged. It starts at mapMode in Menu, which also describes how the menu behaves with each. A menu that is open when the mode changes closes; the next open uses the new mode. Anything other than the two names is refused: it returns false and the mode stays as it was. GetMapMode reports the current mode. The mode lives on the client and is back to mapMode when the resource restarts, so set it when the player spawns, for example from an event your server sends:

RegisterNetEvent('myserver:mapMode', function(mode)
  exports.element_3d_pausemenu:SetMapMode(mode)
end)

With the game’s map, Open, Toggle, Close and IsOpen work as with the 3D map, and the events carry the id of the view that was opened. Views belong to the 3D map: a view id passed to Open must still be registered and willing to open, and the game’s map is shown in its place.

Moving the map

FocusMap flies the open map over a point, for example to show the player where a call came from. height is metres above the ground there; left out, the camera keeps the height it is at. seconds is how long the move takes; left out, it takes as long as a click on a marker does (focus.panDuration in Camera). The point is kept inside the area the map can be dragged over, and the height inside its limits. It returns false and does nothing when there is no map on screen to move: the menu is closed, still opening or closing, or showing the game’s own map. While the camera moves, the player’s own drag and zoom wait for it to land. Calling it again before then takes over from the first move.

local map = exports.element_3d_pausemenu
map:ClosePage()
map:FocusMap(vector3(441.8, -982.0, 30.7), 250.0)

The advanced legend

SetLegendMode chooses the legend for this player: "default", the game’s list, or "advanced", with a search, headings and a switch on every row. It starts at legendMode in Menu, which describes what the player can do with it. An open menu changes at once. GetLegendMode reports the current mode. A heading is a category your resource registers with RegisterLegendCategory: an id you place blips by, the label the player reads, and an order, lowest first (0 when left out). Headings with the same order are sorted by label. Registering an id again changes its label and order. The id "other" is taken: it is where every blip nobody placed goes, last. Blips are placed three ways, from the most specific:

SetBlipLegendCategory places one blip: a game blip handle, from AddBlipForCoord or any other blip native, or the id this menu’s AddBlip returned. On the 3D map the blip gets a row of its own under that heading. On the game’s map the game decides the rows, so the whole row the blip is listed in moves.
SetNameLegendCategory places every blip with that name, without case. * stands for anything, so "*Depot" covers "Garbage Depot" and "Cypress Flats Depot". A name written out wins over a pattern that also covers it.
SetSpriteLegendCategory places every blip with that sprite.

Calling one without a category takes the rule away. A rule naming a category nobody registered still groups its blips, under the id. What a resource registers is removed when it stops.

local legend = exports.element_3d_pausemenu
legend:RegisterLegendCategory('government', 'Government', 1)
legend:RegisterLegendCategory('jobs', 'Jobs', 2)
legend:SetSpriteLegendCategory(60, 'government')     -- every police station
legend:SetNameLegendCategory('City Hall', 'government')
legend:SetNameLegendCategory('*Depot', 'jobs')
legend:SetBlipLegendCategory(myBlip, 'jobs')

SetLegendCategoryHidden switches a whole heading off or on for the player, as its switch does, and IsLegendCategoryHidden reads it. With rememberLegend on, the change is kept with the player’s own.

Keeping entities in sight

With hideWorld on, the map hides every ped and vehicle except the player, the vehicle they are in and whoever is inside it. AddWorldException keeps something else in sight on every view; for one view only, use its show field. A target names exactly one of these:

Field	Type	Meaning
`player`	`number`	A player’s server ID. Follows them as they stream in and out.
`netId`	`number`	A network ID, for a networked vehicle, ped or object. Follows it the same way.
`entity`	`number`	A local entity handle, for something that exists only on this client. It does not survive the entity streaming out.

and optionally:

Field	Type	Meaning
`vehicle`	`boolean`	Also show the vehicle the target is in, or the target itself if it is a vehicle, with everyone inside.

AddWorldException returns the exception’s id, or nil when the target does not read, with the reason in the console. It takes effect at once, on an open map too. An exception belongs to the resource that added it. Only that resource can remove it, and ClearWorldExceptions removes only that resource’s own. When the resource stops, its exceptions go with it. ListWorldExceptions returns every exception and the resource that owns it. These are client exports. To decide on the server who sees whom, send the list to the client and add the exceptions there:

-- server
TriggerClientEvent('myjob:units', policeSource, { 12, 31, 44 })

-- client
RegisterNetEvent('myjob:units', function(serverIds)
  local map = exports.element_3d_pausemenu
  map:ClearWorldExceptions()
  for _, serverId in ipairs(serverIds) do
    map:AddWorldException({ player = serverId, vehicle = true })
  end
end)

The world is hidden on the client, so this is not a security boundary: it keeps a player from using the map to find others, not a modified client.

Changing the world while the server runs

SetWorldConfig changes the settings of World without editing configs/map-world.jsonc: the colour grade, the time and the weather, what is hidden and the detail distance. It takes any of that file’s keys, laid over what is set key by key, so { time = { hour = 20 } } changes the hour and leaves time.lock as it was. It applies to every view, at once, on an open map too. A view’s own world still has the last word over it. A patch with a key the file does not have, a value of the wrong kind, or an hour that is not a whole one from 0 to 23 changes nothing: SetWorldConfig answers false and the reason is in the console. GetWorldConfig returns the settings in force, the file’s with every change laid over them, and ResetWorldConfig goes back to the file. Nothing is saved: the changes last until the resource restarts, and they are this client’s only. Any resource can make them, and the last change wins.

local map = exports.element_3d_pausemenu
-- The map at night, lit by the clock instead of always at midday.
map:SetWorldConfig({ alwaysMidday = false, time = { hour = 22 } })
-- Or the world's own time and weather, whatever a time and weather script sets.
map:SetWorldConfig({ time = { lock = false }, weather = { lock = false } })

`AddBlip` options

Only coords is required. Position and appearance

Field	Type	Meaning
`coords`	`vector3`	Where the marker is. `x` and `y` must be numbers; `z` defaults to `0.0`.
`sprite`	`number`	The icon. Falls back to the configured default.
`color`	`number`	The colour index. Falls back to the configured default.
`rgb`	`{ r, g, b }`	A colour outside the palette, `0`-`255` per channel. Drawn by the legend and by page rows; the map’s own icons are drawn from the palette, so `color` still decides those.
`bright`	`boolean`	Draw the light variant of the palette colour, as the game’s `SetBlipBright` does. Shapes are drawn bright unless this says otherwise.
`scale`	`number`	The size, where `1.0` is standard.
`stretch`	`number`	The height as a share of the width, for a marker that is not scaled the same both ways. `1.0` is the default; `2.0` is twice as tall as it is wide.
`alpha`	`number`	Opacity, `0` to `255`, of the marker and of its cone, outline and the marks on it. `0` also removes it from the legend.
`rotation`	`number`	The heading the icon points in, in degrees.
`font`	`number`	The font of the marker’s label.
`onTop`	`boolean`	Draw above other markers.
`shortRange`	`boolean`	Treat as a short-range marker.
`display`	`number`	The game’s display mode for the marker.

Labels and the legend

Field	Type	Meaning
`name`	`string`	The name shown in the legend. Without it, the marker is listed under the generic label for the active language.
`text`	`string`	A label drawn on the map itself. A marker with `text` and no `name` is left out of the legend.
`category`	`number`	Orders the legend: lower numbers first, then by name, markers with no category last. See Categories.
`hiddenOnLegend`	`boolean`	Keep the marker on the map but out of the legend.
`number`	`number`	Draw a number badge on the marker.
`priority`	`number`	Which marker wins when two overlap under the cursor. Higher wins.

Category	Row
`2`	The name followed by the distance from you, such as `Drop (120 m)`.
`7`	One row for every marker in the category: the game’s label for other players, the name, and the distance from you.
`10`	One row for every marker in the category: the game’s label for properties, then the name.
`11`	One row for every marker in the category: the game’s label for owned apartments, then the name.
`12` to `133`	A category of your own. One row for every marker in it, reading `<category name>: <name>` once you have named it.
`134` to `254`	A category of your own with no name: one row for every marker in it.

Field	Type	Meaning
`clickable`	`boolean`	Whether clicking it selects it. Forced to `false` for shapes.
`followPlayer`	`boolean`	Keep the marker on the player’s position. Such a marker is never listed in the legend.
`edgeIndicator`	`boolean`	Show it at the edge of the screen when it is off view.
`tick`, `goldTick`	`boolean`	Put the game’s tick on the marker, green or gold.
`headingIndicator`	`boolean`	Draw a pointer round the marker showing which way it faces. It follows `coneHeading`, then `rotation`.
`outline`	`boolean`	Draw a ring round the marker, in `markRgb`.
`friendIndicator`, `crewIndicator`	`boolean`	Put the game’s friend mark or crew mark on the marker. The crew mark is drawn in `markRgb`.
`markRgb`	`{ r, g, b }`	The colour of the outline and the crew mark. Falls back to `rgb`, then to white.
`flashing`	`boolean`	Make it flash. `false` keeps it still whatever `flashSpeed` says.
`flashSpeed`	`number`	Its flash period in milliseconds. Falls back to the configured value. A marker that sets this and leaves `flashing` out flashes.
`route`	`boolean`	Draw a route to it.
`routeColor`	`number`	The colour of that route, as a hud colour index. Omitted to let the map pick what the built-in minimap would: the blip’s own palette entry, yellow when the blip itself is default-coloured.

Field	Type	Meaning
`radius`	`number`	Draw a circle of this radius, in metres, instead of an icon.
`radiusEdge`	`boolean`	Draw that circle as an outline.
`areaWidth`, `areaHeight`	`number`	Draw a rectangle of this size, in metres, instead of an icon.

Field	Type	Meaning
`cone`	`boolean`	Draw a cone in the direction the marker faces.
`coneHeading`	`number`	That direction, in degrees. Falls back to `rotation`, then to `0`.
`coneFov`, `coneRange`, `coneColor`	`number`	Width in degrees, reach in metres, and colour. Each falls back to the configured value.

`UpdateBlip`

Changes a marker your resource added with AddBlip, in place: the fields the patch names, with the meanings above, and nothing else. A moving unit, a drop that is done or a robbery that stops flashing keeps its id and its row in the legend, where RemoveBlip followed by AddBlip would make it a new marker.

local map = exports.element_3d_pausemenu
local unit = map:AddBlip({ coords = GetEntityCoords(vehicle), sprite = 56, color = 38, cone = true })

-- Later, as the unit drives:
map:UpdateBlip(unit, { coords = GetEntityCoords(vehicle), coneHeading = GetEntityHeading(vehicle) })

It returns false for a marker that is gone and for one another resource added: each resource changes only its own.

`SetBlipMeta`

Attaches map information to a marker another resource created with the game’s own functions, so that marker gains a legend name, an icon, a cone and the rest.

exports.element_3d_pausemenu:SetBlipMeta(handle, meta)

handle is the marker handle the game returned. meta accepts name, icon, category, hiddenOnLegend, routeColor, radius, radiusEdge, cone, coneColor, coneFov, coneRange, flashSpeed, number, tick, goldTick, headingIndicator, outline, friendIndicator, crewIndicator, priority, areaWidth, areaHeight, scale, stretch, rgb and bright, with the meanings above. On a marker the game created, rgb is its secondary colour: the colour of the marker itself while its colour index is 84, and of its outline and crew mark whatever its colour. Calls are merged, so setting name and later setting category keeps both. The integration fills most of these in on its own from the game’s functions: a marker given SetRadiusBlipEdge, SetBlipScaleTransformation, a flash that runs for a set time with SetBlipFlashTimer, or a tick, a heading pointer, an outline, a friend or a crew mark with the game’s Show…OnBlip functions shows on the map as it does on the game’s, and PulseBlip pulses it there too. A marker you coloured with SetBlipSecondaryColour is picked up on its own (the integration watches that function) and its colour is used while the marker’s colour index is 84 (BLIP_COLOUR_USE_COLOUR32), which is the same rule the game draws by. rgb here is for a marker whose colour the game never saw. This reaches only markers the map can see, which is what the integration is for. See Markers do not appear.

The player card

SetProfile replaces any of the three fields and leaves the others as they are.

Field	Type	Meaning
`name`	`string`	Replaces the name taken from your framework.
`avatar`	`string`	An image address for the portrait. Replaces the one generated from the character in game.
`tags`	`string[]`	Short labels shown beside the ID, under the name.

The player card can be turned off entirely. See Map.

Pages

RegisterPage adds a tab beside the map’s own and the screen behind it. id must be unique; registering your own id again replaces the first, and order decides the position. A page is changed and removed only by the resource that registered it. The map draws the page from the content you registered, and reports what the player does with it. Everything a page can contain is in Pages.

Opening the settings

OpenSettings opens the menu on the Settings tab, on the category your resource registered with RegisterSettings under that id. Left out, or naming a category that is not registered, it opens on the first category, as the tab does. An open menu moves to the settings; one already on them moves to that category. A view that does not offer the Settings tab is left as it is.

RegisterCommand('hudsettings', function()
  exports.element_3d_pausemenu:OpenSettings('myhud')
end, false)

The start tab

SetStartTab chooses the tab the menu opens on, in place of startTab in Menu: "map", "settings" or a page id. The second argument replaces startCamera: whether the camera flies up before that tab is shown. Leaving either argument out goes back to the configured value. It applies from the next time the menu opens. OpenPage is not affected by either: it opens the menu on the page it names, without the camera unless its own second argument is true.

What they return

Export	Returns
`AddBlip`	The marker’s id, for `RemoveBlip`. These ids are separate from the game’s own marker handles.
`IsOpen`	Whether the map is open. Reports `false` while it is still opening.
`RegisterPage`, `UpdatePage`, `SetPageContent`	Whether the page was accepted. `false` means the map could not render what it was given, or the page belongs to another resource.
`RegisterView`, `UpdateView`, `RemoveView`	Whether the view was accepted or removed. `false` means it did not read, or belongs to another resource.
`SetViewParams`, `PatchView`	Whether the open view took the change. `false` when no map is open, or the view refused it.
`ClosePage`	Whether a page was open.
`FocusMap`	Whether there was a map on screen to move.
`UpdateBlip`	Whether the marker was changed: `false` when it is gone or another resource added it.
`CurrentPage`	The id of the page on screen, or nothing.
`StartTab`	The tab the menu opens on: the `SetStartTab` choice, or the configured one.
`SetWorldConfig`	Whether the change was taken. `false` means it did not read, and nothing changed.
`GetWorldConfig`	The world settings in force.
Everything else	Nothing.

ClearBlips removes only the markers your resource added through AddBlip. Markers other resources added, the player’s own marker and markers mirrored from the game’s are not affected. When your resource stops, the markers it added are removed with it.

Errors

Coordinates without numeric x and y raise an error naming the product, and so does calling AddBlip with no coordinates or no options at all:

[Map] Blip coordinates require numeric x and y components.

A missing z is not an error: it defaults to 0.0. Calling any export before element_3d_pausemenu has started does nothing, because the export does not exist yet. Wait for el:pausemenu:ready. See Events. RemoveBlip with an unknown id, and Close while the map is closed, do nothing.

Example

AddEventHandler('el:pausemenu:ready', function()
  local id = exports.element_3d_pausemenu:AddBlip({
    coords = vector3(215.0, -810.0, 31.0),
    sprite = 1,
    color = 5,
    name = 'Meeting point',
    category = 2,
    cone = true,
    coneHeading = 90.0,
  })

  exports.element_3d_pausemenu:SetProfile({ name = 'Dispatch', tags = { 'On duty' } })

  Wait(60000)
  exports.element_3d_pausemenu:RemoveBlip(id)
end)

Attaching map information to a marker created with the game’s own functions:

local handle = AddBlipForCoord(-1037.0, -2738.0, 20.0)
SetBlipSprite(handle, 90)

exports.element_3d_pausemenu:SetBlipMeta(handle, {
  name = 'Airport',
  category = 3,
})

Get started

Guides

Configuration

For scripters

Troubleshooting

Changelog

Exports

Calling an export

Opening and closing

The legend

Markers

Postal numbers

The player card and tabs

Views

Custom settings

World exceptions

The world under the map

Exports

Opening

Choosing the map

Moving the map

The advanced legend

Keeping entities in sight

Changing the world while the server runs

`AddBlip` options

Categories

`UpdateBlip`

`SetBlipMeta`

The player card

Pages

Opening the settings

The start tab

What they return

Errors

Example

Get started

Guides

Configuration

For scripters

Troubleshooting

Changelog

Calling an export

Opening and closing

The legend

Markers

Postal numbers

The player card and tabs

Views

Custom settings

World exceptions

The world under the map

Exports

Opening

Choosing the map

Moving the map

The advanced legend

Keeping entities in sight

Changing the world while the server runs

AddBlip options

Categories

UpdateBlip

SetBlipMeta

The player card

Pages

Opening the settings

The start tab

What they return

Errors

Example

Related

`AddBlip` options

`UpdateBlip`

`SetBlipMeta`