Events - Element Labs

All events on this page are client-side and local to the client. Use AddEventHandler to listen and TriggerEvent to raise.

Contract

Raised by the map

Event	Arguments	When
`el:map:ready`	none	The map’s client side has finished loading and its exports are callable.
`el:map:open`	`view: string`	The map has begun opening, on that view. The camera transition has not finished yet.
`el:map:close`	none	The map has closed and the camera has returned.
`el:map:view:enter`	`view: string`	A view is on screen. Raised with `el:map:open`, and again after a `SwitchView`.
`el:map:view:leave`	`view: string`	That view is no longer on screen.
`el:map:stop`	none	The `element_map` resource is stopping.
`el:map:page:enter`	`id: string`	A page registered with `RegisterPage` is on screen.
`el:map:page:leave`	`id: string`	A page was left, or the map closed under it.
`el:map:page:action`	`action: table`	Something in a page was used. See Pages.

Listened for by the map

Event	Arguments	Effect
`el:map:blip:meta`	`handle: number`, `fields: table`	Attaches map information to a marker created with the game’s own functions. The same as calling `SetBlipMeta`.
`el:map:blip:gone`	`handle: number`	Forgets the information attached to that marker.
`el:map:blip:new`	`handle: number`	Tells the map a marker was created, so it appears without waiting for the next sweep.
`el:map:blip:touch`	`handle: number`	Tells the map a marker has changed, so its appearance is refreshed.

A view also reports itself through the SDK’s hooks — el:map:view:open, el:map:view:ready, el:map:view:close and el:map:view:params — which is where a resource takes part rather than only being told. el:map:view:open is the one that can refuse an open. See Views. The four listened-for events are what the map’s integration uses. Raising them yourself is supported, and is the alternative to SetBlipMeta when your code cannot reach the export.

Inputs

The page events carry the id you gave RegisterPage. Compare against your own id: every registered page raises the same events. The fields table of el:map:blip:meta accepts the same keys as SetBlipMeta. See Exports. Repeated calls for one marker are merged.

Outputs

el:map:open is raised as the map starts opening, so a handler runs before the camera has finished moving. Use it to prepare state, not to assume the map is on screen. el:map:close is raised in every case the map stops being open: the player closed it, the player died, or the resource was stopped. It is also raised if opening failed part way through, so an el:map:open handler is always followed by an el:map:close handler. el:map:open carries the id of the view being opened, so a handler can tell the standard map from a view of its own without asking. el:map:view:leave is raised for every view that leaves the screen, including when the map closes and when a resource stop takes it down. el:map:ready is raised once per resource start. A resource that starts after the map has already started never sees it. Use GetResourceState('element_map') in that case.

Errors

None of these events report failure. An unknown marker handle is ignored, and an unregistered page id never occurs in the page events because the map only raises ids it was given.

While the map is open

The integration changes one thing in your other resources: while the map is open, the game’s pause-menu check reports that the pause menu is active. The map takes the place of the pause map, so code that pauses on the pause menu behaves the same way for the map. This applies inside every resource the integration was installed into, and only while the map is open. If a resource of yours must tell the two apart, listen for el:map:open and el:map:close and track it yourself. See Product integrations for what the integration is and how to install it.

Example

Waiting for the map to be ready, then registering a page and reacting to it:

AddEventHandler('el:map:ready', function()
  exports.element_map:RegisterPage({
    id = 'jobs',
    label = 'Jobs',
    order = 2,
    content = { schemaVersion = 1, title = 'Jobs', sections = {} },
  })
end)

AddEventHandler('el:map:page:action', function(event)
  if event.page == 'jobs' and event.action == 'refresh' then
    exports.element_map:SetPageContent('jobs', jobsPage())
  end
end)

The content of a page and what it reports are described in Pages. Pausing your own work while the map is open:

local mapOpen = false

AddEventHandler('el:map:open', function() mapOpen = true end)
AddEventHandler('el:map:close', function() mapOpen = false end)

Attaching information to a marker without calling the export:

local handle = AddBlipForCoord(-1037.0, -2738.0, 20.0)
TriggerEvent('el:map:blip:meta', handle, { name = 'Airport', category = 3 })

​Contract

​Raised by the map

​Listened for by the map

​Inputs

​Outputs

​Errors

​While the map is open

​Example

​Related