Exports

nx_hud answers for ox_lib, ox_inventory and ox_target, so the existing APIs of those resources work as documented by Overextended: ox_lib, ox_inventory and ox_target. Keep calling them by their usual names, for example exports.ox_inventory:AddItem(...).

This page documents what nx_hud adds. These exports live under nx_hud's own name: call them as exports.nx_hud:fn(...), never through exports.ox_inventory or exports.ox_lib.

A few rules apply to all of them:

• Every registration (a hide, a status override, a reader, a gate, an item effect, a payment method, a resolver, a price modifier, a search check, a crafting bench, a combine recipe) belongs to the resource that made it, and is released when that resource stops.
• The functions you pass run inside a protected call. An error is logged to the console and the safe default applies, so a broken callback does not take the HUD or the inventory down with it.
• None of these exports yields, except showItem, which waits for the server's answer. Your callbacks should not yield either.

HUD (client)

Visibility

Hiding the HUD removes the gauges, the street line, the vehicle cluster, the radar, the windscreen HUD and the hotbar, and the hotbar keys rest. Notifications, progress bars, menus, dialogs, the radial menu, targeting and the inventory keep working. The island moves down into the radar's place and appears only when one of them needs it. Each resource holds its own hide, so the HUD shows again only when no resource hides it. The pause menu also hides the HUD while it is open.

exports.nx_hud:hideHud()   -- for a cutscene
-- later
exports.nx_hud:showHud()

exports.nx_hud:setHudVisible(not inCamera)

Strict hide

The strict hide removes everything nx_hud draws except what the player must answer: the HUD, the island, notifications, progress bars and the inventory go, and the inventory cannot be opened. Use it for a death screen, a camera viewfinder or a cutscene. Notifications sent meanwhile wait and show in order once the last reason ends (an identical one once, at most 20). Progress bars keep running unseen. A dialog, context or list menu, radial menu, skill check, text prompt or the target (while the player aims) is shown on its own, so a death screen's prompt and its confirm dialog keep working. isHudVisible still answers the normal hide only.

nx_hud also strict-hides itself while the player is dead or in last stand (Config.strictHide in config/hud.lua).

exports.nx_hud:SetStrictHidden('deathscreen', true)
-- later
exports.nx_hud:SetStrictHidden('deathscreen', false)

Seatbelt

if not exports.nx_hud:isSeatbeltOn() then
    -- apply your own crash damage
end

exports.nx_hud:registerSeatbeltReader(function()
    return beltOn
end)

Status and money

Values cross this API in 0 to 100, as frameworks use them.

exports.nx_hud:setStatus('stress', 45)
-- give the gauge back to the framework
exports.nx_hud:setStatus('stress', nil)

exports.nx_hud:moneyPop('crypto', -250, 1750)

Fuel

exports.nx_hud:registerFuelReader(function(vehicle)
    return exports.my_fuel:GetFuel(vehicle)
end)

Weapon pill

The weapon pill shows the rounds in the magazine and the spare rounds after the slash. A weapon that a script gives infinite ammo shows its name instead of a number. A script that keeps its own count, such as a taser's cartridges or a battery, can show that count with a reader.

exports.nx_hud:registerAmmoReader('WEAPON_STUNGUN', function(ped, weapon)
    return cartridgesLoaded, 2, cartridgesInPocket
end)

Damage

exports.nx_hud:pushHit(GetEntityCoords(attackerPed))

Player settings

Each player's F7 settings are saved on their own PC. The server sets the defaults they start with in config/settings.lua (see Configuration). These exports read the settings in force for a player, under the names config/settings.lua uses: vehicle, face, glass, units, radar, radarZoom, zoomMode, prompts, radial, sounds, volume, inventory and targeting. Newer F7 rows can appear under their own names.

changed lists what the player set themselves, as { [name] = true }. Every other setting is the server's default.

local settings, changed = exports.nx_hud:getSettings()
if settings and settings.units == 'kmh' then
    -- show your own speeds in km/h
end

local settings, err = exports.nx_hud:getSettings(source)
if not settings then
    print(('settings not available: %s'):format(err))
