Api

🛠️ The `options` Table

Whenever you add a target (to an entity, model, zone, or globally), you must pass an options table. This defines what the player sees and what happens when they click the option.

Option Parameters

Parameter	Type	Description
`name`	`string`	A unique identifier for the option.
`label`	`string`	The text displayed in the target menu.
`icon`	`string`	The FontAwesome icon class (e.g., `'fas fa-car'`).
`description`	`string`	(Optional) Extra description text below the label.
`distance`	`number`	The maximum distance the player can interact from.
`bones`	`string` / `table`	(Optional) Specific entity bones the player must look at.
`offset`	`vector3`	(Optional) Offset from the entity's center.
`groups`	`string` / `table`	(Optional) Restrict to specific jobs, gangs, or citizen IDs.
`items`	`string` / `table`	(Optional) Restrict to players carrying specific item(s).
`anyItem`	`boolean`	(Optional) If `true`, the player only needs one of the specified items.
`canInteract`	`function`	(Optional) A custom check function returning `true` or `false`.
`submenu`	`table`	(NEW) (Optional) A nested table of target options to create a multi-level drop-down menu.

Action Handlers (Pick One)

You must define one of the following to execute an action when the player clicks the option (unless the option is just a parent for a submenu):

onSelect or action: A direct Lua callback function. Receives a data table (entity, coords, distance, zone).
event: Triggers a Client Event.
serverEvent: Triggers a Server Event (automatically converts entity to netId).
command: Executes a console command.
export: Calls an export formatted as 'resourceName.exportName'.

📂 Submenus (Nested Options)

You can now nest target options inside one another to create clean, organized submenus. Options containing a submenu table will act as a folder and do not need an action handler (like onSelect).

You can nest submenus as deeply as you want!

Example Submenu Table

local myOptions = {
    {
        name = "vehicle_options",
        icon = "fas fa-car",
        label = "Vehicle Options",
        distance = 2.5,
        -- Level 1 Submenu
        submenu = {
            {
                name = "inspect_vehicle",
                icon = "fas fa-magnifying-glass",
                label = "Inspect Vehicle",
                distance = 2.5,
                onSelect = function(data)
                    print("Inspecting vehicle entity ID: " .. tostring(data.entity))
                end
            },
            {
                name = "door_controls",
                icon = "fas fa-door-open",
                label = "Door Controls",
                distance = 2.5,
                -- Level 2 Submenu (Nested inside Level 1)
                submenu = {
                    {
                        name = "toggle_hood",
                        icon = "fas fa-angle-up",
                        label = "Toggle Hood",
                        distance = 2.5,
                        onSelect = function(data)
                            print("Toggling hood for vehicle: " .. tostring(data.entity))
                        end
                    },
                    {
                        name = "toggle_trunk",
                        icon = "fas fa-angle-down",
                        label = "Toggle Trunk",
                        distance = 2.5,
                        onSelect = function(data)
                            print("Toggling trunk for vehicle: " .. tostring(data.entity))
                        end
                    }
                }
            }
        }
    }
}

-- Adding the submenu to all vehicles
exports.ak47_target:addGlobalVehicle(myOptions)

🌍 Global Targets

Global targets apply to every entity of a specific type across the entire map.

addGlobalPed

Adds options to all Peds.

exports.ak47_target:addGlobalPed(options)

addGlobalVehicle

Adds options to all Vehicles.

exports.ak47_target:addGlobalVehicle(options)

addGlobalObject

Adds options to all Objects.

exports.ak47_target:addGlobalObject(options)

addGlobalPlayer

Adds options to all other Players.

exports.ak47_target:addGlobalPlayer(options)

addGlobalOption

Adds an option anywhere in the world (catches world coordinates if no entity is hit).

exports.ak47_target:addGlobalOption(options)

📦 Model & Entity Targets

addModel

Adds options to specific entity models (props, vehicle models, ped models).

-- Models can be a single string/hash or a table of strings/hashes
local models = { 'prop_atm_01', 'prop_atm_02', `prop_atm_03` }

exports.ak47_target:addModel(models, {
    {
        name = 'use_atm',
        icon = 'fas fa-credit-card',
        label = 'Use ATM',
        distance = 1.5,
        event = 'myBank:client:openMenu'
    }
})

addEntity (Networked)

Adds options to specific networked entities using their netId.

exports.ak47_target:addEntity(netId, options) -- Accepts single netId or table of netIds

addLocalEntity (Non-Networked)

Adds options to specific local entities using their local entity ID.

exports.ak47_target:addLocalEntity(entityId, options) -- Accepts single ID or table of IDs

📍 Zone Targets

Zones allow you to define 3D areas in the world that act as targets without needing a physical prop.

addSphereZone

Creates a spherical interaction zone. Returns a unique Zone ID.

local zoneId = exports.ak47_target:addSphereZone({
    coords = vector3(100.0, -100.0, 30.0),
    radius = 2.5,
    debug = false, -- Set to true to see the zone outline
    options = {
        {
            name = 'sphere_interact',
            icon = 'fas fa-hand',
            label = 'Interact Sphere',
            distance = 2.5,
            action = function(data) print("Sphere clicked!") end
        }
    }
})

addBoxZone

Creates a rectangular interaction box. Returns a unique Zone ID.

local zoneId = exports.ak47_target:addBoxZone({
    coords = vector3(120.0, -120.0, 30.0),
    size = vector3(3.0, 2.0, 2.0), -- Width, Length, Height
    rotation = 45.0, -- Heading
    debug = false,
    options = { ... }
})

addPolyZone

Creates a custom polygon interaction zone. Returns a unique Zone ID.

local zoneId = exports.ak47_target:addPolyZone({
    points = {
        vector3(10.0, 10.0, 0.0),
        vector3(15.0, 10.0, 0.0),
        vector3(15.0, 15.0, 0.0),
        vector3(10.0, 15.0, 0.0)
    },
    thickness = 2.0,
    minZ = 28.0,
    maxZ = 32.0,
    debug = true,
    options = { ... }
})

🗑️ Removing Targets

Use these exports to clean up targets, especially inside onResourceStop handlers.

removeGlobalPed(labels)
removeGlobalVehicle(labels)
removeGlobalObject(labels)
removeGlobalPlayer(labels)
removeGlobalOption(labels)

Note: labels can be a single string (the option name or label) or a table of strings.

Removing Models & Entities:

exports.ak47_target:removeModel({'prop_atm_01'}, {'Use ATM'})
exports.ak47_target:removeEntity(netId, {'Rob Ped'})
exports.ak47_target:removeLocalEntity(entityId, {'Rob Ped'})

Removing Zones (Pass the Zone ID returned when you created it):

exports.ak47_target:removeZone(zoneId)

⚙️ Utility Exports

disableTargeting

Temporarily disable or re-enable the targeting eye.

exports.ak47_target:disableTargeting(true) -- Disables targeting and closes UI
exports.ak47_target:disableTargeting(false) -- Re-enables targeting

isDisabled

Check if targeting is currently disabled.

local disabled = exports.ak47_target:isDisabled()

zoneExists

Check if a specific zone ID is currently active.

local exists = exports.ak47_target:zoneExists(zoneId)

ak47_target

🛠️ The options Table