ox_target Exports

All exports documented on this page are client-side exports.

This page covers the original client API together with the category fields added by ScriptsM. You can also consult the official TargetOptions (opens in a new tab) and client exports (opens in a new tab) references for the upstream API.

local ox_target = exports.ox_target

The category structure described in the main documentation can be passed through every export that accepts target options.

Target Option

Standard options and category options share the same parent-level restrictions.

{
    name = 'unique_option_name',
    label = 'Option label',
    icon = 'fa-solid fa-hand',
    iconColor = '#ffffff',
    distance = 2.0,
    groups = { police = 0 },
    items = { 'radio' },
    anyItem = false,
    bones = { 'boot' },
    offset = vec3(0.0, 0.0, 0.0),
    offsetSize = 1.0,
    canInteract = function(entity, distance, coords, name, bone)
        return true
    end,
    onSelect = function(data)
        print(data.entity)
    end
}

Field	Type	Description
`label`	`string`	Text displayed for a standard target option.
`name`	`string`	Identifier used to replace or remove an option.
`icon`	`string`	Font Awesome icon name.
`iconColor`	`string`	CSS color used by the icon.
`distance`	`number`	Maximum distance at which the option is displayed.
`bones`	`string/string[]`	Entity bone or bones where the option is available.
`offset`	`vector3`	Targetable position relative to the model dimensions.
`offsetSize`	`number`	Radius around the configured entity offset.
`groups`	`string/string[]/table`	Framework groups or minimum group grades required.
`items`	`string/string[]/table`	Framework items or item counts required.
`anyItem`	`boolean`	Requires any one configured item instead of every item.
`canInteract`	`function`	Controls whether the option is currently displayed.
`menuName`	`string`	Displays the option only while the named menu is active.
`openMenu`	`string`	Opens a named target menu when selected.
`onSelect`	`function`	Executes a Lua callback.
`export`	`string`	Calls an export in the registering resource.
`event`	`string`	Triggers a client event.
`serverEvent`	`string`	Triggers a server event.
`command`	`string`	Executes a client command.

For standard options, actions are resolved in this order: onSelect, export, event, serverEvent, then command. Category suboptions are stricter and must define exactly one action handler.

To create a category, replace label, icon, and the direct action with the category fields:

{
    name = 'unique_category_name',
    usedouble = true,
    labelcategory = 'Category Label',
    iconcategory = 'fa-solid fa-folder',
    iconColor = '#ffffff',
    subcategory = {
        {
            label = 'First action',
            icon = 'fa-solid fa-hand',
            event = 'my_resource:firstAction'
        }
    }
}

Zones

addSphereZone

Creates a spherical target zone and returns its numeric zone ID.

local zoneId = exports.ox_target:addSphereZone({
    name = 'example_sphere',
    coords = vec3(441.2, -981.9, 30.7),
    radius = 1.5,
    debug = false,
    drawSprite = true,
    options = {
        {
            name = 'example_sphere_action',
            label = 'Use sphere zone',
            icon = 'fa-solid fa-circle',
            event = 'my_resource:useSphere'
        }
    }
})

addBoxZone

Creates a box target zone and returns its numeric zone ID.

local zoneId = exports.ox_target:addBoxZone({
    name = 'example_box',
    coords = vec3(441.2, -981.9, 30.7),
    size = vec3(2.0, 2.0, 2.0),
    rotation = 45.0,
    debug = false,
    drawSprite = true,
    options = {
        {
            name = 'example_box_action',
            label = 'Use box zone',
            icon = 'fa-solid fa-cube',
            event = 'my_resource:useBox'
        }
    }
})

addPolyZone

Creates a polygon target zone and returns its numeric zone ID.

local zoneId = exports.ox_target:addPolyZone({
    name = 'example_polygon',
    points = {
        vec3(438.0, -985.0, 30.0),
        vec3(445.0, -985.0, 30.0),
        vec3(445.0, -978.0, 30.0),
        vec3(438.0, -978.0, 30.0)
    },
    thickness = 3.0,
    debug = false,
    drawSprite = true,
    options = {
        {
            name = 'example_polygon_action',
            label = 'Use polygon zone',
            icon = 'fa-solid fa-draw-polygon',
            event = 'my_resource:usePolygon'
        }
    }
})

zoneExists

Checks whether a zone exists. Accepts a numeric zone ID or string zone name.

local existsById = exports.ox_target:zoneExists(zoneId)
local existsByName = exports.ox_target:zoneExists('example_box')

Returns true when the zone exists and false otherwise.

removeZone

Removes a zone by numeric ID or string name.

exports.ox_target:removeZone(zoneId)
exports.ox_target:removeZone('example_box')

An optional second argument suppresses the warning when the zone does not exist.

exports.ox_target:removeZone('example_box', true)

Models

addModel

Adds options to one or more entity models. Models can be passed as names or hashes.

exports.ox_target:addModel({ 'police', 'police2' }, {
    {
        name = 'police_vehicle_category',
        usedouble = true,
        labelcategory = 'Police Equipment',
        iconcategory = 'fa-solid fa-toolbox',
        distance = 2.0,
        bones = { 'boot' },
        subcategory = {
            {
                label = 'Take cone',
                icon = 'fa-solid fa-triangle-exclamation',
                event = 'equipment:takeCone'
            },
            {
                label = 'Take barrier',
                icon = 'fa-solid fa-road-barrier',
                event = 'equipment:takeBarrier'
            }
        }
    }
})

removeModel

Removes named options from one or more models.

exports.ox_target:removeModel({ 'police', 'police2' }, 'police_vehicle_category')

Pass an array to remove multiple named options.

