# 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](/docs/resources/qb-target) 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`:

```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:

```cfg
ensure ox_lib
ensure ox_target
ensure docs_ox_target
```

Use 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.

```lua
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](/docs/core/player-data). 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](/docs/security).

## Why are ox_target options missing or duplicated?

- **No zone:** check the first startup/F8 error, manifest, `ox_lib`, coordinates and height. Temporarily enable `debug` on 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. `addBoxZone` is a client registration API; use the [missing-export guide](/docs/troubleshooting/no-such-export).
- **Action fires with wrong data:** convert the callback rather than passing a qb-target `entity` callback 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](https://github.com/overextended/ox_target/blob/bf03d52c09cb5f677ac063531740fddcb51ca7cf/client/api.lua): zone registration and removal.
- [Group-check fallback and adapter detection](https://github.com/overextended/ox_target/blob/bf03d52c09cb5f677ac063531740fddcb51ca7cf/client/utils.lua).
- [Framework adapters at bf03d52c](https://github.com/overextended/ox_target/tree/bf03d52c09cb5f677ac063531740fddcb51ca7cf/client/framework): the reviewed adapter set.
- [Upstream target option reference](https://overextended.dev/docs/ox_target/TargetOptions) and [client API documentation](https://overextended.dev/docs/ox_target/Functions/Client): option callbacks and local/network entity distinctions.