elseif settings.glass == 'off' then
    -- this player runs the lightest glass
end

Inventory (client)

The defaults these sit on are in inventory/custom/client.lua, which you can edit directly. See Customization.

local gate = exports.nx_hud:addOpenGate(function(ctx)
    if ctx.invType == 'trunk' and LocalPlayer.state.isCuffed then
        return false, 'Not with your hands cuffed'
    end
end)

exports.nx_hud:addUseGate(function(item)
    if item.name == 'lockpick' and IsPedInAnyVehicle(PlayerPedId(), false) then
        return false, 'Get out of the vehicle first'
    end
end)

exports.nx_hud:registerItemEffect('bandage', function(itemDef, item, slot)
    exports.ox_inventory:useItem(itemDef, function(data)
        if data then TriggerEvent('my_medical:bandaged') end
    end)
end)

exports.nx_hud:setStealCheck(function(ped, serverId)
    if LocalPlayer.state.isTiedUp then return true end
end)

CreateThread(function()
    local res = exports.nx_hud:showItem(slot)
    if res.viewers then print(('shown to %d players'):format(res.viewers)) end
end)

local carrying, item = exports.nx_hud:isCarrying()
if carrying then
    return false, ('Put the %s down first'):format(item)
end

Inventory (server)

Payments

A shop item's currency, a shop's payment field, or a licence's currency names what a purchase is paid with: an item ('money', 'black_money', any item) or a payment method. A shop's payment can also be a list, and the player picks from it in the shop. Shops without one use payments.choices in config/inventory.lua. With nothing set anywhere, the player pays with the money item, as in ox_inventory. Two methods ship in inventory/custom/server.lua:

• 'bank': paying by card from the player's bank account (ESX account, Qbox money type).
• 'society:<name>', for example 'society:police': that society's account, for members of that job only. ESX reads esx_addonaccount's society_<name>. Qbox reads Renewed-Banking.

How a purchase is charged:

1. canAfford is checked before the buyItem hook and again after it.
2. An item currency is taken right after the goods are placed, as ox_inventory does.
3. Any other method is charged before the goods are placed, and refunded with refund if they cannot be placed. A refused charge rolls the stock back and hands out nothing.

Every method function receives (src, amount, ctx), where ctx is a fresh copy for each call:

exports.nx_hud:registerPaymentMethod('tokens', {
    label = 'Casino tokens',
    prefix = '', suffix = ' tokens',
    balance = function(src) return exports.my_casino:getTokens(src) end,
    canAfford = function(src, amount) return exports.my_casino:getTokens(src) >= amount end,
    charge = function(src, amount, ctx) return exports.my_casino:takeTokens(src, amount, ctx.reason) end,
    refund = function(src, amount, ctx) return exports.my_casino:giveTokens(src, amount, ctx.reason) end,
})

-- data/shops.lua: a shop item paid with it
{ name = 'scratchcard', price = 5, currency = 'tokens' },
-- or a shop where the player picks cash, card or tokens
payment = { 'money', 'bank', 'tokens' },

-- cash first, the bank when the cash is short
exports.nx_hud:setPaymentResolver(function(src, ctx)
    if ctx.currency == 'money' and exports.ox_inventory:GetItemCount(src, 'money') < ctx.total then
        return 'bank'
    end
end)

Prices

-- 10 % off for players with the vip state
exports.nx_hud:setShopPriceModifier(function(src, ctx)
    if Player(src).state.vip then return ctx.price * 0.9 end
end)

-- half price on the hunting licence for players with the veteran state
exports.nx_hud:setLicencePriceModifier(function(src, ctx)
    if ctx.license == 'hunting' and Player(src).state.veteran then
        return ctx.price * 0.5
    end
end)

Searching players

local ZipTied = {}   -- [serverId] = true, set by your zip-tie item on the server

exports.nx_hud:setSearchCheck(function(src, target)
    if Player(target).state.inSafeZone then return false end
    if ZipTied[target] then return true end
end)

Carrying

local carry = exports.nx_hud:getCarry(source)
if carry and carry.vehicle == false then
    return false, 'You cannot drive while carrying that'
