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

# Exports

This HUD resource provides a set of client-side exports for interacting with the UI from other resources.

These exports allow you to:

* Insert, update, and remove **status** items
* Insert, update, and remove **vehicle data** items
* Add, update, and remove **custom balance** items
* Send **notifications** to the UI

> **Note:** All custom icons used in these exports must match the name of the SVG file placed in `ui/dist/assets/icons`.

***

## Available Exports

### General Exports

#### `IsHudHidden()` 

Checks the current visibility status of the HUD.

Returns: `boolean` (`true` if hidden, `false` if visible)

***

#### `SetHudHidden(state)` 

Sets the visibility state of the HUD.

**Parameters**

| Name    | Type      | Required | Description                                           |
| ------- | --------- | -------- | ----------------------------------------------------- |
| `state` | `boolean` | Yes      | Set to `true` to hide the HUD, or `false` to show it. |

***

### Status Exports

#### `insertStatus(data)`

Insert a new status item into the HUD.

**Parameters**

| Name   | Type    | Required | Description   |
| ------ | ------- | -------- | ------------- |
| `data` | `table` | Yes      | Status object |

**Data structure**

```lua
{
    id = "stress",
    icon = "brain",
    value = 35,
    color = "#ff0000"
}
```

**Example**

```lua
exports['ayc-hud']:insertStatus({
    id = 'stress',
    icon = 'brain',
    value = 35,
    color = '#ff0000'
})
```

***

#### `removeStatus(id)`

Remove an existing status item from the HUD.

**Parameters**

| Name | Type     | Required | Description       |
| ---- | -------- | -------- | ----------------- |
| `id` | `string` | Yes      | Status identifier |

**Example**

```lua
exports['ayc-hud']:removeStatus('stress')
```

***

#### `updateStatus(id, data)`

Update an existing status item.

**Parameters**

| Name   | Type     | Required | Description       |
| ------ | -------- | -------- | ----------------- |
| `id`   | `string` | Yes      | Status identifier |
| `data` | `table`  | Yes      | Updated fields    |

**Data structure**

```lua
{
    icon = "brain",
    value = 60,
    color = "#ffaa00"
}
```

**Example**

```lua
exports['ayc-hud']:updateStatus('stress', {
    icon = 'brain',
    value = 60,
    color = '#ffaa00'
})
```

***

### Vehicle Data Exports

#### `insertVehicleData(data)`

Insert a new vehicle HUD item.

**Parameters**

| Name   | Type    | Required | Description         |
| ------ | ------- | -------- | ------------------- |
| `data` | `table` | Yes      | Vehicle data object |

**Data structure**

```lua
{
    id = "fuel",
    icon = "gas-pump",
    value = 82
}
```

**Example**

```lua
exports['ayc-hud']:insertVehicleData({
    id = 'fuel',
    icon = 'gas-pump',
    value = 82
})
```

***

#### `removeVehicleData(id)`

Remove an existing vehicle HUD item.

**Parameters**

| Name | Type     | Required | Description             |
| ---- | -------- | -------- | ----------------------- |
| `id` | `string` | Yes      | Vehicle item identifier |

**Example**

```lua
exports['ayc-hud']:removeVehicleData('fuel')
```

***

#### `updateVehicleData(id, data)`

Update an existing vehicle HUD item.

**Parameters**

| Name   | Type     | Required | Description             |
| ------ | -------- | -------- | ----------------------- |
| `id`   | `string` | Yes      | Vehicle item identifier |
| `data` | `table`  | Yes      | Updated fields          |

**Data structure**

```lua
{
    icon = "gas-pump",
    value = 45
}
```

**Example**

```lua
exports['ayc-hud']:updateVehicleData('fuel', {
    icon = 'gas-pump',
    value = 45
})
```

***

### Custom Balance Exports

#### `AddCustomBalance(id, value, icon, currency, color)`

Add a custom balance entry to the HUD.

**Parameters**

| Name       | Type     | Required | Description               |
| ---------- | -------- | -------- | ------------------------- |
| `id`       | `string` | Yes      | Unique balance identifier |
| `value`    | `number` | No       | Current amount            |
| `icon`     | `string` | No       | Icon name                 |
| `currency` | `string` | No       | Currency label or symbol  |
| `color`    | `string` | No       | Display color             |

