> For the complete documentation index, see [llms.txt](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/integrations.md).

# Integrations & adapters

The HUD reads fuel, status (hunger/thirst/stress), voice and seatbelt through **adapters** in `adapters/` (not encrypted). At start the console prints which adapter was chosen for each kind.

## Built-in adapters

| Kind     | Adapter      | Detected when                      | Source                                                                                |
| -------- | ------------ | ---------------------------------- | ------------------------------------------------------------------------------------- |
| fuel     | `ox_fuel`    | `ox_fuel` started                  | Vehicle `fuel` statebag                                                               |
| fuel     | `LegacyFuel` | `LegacyFuel` started               | `exports['LegacyFuel']:GetFuel(vehicle)`                                              |
| fuel     | `cdn-fuel`   | `cdn-fuel` started                 | `exports['cdn-fuel']:GetFuel(vehicle)`                                                |
| fuel     | `native`     | always (last fallback)             | GTA fuel level / tank capacity                                                        |
| status   | `esx_status` | `esx_status` started               | `esx_status:onTick` (hunger, thirst; stress if a third-party script adds it)          |
| status   | `qb`         | framework is QBCore or Qbox        | Player metadata + `hud:client:UpdateNeeds` / `hud:client:UpdateStress`                |
| status   | `exports`    | first `setStatus` call, or forced  | `exports.ghiaccio_hud:setStatus`                                                      |
| voice    | `pma-voice`  | `pma-voice` started                | Proximity statebag, radio channel, talking (default ranges 3 / 8 / 15 m)              |
| voice    | `saltychat`  | `saltychat` started                | `GetVoiceRange`, `GetRadioChannel`; range mapped to 3 levels (<= 4 m, <= 10 m, above) |
| seatbelt | `external`   | a known seatbelt script is running | Events / statebag (see below)                                                         |
| seatbelt | `builtin`    | no external script                 | The HUD's own seatbelt (`Config.Seatbelt`)                                            |

With `'auto'` the adapters are tried in manifest order and the first detected one is used. Force one with `Config.Integrations.<kind> = '<name>'` or disable a kind with `false`.

## Hunger, thirst and stress from any script

### (a) Automatic

On ESX the `esx_status` adapter reads hunger/thirst. On QBCore/Qbox the player metadata (`hunger`, `thirst`, `stress`) and the `hud:client:UpdateNeeds` / `hud:client:UpdateStress` events are read. Nothing to configure (`Config.Integrations.status = 'auto'`).

### (b) `setStatus` / `getStatus` exports

For a metabolism or any other script that manages hunger/thirst/stress. On the **client**:

```lua
-- name: 'hunger' | 'thirst' | 'stress'; value: number 0..100 (out of range is clamped; non-number types are rejected: returns false)
CreateThread(function()
    while true do
        Wait(5000)
        exports.ghiaccio_hud:setStatus('hunger', myHunger)   -- e.g. from your metabolism
        exports.ghiaccio_hud:setStatus('thirst', myThirst)
    end
end)
RegisterNetEvent('my_metabolism:update', function(h, t) exports.ghiaccio_hud:setStatus('hunger', h); exports.ghiaccio_hud:setStatus('thirst', t) end)
local hunger = exports.ghiaccio_hud:getStatus('hunger')     -- value shown by the HUD, or nil
```

* It turns itself on at the **first call** of `setStatus` (or right away with `Config.Integrations.status = 'exports'`, in which case hunger/thirst stay hidden until some script sets them).
* **Precedence:** if another adapter (`esx_status`, `qb`) is active and `setStatus` calls arrive, the **export values win**; entries never set through the export keep coming from the other adapter.
* With `Config.Integrations.status = false` the export is disabled (`setStatus` returns `false`).
* `setStatus('stress', v)` stays consistent with `setStress` / `addStress`: with the built-in stress (`Config.Stress.enabled`) it updates that one (with decay and saving), otherwise the value lives in the adapter.

### (c) Writing your own adapter

Create a file in `adapters/status/` (copy `esx_status.lua`). Example for a metabolism that fires the client event `my_metabolism:tick (hunger, thirst)`:

```lua
-- adapters/status/my_metabolism.lua
local cache = {}
GHUD.Adapters.register('status', 'my_metabolism', {
    resource = 'my_metabolism',                                  -- detected automatically when the resource is started (or: detect = function() return ... end)
    provides = { hunger = true, thirst = true, stress = false }, -- what it provides: the rest stays hidden
    start = function()                                           -- called once at startup
        AddEventHandler('my_metabolism:tick', function(hunger, thirst)
            if type(hunger) == 'number' then cache.hunger = hunger end
            if type(thirst) == 'number' then cache.thirst = thirst end
            GHUD.Adapters.changed('status')                      -- the HUD rereads and sends the diff to the NUI
        end)
    end,
    read = function() return cache.hunger, cache.thirst, nil end, -- hunger, thirst, stress (0..100, nil = not provided)
})
```

Then add `'adapters/status/my_metabolism.lua',` to `fxmanifest.lua` (in `client_scripts`, after `adapters/status/qb.lua`) and, to force it, set `Config.Integrations.status = 'my_metabolism'`.

### (d) No source

