> 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/it/hud/integrations.md).

# Integrazioni e adapter

L'HUD legge carburante, status (fame/sete/stress), voce e cintura tramite **adapter** in `adapters/` (non cifrati). All'avvio la console indica quale adapter è stato scelto per ogni tipo.

## Adapter inclusi

| Tipo     | Adapter      | Rilevato quando                         | Fonte                                                                                   |
| -------- | ------------ | --------------------------------------- | --------------------------------------------------------------------------------------- |
| fuel     | `ox_fuel`    | `ox_fuel` avviato                       | Statebag `fuel` del veicolo                                                             |
| fuel     | `LegacyFuel` | `LegacyFuel` avviato                    | `exports['LegacyFuel']:GetFuel(vehicle)`                                                |
| fuel     | `cdn-fuel`   | `cdn-fuel` avviato                      | `exports['cdn-fuel']:GetFuel(vehicle)`                                                  |
| fuel     | `native`     | sempre (ultimo fallback)                | Livello carburante di GTA / capacità del serbatoio                                      |
| status   | `esx_status` | `esx_status` avviato                    | `esx_status:onTick` (fame, sete; stress se uno script di terze parti lo aggiunge)       |
| status   | `qb`         | framework QBCore o Qbox                 | Metadata del giocatore + `hud:client:UpdateNeeds` / `hud:client:UpdateStress`           |
| status   | `exports`    | prima chiamata a `setStatus`, o forzato | `exports.ghiaccio_hud:setStatus`                                                        |
| voice    | `pma-voice`  | `pma-voice` avviato                     | Statebag di prossimità, canale radio, parlato (range di default 3 / 8 / 15 m)           |
| voice    | `saltychat`  | `saltychat` avviato                     | `GetVoiceRange`, `GetRadioChannel`; range mappato su 3 livelli (<= 4 m, <= 10 m, oltre) |
| seatbelt | `external`   | è avviato uno script cintura noto       | Eventi / statebag (vedi sotto)                                                          |
| seatbelt | `builtin`    | nessuno script esterno                  | La cintura integrata dell'HUD (`Config.Seatbelt`)                                       |

Con `'auto'` gli adapter vengono provati in ordine di manifest e si usa il primo rilevato. Forzane uno con `Config.Integrations.<tipo> = '<nome>'` o disattiva un tipo con `false`.

## Fame, sete e stress da qualunque script

### (a) Automatico

Su ESX l'adapter `esx_status` legge fame/sete. Su QBCore/Qbox vengono letti i metadata del giocatore (`hunger`, `thirst`, `stress`) e gli eventi `hud:client:UpdateNeeds` / `hud:client:UpdateStress`. Nulla da configurare (`Config.Integrations.status = 'auto'`).

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

Per un metabolismo o qualunque altro script che gestisce fame/sete/stress. Sul **client**:

```lua
-- name: 'hunger' | 'thirst' | 'stress'; value: numero 0..100 (fuori range viene limitato; tipi non numerici rifiutati: ritorna false)
CreateThread(function()
    while true do
        Wait(5000)
        exports.ghiaccio_hud:setStatus('hunger', myHunger)   -- es. dal tuo metabolismo
        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')     -- valore mostrato dall'HUD, oppure nil
```

* Si attiva da solo alla **prima chiamata** di `setStatus` (o subito con `Config.Integrations.status = 'exports'`, nel qual caso fame/sete restano nascoste finché uno script non le imposta).
* **Precedenza:** se un altro adapter (`esx_status`, `qb`) è attivo e arrivano chiamate a `setStatus`, **vincono i valori dell'export**; le voci mai impostate tramite export continuano ad arrivare dall'altro adapter.
* Con `Config.Integrations.status = false` l'export è disattivato (`setStatus` ritorna `false`).
* `setStatus('stress', v)` resta coerente con `setStress` / `addStress`: con lo stress integrato (`Config.Stress.enabled`) aggiorna quello (con decadimento e salvataggio), altrimenti il valore vive nell'adapter.

### (c) Scrivere un proprio adapter

Crea un file in `adapters/status/` (copia `esx_status.lua`). Esempio per un metabolismo che emette l'evento client `my_metabolism:tick (hunger, thirst)`:

```lua
-- adapters/status/my_metabolism.lua
local cache = {}
GHUD.Adapters.register('status', 'my_metabolism', {
    resource = 'my_metabolism',                                  -- rilevato in automatico quando la risorsa e' avviata (oppure: detect = function() return ... end)
    provides = { hunger = true, thirst = true, stress = false }, -- cosa fornisce: il resto resta nascosto
    start = function()                                           -- chiamata una volta all'avvio
        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')                      -- l'HUD rilegge e invia la differenza alla NUI
        end)
    end,
    read = function() return cache.hunger, cache.thirst, nil end, -- fame, sete, stress (0..100, nil = non fornito)
})
```

