> For the complete documentation index, see [llms.txt](https://docs.menanak47.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.menanak47.com/multi-framework/ak47_hud/configuration-guide.md).

# Configuration Guide

The `ak47_hud` is designed to be highly modular. Whether you want a plug-and-play experience or want to micromanage every pixel and system, the `config.lua` and `presets.lua` files give you absolute control.

Below is a guide on how to configure your new HUD, ranging from basic feature toggles to advanced UI presets.

***

### 🟢 1. Basic Configuration (Global Toggles)

If you only want to use certain parts of the HUD (for example, you already have a chat script or a seatbelt script you prefer), you can easily disable our built-in systems.

Open `config.lua` and locate the **GLOBAL HUD TOGGLES** section.

```lua
Config.UseChat = true
Config.UsePartyFrame = true
Config.UseCrosshair = true
Config.UseSeatBelt = false -- Set to false to use an external seatbelt script
Config.UsePoliceRadar = true
Config.UseCustomizer = true -- Allows players to type /hud

```

* **Community Name:** Don't forget to change `Config.CommunityName = 'Ak47 Server'` to your actual server name so it displays correctly in the player's `/hud` menu!
* **Default UI:** By default, the script hides the native GTA ammo, vehicle name, and street names to prevent overlapping. You can toggle these back on under the **GTA DEFAULT UI ELEMENT** section.

***

### 🔵 2. Tuning Core Systems

#### 😰 Stress System

The stress system uses dynamic multipliers instead of hardcoded checks. You can configure exactly who gets stress and how much.

* **Job Multipliers:** Multiply stress gained based on the job. `0.0` means no stress, `2.0` means double stress.

```lua
Config.Stress.JobStressMultiplier = {
    police = 0.3,    -- Cops get 70% less stress
    ambulance = 0.0, -- EMS get ZERO stress
}

```

* **Complete Exemptions:** If you want to entirely disable stress for certain weapons or vehicle classes (like helicopters or boats), add them to the `NoStress` tables:

```lua
Config.Stress.NoStressVehicleClass = {
    [14] = true, -- Boats
    [15] = true, -- Helicopters
    [16] = true, -- Planes
}

```

#### 🏎️ Seatbelt System

You can configure at what speeds players are ejected through the windshield (`Config.MinSpeedToEjectUnbuckled`).

* **Whitelists/Blacklists:** Use `Config.BlacklistedClasses = {8, 13, 14, 15, 16, 21}` to ensure players don't get a "Press B to buckle" prompt while riding a bicycle or flying a plane.

#### 💬 Chat Channels & Templates

Under `Config.ChatSubChannels`, you can edit the icons and colors of the chat tabs (OOC, Me, Do, 911). You can also completely redesign how messages look by editing the HTML inside `Config.ChatTemplates`.

***

### 🟣 3. Customizer Access (Permissions)

By default, players can type `/hud` to open a massive customization menu. As a server owner, you might want to restrict what they can change to maintain a consistent server theme.

Locate `Config.CustomizerAccess`.

* **Bulk Access:** Disabling items here removes the entire category from the `/hud` menu.
* **Single Access:** This allows you to micromanage specific settings.
* *Example:* You want players to be able to change the color of their Minimap, but you want to FORCE the minimap to stay round and a specific size. You would change `minimapShape = false`, `height = false`, and `width = false` inside `Config.CustomizerAccess.Single.minimap`.

***

### 🔴 4. Advanced: Forced UI Overwrites

If you want to force a specific UI style on **all players** (overriding their personal saved settings), you will use the `Config.SettingOverwrite` section at the bottom of `config.lua`.

**How it works:** By default, everything in this section is commented out (with `--`). This means the script uses the player's saved NUI preferences. If you uncomment a line, you **lock** that setting server-wide.

**Example: Forcing a specific Status HUD style** If you want everyone on the server to use the "water" fill style with square icons, you would uncomment those specific lines:

```lua
    statusHud = {
        -- show = true,
        displayStyle = "icon", 
        -- size = 70,
        radius = 4, -- Forces square corners
        -- borderSize = 2,
        fillStyle = "water", -- Forces the water animation
    },

```

***

### 🌟 5. Server Presets (Fast Configs)

Instead of forcing a single style on everyone, you can create **Server Presets**. These act as "Themes" that players can select with one click inside their `/hud` menu (e.g., "Dark Mode", "Neon Theme", "Minimalist").

To add a preset, open the **`presets.lua`** file.

Here is a template for creating a new preset. You define the ID, the Display Name, and then pass any UI settings you want that preset to change:

```lua
table.insert(Config.ServerPresets, {
    id = "cyberpunk_theme",
    name = "Cyberpunk Neon",
    hudItems = {
        -- Make the minimap square with a pink border
        minimap = {
            minimapShape = "squaremap"
        },
        minimapRing = {
            color1 = "#ff00ff"
        },
        -- Turn the health and armor bars into a glowing neon style
        health = {
            color1 = "#ff00ff",
            color2 = "#200020",
            fillStyle = "water"
        },
        armor = {
            color1 = "#00ffff",
            color2 = "#002020",
            fillStyle = "water"
        },
        -- Customize the speedo
        vehicleDigital = {
            speedUnit = "KMH",
            color1 = "#ff00ff"
        }
    }
})

```

**How to find the setting names:** Look at the `Config.SettingOverwrite` section in `config.lua`. Every variable listed there (like `color1`, `radius`, `fillStyle`, `shadow`) can be used inside a preset!