Configuration

NN-HUD Configuration Guide

Overview

The NN-HUD configuration file (config.lua) provides comprehensive control over the HUD system's behavior, appearance, and functionality. This guide will walk you through all available configuration options and their impact on your FiveM server.

Table of Contents

• Framework Selection

• General Settings

• Stress System Configuration

• Whitelist Configuration

• Vehicle Class Stress Settings

• Stress Effect Configuration

• HUD Display Settings

• Resource Integration

• Minimap Configuration

• Update Intervals

• UI Theme Settings

• Key Bindings

• Debug Mode

Framework Selection

Config.Framework = 'qb' -- Change to 'esx' for ESX or 'qb' for QBCore

Description: Specifies which framework your server uses.

Options:

• 'qb' - QBCore Framework

• 'esx' - ESX Framework

Example:

-- For QBCore servers
Config.Framework = 'qb'

-- For ESX servers
Config.Framework = 'esx'

General Settings

Config.UseMPH = true -- If true speed will be shown in MPH, if false KPH
Config.DisableStress = true -- If true, stress system will be completely disabled
Config.DisableStamina = true -- If true, stamina system will be completely disabled
Config.DisableOxygen = false -- If true, oxygen system will be completely disabled
Config.UseDistanceInMiles = true -- If true, GPS distance will be shown in miles, if false in kilometers

Description: Core system settings that control basic HUD functionality.

Options:

• UseMPH - Speed display unit (MPH/KPH)

• DisableStress - Completely disable stress system

• DisableStamina - Completely disable stamina system

• DisableOxygen - Completely disable oxygen system

• UseDistanceInMiles - GPS distance unit (miles/kilometers)

Stress System Configuration

Config.StressChance = 0.1 -- Percentage chance of gaining stress when shooting (0-1)
Config.MinimumStress = 50 -- Minimum stress level for screen effects
Config.MinimumSpeedUnbuckled = 50 -- Speed limit without seatbelt before gaining stress
Config.MinimumSpeed = 100 -- Speed limit with seatbelt before gaining stress

Description: Controls how the stress system behaves and when stress is gained.

Parameters:

• StressChance - Probability of gaining stress when shooting (0.0 to 1.0)

• MinimumStress - Minimum stress level required for visual effects

• MinimumSpeedUnbuckled - Speed threshold for stress gain without seatbelt

• MinimumSpeed - Speed threshold for stress gain with seatbelt

Example:

-- More aggressive stress system
Config.StressChance = 0.3
Config.MinimumStress = 30
Config.MinimumSpeedUnbuckled = 30
Config.MinimumSpeed = 80

-- Relaxed stress system
Config.StressChance = 0.05
Config.MinimumStress = 70
Config.MinimumSpeedUnbuckled = 80
Config.MinimumSpeed = 120

Whitelist Configuration

Whitelisted Jobs

Config.WhitelistedJobs = {
    ['police'] = true,
    ['ambulance'] = true,
    ['leo'] = true
}

Description: Jobs that are exempt from stress gain and certain HUD restrictions.

Usage: Add job names as keys with true values to whitelist them.

Example:

Config.WhitelistedJobs = {
    ['police'] = true,
    ['ambulance'] = true,
    ['leo'] = true,
    ['mechanic'] = true,
    ['taxi'] = true
}

Whitelisted Weapons

Config.WhitelistedWeapons = {
    [`weapon_petrolcan`] = true,
    [`weapon_hazardcan`] = true,
    [`weapon_fireextinguisher`] = true,
    [`weapon_flashlight`] = true
}

Description: Weapons that won't trigger armed status or cause stress gain.

Usage: Add weapon hashes as keys with true values to whitelist them.

Example:

Config.WhitelistedWeapons = {
    [`weapon_petrolcan`] = true,
    [`weapon_hazardcan`] = true,
    [`weapon_fireextinguisher`] = true,
    [`weapon_flashlight`] = true,
    [`weapon_parachute`] = true,
    [`weapon_briefcase`] = true
}

Vehicle Class Stress Settings

Config.VehClassStress = {
    [0] = true,   -- Compacts
    [1] = true,   -- Sedans
    [2] = true,   -- SUVs
    [3] = true,   -- Coupes
    [4] = true,   -- Muscle
    [5] = true,   -- Sports Classics
    [6] = true,   -- Sports
    [7] = true,   -- Super
    [8] = true,   -- Motorcycles
    [9] = true,   -- Off Road
    [10] = true,  -- Industrial
    [11] = true,  -- Utility
    [12] = true,  -- Vans
    [13] = false, -- Cycles
    [14] = false, -- Boats
    [15] = false, -- Helicopters
    [16] = false, -- Planes
    [18] = false, -- Emergency
    [19] = false, -- Military
    [20] = false, -- Commercial
    [21] = false  -- Trains
}

