> ## Documentation Index
> Fetch the complete documentation index at: https://docs.shdevelopment.org/llms.txt
> Use this file to discover all available pages before exploring further.

# sh-hud: Player HUD for FiveM Servers

> sh-hud is a standalone NUI heads-up display for FiveM that shows speed, fuel, gear, compass, and plate — no framework required.

sh-hud is a lightweight, fully standalone heads-up display resource that gives players at-a-glance information without relying on any server framework. It automatically detects whether a player is on foot or inside a vehicle and switches between two distinct display panels, fading smoothly between them every 200 ms. Because all behavior is built directly into the resource, there is no configuration file to edit and no external dependencies to manage — simply drop it into your server and start it.

## What sh-hud Displays

sh-hud renders two panels depending on the player's current state.

<Tabs>
  <Tab title="On-Foot Panel">
    When a player is not inside a vehicle, sh-hud shows a compact panel with the following information:

    | Field         | Description                                                                                            |
    | ------------- | ------------------------------------------------------------------------------------------------------ |
    | **Server ID** | The player's current FiveM server ID                                                                   |
    | **Compass**   | Cardinal and intercardinal direction (N, NE, E, SE, S, SW, W, NW) based on the player's entity heading |
  </Tab>

  <Tab title="Vehicle Panel">
    When a player enters any vehicle, sh-hud automatically transitions to the vehicle panel:

    | Field             | Description                                                                 |
    | ----------------- | --------------------------------------------------------------------------- |
    | **Server ID**     | The player's current FiveM server ID                                        |
    | **Licence Plate** | The plate string of the occupied vehicle                                    |
    | **Speed**         | Current speed in MPH                                                        |
    | **Gear**          | Current gear — displays `N` when stationary and `R` when reversing at speed |
    | **Fuel**          | Fuel level as a percentage                                                  |
    | **Compass**       | Cardinal and intercardinal direction based on player entity heading         |
  </Tab>
</Tabs>

## Installation

Installing sh-hud takes only two steps.

<Steps>
  <Step title="Add the resource to your server">
    Download the `sh-hud` folder and place it inside your server's `resources` directory.

    ```
    resources/
    └── sh-hud/
        ├── fxmanifest.lua
        ├── client/
        └── nui/
    ```
  </Step>

  <Step title="Start the resource in server.cfg">
    Open your `server.cfg` file and add the following line. Place it after any resources sh-hud should load alongside, though ordering is flexible since sh-hud has no dependencies.

    ```cfg server.cfg theme={null}
    ensure sh-hud
    ```
  </Step>
</Steps>

<Note>
  sh-hud has no `config.lua` and no exported functions. All HUD behavior — update interval, panel transitions, displayed fields, and compass logic — is built into the resource and cannot be changed without modifying the source directly.
</Note>

## Technical Details

<Accordion title="Update interval and performance">
  sh-hud polls vehicle and player data every **200 ms** inside a NUI-driven loop. This interval keeps the display responsive while keeping client-side CPU overhead minimal. The panels use CSS transitions to fade in and out smoothly whenever the player enters or exits a vehicle, so there is no jarring visual snap between states.
</Accordion>

<Accordion title="Compass calculation">
  The compass direction is derived from the player's entity heading value (0–360°), normalised to always be positive, and mapped to the nearest of the eight cardinal and intercardinal points. The value updates on the same 200 ms cycle as all other HUD fields.

  | Heading Range   | Displayed Direction |
  | --------------- | ------------------- |
  | 337.5° – 22.5°  | N                   |
  | 22.5° – 67.5°   | NW                  |
  | 67.5° – 112.5°  | W                   |
  | 112.5° – 157.5° | SW                  |
  | 157.5° – 202.5° | S                   |
  | 202.5° – 247.5° | SE                  |
  | 247.5° – 292.5° | E                   |
  | 292.5° – 337.5° | NE                  |
</Accordion>

<Accordion title="Gear display logic">
  | Condition                                         | Displayed Label            |
  | ------------------------------------------------- | -------------------------- |
  | Speed = 0 and gear = 0, or speed = 0 and gear = 1 | `N` (neutral / stationary) |
  | Speed > 0 and gear = 0                            | `R` (reversing)            |
  | Gear 1–8 at speed                                 | `1` – `8`                  |
</Accordion>

<Tip>
  Because sh-hud is fully standalone, it is safe to run alongside any framework — ESX, QBCore, or a custom stack — without conflict.
</Tip>