4 min read
How to use ox_target with QBCore
ox_target can register standalone interactions on a QBCore server, but its reviewed framework adapters do not include stock qb-core. Do not assume groups automatically checks QBCore jobs or gangs. Migrate the registration API, implement visibility against your actual player data and keep permissions and rewards server-authoritative.
The API baseline is Overextended bf03d52c, source-reviewed on November 13, 2026. The example is not an executed in-game test. For existing qb-target code, keep the qb-target reference open while converting each caller.
Install dependencies and register one zone
Install the selected ox_target release and its required ox_lib version. Retain the exact resource names. Create a separate docs_ox_target resource with this fxmanifest.lua:
fx_version 'cerulean'
game 'gta5'
shared_script '@ox_lib/init.lua'
client_script 'client.lua'
dependencies { 'ox_lib', 'ox_target' }Start it after its dependencies, leaving the rest of your server recipe intact:
ensure ox_lib
ensure ox_target
ensure docs_ox_targetUse this complete client.lua for a harmless local notification. Move the example coordinates to a reachable location on your map. It intentionally grants no items, money or protected access.
local zoneId = exports.ox_target:addBoxZone({
coords = vec3(441.2, -981.9, 30.7),
size = vec3(1.0, 1.0, 2.0),
rotation = 0,
debug = false,
options = {
{
name = 'docs_counter_info',
icon = 'fa-solid fa-circle-info',
label = 'Read counter information',
distance = 2.0,
onSelect = function()
lib.notify({ description = 'The counter interaction is registered.' })
end,
},
},
})
AddEventHandler('onResourceStop', function(resourceName)
if resourceName ~= GetCurrentResourceName() then return end
if GetResourceState('ox_target') == 'started' then
exports.ox_target:removeZone(zoneId, true)
end
end)Expected manual result: the option appears in range and selection shows one notification. Test your actual target keybinding, leaving/entering range and restarting the caller. If ox_target itself restarts, restart this caller afterward to register its zone again.
Convert qb-target calls explicitly
| qb-target concept | ox_target equivalent | Migration detail |
|---|---|---|
AddBoxZone(name, center, length, width, zoneOptions, targetOptions) | addBoxZone({ coords, size, rotation, options }) | Convert positional arguments to a table; check vertical bounds |
minZ / maxZ | coords.z and size.z | Center height is (minZ + maxZ) / 2; thickness is maxZ - minZ |
heading | rotation | Verify the box orientation in debug mode |
action(entity) | onSelect(data) | The entity is data.entity; callback arguments differ |
job / gang | Framework-specific groups or a custom canInteract | No native stock-QBCore group adapter in the reviewed revision |
RemoveZone(name) | removeZone(idOrName) | Store the returned ID or assign a stable zone name |
AddTargetEntity | addLocalEntity or addEntity | Local entity handle and network ID are different identifiers |
Do not globally replace the text qb-target with ox_target. Resource names, function names, option fields and callback data all form part of the contract. Compatibility wrappers for another target API do not prove support for every qb-target call.
How do QBCore job and gang checks work?
The reviewed client/framework/ directory contains esx, nd, ox and qbx adapters. Its Qbox adapter calls exports.qbx_core:HasGroup, which is not a stock-QBCore API. Without a supported adapter, the reviewed default hasPlayerGotGroup returns true, so a groups condition does not restrict access. Check the actual fork rather than assuming groups = 'police' will filter correctly.
For a custom stock-QBCore integration, read the current job or gang in canInteract through the player data lifecycle. Refresh that data on load, job/gang changes and unload; a one-time login snapshot becomes stale. Handle missing player data during loading. Verify the installed core's grade shape before comparing grade levels.
Visibility is only a user-interface condition. Every server action must recheck the real player's identity, job/grade, distance, item requirements and operation state. Never accept client-supplied job names or prices as authorization. See resource security.
Why are ox_target options missing or duplicated?
- No zone: check the first startup/F8 error, manifest,
ox_lib, coordinates and height. Temporarily enabledebugon staging to see the actual box. - Zone exists, option missing: check
distance,canInteract, group/item filters and player loading. Test an unrestricted notification first to separate geometry from permission logic. - Two eye menus or duplicate options: inspect both target resources and repeated registration. Migrate callers in a controlled staging batch; do not disable qb-target while active callers still require it.
- No such export: check spelling and execution side.
addBoxZoneis a client registration API; use the missing-export guide. - Action fires with wrong data: convert the callback rather than passing a qb-target
entitycallback unchanged.
Migration acceptance
Test each converted location with an allowed and denied job/grade, before login, after job change, at an invalid distance and after caller restart. Test entity interactions after entity deletion/recreation. Verify that rejected server requests give no protected result. Save the old caller and configuration revisions for rollback; changing the targeting library alone does not migrate its consumers.
Sources
- Client API at bf03d52c: zone registration and removal.
- Group-check fallback and adapter detection.
- Framework adapters at bf03d52c: the reviewed adapter set.
- Upstream target option reference and client API documentation: option callbacks and local/network entity distinctions.
Found an issue in this guide?
Send the page URL, the affected example, and a source or reproduction to the site maintainer. For a server or resource problem, use the support guide.
ox_inventory on QBCore
Check ox_inventory forks, QBCore bridges, dependencies and migration risks before replacing qb-inventory. Diagnose missing exports and item failures.
Add custom vehicles
Integrate an add-on vehicle into QBCore step by step: validate streaming, add the correct vehicles.lua entry, configure a dealership or job garage and verify persistence.
