# HUD V2

###

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

### 1) Overview

Risk HUD V2 is a comprehensive, customizable HUD system featuring:

* 🚗 **Advanced Speedometer** — Real-time speed, fuel, gear, RPM, seatbelt
* 💰 **Balance Display** — Cash, bank, black money tracking
* 👔 **Job System** — Dynamic job and grade display
* 📊 **Visa/Level System** — Player progression with combat restrictions
* 💬 **Integrated Chat** — RP Chat and Admin Chat systems
* 🔔 **Notification System** — Custom notifications with multiple types
* 📢 **Announcements** — Server-wide and targeted announcements
* ⏳ **Progress Bars** — Animated progress with animations and props
* 🗺️ **Street Display** — Current street and area names
* 🎤 **Voice Integration** — Proximity voice indicators
* ⚙️ **In-Game Settings** — Players can customize their HUD
* 📱 **Item Notifications** — Inventory item tracking
* 🎬 **Cinematic Mode** — Toggle letterbox mode
* 🎨 **Fully Customizable** — Colors, positions, sizes, visibility

***

### 2) Dependencies

**Required:**

* [oxmysql](https://github.com/overextended/oxmysql) — For Visa system and settings storage
* ESX or QBCore framework

**Optional:**

* Voice system (pma-voice, saltychat, tokovoip, mumble-voip)

```
ensure oxmysql
ensure risk-hudv2
```

***

### 3) Basic Configuration

#### Server Information

```lua
Config.ServerName = "Risk Scripts"
```

Displayed in the top-left corner of the HUD.

**Examples:**

```lua
Config.ServerName = "Los Santos RP"
Config.ServerName = "My Roleplay Server"
Config.ServerName = "LS:RP"
```

#### Framework Detection

```lua
-- Automatic detection (recommended)
-- No configuration needed
```

The HUD automatically detects:

* `es_extended` (ESX)
* `qb-core` (QBCore)
* `qbx_core` (QBox)

#### Update Intervals

```lua
Config.SpeedoMeterUpdateInterval = 10
```

**How often the speedometer updates (in milliseconds)**

```lua
Config.SpeedoMeterUpdateInterval = 10   -- Very smooth (higher performance cost)
Config.SpeedoMeterUpdateInterval = 50   -- Balanced (recommended)
Config.SpeedoMeterUpdateInterval = 100  -- Performance mode
```

***

### 4) Money System Configuration

#### Money Types

```lua
Config.UseBlackMoney = true
```

* `true` — Shows cash, bank, and black money
* `false` — Shows only cash and bank

#### Supporter System (Optional)

```lua
Config.useSupporter = false
```

Enable if you have a supporter/VIP system integrated.

***

### 5) Speed Type Configuration

```lua
Config.SpeedType = "kmh"
```

**Options:**

* `"kmh"` — Kilometers per hour (metric)
* `"mph"` — Miles per hour (imperial)

**Maximum Speed Display:**

```lua
Config.MaxSpeed = 240
```

The speedometer shows 0-100% based on this maximum speed (in km/h).

```lua
Config.MaxSpeed = 200  -- Lower max (most civilian vehicles)
Config.MaxSpeed = 240  -- Default (balanced)
Config.MaxSpeed = 300  -- High performance (supercars)
```

***

### 6) Minimap Configuration

#### Always Show Minimap

```lua
Config.ShowAlwaysMiniMap = false
```

* `false` — Minimap only shows when in vehicle (default)
* `true` — Minimap always visible (even on foot)

**Recommended:**

```lua
Config.ShowAlwaysMiniMap = false  -- Immersive RP servers
Config.ShowAlwaysMiniMap = true   -- Action/PvP servers
```

***

### 7) Seatbelt System

```lua
Config.Belt = {
    active = true,
    key = 'K',
    notify_on = {
        type = 'success',
        title = 'Seatbelt',
        message = 'Seatbelt fastened.',
        duration = 3000
    },
    notify_off = {
        type = 'error',
        title = 'Seatbelt',
        message = 'Seatbelt removed.',
        duration = 3000
    }
}
```

#### Seatbelt Settings

**Enable/Disable:**

```lua
Config.Belt.active = true   -- Enable seatbelt system
Config.Belt.active = false  -- Disable (players always safe)
```

**Change Keybind:**

```lua
Config.Belt.key = 'K'       -- Default
Config.Belt.key = 'B'       -- Alternative
Config.Belt.key = 'L'       -- Another option
```

**How it works:**

* Without seatbelt: High-speed crashes **eject player** from vehicle
* With seatbelt: Player stays in vehicle during crashes
* Prevents exiting vehicle with `F` when seatbelt is on
* Auto-removes seatbelt when exiting vehicle normally

**Eject Parameters:**

* Triggers if speed > 65 km/h
* Triggers if deceleration > 35 km/h
* 1.5 second cooldown between ejects

**Customize Notifications:**

```lua
Config.Belt.notify_on = {
    type = 'success',
    title = 'Safety',
    message = 'You buckled your seatbelt.',
    duration = 2000
}

Config.Belt.notify_off = {
    type = 'warning',
    title = 'Safety',
    message = 'Seatbelt removed! Drive carefully.',
    duration = 2000
}
```

***

### 8) Visa / Level System

The Visa system is a **player progression mechanic** that restricts combat until players reach a certain level.

```lua
Config.Visa = {
    active = true,
    punch_level = 10,
    notify = true,
    other_level_time = 3,
    admins = {},
    levels = {
        {level = 0, time = 3},
        {level = 1, time = 3},
        {level = 2, time = 3},
        {level = 3, time = 3},
        {level = 4, time = 3},
        {level = 5, time = 5},
        {level = 10, time = 5},
        {level = 15, time = 5},
        {level = 20, time = 5},
        {level = 50, time = 10},
    },
    notify_settings = {
        type = 'info',
        title = 'Visa Level',
        duration = 5000
    },
    message = {
        visa_up = "Your visa level increased to %d",
        cant_attack = "You need visa level %d to attack other players.",
    }
}
```

#### How It Works

**Level Progression:**

* Players start at Visa Level 0
* Level increases automatically based on play time
* Each level has a specific time requirement (in minutes)
* Example: Level 0 → Level 1 requires 3 minutes of playtime

**Combat Restriction:**

```lua
Config.Visa.punch_level = 10
```

Players **cannot attack** (punch, shoot, use weapons) until they reach this level.

**Examples:**

```lua
Config.Visa.punch_level = 5   -- Can attack after 5 levels (easy)
Config.Visa.punch_level = 10  -- Can attack after 10 levels (default)
Config.Visa.punch_level = 20  -- Can attack after 20 levels (strict)
Config.Visa.punch_level = 0   -- Can attack immediately (disabled)
```

#### Disable Visa System

```lua
Config.Visa.active = false
```

#### Level Time Configuration

```lua
Config.Visa.levels = {
    {level = 0, time = 3},   -- Level 0→1: 3 minutes
    {level = 1, time = 3},   -- Level 1→2: 3 minutes
    {level = 5, time = 5},   -- Level 5→6: 5 minutes
    {level = 10, time = 10}, -- Level 10→11: 10 minutes
}
```

**For levels not in the list:**

```lua
Config.Visa.other_level_time = 3  -- Default time (minutes)
```

**Fast Progression (new player friendly):**

```lua
Config.Visa.levels = {
    {level = 0, time = 1},
    {level = 1, time = 1},
    {level = 2, time = 1},
    {level = 5, time = 2},
    {level = 10, time = 3},
}
Config.Visa.other_level_time = 2
```

**Slow Progression (strict RP):**

```lua
Config.Visa.levels = {
    {level = 0, time = 5},
    {level = 5, time = 10},
    {level = 10, time = 15},
    {level = 20, time = 20},
}
Config.Visa.other_level_time = 10
```

#### Admin Commands

**Set player visa level:**

```
/setvisa <playerID> <level>
```

**Admin Permissions:**

```lua
Config.Visa.admins = {
    "license:abc123",  -- Add license identifiers
    "license:def456",
}
```

Only admins in this list can use `/setvisa` command.

#### Customize Messages

```lua
Config.Visa.message = {
    visa_up = "Level Up! You are now Visa Level %d",
    cant_attack = "You must reach Visa Level %d before engaging in combat.",
}
```

***

### 9) Chat System

Risk HUD V2 includes **two separate chat systems**:

#### A) RP Chat (Roleplay Chat)

```lua
Config.UseChat = true
Config.UseRPChat = true
Config.UseAdminChat = false
```

**Features:**

* Everyone can send and see messages
* Shows player name, ID, and job (if employed)
* Unemployed/citizen players show **ID only** (no job tag)
* Perfect for in-game IC (In-Character) chat

**Example Display:**

```
[15:30] John Smith [Police | Officer] [ID: 12]: Need backup at the bank
[15:31] Mike Johnson [ID: 24]: Just bought a car!
[15:32] Sarah Miller [EMS | Paramedic] [ID: 7]: On my way to Pillbox
```

#### B) Admin Chat (Staff Chat)

```lua
Config.UseChat = true
Config.UseRPChat = false
Config.UseAdminChat = true
```

**Features:**

* **Only admins** can send messages
* **Only admins** can see messages
* Shows admin rank instead of job
* Perfect for staff communication

**Example Display:**

```
[15:30] Admin John [Moderator] [ID: 12]: Player reported for RDM
[15:31] Admin Sarah [Admin] [ID: 7]: Handling it now
```

#### Admin Ranks Configuration

```lua
Config.AdminChatGroups = {
    ['owner'] = 'Owner',
    ['admin'] = 'Admin',
    ['mod'] = 'Moderator',
    ['superadmin'] = 'Super Admin',
    ['god'] = 'God',
}
```

#### Disable Chat System

```lua
Config.UseChat = false
```

This will use the default GTA chat instead.

***

### 10) Announcement System

```lua
Config.Announcement = {
    active = true,
    command = 'announcement',
    targetCommand = 'announcementto',
    permission = {'admin', 'superadmin', 'god', 'mod', 'owner'},
    DefaultName = "Server",
    DefaultTitle = "Server Announcement",
    DefaultDuration = 10000,
    TxAdminDuration = 15000,
    UseCharacterNameFallback = false,
}
```

#### Announcement Settings

**Enable/Disable:**

```lua
Config.Announcement.active = true   -- Enable announcements
Config.Announcement.active = false  -- Disable
```

**Commands:**

```lua
Config.Announcement.command = 'announcement'      -- /announcement
Config.Announcement.targetCommand = 'announcementto'  -- /announcementto
```

**Permissions:**

```lua
Config.Announcement.permission = {
    'admin',
    'superadmin',
    'god',
    'mod',
    'owner'
}
```

Only players with these permissions can send announcements.

**Default Values:**

```lua
Config.Announcement.DefaultName = "Admin Team"
Config.Announcement.DefaultTitle = "Important Announcement"
Config.Announcement.DefaultDuration = 15000  -- 15 seconds
```

**Sender Name:**

```lua
Config.Announcement.UseCharacterNameFallback = false  -- Use config name
Config.Announcement.UseCharacterNameFallback = true   -- Use character name
```

#### TxAdmin Integration

```lua
Config.UseTxAdminAnnouncements = true
Config.TxAdminName = "TxAdmin"
```

* Automatically shows TxAdmin announcements and restart warnings
* Set to `false` to disable

**TxAdmin announcement duration:**

```lua
Config.Announcement.TxAdminDuration = 15000  -- 15 seconds
```

***

### 11) Notification System

```lua
Config.UseRiskNotifyV2 = true
```

**Must be `true` for:**

* Notifications
* HelpNotify
* Progress Bars
* Announcements

If `false`, these features are disabled.

***

### 12) Settings Menu

```lua
Config.Settings = {
    active = true,
    command = 'hudsettings'
}
```

**In-game settings menu** allows players to:

* Toggle HUD elements on/off
* Switch speedometer style
* Customize their experience

**Command:**

```
/hudsettings
```

**Disable settings menu:**

```lua
Config.Settings.active = false
```

***

### 13) Default HUD Configuration

```lua
Config.DefaultHUD = {
    cash = true,
    bank = true,
    black_money = true,
    job = true,
    id = true,
    players = true,
    time = true,
    admins = true,
    street = true,
    area = true,
    voice = true,
    visa = true,
    speedo = 1,  -- 1 or 2 (speedometer style)
}
```

#### HUD Element Toggle

**Disable specific elements by default:**

```lua
Config.DefaultHUD = {
    cash = true,           -- Show cash
    bank = true,           -- Show bank balance
    black_money = false,   -- Hide black money
    job = true,            -- Show job
    id = true,             -- Show player ID
    players = true,        -- Show player count
    time = true,           -- Show time
    admins = false,        -- Hide admin count
    street = true,         -- Show street name
    area = true,           -- Show area name
    voice = true,          -- Show voice indicator
    visa = true,           -- Show visa level
    speedo = 1,            -- Speedometer style (1 or 2)
}
```

**Speedometer Styles:**

* `1` — Classic circular style
* `2` — Modern digital style

***

### 14) Item Notification System

```lua
Config.UseItemNotify = true
```

**Shows notifications when:**

* Items are added to inventory
* Items are removed from inventory
* Weapons are given/taken

**Supported Inventory Systems:**

* ESX inventory
* QBCore inventory
* ox\_inventory
* qb-inventory
* Any inventory using standard events

**Disable item notifications:**

```lua
Config.UseItemNotify = false
```

***

### 15) Voice System Configuration

The HUD automatically detects and integrates with:

* pma-voice
* saltychat
* tokovoip
* mumble-voip

```lua
Config.MaxVoiceLevels = 3
```

**Voice indicator shows:**

* Current voice distance (percentage)
* Talking status (microphone icon lights up)
* Muted/unmuted status

**Change max voice levels:**

```lua
Config.MaxVoiceLevels = 3  -- Default (Whisper, Normal, Shout)
Config.MaxVoiceLevels = 4  -- Extra level
```

***

### 16) Debug Mode

```lua
Config.DebugMode = false
```

Enable for troubleshooting:

```lua
Config.DebugMode = true
```

Prints debug information to console for:

* Money updates
* Player data
* Framework detection
* Event triggers

***

### 17) Complete Configuration Examples

#### Example 1: Pure RP Server (Strict)

```lua
Config.ServerName = "Los Santos Roleplay"
Config.SpeedType = "mph"
Config.ShowAlwaysMiniMap = false
Config.UseBlackMoney = true

Config.Belt.active = true
Config.Belt.key = 'K'

Config.Visa.active = true
Config.Visa.punch_level = 20  -- Very strict
Config.Visa.levels = {
    {level = 0, time = 5},
    {level = 5, time = 10},
    {level = 10, time = 15},
    {level = 20, time = 20},
}

Config.UseChat = true
Config.UseRPChat = true
Config.UseAdminChat = false

Config.Announcement.active = true
Config.UseTxAdminAnnouncements = true

Config.DefaultHUD = {
    cash = true,
    bank = true,
    black_money = true,
    job = true,
    id = false,         -- Hide IDs for immersion
    players = false,    -- Hide player count
    time = true,
    admins = false,
    street = true,
    area = true,
    voice = true,
    visa = true,
    speedo = 1,
}
```

#### Example 2: Action Server (Casual)

```lua
Config.ServerName = "Action RP"
Config.SpeedType = "kmh"
Config.ShowAlwaysMiniMap = true  -- Always show minimap
Config.UseBlackMoney = false

Config.Belt.active = false  -- No seatbelt system

Config.Visa.active = false  -- No visa system

Config.UseChat = true
Config.UseRPChat = true
Config.UseAdminChat = false

Config.Announcement.active = true
Config.UseTxAdminAnnouncements = true

Config.DefaultHUD = {
    cash = true,
    bank = true,
    black_money = false,
    job = true,
    id = true,
    players = true,
    time = true,
    admins = true,
    street = false,     -- Hide street names
    area = false,       -- Hide area names
    voice = true,
    visa = false,
    speedo = 2,         -- Modern style
}
```

#### Example 3: Balanced Server

```lua
Config.ServerName = "Balanced RP"
Config.SpeedType = "kmh"
Config.ShowAlwaysMiniMap = false
Config.UseBlackMoney = true

Config.Belt.active = true
Config.Belt.key = 'B'

Config.Visa.active = true
Config.Visa.punch_level = 10  -- Default
Config.Visa.other_level_time = 3

Config.UseChat = true
Config.UseRPChat = true
Config.UseAdminChat = false

Config.Announcement.active = true
Config.UseTxAdminAnnouncements = true

Config.DefaultHUD = {
    cash = true,
    bank = true,
    black_money = true,
    job = true,
    id = true,
    players = true,
    time = true,
    admins = true,
    street = true,
    area = true,
    voice = true,
    visa = true,
    speedo = 1,
}
```

***

### 18) In-Game Commands

#### Player Commands

```
/hudsettings        — Open HUD settings menu
/chat               — Open chat (default: T key)
/showhud            — Show HUD
/hidehud            — Hide HUD
/seatbelt           — Toggle seatbelt (default: K key)
```

#### Admin Commands

```
/announcement <duration_sec> <message>               — Send server-wide announcement
/announcementto <playerID> <duration_sec> <message>  — Send announcement to specific player
/setvisa <playerID> <level>                          — Set player visa level (requires permission)
```

***

### 19) Cinematic Mode

**Toggle cinematic mode (letterbox):**

**Event:**

```lua
TriggerEvent('risk:client:hud_off_cine')
```

**Features:**

* Adds black bars (letterbox effect)
* Hides HUD
* Perfect for screenshots/videos
* Toggle on/off

**Just toggle HUD:**

```lua
TriggerEvent('risk:client:hud_toggle')
```

***

### 20) Troubleshooting

#### ❌ HUD not showing

**Possible causes:**

* Framework not detected
* `Config.UseRiskNotifyV2 = false`
* Player not loaded

**Solution:**

* Check server console for framework detection message
* Set `Config.UseRiskNotifyV2 = true`
* Try `/showhud` command
* Relog to server

#### ❌ Speedometer not working

**Possible causes:**

* Update interval too high
* Vehicle class not supported
* HUD hidden

**Solution:**

* Lower `Config.SpeedoMeterUpdateInterval` to 50
* Check if vehicle is a valid drivable vehicle
* Use `/showhud`

#### ❌ Money not updating

**Possible causes:**

* Framework not detected
* Wrong money type configured
* Account doesn't exist

**Solution:**

* Verify framework is started before HUD
* Check `Config.UseBlackMoney` setting
* Enable `Config.DebugMode` to see money update logs

#### ❌ Visa system not working

**Possible causes:**

* `Config.Visa.active = false`
* oxmysql not started
* Database table not created

**Solution:**

* Enable visa system in config
* Ensure `oxmysql` is started first
* Check server console for SQL errors
* Restart resource

#### ❌ Chat not working

**Possible causes:**

* `Config.UseChat = false`
* Both RP and Admin chat disabled
* Framework not detected

**Solution:**

* Set `Config.UseChat = true`
* Enable either `Config.UseRPChat` or `Config.UseAdminChat`
* Verify framework detection

#### ❌ Seatbelt not working

**Possible causes:**

* `Config.Belt.active = false`
* Keybind conflict
* Not in driver seat

**Solution:**

* Enable seatbelt system
* Change `Config.Belt.key` if conflicting
* Must be in driver seat to use seatbelt

#### ❌ Announcements not showing

**Possible causes:**

* `Config.Announcement.active = false`
* No permission
* `Config.UseRiskNotifyV2 = false`

**Solution:**

* Enable announcements in config
* Check admin permissions
* Enable Risk Notify V2

***

### 21) Best Practices

✅ **Enable Debug Mode during setup** — Helps identify issues quickly\
✅ **Test all features after configuration** — Don't assume everything works\
✅ **Balance Visa progression** — Don't make it too easy or too hard\
✅ **Customize for your server type** — RP servers need different settings than action servers\
✅ **Use seatbelt system on RP servers** — Adds realism and consequence\
✅ **Give players `/hudsettings` access** — Let them customize their experience\
✅ **Keep announcements concise** — Long messages are annoying\
✅ **Use appropriate notification types** — success, error, info, warning\
✅ **Monitor performance** — Lower update intervals if needed\
✅ **Keep admin permissions secure** — Only trusted staff should have announcement access

***

### 22) Performance Optimization

**For low-end servers:**

```lua
Config.SpeedoMeterUpdateInterval = 100  -- Reduce speedometer updates
Config.ShowAlwaysMiniMap = false         -- Save resources
Config.UseItemNotify = false             -- Disable if not needed
Config.Visa.active = false               -- Disable if not used
```

**For high-end servers:**

```lua
Config.SpeedoMeterUpdateInterval = 10   -- Smooth updates
Config.ShowAlwaysMiniMap = true         -- Better UX
Config.UseItemNotify = true             -- Full features
Config.Visa.active = true               -- All systems enabled
```


---

# Agent Instructions: 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:

```
GET https://risk-scripts.gitbook.io/risk-scripts/scripts/hud-v2.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
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.