Type File

--- @meta

--- @class VivumTargetExports
--- @field AddTarget fun(self: VivumTargetExports, menu: VivumTargetMenu): string | nil
--- @field UpdateTarget fun(self: VivumTargetExports, id: number | string, partial: PartialVivumTargetMenu): VivumTargetMenu
--- @field RemoveTarget fun(self: VivumTargetExports, id: number | string, resource?: string): nil
--- @field GetTarget fun(self: VivumTargetExports, id: number | string, resource?: string): VivumTargetMenu, number
--- @field Toggle fun(self: VivumTargetExports, state?: boolean): nil
--- @field RemoveNames fun(self: VivumTargetExports, id: number | string, names: string | string[], resource?: string): nil
--- @field PreloadIcons fun(self: VivumTargetExports, icons: string[]): boolean
--- @field [string] any # <b>Unknown export</b>. Check the [docs](https://vivum.dev/docs/) to make sure that it exists.

--- @type VivumTargetExports
--- @diagnostic disable: missing-fields
exports["vivum-target"] = {}

--- @alias VivumTargetGlobalTargetType "all" | "player" | "ped" | "vehicle" | "object"
--- @alias VivumTargetCompatiblityType "ox" | "qb" | "q"

--- @class VivumTargetMenu
--- @field id? string Automatically set to a unique id. Do not set this yourself unless necessary.
--- @field resource? string Automatically set to the invoking resource. Do not set this yourself.
--- @field name? string A unique name for the menu. If not specified, the name will be set to the generated id.
--- @field target { position?: vector3, box?: VivumTargetBoxTarget, poly?: VivumTargetPolyTarget, circle?: VivumTargetCircleTarget, entity?: VivumTargetEntityTarget, global?: VivumTargetGlobalTarget } The type of target to render. Specify **one** of the target types.
--- @field items? VivumTargetItem[] | fun(entity: number): VivumTargetItem[] A table of items or a function that returns a table of items every ≈100ms.
--- @field canInteract? fun(entity?: number): boolean
--- @field hideOnInteract? boolean Override the default behavior of `Config.HideOnAction` for this specific menu.
--- @field action? fun(menu: VivumTargetMenu, 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.
--- @field 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`)
--- @field icon? string | VivumTargetMenuIconTexture 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).
--- @field tooltip? string An optional help text to display over the target star. Will be hidden if the star is hovered.
--- @field linestrip? VivumTargetLinestrip Draws a linestrip from the center of the star to the specified point (vector or entity handle).
--- @field uniqueKey? string Multiple targets with the same `uniqueKey` will only render the closest one.
--- @field seethrough? boolean If set to `true`, the target star will be rendered even if something is visually obstructing it.
--- @field distance? number Override maximum distance at which the target can be interacted with.
--- @field renderDistance? number Override render distance of the target.
--- @field 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.**
--- @field 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.**
--- @field starTint? [number, number, number] Set a tint (RGB) for the target star.
--- @field 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.
--- @field 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.
--- @field onUpdate? fun(self: VivumTargetMenu): VivumTargetMenu 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`).
--- @field compatibility? VivumTargetCompatiblityType The compatibility layer that was used when creating the target. Do not set this yourself.

--- @class VivumTargetItem : VivumTargetEntityPositioner
--- @field resource? string Automatically set to the invoking resource. Do not set this yourself.
--- @field label string
--- @field name? string Optional name to reference the item by. `Item.label` will be used if not specified.
--- @field icon? string | VivumTargetMenuIconTexture 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).
--- @field style? "default" | "destructive" | "success" | "ghost" The theming of the item. Any value specified in `Config.Graphics.Menu.Styles` will work.
--- @field action? fun(menu: VivumTargetMenu, itemIndex: number, item: VivumTargetItem, 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.
--- @field canInteract? fun(entity?: number, coords: vector3, distance: number, name?: string, bone?: string | number | number[] | string[]): boolean
--- @field distance? number Override maximum distance at which the item can be interacted with.

--- @class VivumTargetEntityPositioner Properties to position the target star at an entity's bone or offset. Only works on `entity` and `global` targets.
--- @field bone? string | string[] | number | number[]  The bone name or bone index to position the star at. If multiple bones are specified, the first valid one will be used.
--- @field offset? VivumTargetEntityOffset The offset to apply to the star positioning (will be added *after* the bone position if specified)
--- @field allowEntityHovering? boolean If set to `true`, the entity can be hovered in addition to the detached star when used with positioning properties like `bone` or `offset`.

--- @class VivumTargetEntityOffset
--- @field relative? vector3 Offset relative to the entity, meaning X is left/right, Y is forward/backward, and Z is up/down.
--- @field absolute? vector3 Offset in absolute world coordinates. Meaning that the offset will remain constant independent of the entity's rotation.
--- @field outwards? vector3 The normalized difference between the entity coordinates and the offsets (bones, relative and absolute offsets). Skips the Z (up/down) component.
--- @field fn? fun(ref: vector3): vector3 A function to mutate the offset with external logic. This function will be called every frame and as such *must* only be used in an integration in the `vivum-target/integrations` folder.

--- @class VivumTargetLinestrip
--- @field entity? number A handle to an entity to take the position from.
--- @field position? vector3 The position to draw the linestrip to, this will be overriden if `entity` is specified.
--- @field offset? vector3 Offset of the entity coords or specified position.

--- @class VivumTargetBoxTarget
--- @field center vector3
--- @field size vector3
--- @field rotation? number
--- @field debug? boolean If `true`, draws a red debug box while interacting.

--- @class VivumTargetPolyTarget
--- @field points vector3[]
--- @field height number
--- @field debug? boolean If `true`, draws a red debug poly while interacting.

--- @class VivumTargetCircleTarget
--- @field center vector3
--- @field radius number
--- @field debug? boolean If `true`, draws a red debug sphere while interacting.

--- @class VivumTargetEntityTarget : VivumTargetEntityPositioner
--- @field handle number The entity handle.

--- @class VivumTargetGlobalTarget : VivumTargetEntityPositioner
--- @field type VivumTargetGlobalTargetType
--- @field model? number | string Optionally filter the global target with a model.
--- @field preserveLastEntity? boolean Keep rendering the target (will only be visible if the target has `bone` or `offset` specified) on the last entity that was raycasted.

--- @class VivumTargetMenuIconTexture Can be used to specify a ingame texture for the menu icon (e.g. a ped headshot).
--- @field txn string
--- @field txd? string If not specified, the `txd` will be set to the same value as `txn`.
--- @field width? number Defaults to `1`.
--- @field height? number Defaults to `1`.

--- @class (partial) PartialVivumTargetMenu: VivumTargetMenu