# Configuration

`HUD System` uses a configuration file located in:

* `data/config.lua`

This file controls localization, update intervals, default variants, minimap behavior, optional integrations, weapon images, weather icons, key mappings, and minimap defaults.

### Localization

```lua
Locale = 'en' -- 'en' or 'pl'
```

Defines which language should be used.

Supported values:

* `en`
* `pl`

To add a new language, copy `locales/en.json` and create your own language file.

***

### General Settings

```lua
Locale = 'en'
```

This defines the default resource language.

***

### Update Intervals

These settings control how often each HUD section refreshes.

```lua
Intervals = {
    Status = 250,
    Vehicle = 100,
    Watermark = 2000,
    Location = 200,
    Weapon = 150,
    Minimap = 500,
}
```

#### `Status`

Refresh rate for:

* health
* armor
* stamina
* food
* drink
* alcohol
* oxygen

#### `Vehicle`

Refresh rate for vehicle HUD data such as:

* speed
* RPM
* gear
* fuel
* engine health
* nitro

#### `Watermark`

Refresh rate for:

* player name
* money
* weather
* time

#### `Location`

Refresh rate for:

* street name
* compass heading

#### `Weapon`

Refresh rate for weapon and ammo information.

#### `Minimap`

Refresh rate for minimap-related logic.

> Lower values make updates smoother, but they also increase CPU usage.

***

### Default Variants

These are the default visual styles used by the HUD.

```lua
Variants = {
    Watermark = 'glass',
    WatermarkMode = 'full',
    Status = 'hexagon',
    Location = 'compass',
    Car = 'modern',
}
```

#### `Watermark`

Supported values:

* `glass`
* `clean`
* `neon`

#### `WatermarkMode`

Supported values:

* `full`
* `small`

#### `Status`

Supported values:

* `circle`
* `hexagon`
* `square`
* `bars`
* `modern`
* `pills`

#### `Location`

Supported values:

* `compass`
* `pill`
* `minimap`

#### `Car`

Supported values:

* `modern`
* `sport`
* `digital`
* `gauge`
* `classic`

Players can override these defaults from the in-game HUD settings panel.

***

### Status Defaults

```lua
StatusFilled = false
StatusShowPercent = true
```

#### `StatusFilled`

When enabled, status icons use filled styling instead of outlined styling.

#### `StatusShowPercent`

When enabled, status values are shown as percentages.

***

### Minimap Visibility

```lua
ShouldShowMinimap = function(alwaysOn)
    if cache.vehicle or alwaysOn then return true end
    local state = LocalPlayer.state
    if state.PhoneOpen or state.IsJail or state.NoClip or state.BattleRoyalGame then
        return true
    end
    return false
end
```

This function controls when the GTA minimap should be visible.

You can modify this function to add your own custom conditions.

***

### Optional Integrations

```lua
FuelSystem = true
NitroSystem = GetResourceState('prp_nitro') == 'started'
```

#### `FuelSystem`

Enables the fuel gauge in the vehicle HUD.

#### `NitroSystem`

Enables nitro support if the required nitro resource is active.

***

### Weapon Image Configuration

```lua
WeaponImageUrl = 'https://upload.domain.pl/static/%s.png'
```

Defines the image path used for weapon icons.

`%s` is replaced by the configured weapon name.

Example:

```lua
https://upload.domain.pl/static/WEAPON_PISTOL.png
```

***

### Weapons Table

```lua
Weapons = {
    [`WEAPON_PISTOL`] = 'WEAPON_PISTOL',
    [`WEAPON_COMBATPISTOL`] = 'WEAPON_COMBATPISTOL',
    [`WEAPON_ASSAULTRIFLE`] = 'WEAPON_ASSAULTRIFLE',
}
```

This table maps GTA weapon hashes to image names and translation keys.

Each value is also used as the translation key inside `locales/*.json` under `weapons.*`.

***

### Sniper Scope Weapons

```lua
SniperRifleWeapons = {
    [`WEAPON_SAUER`] = true,
}
```

Weapons listed here use the native GTA crosshair instead of the custom HUD crosshair.

This is useful for sniper rifles and scoped weapons.

***

### Weather Entries

```lua
WeatherEntries = {
    { 'CLEAR',      'fa-sun' },
    { 'EXTRASUNNY', 'fa-sun' },
    { 'CLOUDS',     'fa-cloud' },
    { 'RAIN',       'fa-cloud-rain' },
    { 'THUNDER',    'fa-cloud-bolt' },
    { 'SNOW',       'fa-snowflake' },
}
```

This table maps GTA weather names to Font Awesome icons.

Weather labels are taken from the locale files under `weather.*`.

***

### Key Mappings

```lua
KeyMappings = {
    INPUT_CONTEXT = 'E',
    INPUT_ENTER = 'F',
    INPUT_RELOAD = 'R',
    INPUT_SPRINT = 'LEFT SHIFT',
    INPUT_JUMP = 'SPACE',
}
```

