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

# HUD

<figure><img src="/files/ivxck7vzCxyNicDFcRpC" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/lYCgMrNF5lPTqhMi3l5u" alt=""><figcaption></figcaption></figure>

<figure><img src="/files/TKJPCxaB6gMNMNvin2L3" alt=""><figcaption></figcaption></figure>

#### Crosshair Customization

{% embed url="<https://streamable.com/1ptp9c>" %}

#### Repositioning Elements

{% embed url="<https://streamable.com/02t0yv>" %}

#### Pause Menu & Waypoint Color

{% embed url="<https://streamable.com/14hq72>" %}

{% hint style="danger" %}
Installation:

* Drag and drop (only dependency being ox\_lib)

ox\_lib: <https://overextended.dev/ox_lib>

#### <mark style="color:red;">If using QBCore there is a line that needs to be commented out in the fxmanifest.lua</mark>

{% endhint %}

{% hint style="warning" %}
Minimap Blur

I did not intend to have the minimap be squared without the blurr so from here these steps are on you. You would need to adjust the minimap positions yourself or make your own squareminimap ytd mask to better fit thats on you. This is just a how to if you are one of these persons that want it changed.

If you wish to proceed then follow the steps:

* Download the square minimap from <https://github.com/Qbox-project/qbx_hud/blob/main/stream/squaremap.ytd>
* Paste the file in the hud stream folder
* Next navigate to client > minimap.lua and uncomment the lines of code
  {% endhint %}

## Text Prompt

{% hint style="warning" %}
Prompt UI is not meant to be ran every frame
{% endhint %}

```lua
exports['kevin-hud']:textPrompt(data)

exports['kevin-hud']:hideTextPrompt()
```

* **data** (table): The configuration for the text prompt.
  * text (string, required): The text to display in the prompt.
  * position (string, optional): The position of the prompt on the screen. Default: 'bottom-center'.
    * Accepted values:
      * 'right-center'
      * 'left-center'
      * 'top-center'
      * 'bottom-center'

#### Example Usages:

{% hint style="info" %}
For the Key to be displayed it needs to be encased in \[ ]

Eg. \[F1] , \[E], \[G] etc. all of these would be positioned in the key component
{% endhint %}

```lua
exports['kevin-hud']:textPrompt({
    text = '[E] Interact with Object',
    position = 'top-center'
})
```

```lua
lib.zones.sphere({
    coords = vector3(226.14, -791.49, 30.1),
    radius = 3.0,
    debug = false,
    onEnter = function()
        exports['kevin-hud']:textPrompt({
            text = '[E] Park Vehicle',
            position = 'bottom-center'
        })
    end,
    onExit = function()
        exports['kevin-hud']:hideTextPrompt()
    end
})
```

***

## Notifications

```lua
exports['kevin-hud']:notify(data)
```

* **data** (table): The notification configuration.
  * title (string, optional): The title of the notification. Default: 'Notification'.
  * description (string, optional): The description or body of the notification. Default: 'No description provided.'.
  * type (string, optional): Type of the notification. Determines the color and style. Default: 'info'.
    * Accepted values:
      * 'info': Informational messages.
      * 'success': Positive feedback messages.
      * 'error': Error messages.
      * 'warning': Warning or cautionary messages.
  * length (number, optional): Duration of the notification in milliseconds. Default: 5000.
  * icon (string, optional): FontAwesome icon to display with the notification. Default: 'fa-solid fa-info-circle'

#### Example Usages:

<pre class="language-lua"><code class="lang-lua">exports['kevin-hud']:notify({
<strong>    title = 'Action Completed',
</strong>    description = 'You have successfully completed the task.',
    type = 'success',
    length = 3000,
    icon = 'fa-solid fa-check-circle'
})
</code></pre>

#### Code to replace to have in <mark style="color:red;">qb-core</mark> to use my notifications default <mark style="color:red;">(Optional)</mark>

```lua
function QBCore.Functions.Notify(text, texttype, length, icon)
    local data = {
        title = 'Notification',
        description = 'No description provided.',
        type = texttype or 'info',
        length = length or 5000,
        icon = icon or 'fa-solid fa-info-circle'
    }

    if type(text) == 'table' then
        data.title = text.text or 'Notification'
        data.description = text.caption or 'No description provided.'
    else
        data.description = text
    end

    exports['kevin-hud']:notify(data)
end

```

#### Code to replace to have in <mark style="color:orange;">qbx-core</mark> to use my notifications default <mark style="color:orange;">(Optional)</mark>

```lua
function Notify(text, notifyType, duration, subTitle, notifyPosition, notifyStyle, notifyIcon, notifyIconColor)
    local title, description
    if type(text) == 'table' then
        title = text.text or 'Placeholder'
        description = text.caption or nil
    elseif subTitle then
        title = text
        description = subTitle
    else
        title = 'Notification'
        description = text
    end

    local data = {
        title = title,
        description = description,
        type = notifyType or 'info',
        length = duration or 5000,
        icon = notifyIcon or 'fa-solid fa-info-circle',
        iconColor = notifyIconColor
    }

    exports['kevin-hud']:notify(data)
end

```

#### Code to replace to have in <mark style="color:orange;">ox\_lib</mark> to use my notifications default <mark style="color:orange;">(Optional)</mark>

```lua
function lib.notify(data)
    local sound = settings.notification_audio and data.sound
    data.sound = nil
    data.position = data.position or settings.notification_position

    local notifyData = {
        title = data.title or 'Notification',
        description = data.description or 'No description provided.',
        type = data.type or 'info',
        length = data.duration or 5000,
        icon = data.icon or 'fa-solid fa-info-circle',
        iconColor = data.iconColor
    }

    exports['kevin-hud']:notify(notifyData)

    if not sound then return end

    if sound.bank then lib.requestAudioBank(sound.bank) end

    local soundId = GetSoundId()
    PlaySoundFrontend(soundId, sound.name, sound.set, true)
    ReleaseSoundId(soundId)

    if sound.bank then ReleaseNamedScriptAudioBank(sound.bank) end
end
```

