Installation

This page covers what nx_hud needs beyond the generic installation guide. Because nx_hud takes the place of ox_lib, ox_inventory and ox_target, installing it means removing those three. Read the whole page before you start.

Requirements

• FXServer artifact 7290 or newer, with OneSync on.
• For the inventory: ESX or Qbox. The HUD, the ox_lib layer and targeting also work on QBCore or with no framework.

ox_lib, ox_inventory, ox_target, qtarget and qb-target come off the server. The steps below show how.

What it replaces

Scripts that use @ox_lib/init.lua, exports.ox_inventory, exports.ox_target, exports.qtarget or exports['qb-target'], or list those resources as a dependency, find nx_hud in their place. The APIs are documented by Overextended: ox_lib, ox_inventory and ox_target.

Install

1. Back up your database: the ox_inventory table and your framework's player and vehicle tables.
2. Put the nx_hud folder in your resources folder.
3. In your server config, put ensure nx_hud where ensure ox_lib was, before your framework. Delete the ensure ox_lib, ensure ox_inventory, ensure ox_target, ensure qtarget and ensure qb-target lines.
4. Move the ox_lib, ox_target, qtarget and qb-target folders out of resources, including copies inside [category] folders. Leave the ox_inventory folder where it is for now: the next steps read your data from it.
5. If your config grants ACE permissions to resource.ox_lib, grant the same ones to resource.nx_hud.
6. Restart the whole server, with nobody connected. The console says the inventory is off because a folder named ox_inventory is still installed. That is expected at this step.
7. In the server console, run nxinv migrate check from=<full path to your ox_inventory folder>. It should end with PREFLIGHT: GO.
8. Run nxinv migrate apply from=<the same path>. It copies your items, shops, stashes, crafting and other data into nx_hud/data/, and the images your items use into nx_hud/web/images/. It should end with validated.
9. Move the ox_inventory folder out of resources and keep it as a backup. Your inventory:* convars keep working.
10. Restart the whole server.

# server.cfg: the start of the list
ensure oxmysql
ensure nx_hud        # where ensure ox_lib was

# your framework core (es_extended or qbx_core) and the rest go here

For step 5: Qbox's permissions.cfg usually grants these four to resource.ox_lib. Grant them to nx_hud instead:

add_ace resource.nx_hud command.add_ace allow
add_ace resource.nx_hud command.remove_ace allow
add_ace resource.nx_hud command.add_principal allow
add_ace resource.nx_hud command.remove_principal allow

A server that never ran ox_inventory

Skip steps 7 to 9. data/ ships with a starter set: a few items and weapons, four shops (a corner store, Ammu-Nation, a police armoury and a vending machine), one crafting bench and a weapon licence. Replace them with your own (see Customization).

Item images

web/images/ ships empty. nxinv migrate apply fills it with the images your items use. To add one yourself, put a PNG named after the item in nx_hud/web/images/, for example water.png.

nx_hud points the inventory:imagepath convar at its own image folder, so scripts that build image links from that convar find the pictures.

The migrate tool copies only the images your items reference, so the resource stays under the number of files a client can download on connect. NxInventory.fileBudget sets that limit, and the all and force options of nxinv migrate apply override it. See Commands.

Targeting

• Scripts written for ox_target, qtarget or qb-target need no changes. The target key is Left Alt, as in ox_target, and the ox_target:* convars still work.
• If a folder named ox_target, qtarget or qb-target is still in resources, nx_hud turns targeting off and says so in the console. The same happens when another resource declares provide for one of those names. Move the folder out and restart the server.
• Settings are in config/target.lua, including whether idle target dots show (dots.enabled). Each player picks only the look in F7: Tether (the default) or Bloom.

First configuration

Check these before the first start:

• config/hud.lua: Config.framework, Config.fuel and Config.seatbelt detect your scripts on 'auto'. Name one if detection picks the wrong script.
• config/compat.lua: radialKey is G by default.
• config/settings.lua: the F7 settings every player starts with, such as km/h instead of mph or a lighter glass. Players can still change their own.
• inventory:framework: nx_hud sets it when it is empty, from the framework it finds (qbx_core, then es_extended). Set it yourself in server.cfg if you run both.

Everything under config/, data/ and the locale folders is plain text in the release. See Customization for the full list of files you can edit.

Troubleshooting

Credits

The target menu icons are from Font Awesome Free 6.7.2 by Fonticons, Inc. (fontawesome.com), licensed under CC BY 4.0.