FA Target

Modern interaction system for FiveM with Focus, Cursor and World modes.

Documentation • Download • Discord • Showcase [SOON]

FA Target is a modern, free and open-source interaction system for FiveM, built on the proven ox_target engine.
Maintain compatibility with existing resources while adding modern interaction modes, world-anchored UI, per-option keybinds, hold interactions, action feedback, and a fully customizable Theme Creator.
Designed as a drop-in replacement for ox_target, with compatibility adapters for qb-target and qtarget.

Features

• 3 interaction modes - Focus, Cursor and World (configuration IDs: focus, classic, dui)
• Theme Creator - customize the interaction UI directly in-game
• Option keybinds - trigger interactions using configurable keys
• Hold interactions - require an option to be held for a configured duration
• Descriptions & badges - provide additional context without cluttering labels
• Action feedback - pending, success and error states for asynchronous interactions
• World-anchored UI - DUI mode follows the target position in the world
• Drop-in ox_target compatibility - existing exports.ox_target:* calls continue to work
• qb-target & qtarget adapters - supports common legacy registration formats
• Controller support
• Zones, entities, models, bones and global targets
• Runtime theme updates - server themes update connected players without a restart
• ACE-controlled theme administration

Preview

_{Focus • Classic • DUI}

Compatibility

Feature	ox_target	qb-target	qtarget
Zones	✅	✅	✅
Entities	✅	✅	✅
Models	✅	✅	✅
Bones	✅	✅	✅
Global options	✅	✅	✅
Jobs	✅	✅	✅
Gangs	—	✅	✅
Items	✅	✅	✅
Client events	✅	✅	✅
Server events	✅	✅	✅
Callbacks / actions	✅	✅	✅

Existing resources using exports.ox_target:* do not need to be rewritten.

Requirements

• ox_lib >= 3.30.0
• OneSync recommended

Installation

1. Download the latest release.
2. Extract it into your resources directory as fa_target.
3. Add the resource to your server.cfg after ox_lib:

ensure ox_lib
ensure fa_target

4. Remove your previous target resource.
5. Restart the server.

Important

Do not run FA Target alongside another resource providing ox_target, qb-target, or qtarget.

Theme Creator

FA Target includes an in-game Theme Creator for customizing the interaction UI without manually editing CSS.

Player preferences

Use /fatheme to open personal appearance settings when enabled by the server.

Server theme editor

Administrators with the following ACE permission can use /fathemeadmin:

add_ace group.admin fa_target.theme allow

Server themes:

• Persist between restarts using resource KVP
• Update connected players live
• Define which fields players may override locally

Configuration

config.lua controls framework and inventory detection, interaction modes, keybinds, blocking states, visual indicators, and player theme permissions.

Explicit bridge values take precedence over auto-detection.

DUI mode uses the regular NUI renderer anchored to the raycast world coordinate, avoiding a separate browser instance for every target.

Local fonts

Montserrat Variable is bundled locally for runtime interactions. The Theme Creator uses its own local Inter font, independent of the selected target font. To add a custom target font, copy its .woff2 file to web/public/fonts, add one entry to Config.Theme.fonts, and rebuild the UI:

{
    id = 'customer_font', label = 'Customer Font', family = 'Customer Font',
    file = 'CustomerFont.woff2', weight = '100 900'
}

Only local .woff2 filenames are accepted.

API

ox_target compatibility

fa_target registers ox_target's exports. Together with provide 'ox_target', this keeps exports.ox_target:* calls.

exports.ox_target:addBoxZone({
    coords = vec3(441.2, -981.9, 30.7), size = vec3(2, 2, 2),
    options = {{ name = 'armoury', label = 'Open armoury', event = 'police:armoury' }}
})

FA Target extensions

FA extensions are accepted on every option:

exports.fa_target:addLocalEntity(ped, {{
    name = 'dealer_talk', label = 'Talk to dealer',
    description = 'Browse available vehicles', icon = 'fa-solid fa-car',
    badge = 'NEW', key = 'E', hold = 1200, mode = 'focus',
    onSelect = function(data)
        return { status = 'success', message = 'Opening catalogue' }
    end
}})

Property	Type	Description
description	string	Secondary text displayed below the option label
badge	string	Small badge displayed alongside the option
key	string	Key used to trigger the option
hold	number	Required hold duration in milliseconds
mode	string	Overrides the interaction mode for the option
category	string	Identifier matching a color in Theme.categoryColors
unavailable	'show' / 'hide'	Overrides how unavailable actions are displayed
disabled	boolean	Explicitly marks an action unavailable
getState	function	Returns status, optional reason and remainingMs

Unavailable actions