Description: Controls which vehicle classes can cause stress when speeding.

Vehicle Classes:

• 0-12 - Ground vehicles (can cause stress)

• 13-21 - Special vehicles (no stress gain)

Example:

-- Only allow stress from sports and super cars
Config.VehClassStress = {
    [0] = false,  -- Compacts
    [1] = false,  -- Sedans
    [2] = false,  -- SUVs
    [3] = false,  -- Coupes
    [4] = false,  -- Muscle
    [5] = true,   -- Sports Classics
    [6] = true,   -- Sports
    [7] = true,   -- Super
    -- ... rest set to false
}

Stress Effect Configuration

Stress Intensity Settings

Config.StressIntensity = {
    [1] = {
        min = 50,
        max = 60,
        intensity = 1500,
    },
    [2] = {
        min = 60,
        max = 70,
        intensity = 2000,
    },
    [3] = {
        min = 70,
        max = 80,
        intensity = 2500,
    },
    [4] = {
        min = 80,
        max = 90,
        intensity = 2700,
    },
    [5] = {
        min = 90,
        max = 100,
        intensity = 3000,
    },
}

Description: Defines stress levels and their corresponding visual effect intensity.

Parameters:

• min - Minimum stress level for this tier

• max - Maximum stress level for this tier

• intensity - Visual effect intensity (higher = more intense)

Stress Effect Intervals

Config.StressEffectInterval = {
    [1] = {
        min = 50,
        max = 60,
        timeout = math.random(50000, 60000)
    },
    [2] = {
        min = 60,
        max = 70,
        timeout = math.random(40000, 50000)
    },
    [3] = {
        min = 70,
        max = 80,
        timeout = math.random(30000, 40000)
    },
    [4] = {
        min = 80,
        max = 90,
        timeout = math.random(20000, 30000)
    },
    [5] = {
        min = 90,
        max = 100,
        timeout = math.random(15000, 20000)
    }
}

Description: Controls how often stress effects trigger at different stress levels.

Parameters:

• min/max - Stress level range

• timeout - Time interval between effects (in milliseconds)

HUD Display Settings

Config.HudSettings = {
    showHealth = true,
    showArmor = true,
    showHunger = true,
    showThirst = true,
    showStress = true,
    showOxygen = true,
    showVoice = true,
    showSpeed = true,
    showFuel = true,
    showEngine = true,
    showSeatbelt = true,
    showCruise = true,
    animateStatusBars = true,
}

Description: Controls which HUD elements are displayed and their behavior.

Options:

• showHealth - Display health bar

• showArmor - Display armor bar

• showHunger - Display hunger bar

• showThirst - Display thirst bar

• showStress - Display stress bar

• showOxygen - Display oxygen bar

• showVoice - Display voice indicator

• showSpeed - Display speedometer

• showFuel - Display fuel gauge

• showEngine - Display engine health

• showSeatbelt - Display seatbelt status

• showCruise - Display cruise control status

• animateStatusBars - Enable smooth animations

Example:

-- Minimal HUD for performance
Config.HudSettings = {
    showHealth = true,
    showArmor = true,
    showHunger = false,
    showThirst = false,
    showStress = false,
    showOxygen = false,
    showVoice = true,
    showSpeed = true,
    showFuel = true,
    showEngine = false,
    showSeatbelt = true,
    showCruise = true,
    animateStatusBars = false,
}

Resource Integration

Config.FuelResource = 'LegacyFuel' -- Change this to your fuel resource name
Config.VoiceResource = 'pma-voice' -- Change this to your voice resource name

Description: Specifies which resources to integrate with for fuel and voice functionality.

Common Options:

• Fuel: 'LegacyFuel', 'ps-fuel', 'ox_fuel'

• Voice: 'pma-voice', 'mumble-voip', 'toko-voip'

Minimap Configuration

Config.MinimapWalking = true -- Show minimap when walking (true/false)
Config.MinimapTexture = 'nano_minimap' -- Texture dictionary name for custom minimap

Description: Controls minimap behavior and appearance.

Options:

• MinimapWalking - Show minimap when on foot

• MinimapTexture - Custom minimap texture (requires resource)

