Views - Element Labs

A view is a named map: its own markers, camera limits, look, interactions and interface. A resource registers one, then opens the map with its id. Use a view for a map that is not the world map, such as a property viewer, a job board or a delivery selector. For adding markers to the standard map, use AddBlip instead. See Exports. Nothing is resolved when a view is registered. Everything — the configuration, the views it extends, the parameters it was opened with — is worked out when the map opens, so a reloaded config or an edited parent view reaches every view built on it without anyone registering anything again.

Contract

exports.element_map:RegisterView(view)   --> boolean
exports.element_map:Open('property', { house = 12 })

RegisterView answers whether the view was accepted. A view whose fields are of the wrong kind is refused, with the reason in the server console, rather than being carried into a map that then fails to open. The standard map is registered under the id world. Registering a view with that id replaces it.

Inputs

Field	Type	Default	Meaning
`id`	`string`	required	The id passed to `Open`. Registering the same id twice replaces the first.
`extends`	`string` or list	none	Views this one is built on, applied in order before it.
`label`	`string`	none	The view’s name, passed to the interface.
`params`	function	none	Checks what `Open` was called with. See Parameters.
`camera`	table	none	Camera overrides for this view.
`visual`	table	none	Look overrides for this view.
`focus`	see below	player	Where the map opens.
`blips`	list of layers	none	Where the markers come from. See Marker layers.
`capabilities`	table	all on	What the player may do. See Capabilities.
`surface`	table	config	What the interface draws. See Surface.
`on`	table	none	The handlers. See Handlers.

`extends`

A view listed in extends is applied first, and this view’s own fields are applied over it. Camera and look groups merge key by key, capabilities and interface fields are replaced one by one, marker layers are matched by their id, and the handlers of both run.

exports.element_map:RegisterView({
  id = 'job-base',
  camera = { openHeight = 600.0 },
  capabilities = { poi = false },
  surface = { legend = false },
})

exports.element_map:RegisterView({
  id = 'delivery',
  extends = 'job-base',
  blips = { { id = 'drops', kind = 'static', blips = drops } },
})

A chain that loops back on itself, or that names a view which is not registered, is reported and the missing level is skipped; the rest of the chain still applies.

`focus`

Where the map opens, instead of over the player.

Value	Meaning
`vector3`	Opens over that point.
`{ coords = vector3, height = number }`	The same, at your own altitude instead of the camera’s `openHeight`.
`{ entity = number, height = number }`	Opens over an entity, following it while the camera flies in.
A function returning any of the above	Worked out each time the view opens.

Marker layers

blips is a list of layers drawn together, each with an id of its own. A view that mirrors the world map and adds markers of its own is two layers, not a choice between them.

`kind`	Fields	Meaning
`world`	`filter`, `decorate`	The markers your other resources create.
`static`	`blips`	A fixed list, created when the view opens.
`dynamic`	`blips`, `refresh`	A function returning a list, called on every rebuild.
`provider`	`load`, `refresh`	A list that has to be fetched, answered through a callback.

filter(ctx, blip) returns whether a world marker reaches the map at all. decorate(ctx, blip) returns marker information — the same fields as SetBlipMeta — layered over what the marker’s own resource set. The blip it is handed has handle, coords, type, sprite, color, alpha, display, shortRange, route, entity, name, icon and category. refresh is a number of milliseconds. Left out, a layer is built once per open. A layer is also rebuilt on demand with RefreshView, or from a handler with ctx.invalidate(layerId).

blips = {
  { id = 'world', kind = 'world', filter = function(ctx, blip) return blip.category == 3 end },
  { id = 'shops', kind = 'static', blips = shops },
  { id = 'players', kind = 'dynamic', refresh = 2000, blips = function(ctx) return nearbyPlayers() end },
  {
    id = 'houses',
    kind = 'provider',
    load = function(ctx, done)
      lib.callback('myresource:houses', false, done)
    end,
  },
}

A view mirrors the world map once: a second world layer is refused.

Capabilities

