Views

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.

Calls

exports.element_3d_pausemenu:RegisterView(view)   --> boolean
exports.element_3d_pausemenu: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. When the resource that replaced it stops, or removes its view, the standard map comes back, so the menu always has a map to open. A view belongs to the resource that registered it. Only that resource can update it, register over it or remove it; UpdateView, RemoveView and RegisterView answer false to anyone else and say why in the console. The standard map is the exception: any resource may replace it, and the replacement then belongs to that resource.

Fields

Field	Type	Default	Meaning
`id`	`string`	required	The id passed to `Open`. Registering your own id again replaces the first.
`extends`	`string` or list	none	Views this one is built on, applied 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, any key of Camera.
`world`	table	none	World overrides for this view, any key of World.
`show`	list or function	none	Players and entities kept in sight while `hideWorld` hides the rest. See `show`.
`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_3d_pausemenu:RegisterView({
  id = 'job-base',
  camera = { openHeight = 600.0 },
  capabilities = { poi = false },
  surface = { legend = false },
})

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

Each view in extends brings the views it extends itself, however deep that goes. In a list, the view written first has the last word among them: extends = { 'a', 'b' } applies b, then a, then this view. A view reached twice, because two parents are built on it, is applied once. 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.

`show`

What this view keeps in sight while hideWorld hides every other ped and vehicle. Each entry is a target, the same table AddWorldException takes, and applies only while this view is open.

exports.element_3d_pausemenu:RegisterView({
  id = 'dispatch',
  show = function(ctx)
    local targets = {}
    for _, serverId in ipairs(onDutyUnits) do
      targets[#targets + 1] = { player = serverId, vehicle = true }
    end
    return targets
  end,
})

A list is fixed when the view is registered. A function is called about four times a second while the view is open, so a unit that comes on duty appears without the view being opened again; keep it cheap. A list that does not read is refused with the view. An entry a function returns that does not read is left out, and the first reason is printed once. PatchView({ show = ... }) replaces the list on the open view and takes effect at once. A function that raises an error is reported once and not called again until the view is opened or changed again.

`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. Markers added with AddBlip, by any resource, belong to the world map too. A view without a world layer does not draw them, so it shows its own layers and nothing else; they come back when the view closes. The player’s arrow, the waypoint and points of interest are drawn on every view. A marker a layer returns that cannot be added, such as one without coords, is left out and reported once. The rest of the layer is drawn. A provider that calls done again replaces the markers it gave before.

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 Close 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 panels set in Map, 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_3d_pausemenu: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_3d_pausemenu:Open('property', { house = 12 })

SetViewParams changes them while the map stays open: the markers, the rules and the interface are all worked out again. The new value goes through the view’s params first, the same as on Open. When params returns nothing, the view keeps the parameters it has and SetViewParams answers false.

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 once and is not called again until the view is opened or changed again; the map stays open. The same holds for a capability, a marker filter and every other function a view supplies. 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.world`	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, through the view’s `params` check.
`ctx.patch(patch)`	Changes `camera`, `world`, `show`, `capabilities` or `surface` while open.
`ctx.invalidate(layerId)`	Rebuilds one marker layer, or every one.
`ctx.close()`	Closes the map. Called from `onOpen` or `onReady`, it closes as soon as the map has finished opening.

Following a view from another resource

A view’s on handlers belong to whoever registered it. Everybody else is told what happened through events, and can refuse one thing through a hook.

Event	Arguments	When
`el:pausemenu:view:enter`	`view: string`	The view is on screen.
`el:pausemenu:view:ready`	`view: string`	The camera has arrived.
`el:pausemenu:view:params`	`view: string`, `params: any`	Its parameters were replaced.
`el:pausemenu:view:leave`	`view: string`	The view has left the screen.

An event carries the view’s id, not its context. To act on the view from a handler, use the exports: SetViewParams, PatchView, RefreshView and Close. The hook is beforeOpen, registered with the map’s RegisterHook export. It is called with the view’s context before the camera moves, and returning false stops the map from opening.

exports.element_3d_pausemenu:RegisterHook('beforeOpen', function(ctx)
  if ctx.id == 'property' and not playerMayBrowse() then
    return false
  end
end)

The context is the one the view’s own handlers are given, minus any knowledge of what its parameters mean.

What happens

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 beforeOpen hook, then raises el:pausemenu:open and el:pausemenu:view:enter with the view’s id and calls onOpen. Once the camera has arrived, onReady is called and el:pausemenu:view:ready raised. Closing calls onClose and raises el:pausemenu:view:leave and el:pausemenu: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. A view whose parameters are refused, whose canOpen says no, or whose beforeOpen hook is refused by another resource, also opens nothing. The player is left where they were. SwitchView asks the same questions before it closes the map on screen, so a switch that cannot happen leaves that map open. PatchView and ctx.patch check the patch the way RegisterView checks a view. A patch with a field of the wrong kind is refused whole: nothing changes, PatchView answers false and the reason is in the console. When a patch or new parameters take a page away from the view, a page that is on screen is closed and the player is back on the map. 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:pausemenu:ready', function()
  exports.element_3d_pausemenu: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_3d_pausemenu: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_3d_pausemenu:RegisterView({
  id = 'delivery',
  extends = 'world',
  on = {
    onWaypoint = function(ctx, coords)
      TriggerServerEvent('myresource:deliveryTarget', coords)
    end,
  },
})

Get started

Guides

Configuration

For scripters

Troubleshooting

Changelog

Calls

Fields

`extends`

`show`

`focus`

Marker layers

Capabilities

Surface

Parameters

Handlers

The context

Following a view from another resource

What happens

Errors

Example

Get started

Guides

Configuration

For scripters

Troubleshooting

Changelog

Calls

Fields

extends

show

focus

Marker layers

Capabilities

Surface

Parameters

Handlers

The context

Following a view from another resource

What happens

Errors

Example

Related

`extends`

`show`

`focus`