Poi aggiungi `'adapters/status/my_metabolism.lua',` in `fxmanifest.lua` (in `client_scripts`, dopo `adapters/status/qb.lua`) e, per forzarlo, imposta `Config.Integrations.status = 'my_metabolism'`.

### (d) Nessuna fonte

Se fame/sete non hanno una fonte (nessun adapter, nessuna chiamata a `setStatus`) le icone sono **nascoste** (mai valori finti) e le altre icone del gruppo chiudono il buco.

## Formato degli adapter (tutti i tipi)

Ogni adapter è un file `adapters/<tipo>/<nome>.lua` che chiama `GHUD.Adapters.register(tipo, nome, def)`. Campi comuni: `resource` (rilevato quando è avviata), `detect` (funzione personalizzata), `start` (registra gli eventi). Per tipo:

| Tipo       | Funzioni richieste                                                                                                                         |
| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `fuel`     | `get(veh)` ritorna 0..100 o nil                                                                                                            |
| `status`   | `read()` ritorna fame, sete, stress (nil = non fornito); `provides = { hunger, thirst, stress }`; `manual = true` = mai scelto da `'auto'` |
| `voice`    | `read()` ritorna `{ range, rangeMeters, talking, radio, radioTalking }`                                                                    |
| `seatbelt` | `get()`, `set(bool)`, `toggle()`, `onEnter(veh)`, `onExit()`, `tick(veh, speedKmh)`, `controllable`                                        |

Gli adapter a eventi chiamano `GHUD.Adapters.changed(tipo)` quando arrivano dati nuovi. Ricorda di elencare ogni nuovo file adapter in `fxmanifest.lua`.

{% tabs %}
{% tab title="Esempio adapter carburante" %}

```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,
})
```

Aggiungilo in `fxmanifest.lua` **prima** di `adapters/fuel/native.lua` (il fallback nativo è sempre rilevato e `'auto'` usa il primo che corrisponde).
{% endtab %}
{% endtabs %}

## Script cintura

Con `Config.Integrations.seatbelt = 'auto'` viene usato l'adapter `external` se è avviato uno di questi: `qb-smallresources`, `qbx_seatbelt`, `qbx_smallresources`, `esx_seatbelt`, `seatbelt`, `vms_seatbelt`, `wasabi_seatbelt`. Altrimenti si usa la cintura integrata.

Lo stato esterno arriva da:

1. l'evento locale `ghiaccio_hud:client:seatbelt (bool)`, che qualunque script può emettere;
2. l'evento `seatbelt:client:ToggleSeatbelt` (qb-smallresources e cloni: senza argomento inverte, con un bool lo imposta);
3. lo statebag `LocalPlayer.state.seatbelt`, se lo script lo imposta.

```lua
-- dal tuo script cintura (client)
TriggerEvent('ghiaccio_hud:client:seatbelt', true)
```

Per supportare un altro nome di risorsa aggiungilo alla lista `KNOWN` in `adapters/seatbelt/external.lua`.

## Export

### Client

```lua
exports.ghiaccio_hud:toggleHud(true)          -- mostra/nascondi (senza argomento: inverte)
exports.ghiaccio_hud:isHudVisible()
exports.ghiaccio_hud:openEditor() / closeEditor()
exports.ghiaccio_hud:setStress(v) / addStress(d) / removeStress(d) / getStress()   -- stress integrato
exports.ghiaccio_hud:setStatus('hunger'|'thirst'|'stress', 0..100) / getStatus(name)  -- da qualunque script (vedi sopra)
exports.ghiaccio_hud:setCinematic(bool) / isCinematic()
exports.ghiaccio_hud:setStreamerMode(bool)
exports.ghiaccio_hud:setSeatbelt(bool) / isSeatbeltOn()
exports.ghiaccio_hud:hideWidget('cash', true)  -- id del registro
exports.ghiaccio_hud:getLayout()
```

Id dei widget per `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, altrimenti lo stress integrato del client
exports.ghiaccio_hud:addStress(src, delta)
exports.ghiaccio_hud:getServerDefault()        -- JSON | false
exports.ghiaccio_hud:publishDefault(jsonString) -- senza ACE (console/altre risorse)
```

## Eventi client locali

| Evento                           | Direzione       | Dati                                    |
| -------------------------------- | --------------- | --------------------------------------- |
| `ghiaccio_hud:client:visibility` | emesso dall'HUD | `visible` (bool)                        |
| `ghiaccio_hud:client:toggle`     | ascoltato       | `visible` (bool), come `toggleHud`      |
| `ghiaccio_hud:client:seatbelt`   | ascoltato       | `on` (bool), per script cintura esterni |

## Bridge del framework

`bridge/` (non cifrato) contiene un file client e uno server per ogni framework (`esx`, `qbcore`, `qbox`, `standalone`) e `bridge/init.lua` (rilevamento). Fornisce giocatore caricato/scaricato, contanti e banca, fame/sete/stress, stato di morte, license, controllo admin e stress. Adattalo se il tuo framework è personalizzato.


---

# 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/it/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.