Every capability is on unless the view turns it off. A capability is either a switch or a function asked again on every frame, which is how one depends on where the camera is or on what your resource knows at that moment.

Capability	Off removes
`pan`	Dragging the camera.
`zoom`	Zooming.
`blipHover`	The growth of a marker under the cursor.
`blipClick`	Selecting markers.
`blipFocus`	The camera’s move onto a selected marker, while the click is still reported.
`waypoint`	Setting a destination, by any means.
`poi`	Placing points of interest.
`route`	Route drawing, and the wide map view routes need.
`highDetail`	The high/low marker-detail toggle.
`pages`	The page tabs.
`settings`	The Settings tab.
`exit`	The Exit tab, and Escape as a way out of the map.

capabilities = {
  poi = false,
  waypoint = function(ctx) return ctx.coords.z < 500.0 end,
}

The on-screen prompts follow the answers, so the player is never told about a control the view does not have. A view that turns exit off must close itself — from a handler with ctx.close(), or from your resource with Close.

Surface

What the interface draws around the map. Every field defaults to the hud configuration, so a view that says nothing looks like the standard map.

Field	Type	Meaning
`title`	`string` or function	A line drawn under the tabs.
`subtitle`	`string` or function	A second, quieter line.
`theme`	`string`	Passed to the interface untouched, for a look of your own.
`profile`	`boolean`	The player card.
`legend`	`boolean`	The marker list.
`scale`	`boolean`	The scale bar.
`location`	`boolean`	The street and area readout.
`crosshair`	`boolean`	The centre marker.
`tabs`	`boolean`	The tab bar as a whole.
`pages`	`"all"`, `"none"`, a list of ids, or a function	Which registered pages this view hosts.
`instructional`	`boolean`, a list, or a function	The control prompts.

A page the view does not list is neither drawn as a tab nor opened by OpenPage. instructional as a function is handed the prompts the capabilities produced, so a view adds to them rather than restating them.

Parameters

Open takes a second argument, passed through to the view. A view that declares params checks it and turns it into what its handlers receive; returning nothing refuses the open, which is how a view states that it cannot be shown without being told what to show.

exports.element_map:RegisterView({
  id = 'property',
  params = function(raw)
    if type(raw) ~= 'table' or type(raw.house) ~= 'number' then return nil end
    return { house = raw.house }
  end,
  surface = { title = function(ctx) return 'House ' .. ctx.params.house end },
  blips = {
    { id = 'house', kind = 'dynamic', blips = function(ctx) return houseMarkers(ctx.params.house) end },
  },
})

exports.element_map:Open('property', { house = 12 })

SetViewParams changes them while the map stays open: the markers, the rules and the interface are all worked out again.

Handlers

Handlers live under on and are all optional. Each is given the context first.

Handler	Arguments	Returning `true`
`canOpen`	`ctx`	Nothing. Returning `false` or a reason string refuses the open.
`onOpen`	`ctx`	None
`onReady`	`ctx`	None
`onClose`	`ctx`	None
`onTick`	`ctx`, `dt`	None. Runs every frame: keep it short.
`onBlipHover`	`ctx`, `id`, `coords`	None
`onBlipClick`	`ctx`, `id`, `coords`	Suppresses the camera’s move to the marker.
`onBlipContext`	`ctx`, `id` or `nil`, `coords`	Suppresses the destination the right click would set.
`onWaypoint`	`ctx`, `coords`	Suppresses setting a destination and drawing the route.
`onPageEnter`	`ctx`, `id`	None
`onPageLeave`	`ctx`, `id`	None
`onParams`	`ctx`, `params`	None

Returning anything other than true, including nothing, lets the map’s own behaviour run as well. That is how a view adds to a behaviour rather than replacing it. A handler that raises an error is reported and takes that one handler out of that one interaction; the map stays open. Handlers of a view and of the views it extends all run, this view’s own first, and the first one to return true ends the interaction.

The context