Unavailable actions are hidden by default. Set Config.Interaction.unavailable = 'show' to display them with a reason, or use unavailable = 'show' on an individual option. Distance, object/bone/menu matching and vehicle filters still hide irrelevant options. A falsy canInteract result always hides the option, even when unavailable actions are shown, and is checked before group, item and disabled states. Failed canInteract/getState callbacks also hide their option and produce a throttled diagnostic.

getState(entity, distance, coords, name, bone) must be a fast, synchronous client callback. Return one of available, disabled, cooldown, missingItem, noPermission. Cooldowns belong to the integrating resource; FA Target only displays their state. Group/item checks are evaluated before this callback and cannot be bypassed by returning available.

local availableAt = 0
exports.fa_target:addLocalEntity(ped, {{
    name = 'inspect', label = 'Inspect vehicle', category = 'vehicle', hold = 1200,
    getState = function()
        local remaining = availableAt - GetGameTimer()
        return remaining > 0 and { status = 'cooldown', remainingMs = remaining }
            or { status = 'available' }
    end,
    onSelect = function(data)
        availableAt = GetGameTimer() + 5000
        -- The server receiving this request must independently validate the action.
        TriggerServerEvent('my_resource:inspect', data.entity)
    end,
}})

Theme settings and migration

Config.Interaction.allowPlayerModeSwitch defaults to false: the server owner chooses the gameplay mode and the editor's Focus/Cursor/World buttons are preview controls only. Enable it to expose Your gameplay mode in Behavior. It is saved per player in local KVP when Save theme succeeds; Cancel does not change the mode. The choice also works when player theme customization is disabled. Disabling the switch and restarting restores the configured mode and ignores saved player mode preferences. Explicit per-resource/per-option mode overrides remain in effect. Switching stops targeting, cancels holds, releases owned focus and clears old registrations from the current view before the new mode starts; resources do not need restarting.

The editor offers Precision, Minimal, Glass and Legacy. Existing compact saves normalize to minimal while keeping individual colors, radius and scale. Legacy retains the classic preset ID; mode IDs and compatibility exports are unchanged.

The Colors, Shape, Layout, Behavior and Accessibility sections share one live renderer with the game. Preview 1/3/6 options, long labels, unavailable states and a light or dark background. Add your game screenshot as web/public/preview/game.jpg, game.png or game.webp and rebuild to enable the screenshot background. It is a bundled preview asset, not a player screenshot upload.

Additional fields in Config.Theme.default and allowedPlayerFields:

Field	Range / values	Default
blur	0–20 px, Glass surface only	12
width	220–420 px; World and Minimal retain proportional widths	280
textSize	12–20 px	13
indicatorSize	10–24 px	13
indicatorStyle	ring, dot, crosshair	ring
cursorHint	always, first, never	first
highContrast	boolean	false
colorVision	normal, protanopia, deuteranopia, tritanopia	normal
fade	boolean; fades to 35% between expand/reveal distance	false
sound / soundVolume	boolean / 0–1	false / 0.25
categoryColors	up to 16 category identifiers mapped to HEX colors	{}

Explicit option.accent overrides a category color; otherwise the main accent is used. Accessibility display overrides do not rewrite the saved palette. Default runtime reason messages are localized. Custom reason strings come from the integrating resource.

Reset asks for confirmation and only changes editable fields. Export/import uses versioned JSON ({ version = 1, theme = ... } represented as JSON), capped at 64 KB. Imports are previews until Save. File download/upload and a copy/paste JSON panel are available; the latter also works when the embedded browser does not support file dialogs. No player identifiers are exported. The onboarding and first-use cursor hint are remembered locally per browser profile.

Glass uses CSS backdrop blur with a tinted surface as its contrast fallback. Browser rendering does not prove how FiveM composites it over the game; verify Glass on your running server. It does not invoke global screen-blur natives.

Async actions

For asynchronous interactions, return pending and resolve the action later with exports.fa_target:resolveAction(requestId, result).

Handler priority

FA Target preserves the following handler priority:

1. onSelect
2. export
3. client event
4. serverEvent
5. command

Security

Visibility and canInteract are client-side UX checks, not authorization. Server events must independently validate the player, entity, distance, permissions, inventory and all state-changing input. Never trust prices, rewards, item counts or entity ownership received from NUI/client code.

Development / Building from source

If you cloned the repository instead of downloading a release build, build the NUI before starting the resource:

cd web
npm install
npm run build

The production build is generated in web/dist.

Run npm run typecheck and npm test from web for theme validation, Lua migration/permission/selection tests, and Lua syntax checks. Tests use a Lua WASM runtime and stub engine calls; they do not replace FiveM testing.

Note

Release archives already include the compiled web/dist files.

Credits

FA Target is based on the MIT-licensed ox_target project.

See UPSTREAM.md for upstream attribution and information about modifications made by FA Scripts.

License

FA Target is released under the MIT License.