***

## Progress Bar

```lua
exports['kevin-hud']:progressBar(data)

exports['kevin-hud']:cancelProgressBar()
```

*

```
`data`: A table containing the following keys:
```

```
* **duration** (optional, default: `5000`): The duration of the progress bar in milliseconds.
* **label** (optional): The label that appears on the progress bar (e.g., "Crafting", "Loading").
* **anim** (optional): An animation configuration.
  * `dict` (required): The animation dictionary name.
  * `clip` (required): The animation clip name.
  * `blendIn` (optional): The blend-in time (default is `3.0`).
  * `blendOut` (optional): The blend-out time (default is `1.0`).
  * `duration` (optional): The animation duration (default is `-1` for infinite).
  * `flag` (optional): Animation flag (default is `49`).
  * `lockX`, `lockY`, `lockZ` (optional): Whether to lock certain axes (default: `false`).
* **prop** (optional): A table containing prop information.
  * `model` (required): The model name of the prop.
  * `bone` (required): The bone index to attach the prop to.
  * `pos` (required): The position offset from the ped (e.g., `{x=0, y=0, z=0}`).
  * `rot` (required): The rotation of the prop (e.g., `{xRot=0, yRot=0, zRot=0}`).
* **disable** (optional): A table specifying which controls to disable during the progress bar.
  * `car`: If true, disables car controls (e.g., driving).
  * `move`: If true, disables movement controls (e.g., walking).
  * `mouse`: If true, disables mouse controls (e.g., aiming).
  * `combat`: If true, disables combat-related controls (e.g., shooting).
  * `sprint`: If true, disables sprinting.
```

#### Example Usages:

```lua
local success = exports['kevin-hud']:progressBar({
        duration = 5000,
        label = 'Testing Progress Bar',
        anim = {
            dict = 'mp_player_intdrink',
            clip = 'loop_bottle',
        },
        prop = {
            model = `prop_ld_flow_bottle`,
            pos = vec3(0.03, 0.03, 0.02),
            rot = vec3(0.0, 0.0, -1.5)
        },
        disable = {
            car = true,
            move = true,
            mouse = true,
            combat = true,
            sprint = true,
        },
    })
if success then
    print('Progress bar completed.')
else
    print('Progress bar canceled.')
end
```

#### Code to replace to have in <mark style="color:orange;">ox\_lib</mark> to use my progress bar using default ox lib exports <mark style="color:orange;">(Optional)</mark>

```lua
function lib.progressBar(data)
    return exports['kevin-hud']:progressBar(data)
end

function lib.progressCircle(data)
    return exports['kevin-hud']:progressBar(data)
end
```

#### Code to replace to have in qb-core to use my progress bar using default qbcore trigger <mark style="color:red;">(Optional)</mark>

```lua
function QBCore.Functions.Progressbar(name, label, duration, useWhileDead, canCancel, disableControls, animation, prop, propTwo, onFinish, onCancel)
    if GetResourceState('kevin-hud') ~= 'started' then error('kevin-hud needs to be started in order for QBCore.Functions.Progressbar to work') end
    if exports['kevin-hud']:progressBar({
        duration = duration,
        label = label,
        useWhileDead = useWhileDead,
        canCancel = canCancel,
        disable = {
            car = disableControls?.disableCarMovement,
            mouse = disableControls?.disableMouse,
            combat = disableControls?.disableCombat,
            move = disableControls?.disableMovement,
        },
        anim = {
            dict = animation?.animDict,
            clip = animation?.anim,
            flags = animation?.flags,
            scenario = animation?.scenario,
        },
        prop = {
            model = prop?.model,
            pos = prop?.coords,
            rot = prop?.rotation,
        },
    }) then
        if onFinish then
            onFinish()
        end
    else
        if onCancel then
            onCancel()
        end
    end
end
```

## Other HUD Exports

<pre class="language-lua"><code class="lang-lua"><strong>-- toggles the hud visibility (player stsus, vehicle, minimap etc)
</strong><strong>-- Note: isManual needs to be true if calling the export (set to false when done)
</strong><strong>exports['kevin-hud']:isHudVisible(bool, true)
</strong><strong>
</strong><strong>-- toggles the compassq
</strong><strong>exports['kevin-hud']:toggleCompass(bool)
</strong><strong>
</strong><strong>-- toggle player hud showing the health, armor etc
</strong>exports['kevin-hud']:togglePlayerHud(bool)

-- toggle the vehicle hud
<strong>exports['kevin-hud']:toggleVehicleHud(bool)
</strong>
-- is progress bar active
exports['kevin-hud']:isProgressBarActive()

-- Example usege in commands
RegisterCommand('hidehud', function()
    exports['kevin-hud']:isHudVisible(false, true)
end, false)

RegisterCommand('showhud', function()
    exports['kevin-hud']:isHudVisible(true, false)
end, false)

RegisterCommand('toggleplayerhudoff', function()
    exports['kevin-hud']:togglePlayerHud(false)
end, false)

RegisterCommand('toggleplayerhudon', function()
    exports['kevin-hud']:togglePlayerHud(true)
end, false)

RegisterCommand('togglevehiclehudoff', function()
    exports['kevin-hud']:toggleVehicleHud(false)
end, false)

RegisterCommand('togglevehiclehudon', function()
    exports['kevin-hud']:toggleVehicleHud(true)
end, false)
</code></pre>