exports.ox_target:removeModel('police', {
    'police_vehicle_category',
    'another_option'
})

Omit the second argument to remove all options registered by the current resource from the model.

exports.ox_target:removeModel('police')

Networked Entities

addEntity

Adds options to one or more networked entities. Pass network IDs, not local entity handles.

local netId = NetworkGetNetworkIdFromEntity(vehicle)
 
exports.ox_target:addEntity(netId, {
    {
        name = 'network_vehicle_action',
        label = 'Inspect vehicle',
        icon = 'fa-solid fa-magnifying-glass',
        onSelect = function(data)
            print(data.entity)
        end
    }
})

removeEntity

Removes named options from one or more network IDs.

exports.ox_target:removeEntity(netId, 'network_vehicle_action')

Omit the option name to remove every option registered by the current resource from that networked entity.

exports.ox_target:removeEntity(netId)

Local Entities

addLocalEntity

Adds options to one or more local entity handles.

exports.ox_target:addLocalEntity(object, {
    {
        name = 'local_object_action',
        label = 'Pick up object',
        icon = 'fa-solid fa-hand',
        event = 'my_resource:pickupObject'
    }
})

removeLocalEntity

Removes named options from one or more local entity handles.

exports.ox_target:removeLocalEntity(object, 'local_object_action')

Omit the option name to remove every option registered by the current resource from the local entity.

exports.ox_target:removeLocalEntity(object)

Global Targets

Global exports apply options to every supported entity of a specific type.

Global peds

exports.ox_target:addGlobalPed({
    {
        name = 'global_ped_action',
        label = 'Talk',
        icon = 'fa-solid fa-comments',
        event = 'my_resource:talkToPed'
    }
})
 
exports.ox_target:removeGlobalPed('global_ped_action')

Global vehicles

exports.ox_target:addGlobalVehicle({
    {
        name = 'global_vehicle_action',
        label = 'Inspect vehicle',
        icon = 'fa-solid fa-car',
        event = 'my_resource:inspectVehicle'
    }
})
 
exports.ox_target:removeGlobalVehicle('global_vehicle_action')

Global objects

exports.ox_target:addGlobalObject({
    {
        name = 'global_object_action',
        label = 'Inspect object',
        icon = 'fa-solid fa-magnifying-glass',
        event = 'my_resource:inspectObject'
    }
})
 
exports.ox_target:removeGlobalObject('global_object_action')

Global players

exports.ox_target:addGlobalPlayer({
    {
        name = 'global_player_category',
        usedouble = true,
        labelcategory = 'Player Actions',
        iconcategory = 'fa-solid fa-user',
        distance = 2.0,
        subcategory = {
            {
                label = 'Show identification',
                icon = 'fa-solid fa-id-card',
                event = 'my_resource:showIdentification'
            },
            {
                label = 'Escort player',
                icon = 'fa-solid fa-people-pulling',
                event = 'my_resource:escortPlayer'
            }
        }
    }
})
 
exports.ox_target:removeGlobalPlayer('global_player_category')

Every remove export accepts either one option name or an array of option names.

Global Options

addGlobalOption

Adds an option that can be displayed without targeting a specific entity type.

exports.ox_target:addGlobalOption({
    {
        name = 'global_service_category',
        usedouble = true,
        labelcategory = 'Services',
        iconcategory = 'fa-solid fa-bell-concierge',
        subcategory = {
            {
                label = 'Call taxi',
                icon = 'fa-solid fa-taxi',
                command = 'taxi'
            },
            {
                label = 'Call mechanic',
                icon = 'fa-solid fa-wrench',
                command = 'mechanic'
            }
        }
    }
})

removeGlobalOption

Removes one or more named global options registered by the current resource.

exports.ox_target:removeGlobalOption('global_service_category')

Target State

disableTargeting

Disables or enables targeting.

exports.ox_target:disableTargeting(true)
exports.ox_target:disableTargeting(false)

Disabling targeting immediately closes an active target session.

isActive

Returns whether the player is currently using the target system.

local active = exports.ox_target:isActive()
 
if active then
    print('Targeting is active')
end

Reading Registered Options

getTargetOptions

Returns the internal option collections available for an entity.

local entity = GetVehiclePedIsIn(PlayerPedId(), false)
local entityType = GetEntityType(entity)
local model = GetEntityModel(entity)
 
local targetOptions = exports.ox_target:getTargetOptions(entity, entityType, model)

When called without arguments, it returns the active internal option container used by ox_target.

local targetOptions = exports.ox_target:getTargetOptions()

This export exposes internal collections and is mainly intended for advanced integrations and debugging. Do not modify the returned tables unless you understand the target lifecycle.

Selection Data

An onSelect, client event, server event, or export receives a data table containing the available selection context.

{
    entity = 123,
    coords = vec3(0.0, 0.0, 0.0),
    distance = 1.5,
    zone = 4,
    resource = 'my_resource',
    name = 'selected_action'
}

Client callbacks and client events receive a local entity handle in entity.
Server events receive a network ID when the selected entity is networked, otherwise 0.
Zone selections include the numeric zone ID in zone.
Any custom fields added to the selected option are included in the data table.

{
    label = 'Take equipment',
    icon = 'fa-solid fa-toolbox',
    event = 'equipment:take',
    itemName = 'police_cone'
}
 
RegisterNetEvent('equipment:take', function(data)
    print(data.itemName)
end)

Resource Cleanup

Options are associated with the resource that registered them. When that resource stops, its global, model, entity, local entity, and zone options are automatically removed by ox_target.

Use the remove exports when options need to be removed while the registering resource is still running.

Ox Target Categories ScriptsM AirBags