Field	Meaning
`ctx.id`	The view’s id.
`ctx.params`	What the view was opened with, after its own `params` check.
`ctx.camera`, `ctx.visual`	The configuration this view is actually running.
`ctx.coords`	Where the camera is.
`ctx.open`	Whether the map is up.
`ctx.setParams(params)`	Replaces the parameters.
`ctx.patch(patch)`	Changes `camera`, `visual`, `capabilities` or `surface` while open.
`ctx.invalidate(layerId)`	Rebuilds one marker layer, or every one.
`ctx.close()`	Closes the map.

Following a view from another resource

A view’s on handlers belong to whoever registered it. Everybody else takes part through the SDK’s hooks, which give priorities, one-shot handlers and registration that goes away with the resource.

Hook	Argument	When
`el:map:view:open`	`ctx`	Before the camera moves. Returning `false` stops the map from opening.
`el:map:view:ready`	`ctx`	The camera has arrived.
`el:map:view:close`	`ctx`	The view has left the screen.
`el:map:view:params`	`ctx`	Its parameters changed.

local Hooks = ElementLabs.Shared.Hooks

Hooks:register('el:map:view:open', function(ctx)
  if ctx.id == 'property' and not playerMayBrowse() then
    return false
  end
end)

The argument is the same context the view’s own handlers are given, minus any knowledge of what its parameters mean. Only el:map:view:open is waited for, and only it can refuse anything: the other three are told what happened.

Outputs

RegisterView returns true when the view was accepted. It is available to Open from that moment and stays registered until the resource that registered it stops, or until RemoveView is called. Opening a view calls canOpen, then the el:map:view:open hook, then raises el:map:open and el:map:view:enter with the view’s id and calls onOpen. onReady follows once the camera has arrived. Closing raises el:map:view:leave and el:map:close. See Events. Registering a view that is already on screen applies the change to it: the limits, look, rules, interface and markers are taken from the new definition without the map closing. Removing it closes the map, because there is nothing left to show.

Errors

Opening an id that was never registered opens nothing, and says so in the console. This is a change from earlier releases, which fell back to the standard map. A view whose parameters are refused, whose canOpen says no, or whose el:map:view:open hook is refused by another resource, also opens nothing. The player is left where they were. A hook that raises, or that does not answer within its deadline, counts as agreement: the SDK’s hook dispatch reports it and carries on, so the map is not another resource’s to break by failing.

Example

A property viewer: its own markers, no destinations, opening over one house, and a title that follows what it was opened with.

AddEventHandler('el:map:ready', function()
  exports.element_map:RegisterView({
    id = 'property',
    label = 'Property',
    params = function(raw)
      if type(raw) ~= 'table' or type(raw.coords) ~= 'vector3' then return nil end
      return raw
    end,
    focus = function(ctx) return { coords = ctx.params.coords, height = 300.0 } end,
    camera = { openHeight = 400.0 },
    blips = {
      {
        id = 'house',
        kind = 'static',
        blips = { { coords = vector3(-802.0, 175.0, 72.0), sprite = 40, color = 2, name = 'For sale' } },
      },
    },
    capabilities = { waypoint = false, poi = false, route = false },
    surface = { title = 'For sale', legend = false, pages = 'none' },
    on = {
      onBlipClick = function(ctx, id, coords)
        TriggerEvent('myresource:showProperty', coords)
        return true
      end,
    },
  })
end)

RegisterCommand('properties', function()
  exports.element_map:Open('property', { coords = vector3(-802.0, 175.0, 72.0) })
end, false)

Adding to the standard map instead of replacing it. The destination is still set, and the resource is told about it:

exports.element_map:RegisterView({
  id = 'delivery',
  extends = 'world',
  on = {
    onWaypoint = function(ctx, coords)
      TriggerServerEvent('myresource:deliveryTarget', coords)
    end,
  },
})

​Contract

​Inputs

​extends

​focus

​Marker layers

​Capabilities

​Surface

​Parameters

​Handlers

​The context

​Following a view from another resource

​Outputs

​Errors

​Example

​Related