This table replaces GTA `~INPUT_*~` tokens in help notifications with readable key labels.

You can add or edit mappings depending on your needs.

***

### Minimap Defaults

```lua
MinimapStyle = 'rectangle'

MinimapPlacer = {
    offsetX = 0.0,
    offsetY = -0.03,
    scale = 0.0,
}
```

#### `MinimapStyle`

Supported values:

* `rectangle`
* `circle`

#### `MinimapPlacer`

Defines the default minimap position and scale.

* `offsetX` — horizontal offset
* `offsetY` — vertical offset
* `scale` — additional scale

These values can also be changed in-game through the minimap placer.

***

### Command

```lua
/hud
```

Opens the HUD settings panel.

***

### Client Exports

#### `Send`

```lua
exports['msk_hud']:Send(message, title, icon, timeout, type)
```

Shows a notification.

Supported `type` values:

* `info`
* `success`
* `error`
* `warning`

#### `SendAdvanced`

```lua
exports['msk_hud']:SendAdvanced(message, title, icon, timeout, type)
```

Alias for `Send`.

#### `ServerAlert`

```lua
exports['msk_hud']:ServerAlert(message, title, sender, type, duration)
```

Shows a full-screen server alert banner.

#### `ChangeStatus`

```lua
exports['msk_hud']:ChangeStatus({
    hunger = 100,
    thirst = 100,
    drunk = 0,
})
```

Updates HUD status values.

#### `UpdateVoice`

```lua
exports['msk_hud']:UpdateVoice(active, range)
```

Updates the voice activity indicator and voice range.

#### `ShowHelpNotification`

```lua
exports['msk_hud']:ShowHelpNotification(name, text)
```

Shows a help notification.

#### `SetHudHidden`

```lua
exports['msk_hud']:SetHudHidden(val)
```

Shows or hides the full HUD.

#### Variant Exports

```lua
exports['msk_hud']:SetCarVariant(variant)
exports['msk_hud']:SetStatusVariant(variant)
exports['msk_hud']:SetWatermarkVariant(variant)
exports['msk_hud']:SetLocationVariant(variant)
```

These exports change the active HUD variants.

#### Minimap Exports

```lua
exports['msk_hud']:UseMinimapPlacer()
exports['msk_hud']:SetMinimapPlacer(offX, offY, scale)
```

Used to open or control the minimap placement tool.

***

### Client Events

#### `msk_hud:sendNotify`

Shows a notification.

#### `msk_hud:sendAdvancedNotify`

Alias for the notification event.

#### `msk_hud:serverAlert`

Shows a server alert banner.

***

### Server Callbacks

#### `msk_hud:getWatermarkData`

Returns the player character name for the watermark.

#### `msk_hud:sharePreset`

Stores a preset in the database and returns a share code.

#### `msk_hud:importPreset`

Loads a preset by its share code.

***

### HUD Sections

The HUD includes the following main sections:

#### Watermark

Displays:

* player name
* server ID
* money
* weather
* time
* voice indicator
* weapon information

#### Status HUD

Displays:

* health
* armor
* stamina
* hunger
* thirst
* alcohol
* oxygen

#### Location HUD

Displays:

* street name
* compass heading

#### Vehicle HUD

Displays:

* speed
* RPM
* gear
* fuel
* engine health
* nitro
* temperature
* handbrake

#### Minimap Frame

Displays a styled frame around the GTA minimap and waypoint distance information.

#### Crosshair

Displays a customizable crosshair with configurable parts and colors.

#### Notifications

Displays toast notifications with support for custom icons.

#### Server Alerts

Displays a full-width banner alert with sound effects.

#### Help Notifications

Displays short contextual on-screen help text.

#### Settings Panel

Allows players to customize:

* variants
* colors
* thresholds
* icons
* minimap placement
* positions
* scales
* presets

***

### Controls

#### Main

* `/hud` — open settings panel
* `ESC` — close settings

#### Crosshair

* hold `RMB` — show custom crosshair

#### Minimap Placer

* arrow keys — move minimap
* `Numpad +` / `Numpad -` — scale minimap
* `SHIFT` — faster movement
* `CTRL` — slower movement
* `ENTER` — confirm placement

#### Layout Editor

* mouse drag — move HUD elements
* right click — open scaling context menu

***

### Notes

* HUD updates use a diff system, so unchanged values are not resent to the UI
* Minimap position is saved in client KVP storage
* Settings are saved in local storage
* Presets can be shared through the database
* Streamer mode hides sensitive watermark details
* Cinematic mode can hide the HUD without disabling the resource
* Sniper weapons can use the native GTA crosshair
* Voice mute state is read from the player state bag


---

# 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://mskscripts.gitbook.io/mskscripts/scripts/hud-system/configuration.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.