> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/multi-framework/ak47_hud/exports/client.md).

# Client

The `ak47_hud` provides a robust, developer-friendly export API. These client-side exports allow server owners and other script developers to seamlessly interact with the HUD, toggle its features, and dynamically manage systems like stress, seatbelts, and the police radar without modifying the core code.

> Note: All functions below are Client-Side exports. You call them using `exports['ak47_hud']:FunctionName()`.

### 🖥️ Core HUD API

These exports allow you to control the visibility of the HUD and its individual elements.

#### `ToggleHudElement`

Dynamically shows or hides specific elements of the HUD.

| **Parameter** | **Type**  | **Description**                  |
| ------------- | --------- | -------------------------------- |
| `element`     | `string`  | The ID of the HUD element.       |
| `state`       | `boolean` | `true` to show, `false` to hide. |

Valid Elements: `money`, `status`, `compass`, `location`, `vehicle`, `crosshair`, `party`, `killfeed`, `chat`, `notification`, `serverinfo`, `minimap`, `all`.

```lua
-- Hide just the minimap
exports['ak47_hud']:ToggleHudElement('minimap', false)

-- Hide the entire HUD completely
exports['ak47_hud']:ToggleHudElement('all', false)
```

#### `GetHudState`

Returns the current visibility state of a specific HUD element.

| **Parameter** | **Type** | **Description**                                              |
| ------------- | -------- | ------------------------------------------------------------ |
| `element`     | `string` | The ID of the HUD element (same as above, plus `cinematic`). |

```lua
local isMapVisible = exports['ak47_hud']:GetHudState('minimap')
print("Is Minimap Visible? " .. tostring(isMapVisible))
```

#### `SetCinematicMode`

Forces cinematic mode (black bars) on or off. Hides conflicting HUD elements automatically.

| **Parameter** | **Type**  | **Description**                                      |
| ------------- | --------- | ---------------------------------------------------- |
| `state`       | `boolean` | `true` to enable cinematic bars, `false` to disable. |

```lua
-- Great for cutscenes or custom intros!
exports['ak47_hud']:SetCinematicMode(true)
```

#### `Notify`

Triggers the built-in custom notification system.

| **Parameter** | **Type** | **Description**                                   |
| ------------- | -------- | ------------------------------------------------- |
| `message`     | `string` | The text of the notification.                     |
| `type`        | `string` | `default`, `info`, `success`, `warning`, `error`. |
| `duration`    | `number` | Time in milliseconds (e.g., 5000).                |
| `title`       | `string` | (Optional) Custom title text.                     |

```lua
exports['ak47_hud']:Notify("You have been paid $500", "success", 5000, "Salary")
```

### 🏎️ Seatbelt System API

Manage the seatbelt system, ejection logic, and vehicle whitelists dynamically.

#### `ToggleSeatbeltSystem`

Enables or disables the entire seatbelt and ejection physics system. Useful for minigames or admin modes.

| **Parameter** | **Type**  | **Description**                       |
| ------------- | --------- | ------------------------------------- |
| `state`       | `boolean` | `true` to enable, `false` to disable. |

```lua
exports['ak47_hud']:ToggleSeatbeltSystem(false)
```

#### `SetSeatbelt`

Programmatically buckle or unbuckle the local player.

| **Parameter** | **Type**  | **Description**                           |
| ------------- | --------- | ----------------------------------------- |
| `state`       | `boolean` | `true` to buckle up, `false` to unbuckle. |

<pre class="language-lua"><code class="lang-lua"><strong>-- Force buckle the player (e.g., when using a racing harness item)
</strong>exports['ak47_hud']:SetSeatbelt(true)
</code></pre>

#### `HasSeatbeltOn` & `GetSeatbeltSystemState`

Getter functions to check the status of the seatbelt.

<pre class="language-lua"><code class="lang-lua"><strong>-- Returns true if the player is currently buckled in
</strong>local isBuckled = exports['ak47_hud']:HasSeatbeltOn()

-- Returns true if the ejection/seatbelt logic is currently active in the script
local isSystemActive = exports['ak47_hud']:GetSeatbeltSystemState()
</code></pre>

#### `AddToSeatbeltWhitelist` & `RemoveFromSeatbeltWhitelist`

Dynamically allow specific vehicle classes or models to bypass the seatbelt requirement (no ejection/no seatbelt logic).

| **Parameter**   | **Type**        | **Description**                                        |
| --------------- | --------------- | ------------------------------------------------------ |
| `whitelistType` | `string`        | `"class"` or `"model"`.                                |
| `value`         | `string/number` | Class ID (e.g., `18`) or model name (e.g., `"adder"`). |

