# HUD: documentación

> Barras de estado en el minimapa, dinero y trabajo en la esquina, y un cuadro de instrumentos que funciona en vehículos, helicópteros y barcos.

- URL: https://xexstudio.com/es/docs/hud
- Versión: 1.0.1
- Ficha del producto: https://xexstudio.com/es/scripts/hud
Un HUD que no estorba: barras de estado ancladas al minimapa, un panel de dinero y trabajo, y un cuadro de
instrumentos con cinturón, control de crucero e intermitentes replicados. Tres diseños y visibilidad por indicador,
elegidos por cada jugador desde un menú en el juego y recordados en su PC. ESX, QBCore y Qbox.

## Requisitos

- [ox_lib](https://github.com/overextended/ox_lib)
- Un framework: **ESX** (con `esx_status`), **QBCore** o **Qbox**
- Opcional: un recurso de combustible (ox_fuel, LegacyFuel, ps-fuel, cdn-fuel, okokGasStation, lj-fuel, Renewed-Fuel)
  y un banco de sociedades (esx_society, qb-banking, Renewed-Banking o qb-management) para el saldo del jefe

## Instalación

1. Detén cualquier otro HUD (`qbx_hud`, `qb-hud`, `esx_hud`, `trew_hud_ui`, ...). Dos HUD se dibujan uno encima del
   otro.
2. Copia `xex_hud` en tu carpeta de recursos.
3. Añade a `server.cfg` después de tu framework y ox_lib:
   ```cfg
   ensure xex_hud
   ```
4. Configura el idioma con `setr ox:locale en` (o `es`).
5. Pon tu logo en `ui/img/` y apunta `Config.UI.logo` a él, o usa una URL. Déjalo vacío para ocultar el logo.

## Qué ven los jugadores

| Área | Contenido |
| --- | --- |
| Estado (encima o junto al minimapa) | Salud, chaleco, hambre, sed, estrés y sueño cuando el framework los reporta; oxígeno al bucear |
| Cápsulas críticas | Hambre o sed por debajo del 5 % (configurable) con un tinte suave de pantalla y temblor de cámara |
| Encima del bloque de estado | Calle, zona y rumbo de la brújula |
| Panel superior derecho | Logo, trabajo y rango, id del servidor, efectivo, banco, dinero sucio (ESX) y el saldo de la sociedad para los jefes |
| Inferior derecha | Chip de voz: estado de habla, alcance (susurro, normal, grito) y radio, con pma-voice de serie |
| Cuadro de instrumentos | Velocidad, arco de rpm, marcha, combustible, salud del motor, cinturón, luces, intermitentes, control de crucero y altitud en aeronaves |

`/hud` abre el menú de ajustes: diseño (Compact, Balanced, Classic), cada indicador visible u oculto, el panel de
dinero, el cuadro de instrumentos, la línea de calle y el chip de voz. `/togglehud` lo oculta todo. Ambos se recuerdan por jugador. Las teclas del cinturón
(K), el control de crucero (U) y los intermitentes (flechas) las puede cambiar cada jugador en Ajustes > Asignación de teclas > FiveM.

El HUD coloca el minimapa propio de GTA en su posición y tamaño por defecto (`Config.Minimap` puede moverlo),
deshaciendo cualquier posición que haya dejado otro recurso, y ancla el bloque de estado a esa caja con la zona segura
y la relación de aspecto del jugador, de modo que encaja en cualquier resolución y baja a la esquina cuando el radar
está oculto. El tamaño sigue siendo el del juego: su máscara de mapa solo encaja con ese tamaño (los HUD de mapa
cuadrado sustituyen la textura de la máscara para estirarla). Con `manage = false` no toca el minimapa y asume el de
por defecto.

La caja de alcance propia de pma-voice se desactiva mediante su convar `voice_enableUi` (`Config.Voice.hideVoiceResourceUi`),
porque el HUD muestra el alcance en su chip de voz. Los jugadores ya conectados la ven desaparecer en su siguiente
cambio de alcance.

## Configuración

Todo está en `config.lua`:

| Ajuste | Qué hace |
| --- | --- |
| `Config.Framework` | `auto`, o fuerza `esx` / `qb` / `qbox` |
| `Config.Commands` | Nombres de los comandos del menú de ajustes y del interruptor (`false` desactiva uno) |
| `Config.UI` | Color de acento, logo, qué cuentas de dinero y detalles del trabajo mostrar, prefijo de moneda y formato numérico |
| `Config.Status` | Intervalo de actualización, qué indicadores existen, umbral crítico, temblores, avisos de sueño, diseños disponibles y el de por defecto |
| `Config.Minimap` | Posición y tamaño del minimapa al que se ancla el HUD |
| `Config.Location` | Línea de calle, zona y rumbo, y con qué frecuencia se comprueba |
| `Config.Voice` | Chip de voz y las etiquetas de los tres alcances |
| `Config.HideGameHud` | Elementos de GTA que este HUD sustituye (efectivo, nombre del vehículo, nombres de área y de calle) |
| `Config.Vehicle` | Unidad de velocidad, fuente de combustible, cinturón (bloquear la salida, expulsar en choque), control de crucero, salud del motor, intermitentes, sonidos, teclas por defecto y clases de vehículo |

Los textos están en `locales/*.json`. Los colores de las barras son variables CSS al principio de `ui/style.css`.

### Necesidades por framework

| Framework | Hambre / sed | Estrés | Sueño |
| --- | --- | --- | --- |
| ESX | `esx_status` | `esx_status` si existe un estado `stress` | `esx_status` si existe un estado `sleep` (100 = exhausto) |
| QBCore / Qbox | `metadata.hunger` / `metadata.thirst` | `metadata.stress` | no se reporta, barra oculta |

Un indicador que el framework nunca reporta simplemente no se dibuja. Establece `Config.Status.stress` o `sleep` en
`false` para ocultar uno a propósito.

## Para desarrolladores

Exports (cliente):

```lua
exports.xex_hud:setVisible(false)   -- hide temporarily (pause menu, cinematic, character creator); true restores
exports.xex_hud:isVisible()          -- true when the HUD is on screen
exports.xex_hud:isEnabled()          -- the player's own on/off preference
exports.xex_hud:setEnabled(true)     -- change that preference
exports.xex_hud:openSettings()       -- open the settings menu from your own menu
```

Eventos (cliente):

- `xex_hud:setVisible` (`true` / `false`): igual que el export, para recursos que prefieren eventos.
- `xex_hud:visibilityChanged` (`visible`): se dispara cada vez que el HUD aparece o desaparece.

Los intermitentes del vehículo se guardan en el state bag del vehículo como `xex_hud:indicators` (`off`, `left`, `right`, `both`),
establecidos solo por el propietario de la entidad y validados en el servidor.

El `bridge/client.lua` abierto lee necesidades, dinero, trabajo, muerte, combustible y voz (pma-voice: proximidad
desde el state bag del jugador, habla desde mumble); `bridge/server.lua` resuelve el saldo de la sociedad. Adáptalos
para un core, banco o recurso de voz personalizado (saltychat, mumble-voip).

## Rendimiento

Los valores de estado se envían a la NUI solo cuando algo cambia (como máximo una vez por segundo). El bucle de
vehículo se ejecuta cada 100 ms al conducir con el motor encendido y cada 500 ms en caso contrario. No hay ningún
bucle por frame salvo mientras el cinturón está abrochado y `blockExit` está activado, lo que requiere
`DisableControlAction` en cada frame.

Las cifras de resmon se miden en un servidor limpio antes de cada versión y se publican en la página del producto.

## Seguridad

Nada en este recurso da dinero, objetos ni licencias. El saldo de la sociedad se resuelve en el servidor a partir del
trabajo real del jugador, y los intermitentes solo se aceptan del propietario del vehículo.
