ox_target is the go-to third-eye targeting resource for FiveM roleplay servers. It lets players hold a key to open a radial interaction menu tied to world zones, entities, peds, and vehicles — powering everything from job actions to shopkeeper prompts. This guide walks you through installation, configuring your first zones, using the core client exports, and migrating away from the older qtarget API.
Prerequisites
ox_target has a single hard dependency: ox_lib. The resource’s own fxmanifest.lua declares dependency 'ox_lib', and its shared_scripts load @ox_lib/init.lua at startup. If ox_lib is missing or starts after ox_target, the resource will error immediately and no interactions will register. Install ox_lib first from github.com/overextended/ox_lib, then proceed.
Installation
Download a release from github.com/overextended/ox_target/releases and extract the folder into your server’s resources directory. The folder must be named ox_target.
Open your server.cfg and add the ensure lines in the correct order — ox_lib must appear before ox_target, and both must appear before any resource that calls ox_target exports:
ensure oxmysql
ensure ox_lib
ensure ox_target
# your scripts that use ox_target come after this line
ensure my_shop_resource
ensure my_job_resourceThat is all that is required for a basic setup. ox_target ships with framework detection built in, so it will automatically pick up ox_core, ESX (esx-legacy), or QBX (qbx_core) if those are present — no extra configuration is needed to unlock job/group filtering.
Optional Convars
You can tune ox_target behaviour via setr convars in server.cfg. Add any of these before the ensure ox_target line:
# Hold key to open targeting (0) or toggle on/off (1). Default: 0
setr ox_target:toggleHotkey 0
# Key used to activate targeting. Default: LMENU (Left Alt)
setr ox_target:defaultHotkey LMENU
# Draw a dot at the centre of box zones. Default: 1
setr ox_target:drawSprite 1
# Enable built-in default interactions (e.g. doors). Default: 1
setr ox_target:defaults 1
# Show zone outlines for debugging. Default: 0
setr ox_target:debug 0
# Allow left-click to select an option. Default: 1
setr ox_target:leftClick 1Declaring ox_target in Your Own Resource
Any resource that calls ox_target exports must load ox_lib’s init file. A minimal fxmanifest.lua for a script that uses ox_target looks like this:
fx_version 'cerulean'
game 'gta5'
lua54 'yes'
shared_scripts {
'@ox_lib/init.lua',
}
client_scripts {
'client.lua',
}
dependencies {
'ox_lib',
'ox_target',
}The dependencies block tells FiveM to refuse loading your resource if ox_lib or ox_target is missing, giving you a clear error rather than a silent failure.
Core Client Exports
All interaction is defined through client-side Lua exports. The four you will use most are addBoxZone, addLocalEntity, addEntity, and addModel. See the FiveM server hosting docs for wider server-setup context.
addBoxZone
addBoxZone creates a rectangular targetable area in the world. It accepts a single Lua table and returns a numeric zone ID you can use later to remove it:
-- client.lua
local zoneId = exports.ox_target:addBoxZone({
coords = vector3(150.2, -1040.5, 29.37), -- world position
size = vector3(2.0, 1.5, 2.0), -- width, depth, height
rotation = 45.0, -- heading in degrees
debug = false, -- set true to see the box outline
options = {
{
label = 'Open Shop',
icon = 'fa-solid fa-store', -- Font Awesome class name
onSelect = function(data)
-- data.entity, data.coords, data.zone are available here
TriggerEvent('my_shop:open')
end,
},
},
})
-- Remove the zone when your resource stops
AddEventHandler('onResourceStop', function(resourceName)
if resourceName == GetCurrentResourceName() then
exports.ox_target:removeZone(zoneId)
end
end)The icon field takes a Font Awesome class string (e.g. 'fa-solid fa-car'), not an image path — this is one of the key differences from qtarget.
addLocalEntity
addLocalEntity attaches interactions to a specific entity handle that only exists on the local client — useful for props or peds your script spawned:
local prop = CreateObject(`prop_atm_01`, 200.0, -800.0, 31.0, true, true, false)
exports.ox_target:addLocalEntity(prop, {
{
label = 'Use ATM',
icon = 'fa-solid fa-credit-card',
distance = 1.5,
canInteract = function(entity, distance, coords, name, bone)
-- return false to hide the option without removing it
return not IsPedInAnyVehicle(PlayerPedId(), false)
end,
onSelect = function(data)
TriggerEvent('banking:openATM')
end,
},
})addEntity (network entities)
When an entity exists across the network (e.g. a vehicle or ped synced via OneSync), use addEntity and pass the network ID instead of the local entity handle:
-- netId obtained from server or another resource
exports.ox_target:addEntity(netId, {
{
label = 'Impound Vehicle',
icon = 'fa-solid fa-truck-tow',
groups = 'police', -- only players with the 'police' job see this
onSelect = function(data)
TriggerServerEvent('police:impound', NetworkGetEntityFromNetworkId(data.entity))
end,
},
})TargetOptions Field Reference
Every export that accepts an options table expects an array of TargetOption objects. The fields available on each option are:
| Field | Type | Required | Notes |
|---|---|---|---|
label | string | Yes | Text shown in the interaction menu |
icon | string | No | Font Awesome class name (e.g. fa-solid fa-key) |
iconColor | string | No | CSS colour for the icon |
name | string | No | Identifier used when removing specific options later |
distance | number | No | Max range in metres; defaults to 2.0 |
groups | string / string[] / table | No | Job, gang, or group required (framework-dependent) |
items | string / string[] / table | No | Inventory item(s) required to see the option |
canInteract | function(entity, distance, coords, name, bone) | No | Called every frame; return false to hide the option |
onSelect | function(data) | No | Fires on selection (highest priority) |
event | string | No | Client event triggered on selection |
serverEvent | string | No | Server event triggered on selection |
command | string | No | Command executed on selection |
Migrating from qtarget / qb-target
ox_target ships with a compatibility shim at client/compat/qtarget.lua and declares provide 'qtarget' in its manifest, so resources that call the old exports.qtarget:* or qtarget global functions will be redirected automatically for common cases. However, Overextended explicitly states that this shim does not and will never cover 100% of qtarget’s behaviour — it is a stopgap, not a permanent replacement.
For a clean migration, rewrite your calls manually. The main differences are:
- Icons: qtarget used image file paths; ox_target uses Font Awesome class strings.
- Option field names:
actionbecomesonSelect;jobbecomesgroups;item/itemsmoves to theitemsfield. - Zone parameters: qtarget passed positional arguments; ox_target uses a single named-field table.
- Remove by name: ox_target stores zones by ID (returned on creation) or optional string name — you can no longer continuously re-register options under the same name the way qtarget allowed.
For guides on building out the wider server stack, see the ox_lib setup guide and the resource loading errors troubleshooting guide.
Performance Notes
ox_target performs roughly four times faster than qtarget in typical benchmarks cited by Overextended, owing to a rewritten raycast pipeline. The canInteract callback runs every frame while the crosshair is over a target, so keep its logic lightweight — avoid heavy loops or synchronous network calls inside it. Always call removeZone or removeLocalEntity in an onResourceStop handler so you do not leave ghost zones behind after a resource restart.
Hosting Tip
ox_target is a pure client-rendered resource with a tiny server component. It adds negligible load to your server thread, but resource-start order matters more than hardware. If you are running a full QBX or ESX stack and hitting unexplained startup errors, check that ox_lib starts before ox_target — a mis-ordered ensure line is the most common cause. If you need a reliably fast machine to test large resource stacks, a managed FiveM server removes the ordering headaches from the hosting side entirely.
Frequently Asked Questions
Does ox_target work without ox_lib?
No. ox_target’s fxmanifest.lua declares dependency 'ox_lib' and loads @ox_lib/init.lua as a shared script. If ox_lib is absent or starts after ox_target, the resource will fail to initialise and no interactions will register. Always ensure ox_lib appears above ox_target in server.cfg.
Why can players not see my interaction option?
The most common causes are: (1) the player is beyond the distance threshold (default 2.0 m — increase it if needed); (2) your canInteract function is returning false; (3) a groups or items requirement is not met; (4) ox_target or ox_lib failed to start (check server console for errors). Set setr ox_target:debug 1 in server.cfg to draw zone outlines and confirm your coordinates are correct.
Can I use both qtarget and ox_target at the same time?
You should not run both resources simultaneously. ox_target declares provide 'qtarget', meaning it acts as a drop-in provider for the qtarget resource name. Running a separate qtarget resource alongside it will cause a conflict. Rely on ox_target’s built-in compatibility shim for legacy scripts while you migrate them, then remove the shim dependency once everything is rewritten.
Ready to play?
Run your own FiveM server with XGamingServer
Spin up an always-on FiveM server your friends can join in minutes — no port-forwarding, no tech headaches.