```lua
-- Whitelist all emergency vehicles (Class 18) dynamically
exports['ak47_hud']:AddToSeatbeltWhitelist('class', 18)

-- Remove a specific vehicle from the whitelist
exports['ak47_hud']:RemoveFromSeatbeltWhitelist('model', 't20')
```

### 😰 Stress System API

Control stress behaviors, disable certain stress triggers, or whitelist jobs/vehicles on the fly.

#### `ToggleStressSystem`

Toggles specific parts of the stress system on or off.

| **Parameter** | **Type**  | **Description**                                                |
| ------------- | --------- | -------------------------------------------------------------- |
| `system`      | `string`  | `"vehicle"`, `"shooting"`, `"melee"`, `"effects"`, or `"all"`. |
| `state`       | `boolean` | `true` to enable, `false` to disable.                          |

```lua
-- Disable screen shakes and sickness effects (e.g., if a player takes a specific pill)
exports['ak47_hud']:ToggleStressSystem('effects', false)

-- Disable all stress entirely
exports['ak47_hud']:ToggleStressSystem('all', false)
```

#### `GetStressSystemState`

Returns the boolean state of a specific stress sub-system.

| **Parameter** | **Type** | **Description**                                       |
| ------------- | -------- | ----------------------------------------------------- |
| `system`      | `string` | `"vehicle"`, `"shooting"`, `"melee"`, or `"effects"`. |

```lua
local isShootingStressActive = exports['ak47_hud']:GetStressSystemState('shooting')
```

#### `AddToStressBypass` & `RemoveFromStressBypass`

Dynamically exempt specific jobs, vehicles, vehicle classes, or weapons from generating stress.

| **Parameter** | **Type**        | **Description**                                                |
| ------------- | --------------- | -------------------------------------------------------------- |
| `bypassType`  | `string`        | `"job"`, `"vehicle"`, `"class"`, or `"weapon"`.                |
| `value`       | `string/number` | The identifier (e.g., `"ambulance"`, `"WEAPON_STUNGUN"`, etc.) |

```lua
-- Stop players from getting stress while using a taser
exports['ak47_hud']:AddToStressBypass('weapon', 'WEAPON_STUNGUN')

-- Prevent a custom job from generating any stress
exports['ak47_hud']:AddToStressBypass('job', 'mechanic')
```

### 🚓 Police Radar API

Integrate the police radar with radial menus, dispatch systems, or external keybind managers.

#### `OpenRadarUI`

Opens the Police Radar remote control UI programmatically. Bypasses the `/radar` command.

```lua
-- Example: Triggering from a qb-radialmenu callback
exports['ak47_hud']:OpenRadarUI()
```

#### `SetRadarPower`

Turns the radar tracking on or off.

| **Parameter** | **Type**  | **Description**                         |
| ------------- | --------- | --------------------------------------- |
| `state`       | `boolean` | `true` to turn on, `false` to turn off. |

```lua
exports['ak47_hud']:SetRadarPower(true)
```

#### `GetRadarData`

Fetches the live, real-time data currently captured by the radar's antennas.

Returns a table: `{ patrolSpeed = number, front = table, rear = table }`

<pre class="language-lua"><code class="lang-lua"><strong>local data = exports['ak47_hud']:GetRadarData()
</strong>
if data.front.speed > 120 then
    print("Speeding vehicle detected! Plate: " .. data.front.plate)
end
</code></pre>

#### `SetRadarLock`

Locks or unlocks a specific antenna to hold a speed reading.

| **Parameter** | **Type**  | **Description**                    |
| ------------- | --------- | ---------------------------------- |
| `direction`   | `string`  | `"front"` or `"rear"`.             |
| `state`       | `boolean` | `true` to lock, `false` to unlock. |

```lua
-- Lock the front antenna
exports['ak47_hud']:SetRadarLock('front', true)
```

#### `ClearRadarFast`

Clears the saved "Fastest Speed" memory for the antennas.

| **Parameter** | **Type** | **Description**                  |
| ------------- | -------- | -------------------------------- |
| `direction`   | `string` | `"front"`, `"rear"`, or `"all"`. |

```lua
-- Clear all saved fast speeds via a custom external keybind
exports['ak47_hud']:ClearRadarFast('all')
```

#### `GetRadarState`

Gets the current power status and configuration settings of the radar.

Returns a table: `{ power = boolean, settings = table }`

```lua
local radarInfo = exports['ak47_hud']:GetRadarState()
print("Is radar powered on? " .. tostring(radarInfo.power))
```