Update Intervals

Config.UpdateIntervals = {
    playerStats = 100,    -- How often to update player stats
    vehicleStats = 8,     -- How often to update vehicle stats (~120fps for ultra-smooth gear progress)
    stress = 10000,       -- How often to check for stress gain
    fuel = 2000,          -- How often to check fuel level
}

Description: Controls how frequently different HUD elements update.

Parameters:

• playerStats - Player health, armor, hunger, thirst updates (ms)

• vehicleStats - Vehicle speed, fuel, engine updates (ms)

• stress - Stress system checks (ms)

• fuel - Fuel level checks (ms)

Performance Tips:

• Lower values = smoother updates but higher CPU usage

• Higher values = better performance but less responsive HUD

UI Theme Settings

Config.Theme = {
    primaryColor = '#3b82f6',     -- Blue
    successColor = '#10b981',     -- Green
    dangerColor = '#ef4444',      -- Red
    backgroundColor = '#1f2937',  -- Dark gray
    textColor = '#ffffff',        -- White
    opacity = 0.8,                -- Overall HUD opacity
}

Description: Controls the visual appearance of the HUD.

Color Options:

• primaryColor - Main accent color

• successColor - Success/good status color

• dangerColor - Danger/warning color

• backgroundColor - HUD background color

• textColor - Text color

• opacity - Overall transparency (0.0 to 1.0)

Example Themes:

-- Dark Theme
Config.Theme = {
    primaryColor = '#3b82f6',
    successColor = '#10b981',
    dangerColor = '#ef4444',
    backgroundColor = '#1f2937',
    textColor = '#ffffff',
    opacity = 0.9,
}

-- Light Theme
Config.Theme = {
    primaryColor = '#2563eb',
    successColor = '#059669',
    dangerColor = '#dc2626',
    backgroundColor = '#f3f4f6',
    textColor = '#1f2937',
    opacity = 0.8,
}

Key Bindings

Config.Keys = {
    seatbelt = 'b',
    cruise = 'x',
    engine = 'g',
}

Description: Defines key bindings for HUD-related functions.

Available Functions:

• seatbelt - Toggle seatbelt

• cruise - Toggle cruise control

• engine - Toggle engine

Example:

Config.Keys = {
    seatbelt = 'f',    -- Use F key for seatbelt
    cruise = 'c',      -- Use C key for cruise control
    engine = 'e',      -- Use E key for engine toggle
}

Debug Mode

Config.Debug = false -- Disabled to prevent console spam

Description: Enables debug mode for troubleshooting.

Usage:

• true - Enable debug messages in console

• false - Disable debug messages (recommended for production)

Implementation Tips

Performance Optimization

1. Adjust Update Intervals:

   Config.UpdateIntervals = {
       playerStats = 200,    -- Less frequent updates
       vehicleStats = 16,    -- Lower refresh rate
       stress = 15000,       -- Less frequent stress checks
       fuel = 3000,          -- Less frequent fuel checks
   }

2. Disable Unused Features:

   Config.HudSettings = {
       showHealth = true,
       showArmor = true,
       showHunger = false,   -- Disable if not using hunger
       showThirst = false,   -- Disable if not using thirst
       -- ... disable other unused features
   }

3. Optimize Stress System:

   Config.DisableStress = true  -- Disable if not using stress

Customization Examples

Realistic Police Server:

Config.StressChance = 0.2
Config.MinimumSpeed = 120
Config.WhitelistedJobs = {
    ['police'] = true,
    ['ambulance'] = true,
    ['leo'] = true,
    ['mechanic'] = true,
}

Casual Gaming Server:

Config.DisableStress = true
Config.DisableStamina = true
Config.UseMPH = false  -- Use KPH for international players

Racing Server:

Config.MinimumSpeed = 150
Config.VehClassStress = {
    [6] = true,   -- Sports
    [7] = true,   -- Super
    -- All others false
}

Troubleshooting

Common Issues

1. HUD Not Showing:

   • Check if all required resources are started

   • Verify framework selection is correct

   • Ensure player has required permissions

2. Performance Issues:

   • Increase update intervals

   • Disable unused HUD elements

   • Reduce stress effect intensity

3. Resource Conflicts:

   • Ensure only one HUD resource is active

   • Check for conflicting key bindings

   • Verify resource load order

Support

For additional support or feature requests, please refer to the resource documentation or contact the development team.

---

This documentation covers all configuration options available in the NN-HUD system. Adjust settings according to your server's specific needs and performance requirements.