**Example**

```lua
exports['ayc-hud']:AddCustomBalance('crypto', 1250, 'bitcoin', 'BTC', '#f7931a')
```

***

#### `UpdateCustomBalance(id, value, icon, currency, color)`

Update an existing custom balance entry.

**Parameters**

| Name       | Type     | Required | Description               |
| ---------- | -------- | -------- | ------------------------- |
| `id`       | `string` | Yes      | Unique balance identifier |
| `value`    | `number` | No       | Updated amount            |
| `icon`     | `string` | No       | Updated icon              |
| `currency` | `string` | No       | Updated currency          |
| `color`    | `string` | No       | Updated color             |

**Example**

Update only the value:

```lua
exports['ayc-hud']:UpdateCustomBalance('crypto', 1400)
```

Update all fields:

```lua
exports['ayc-hud']:UpdateCustomBalance('crypto', 1400, 'bitcoin', 'BTC', '#f7931a')
```

***

#### `RemoveCustomBalance(id)`

Remove a custom balance entry from the HUD.

**Parameters**

| Name | Type     | Required | Description               |
| ---- | -------- | -------- | ------------------------- |
| `id` | `string` | Yes      | Unique balance identifier |

**Example**

```lua
exports['ayc-hud']:RemoveCustomBalance('crypto')
```

***

### Notification Export

#### `handleNewNotification(data)`

Send a notification to the UI.

**Parameters**

| Name   | Type    | Required | Description         |
| ------ | ------- | -------- | ------------------- |
| `data` | `table` | Yes      | Notification object |

**Data structure**

```lua
{
    message = "Test",
    type = "info",
    duration = 5000
}
```

**Supported notification types**

* `fail`
* `success`
* `info`
* `warning`
* `alert`

**Optional fields**

| Name       | Type     | Required | Description              |
| ---------- | -------- | -------- | ------------------------ |
| `message`  | `string` | No       | Notification text        |
| `type`     | `string` | No       | Notification type        |
| `icon`     | `string` | No       | Custom icon override     |
| `color`    | `string` | No       | Custom color override    |
| `duration` | `number` | No       | Duration in milliseconds |

**Example**

```lua
exports['ayc-hud']:handleNewNotification({
    message = 'Vehicle locked successfully',
    type = 'success',
    duration = 4000
})
```

**Example with custom icon and color**

```lua
exports['ayc-hud']:handleNewNotification({
    message = 'Special event started',
    type = 'alert',
    icon = 'star',
    color = '#FFD700',
    duration = 7000
})
```

***

## Notification UI Behavior

The notification UI uses the following internal configuration:

```js
const config = {
    fail: {
        icon: 'notif-fail',
        color: '#ffa9c6'
    },
    success: {
        icon: 'notif-success',
        color: '#86ffc6'
    },
    info: {
        icon: 'notif-info',
        color: '#86fff9'
    },
    warning: {
        icon: 'notif-warning',
        color: '#ffa9c6'
    },
    alert: {
        icon: 'notif-alert',
        color: '#fff9a8'
    }
}
```

#### Default notification values

If no values are provided, the UI falls back to:

```js
{
    message: 'An error occurred.',
    type: 'info',
    duration: 5000
}
```

#### Behavior summary

* The notification is pushed into the store
* The notification is automatically removed after `duration`

***

## NUI Message Actions

The following NUI actions are used internally by the resource:

| Action              | Description                            |
| ------------------- | -------------------------------------- |
| `insertStatus`      | Insert a status item                   |
| `removeStatus`      | Remove a status item                   |
| `updateStatus`      | Update a status item                   |
| `insertVehicleData` | Insert a vehicle data item             |
| `removeVehicleData` | Remove a vehicle data item             |
| `updateVehicleData` | Update a vehicle data item             |
| `balance:update`    | Update cash, bank, and custom balances |
| `notif`             | Push a new notification                |

***

## Example Test Command

A sample command can be used for testing notifications:

```lua
RegisterCommand("testnotif", function ()
    local data = {
        message = 'This is a test notification.',
        type = 'alert',
        duration = 5000
    }
    exports[GetCurrentResourceName()]:handleNewNotification(data)
end)
```

Use in-game:

```txt
/testnotif
```