Vivum Logo

Vivum Target

Menu

Learn how to add targets

First Item

Second Item

Overview

Each target has a menu that can be configured with any number of items and actions. If no items are configured, the menu only shows the Star. An action on the menu can be configured to be called when the star is clicked, even if there are no items.

@class Menu
FieldTypeDescription
name?

string

A unique name for the menu. If not specified, the name will be set to the generated id.

target

{ position?: vector3, box?: BoxTarget, poly?: PolyTarget, circle?: CircleTarget, entity?: EntityTarget, global?: GlobalTarget }

The type of target to render. Specify one of the target types.

items?

Item[] | fun(entity: number): Item[]

A table of items or a function that returns a table of items every ≈100ms.

canInteract?

fun(entity?: number): boolean

hideOnInteract?

boolean

Override the default behavior of Config.HideOnAction for this specific menu.

action?

fun(menu: Menu, entity?: number, coords: vector3, distance: number): nil

If the menu has no items, this can be used to perform a callback when clicking the menu star itself. The returned value will be used to determine whether the menu should be hidden after the action is performed.

stateful?

boolean

Marks the target as stateful, meaning that if stateful is set to false, it will not render the inner star cicle, however if it's set to true it'll render a larger star (as defined in Config.Graphics.Star.StateSize)

icon?

string | MenuIconTexture

The favicon to display at the center of the star. A texture object can be specified to render a specific ingame texture (like that of a ped headshot).

tooltip?

string

An optional help text to display over the target star. Will be hidden if the star is hovered.

linestrip?

Linestrip

Draws a linestrip from the center of the star to the specified point (vector or entity handle).

uniqueKey?

string

Multiple targets with the same uniqueKey will only render the closest one.

seethrough?

boolean

If set to true, the target star will be rendered even if something is visually obstructing it.

distance?

number

Override maximum distance at which the target can be interacted with.

renderDistance?

number

Override render distance of the target.

scale?

number

Override overall scale of the target (i.e. the size of the target star and the size of the menu) This cannot be above 1, it is only possible to scale the menu down.

starScale?

number

Override only the size of the target star, and not the menu. This cannot be above 1, it is only possible to scale the star down.

starTint?

[number, number, number]

Set a tint (RGB) for the target star.

alwaysShowStar?

boolean

Show the target star even if the player is not holding down the interact keybind (Left Alt by default). This will cause Vivum Target to not be able to idle, making the CPU usage higher at all times.

alwaysInteracting?

boolean

Always have the target in a interactable (hovered) state. This can be used to make a general target for when a player is inside a vehicle, for example.

onUpdate?

fun(self: Menu): Menu

A callback that is called every ≈100ms to do additional calculations. Returning a new menu will replace the current menu (i.e. changing Menu.items or Menu.stateful).

compatibility?

CompatiblityType

The compatibility layer that was used when creating the target. Do not set this yourself.

@class Item : EntityPositioner
FieldTypeDescription
label

string

name?

string

Optional name to reference the item by. Item.label will be used if not specified.

icon?

string | MenuIconTexture

The favicon to display left of the label. A texture object can be specified to render a specific ingame texture (like that of a ped headshot).

style?

"default" | "destructive" | "success" | "ghost"

The theming of the item. Any value specified in Config.Graphics.Menu.Styles will work.

action?

fun(menu: Menu, itemIndex: number, item: Item, coords: vector3, distance: number, entity?: number): boolean | nil

The returned value will be used to determine whether the menu should be hidden after the action is performed. If nil or true is returned, the menu will be hidden (If Config.HideOnAction is set to true), if false is returned it will ignore the Config.HideOnAction setting.

canInteract?

fun(entity?: number, coords: vector3, distance: number, name?: string, bone?: string | number | number[] | string[]): boolean

distance?

number

Override maximum distance at which the item can be interacted with.

main.lua
exports["vivum-target"]:AddTarget({
	name = "menu-name",
	target = {
		position = vector3(0, 0, 0),
	},
	items = {
		{
			label = "First Item",
			action = function()
				dbg("First Item clicked")
			end,
		},
		{
			label = "Second Item",
			action = function()
				dbg("Second Item clicked")
			end,
		},
	},
})