# V-HUD

> V-HUD focuses on modularity. Each widget (status bars, vehicle info, minimap controls) can be enabled, disabled, or repositioned through configuration files or player settings.

## Overview

V-HUD is designed for communities that want a flexible HUD without maintaining multiple forks. It typically includes a configuration interface that allows players to toggle elements on the fly, making it a great option for servers with diverse roleplay styles.

## Core Widgets

- Player vitals: health, armour, thirst, hunger, stress, and stamina
- Voice and radio indicators compatible with pma-voice or mumble-voip
- Vehicle HUD with seatbelt, cruise control, headlights, and turn signals
- Minimap controller with auto-hide, zoom level, and border styling
- Progress circle and interaction prompts for use with qb-target or custom scripts

## Installation Steps

1. Download the V-HUD package and place it in `resources/[qb]/v-hud`.
2. Disable `qb-hud` and other HUD overlays.
3. Add `ensure v-hud` to `server.cfg` after any voice or status resources:

   ```cfg
   ensure qb-core
   ensure pma-voice
   ensure v-hud
   ```

4. Import optional SQL if the resource saves player preferences server-side.
5. Restart your server, join in-game, and open the configuration menu (commonly `/vhud` or a keybind) to verify functionality.

## Configuration Overview

- `Config.Modules`: Toggle each widget and define default positions on screen.
- `Config.Metadata`: Map status keys to match your server's naming convention.
- `Config.Commands`: Enable command shortcuts for toggling modules or opening the HUD settings menu.
- `Config.Storage`: Choose between local storage (client-side) or database saving for per-player settings.
- `Config.Performance`: Adjust update intervals and animation speeds to match your target FPS.

## Player Customization

Many V-HUD builds ship with a settings UI that allows players to:

- Move widgets via drag-and-drop or arrow nudges
- Change opacity, scaling, or colour themes
- Toggle modules such as the minimap, compass, or seatbelt indicator
- Reset to default layout if something breaks

Encourage players to export their settings file after customization so they can restore it later.

## Troubleshooting

| Issue | Fix |
|-------|-----|
| Widgets reset every restart | Ensure database saving is configured or instruct players to export their settings locally. |
| Voice indicator not showing | Confirm `Config.Metadata.Voice` matches the event emitted by your voice resource. |
| Widgets overlap other UI | Adjust the default positions in `Config.Modules` or instruct players to move them using the settings UI. |
| FPS drops when HUD visible | Increase the update interval and disable optional animations in `Config.Performance`. |

## Additional Resources

- Developer documentation included with the download
- Community themes shared on Discord or GitHub gists
- [Pure HUD](/resources/hud/pure-hud) for a lighter setup or [TREW HUD](/resources/hud/trew-hud) for a feature-dense alternative
