> 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
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://ayccoes-assets.gitbook.io/ayccoes-assets/ayc-hud/exports.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.