If hunger/thirst have no source (no adapter, no `setStatus` call) the icons are **hidden** (never fake values) and the other icons of the group close the gap.

## Adapter format (all kinds)

Each adapter is a file `adapters/<kind>/<name>.lua` that calls `GHUD.Adapters.register(kind, name, def)`. Common fields: `resource` (auto-detected when started), `detect` (custom function), `start` (register events). Per kind:

| Kind       | Required functions                                                                                                                                |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `fuel`     | `get(veh)` returns 0..100 or nil                                                                                                                  |
| `status`   | `read()` returns hunger, thirst, stress (nil = not provided); `provides = { hunger, thirst, stress }`; `manual = true` = never picked by `'auto'` |
| `voice`    | `read()` returns `{ range, rangeMeters, talking, radio, radioTalking }`                                                                           |
| `seatbelt` | `get()`, `set(bool)`, `toggle()`, `onEnter(veh)`, `onExit()`, `tick(veh, speedKmh)`, `controllable`                                               |

Event-driven adapters call `GHUD.Adapters.changed(kind)` when new data arrives. Remember to list every new adapter file in `fxmanifest.lua`.

{% tabs %}
{% tab title="Fuel adapter example" %}

```lua
-- adapters/fuel/my_fuel.lua
GHUD.Adapters.register('fuel', 'my_fuel', {
    resource = 'my_fuel',
    get = function(veh)
        local ok, v = pcall(function() return exports['my_fuel']:GetFuel(veh) end)
        if ok and type(v) == 'number' then return v end
        return nil
    end,
})
```

Add it to `fxmanifest.lua` **before** `adapters/fuel/native.lua` (the native fallback is always detected, and `'auto'` uses the first match).
{% endtab %}
{% endtabs %}

## Seatbelt scripts

With `Config.Integrations.seatbelt = 'auto'` the `external` adapter is used if one of these is running: `qb-smallresources`, `qbx_seatbelt`, `qbx_smallresources`, `esx_seatbelt`, `seatbelt`, `vms_seatbelt`, `wasabi_seatbelt`. Otherwise the built-in seatbelt is used.

The external state comes from:

1. the local event `ghiaccio_hud:client:seatbelt (bool)`, which any script can emit;
2. the `seatbelt:client:ToggleSeatbelt` event (qb-smallresources and clones: no argument toggles, a bool sets it);
3. the `LocalPlayer.state.seatbelt` statebag, if the script sets it.

```lua
-- from your seatbelt script (client)
TriggerEvent('ghiaccio_hud:client:seatbelt', true)
```

To support another resource name, add it to the `KNOWN` list in `adapters/seatbelt/external.lua`.

## Exports

### Client

```lua
exports.ghiaccio_hud:toggleHud(true)          -- show/hide (no argument: toggle)
exports.ghiaccio_hud:isHudVisible()
exports.ghiaccio_hud:openEditor() / closeEditor()
exports.ghiaccio_hud:setStress(v) / addStress(d) / removeStress(d) / getStress()   -- built-in stress
exports.ghiaccio_hud:setStatus('hunger'|'thirst'|'stress', 0..100) / getStatus(name)  -- from any script (see above)
exports.ghiaccio_hud:setCinematic(bool) / isCinematic()
exports.ghiaccio_hud:setStreamerMode(bool)
exports.ghiaccio_hud:setSeatbelt(bool) / isSeatbeltOn()
exports.ghiaccio_hud:hideWidget('cash', true)  -- registry id
exports.ghiaccio_hud:getLayout()
```

Widget ids for `hideWidget`: `logo`, `playerId`, `clock`, `health`, `armor`, `hunger`, `thirst`, `stamina`, `oxygen`, `stress`, `voice`, `cash`, `bank`, `weapon`, `speedo`, `rpm`, `gear`, `fuel`, `engine`, `seatbelt`, `lights`, `cruise`, `limiter`, `compass`, `street`, `zone`.

### Server

```lua
exports.ghiaccio_hud:setStress(src, v)         -- 0..100; QBCore/Qbox: metadata, otherwise the client's built-in stress
exports.ghiaccio_hud:addStress(src, delta)
exports.ghiaccio_hud:getServerDefault()        -- JSON | false
exports.ghiaccio_hud:publishDefault(jsonString) -- no ACE (console/other resources)
```

## Local client events

| Event                            | Direction          | Payload                                    |
| -------------------------------- | ------------------ | ------------------------------------------ |
| `ghiaccio_hud:client:visibility` | emitted by the HUD | `visible` (bool)                           |
| `ghiaccio_hud:client:toggle`     | listened           | `visible` (bool), same as `toggleHud`      |
| `ghiaccio_hud:client:seatbelt`   | listened           | `on` (bool), for external seatbelt scripts |

## Framework bridge

`bridge/` (not encrypted) contains one client and one server file per framework (`esx`, `qbcore`, `qbox`, `standalone`) and `bridge/init.lua` (detection). It provides player loaded/unloaded, cash and bank, hunger/thirst/stress, death state, license, admin check and stress. Adapt it if your framework is customised.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://ghiaccioscripts.gitbook.io/ghiaccioscripts-docs/hud/integrations.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
