# Odometer

The Odometer system provides a detailed in-vehicle status HUD, showing real-time health indicators, safety equipment, lighting status, mileage, and NOS information. It supports both visual indicators and optional numerical health values.

***

### Features

* Shows condition of:
  * Engine, body, axle, oil, spark, fuel, battery, tyres
* Displays:
  * Seatbelt & harness status
  * NOS level or purge state
  * Headlights, underglow, door state, manual mode, anti-lag
* Live mileage tracking (format: `000000`)
* Damage visibility logic (only show when under threshold or always-on)
* Can restrict visibility to only driver or show certain icons to passengers
* Integration with `ExtraDamageComponents` for deeper damage display
* Customizable icon glow, positioning, color, and styling
* Modular NUI messages for each icon with full canvas customization

***

### Configuration (in `Config.Odometer`)

<details>

<summary>Config</summary>

#### General Toggles

* `ShowOdo`\
  Enables or disables the odometer mileage display HUD by default.\
  Players can override it in-game using the `/showodohud` and `/hideodohud` commands.
* `ShowToAll`\
  If `true`, all players in the vehicle (not just the driver) can see the odometer icons and data.
* `ShowPassengersAllIcons`\
  When enabled, passengers will also see all odometer icons.\
  If disabled, passengers only see limited icons (e.g., seatbelt/harness).
* `OdoAlwaysShowIcons`\
  Forces all configured icons to always appear, even if their value is healthy.\
  If `false`, icons only appear when a value is under a certain threshold (`OdoShowLimit`).
* `OdoShowLimit`\
  The damage percentage threshold (0–100) below which damage icons will appear.\
  For example, `70` means icons only show if health is below 70%.
* `SeatbeltHideWhenBuckled`\
  If `true`, the seatbelt icon is hidden when the player is buckled.\
  If `false`, it stays visible and changes color based on state (e.g., red/green).
* `HarnessHideWhenBuckled`\
  Same as `SeatbeltHideWhenBuckled` but applies to harnesses.

***

#### Icons Displayed

**`OdoIconsToShow`**

This table defines which indicators appear on the HUD.\
Each key can be `true` (shown) or `false` (hidden):

| Icon Key    | Description                               |
| ----------- | ----------------------------------------- |
| `engine`    | Engine health                             |
| `body`      | Body/chassis integrity                    |
| `oil`       | Oil level (ExtraDamage required)          |
| `spark`     | Spark plug damage (ExtraDamage required)  |
| `fuel`      | Fuel system damage (ExtraDamage required) |
| `axle`      | Axle damage (ExtraDamage required)        |
| `battery`   | Battery health (ExtraDamage required)     |
| `wheel`     | Any tyre burst detection                  |
| `headlight` | Headlight toggle + custom Xenon color     |
| `seatbelt`  | Seatbelt status (and optionally color)    |
| `harness`   | Racing harness status                     |
| `underglow` | Neon/underglow lighting active            |
| `doors`     | One or more doors open                    |
| `manual`    | Manual transmission mode active           |
| `antilag`   | Anti-lag system enabled                   |
| `mileage`   | Display mileage text below HUD            |
| `lowfuel`   | Fuel level below 20%                      |
| `nos`       | NOS pressure meter or purge glow          |

***

#### HUD Appearance — `hudConfig`

* `font`\
  The font used in the odometer HUD (e.g., `DigitalFont`)
* `showHealthValues`\
  If `true`, shows numerical values on icons (e.g., `87` instead of just colored bar)

***

**`position`**

Controls where the HUD appears on screen (percent of screen):

* `top` — Distance from the top (e.g., `70`)
* `left` — Distance from the left (e.g., `1.4`)

***

**`background`**

| Option         | Description                              |
| -------------- | ---------------------------------------- |
| `color`        | RGBA color of the background             |
| `border.color` | Border color                             |
| `border.width` | Border thickness (e.g., `1px`, `0.2rem`) |
| `radius`       | Border radius for rounding HUD corners   |
| `shadow`       | Shadow style and RGBA color              |
| `innerShadow`  | Inset shadow style and color             |

***

**`icons`**

| Option         | Description                                         |
| -------------- | --------------------------------------------------- |
| `glow`         | Enable glow effect on icons                         |
| `size`         | Size of icons (scale unit)                          |
| `colorHealthy` | Color when health is good (RGBA)                    |
| `colorDamaged` | Color when health is poor (RGBA)                    |
| `boxShadow`    | Box shadow styles (enabled, CSS style, corner size) |

***

**`overlayText`**

Text displayed over icons, such as NOS boost level or part %:

| Option     | Description                          |
| ---------- | ------------------------------------ |
| `size`     | Font size (`1.4vh` recommended)      |
| `position` | `{top, left}` CSS string positions   |
| `color`    | RGBA for overlay text                |
| `glow`     | CSS-style glow/shadow effect on text |

***

**`mileage`**

Controls the live mileage number:

| Option    | Description                                 |
| --------- | ------------------------------------------- |
| `enabled` | Whether to show the mileage digits          |
| `size`    | Font size (e.g., `2.3vh`)                   |
| `color`   | RGBA text color                             |
| `glow`    | Glow style and RGBA used on mileage display |

</details>

***

### Commands

* `/showodohud` — Show odometer HUD
* `/hideodohud` — Hide odometer HUD

***

### Notes

* Function: `updateVehicleHUD(distance, vehicle, plate, model, distAdd, seat)`
* Uses `areTablesEqual()` to reduce HUD update spam
