> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nexdevelopment.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Integrations

> How NEX HUD connects to your framework, fuel script, seatbelt, NOS, and postal resources — through adapters/ and the Bridge functions in integration.lua.

Two files wire the HUD into the rest of your server:

* `config.lua` → `Config.Framework` picks a **status adapter** from `adapters/` (hunger, thirst, stress, and the load/logout HUD toggle).
* `integration.lua` → the **`Bridge` functions** feed everything else: seatbelt state, fuel, NOS, the job / money pills, and the postal code.

Both are plain Lua you're meant to edit.

## Framework adapters

Set `Config.Framework` to pick where hunger / thirst / stress come from:

| Value      | Source                                                                                                                                                        |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `"qb"`     | Listens to the `hud:client:UpdateNeeds` and `hud:client:UpdateStress` events. Shows and hides the HUD on `QBCore:Client:OnPlayerLoaded` / `OnPlayerUnload`.   |
| `"esx"`    | Listens to `esx_status:onTick`. Shows and hides the HUD on `esx:playerLoaded` / `esx:onPlayerLogout`.                                                         |
| `"ox"`     | Listens to `ox:statusTick`. Shows and hides the HUD on `ox:playerLoaded` / `ox:playerLogout`.                                                                 |
| `"custom"` | A stub in `adapters/custom.lua` — replace `getPlayerHunger`, `getPlayerThirst`, `getPlayerStress`, and the connect / disconnect event handlers with your own. |
| `"none"`   | No adapter. Hunger, thirst, and stress are not shown; health, armor, oxygen, and stamina still work.                                                          |

## Bridge functions

`integration.lua` defines the `Bridge` functions below. Anything auto-detected checks `GetResourceState(...)`, so no config flag is needed — just start the resource.

### Bridge.getInfo — job, cash, bank, dirty money

Feeds the top-right info column. **QBCore and ESX are auto-detected**, independent of `Config.Framework`:

* QBCore: job label with grade name, `money.cash`, `money.bank`.
* ESX: job label with `grade_label`, plus the `money`, `bank`, and `black_money` accounts. Dirty money is only shown while it's above 0.

For any other framework, return your own snapshot:

```lua theme={null}
function Bridge.getInfo()
    return {
        job = 'Mechanic (Manager)', -- label shown in the job pill
        cash = 250,                 -- number
        bank = 12000,               -- number
        dirtyMoney = nil,           -- number, or nil to hide the pill
    }
end
```

<Info>
  `Bridge.getInfo` runs on every player tick (client-side, every 300 ms) — keep it cheap. Framework detection is cached, and errors in your code won't crash the HUD; it falls back to `Civilian` with zeroed money.
</Info>

### Bridge.getVehicleFuel — fuel level

Auto-detects, in order: `ps-fuel`, `cdn-fuel`, `LegacyFuel`, then `ox_fuel` (statebag). With none of those running it falls back to the native `GetVehicleFuelLevel`. Return a 0–100 number for anything else:

```lua theme={null}
function Bridge.getVehicleFuel(currentVehicle)
    return exports.my_fuel:GetFuel(currentVehicle)
end
```

### Bridge.getNosLevel — NOS

Returns `0` by default, which keeps the NOS bar empty. Wire your nitrous script here:

```lua theme={null}
function Bridge.getNosLevel(currentVehicle)
    return Entity(currentVehicle).state.nitro or 0 -- 0-100
end
```

### Bridge.isSeatbeltOn — external seatbelt

Only used when `Config.UseSeatbeltLogic = false`. Auto-detects `jim-mechanic`; otherwise it reads `LocalPlayer.state.isSeatbeltOn`. Adjust to match wherever your seatbelt script stores its state.

### Bridge.getPostal — postal code

Auto-detects [`nearest-postal`](https://github.com/DevBlocky/nearest-postal). Return a string to show it in the street card's area line, or `nil` to hide it:

```lua theme={null}
function Bridge.getPostal()
    return exports.my_postal:getCurrent()
end
```

## Voice level

The voice pill reads the standard `LocalPlayer.state.proximity` statebag (modes `Whisper`, `Normal`, `Shouting`) as set by pma-voice-style resources. No wiring needed.