end

Worn gear

A bag, a vest, a watch or a bracelet the player wears sits in its own gear slot, next to the pockets, and no longer takes a pocket slot. It still belongs to the player's inventory:

• It counts towards the player's weight and is saved with them.
• Search, GetItemCount, GetSlotWithItem, HasItem and the other ox_inventory exports find it. RemoveItem takes it like any other item.
• Taking it off needs a free pocket slot. With the pockets full it stays on, and the player is told why.
• A player who searches or robs another sees the other player's worn items in a strip on their side, and can drag one into their own pockets.
• An item that leaves the player's inventory, by a give, a drop, a stash or a search, is no longer worn.

Which items can be worn, and on which socket, is set on the item in data/items.lua (see Wearable items). The sockets are in NxInventory.accessories (see Configuration). When the worn gear changes, the server raises nx_hud:wornChanged.

Client

local worn = exports.nx_hud:getWornAccessories()
if worn.watch then
    print(('wearing %s on the left wrist'):format(worn.watch.label))
end

Server

local worn = exports.nx_hud:getWornAccessories(source)
for socket, item in pairs(worn) do
    print(socket, item.name, item.slot)
end
-- watch    watch_classic    51
-- back     backpack         52

-- put a bracelet on whichever wrist is free
local ok, err = exports.nx_hud:setWorn(source, slot, true)
if not ok then print('could not put it on: ' .. err) end

-- take the watch off
local worn = exports.nx_hud:getWorn(source)
if worn.watch then exports.nx_hud:setWorn(source, worn.watch, false) end

local bag = exports.nx_hud:getWornBag(source)
if bag then
    print(('%s: %d of %d g'):format(bag.name, bag.weight, bag.maxWeight))
end

local vest = exports.nx_hud:getPlates(source)
if vest then
    for i, plate in ipairs(vest.plates) do
        print(i, plate and ('%s %d/%d'):format(plate.name, plate.hp, plate.max) or 'empty')
    end
end

Crafting (server)

exports.nx_hud:registerCraftingBench('gang_bench', {
    label = 'Workbench',
    groups = { ballas = 0 },
    zones = { { coords = vec3(-1.6, -1812.9, 29.1), size = vec3(1.6, 0.8, 1.2), rotation = 50.0, distance = 1.8 } },
    points = { vec3(-1.6, -1812.9, 29.1) },
    items = {
        { name = 'lockpick', ingredients = { metal_scrap = 2 }, duration = 4000, chance = 0.8, failResult = 'keep' },
    },
})

Recipe fields

A recipe in data/crafting.lua, or in a bench you register, takes these fields on top of ox_inventory's. A recipe without them crafts as before.

What players see at the bench:

• Chance. A recipe with a chance below 1 shows it next to the craft time, for example "72% chance". The recipe's details also say whether a miss uses the parts. Set hideChance = true to leave it out.
• Requirements. A recipe the player can't make yet is greyed out and says why: "Needs the mechanic job", "Needs the police job, grade 2", "Needs a licence: weapon" or "Needs a wrench". Each tool in requires.items shows next to the ingredients, and it turns ready as soon as the player picks one up. If a player tries anyway, the notice names the missing piece.
• Failed rolls. The craft queue shows how each craft ended. A failed roll reads "Failed, parts used" (failResult = 'consume') or "Failed, nothing used" ('keep'), and the player gets a notice that says the same.

{
    name = 'WEAPON_PISTOL',
    ingredients = { gun_parts = 4, metal_scrap = 10 },
    duration = 12000,
    chance = 0.6,
    requires = { license = 'weapon', items = { gun_toolkit = 1 } },
    resultMetadata = { registered = false },
},

Combine recipes

A player drags one item onto another in their own pockets. When a recipe names that pair, a short progress bar runs and the two become something else. The recipes that ship are in NxInventory.combine in config/inventory.lua (see Configuration).

The craftResult hook runs for combines too, with payload.combine set to the recipe id and no benchId.

