# 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


---

# 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://jixelpatterns.gitbook.io/docs/paid-assets/jim-mechanic/odometer.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.