# nova\_hud

NOVA Framework HUD (Heads-Up Display). Shows health, armor, hunger, thirst, job, cash, bank, and a progress bar for actions.

## Features

* **Health Bar** — Circular ring showing health percentage
* **Armor Bar** — Circular ring (hidden when 0)
* **Hunger Bar** — Circular ring (from metadata)
* **Thirst Bar** — Circular ring (from metadata)
* **Job Display** — Current job label and duty badge
* **Cash & Bank** — Money display
* **Server ID** — Player's server ID
* **Speedometer** — Shows when in vehicle
* **Progress Bar** — For actions (eating, repairing, etc.) with optional animation and cancel

## Configuration

The HUD reads player data from `nova_core` (GetPlayerData). Hunger and thirst come from `player.metadata.hunger` and `player.metadata.thirst` (0–100).

## Progress Bar API

Use the progress bar for timed actions (eating, drinking, repairing, etc.):

```lua
-- Returns true if completed, false if cancelled
local success = exports['nova_hud']:ProgressBar(label, duration, opts)
```

### Parameters

| Parameter  | Type   | Description                |
| ---------- | ------ | -------------------------- |
| `label`    | string | Text shown during progress |
| `duration` | number | Duration in milliseconds   |
| `opts`     | table  | Optional settings          |

### Options (`opts`)

| Option            | Type    | Description                                  |
| ----------------- | ------- | -------------------------------------------- |
| `animation`       | table   | `{ dict, clip, flag }` — Animation to play   |
| `prop`            | table   | `{ model, bone, pos, rot }` — Prop to attach |
| `canCancel`       | boolean | Allow cancel with X key (default: true)      |
| `disableControls` | boolean | Disable sprint/attack/aim (default: true)    |

### Example: Progress with animation

```lua
local success = exports['nova_hud']:ProgressBar('Eating...', 4000, {
    animation = { dict = 'mp_player_inteat@burger', clip = 'mp_player_int_eat_burger', flag = 49 },
    canCancel = true,
})
if success then
    -- Action completed
else
    -- Cancelled by player
end
```

### Example: Simple progress (no animation)

```lua
local success = exports['nova_hud']:ProgressBar('Processing...', 3000)
```

## Exports

| Export              | Parameters                   | Returns | Description                                         |
| ------------------- | ---------------------------- | ------- | --------------------------------------------------- |
| `ProgressBar`       | `label`, `duration`, `opts?` | boolean | Start progress bar (true = done, false = cancelled) |
| `CancelProgressBar` | —                            | —       | Cancel active progress bar                          |
| `IsProgressActive`  | —                            | boolean | Is progress bar currently running?                  |
| `ToggleHud`         | `state` (boolean)            | —       | Show/hide HUD                                       |
| `IsHudVisible`      | —                            | boolean | Is HUD visible?                                     |

## Client Events

| Event             | Parameters        | Description                                       |
| ----------------- | ----------------- | ------------------------------------------------- |
| `nova_hud:toggle` | `state` (boolean) | Toggle HUD visibility (e.g. when inventory opens) |

## Usage Examples

### Show progress bar from inventory/other script

```lua
-- In client/useitems.lua or similar
local success = exports['nova_hud']:ProgressBar(InvL('eating_bread'), 4000, {
    animation = { dict = 'mp_player_inteat@burger', clip = 'mp_player_int_eat_burger', flag = 49 },
    canCancel = true,
})
if success then
    -- Apply hunger effect via server
end
```

### Hide HUD when opening custom UI

```lua
TriggerEvent('nova_hud:toggle', false)
-- Show UI...
-- When closing:
TriggerEvent('nova_hud:toggle', true)
```

### Check if progress is active

```lua
if exports['nova_hud']:IsProgressActive() then
    -- Don't start another action
end
```

## Notes

* HUD updates every 200ms when visible and player is loaded
* Minimap (radar) is hidden when HUD is hidden
* nova\_inventory automatically toggles HUD when opening/closing
* Progress bar uses key **X** (control 73) to cancel when `canCancel` is true
* The user-facing API may also be referenced as `StartProgress` in some contexts; the actual export name is `ProgressBar`