exports.nx_hud:registerCombine('my_pipebomb', {
    items = { 'pipe', 'gunpowder' },
    consume = { pipe = 1, gunpowder = 2 },
    result = { { 'pipebomb', 1 } },
    duration = 4000,
    chance = 0.9,
    requires = { items = { screwdriver = 1 } },
})

Hook events

nx_hud adds five events to ox_inventory's registerHook, and extends two of ox's own (openInventory and buyItem). Register them with exports.ox_inventory:registerHook, the same way as ox's own events.

shopPrice

Asked for each shop slot when a shop opens, and again at the purchase. Return a number of 0 or more to replace the price. It runs after the price modifiers, and each hook sees the price the hooks before it set. It is a query, so it fires no post-hook events.

Payload: source, shopType, shopId, itemName, count, price, basePrice, currency, inventoryId, purpose ('open' or 'buy').

exports.ox_inventory:registerHook('shopPrice', function(payload)
    if payload.shopType == 'ammunation' and isHappyHour() then
        return payload.price * 0.5
    end
end)

licencePrice

Asked when a player is shown a licence's price, and again at the purchase. Return a number of 0 or more to replace the price. It runs after the licence price modifiers, and each hook sees the price the hooks before it set. It is a query, so it fires no post-hook events.

Payload: source, licenseName, licenseIndex, price, basePrice, currency, purpose ('quote' or 'buy').

exports.ox_inventory:registerHook('licencePrice', function(payload)
    if payload.licenseName == 'fishing' and isFishingWeek() then
        return 0
    end
end)

buyLicense

Fires before a licence is bought, and before the framework checks whether the player already has it. Return false to refuse. The player is told they can't buy the licence right now.

Payload: source, licenseName, licenseIndex, price (after the licence price modifiers and licencePrice hooks), basePrice (the price in data/licenses.lua), currency.

exports.ox_inventory:registerHook('buyLicense', function(payload)
    if payload.licenseName == 'weapon' and hasRecord(payload.source) then
        return false
    end
end)

craftResult

Fires after the progress bar and the chance roll, before anything is taken. Return false to cancel the craft: nothing is used up and nothing is made. Return a table to replace the result's metadata.

Payload: source, benchId, benchIndex, recipe, toInventory, toSlot, success (the roll), count, metadata. For a combine, combine is the recipe id and benchId is nil.

exports.ox_inventory:registerHook('craftResult', function(payload)
    if payload.success then
        local meta = payload.metadata or {}
        meta.crafter = GetPlayerName(payload.source)
        return meta
    end
end)

openLockedVehicle

Asked when a player opens the trunk of a locked vehicle, so a vehicle keys script can let them in: with a crowbar, as on-duty police, or for the key holder. Return true to open it. Return false to refuse, with an optional text as the second value that the player sees instead of the usual "locked" notice, or false, false to show nothing (your script told the player itself). Any other answer, and no hook at all, keeps the trunk locked.

Only an explicit true opens it. A hook on openInventory that allows every open does not unlock cars. After a true, the openInventory hooks still run, with locked = true in their payload.

Payload: source, inventoryId, inventoryType ('trunk'), netId, plate, lockStatus (the game's door lock status). registerHook's filters, such as inventoryFilter, apply.

exports.ox_inventory:registerHook('openLockedVehicle', function(payload)
    if exports.my_keys:hasKey(payload.source, payload.plate) then
        return true
    end
    if Player(payload.source).state.crowbar then
        return true
    end
    return false, 'You need the keys or a crowbar'
end)

openInventory

ox_inventory's openInventory hook can say why it refuses. Return false, 'text' and the player sees that text (or its translation, when it is a key from inventory/locales/) instead of the usual "cannot open" notice. Return false, false to show nothing. A plain false shows the usual notice, as in ox_inventory. The payload gains locked = true for a locked trunk that an openLockedVehicle hook opened.

exports.ox_inventory:registerHook('openInventory', function(payload)
    if payload.inventoryType == 'stash' and isRaidActive() then
        return false, 'The stash is sealed during a raid'
    end
end)

buyItem

ox_inventory's buyItem payload gains a payment field: the payment method's name when the purchase is paid with a method, and nil when it is paid with an item.