Exports - Element Labs

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

Contract

exports.element_map:<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`

Markers

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

The player card and tabs

Export	Signature
`SetProfile`	`(profile: { name?: string, avatar?: string, tags?: string[] }) => void`
`SetProfileName`	`(name: string) => void`
`SetProfileAvatar`	`(avatar: string) => void`
`SetProfileTags`	`(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) => void`
`ClosePage`	`() => boolean`
`OpenPageId`	`() => string \| nil`

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) => void`
`PatchView`	`(patch: table) => void`
`RefreshView`	`(layerId?: string) => void`

Described separately in Views.

Inputs

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 closes the map and opens it again on another view. 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. SetViewParams, PatchView and RefreshView act on the view that is on screen and do nothing when the map is closed. Following a view from another resource is not an export: register for the el:map:view:* hooks through the SDK. See Views. 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. 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.

`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.
`alpha`	`number`	Opacity, `0` to `255`. `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, markers with no category last. Categories `7`, `10` and `11` group all their members into one entry regardless of name and icon.
`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.

Behaviour

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.
`flashing`	`boolean`	Make it flash.
`flashSpeed`	`number`	Its flash period in milliseconds. Falls back to the configured value.
`route`	`boolean`	Draw a route to it.
`routeColor`	`number`	The colour of that route.

Shapes

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.

A marker with radius or areaWidth is a shape: it cannot be clicked or hovered, and it is never listed in the legend. Vision cone

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.

Every configured default above is listed in Markers.

`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_map:SetBlipMeta(handle, meta)

handle is the marker handle the game returned. meta accepts name, icon, category, hiddenOnLegend, routeColor, radius, cone, coneColor, coneFov, coneRange, flashSpeed, number, priority, areaWidth, areaHeight, rgb and bright, with the meanings above. Calls are merged, so setting name and later setting category keeps both. 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. SetProfileName, SetProfileAvatar and SetProfileTags each set one.

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 name.

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

Pages

RegisterPage adds a tab beside the map’s own and the screen behind it. id must be unique; registering the same id twice replaces the first, and order decides the position. 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.

Outputs

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.
`ClosePage`	Whether a page was open.
`OpenPageId`	The id of the page on screen, or nothing.
Everything else	Nothing.

ClearBlips removes only markers added through AddBlip. Markers mirrored from your other resources are not affected.

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_map has started does nothing, because the export does not exist yet. Wait for el:map:ready. See Events. RemoveBlip with an unknown id, and Close while the map is closed, do nothing.

Example

AddEventHandler('el:map:ready', function()
  local id = exports.element_map: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_map:SetProfileName('Dispatch')
  exports.element_map:SetProfileTags({ 'On duty' })

  Wait(60000)
  exports.element_map: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_map:SetBlipMeta(handle, {
  name = 'Airport',
  category = 3,
})

​Contract

​Opening and closing

​Markers

​The player card and tabs

​Views

​Inputs

​Opening

​AddBlip options

​SetBlipMeta

​The player card

​Pages

​Outputs

​Errors

​Example

​Related