Configuration

Configure nox-hud by editing the shared.lua file.

Basic Settings

Framework

Set your framework type:

Config = {
    framework = 'qb',  -- 'qb' for QBCore, 'esx' for ESX
}

Default Settings

Default HUD state for new players:

defaults = {
    showhud = true,           -- Show HUD by default
    cinemtic = false,         -- Cinematic mode (hide HUD components)
    circlemap = false,        -- Use circular minimap
    showspeedometer = true,   -- Show vehicle speedometer
    showplayerstatus = true,  -- Show player status icons
    showminimap = true,       -- Show minimap
    speedunitmph = false,     -- Use MPH (false = KPH)
    squaremap = false,        -- Use square minimap
},

HUD Settings

Control HUD behavior and positioning:

hud = {
    hideComponents = {6, 7, 8, 9},  -- GTA native HUD components to hide
    pauseCheckInterval = 500,       -- Pause menu check interval (ms)
    infoUpdateInterval = 1000,      -- Info panel update interval (ms)
    minimapExpandRightPx = 14,      -- Minimap expand right offset
    minimapExpandTopPx = 8,         -- Minimap expand top offset
    minimapNudgeRightPx = -10,      -- Minimap nudge right
    minimapNudgeTopPx = 20,         -- Minimap nudge top
    minimapNuiOffsetRightPx = 0,    -- NUI offset right
    minimapNuiOffsetTopPx = 0,      -- NUI offset top
},

Minimap Settings

Configure minimap position and offsets:

minimap = {
    defaultPosition = 'top-right',  -- 'top-left', 'top-right', 'bottom-left', 'bottom-right'
    nuiOffset = {
        L = 28,   -- Left offset
        R = 15,   -- Right offset
        T = 15,   -- Top offset
        B = 30,   -- Bottom offset
    },
    luaBottomOffset = -0.07,  -- Lua-side bottom offset
},

Status Settings

Configure player status update interval:

status = {
    updateInterval = 1200,  -- Status update interval (ms)
},

Fuel Integration

Configure fuel resource integration:

fuel = {
    enabled = true,           -- Enable fuel display
    resource = 'LegacyFuel',  -- Fuel resource name
    export = 'LegacyFuel',    -- Export resource name
    method = 'GetFuel',       -- Export method name
},

Supported Fuel Resources

Currency Display

Configure money display format:

currency = {
    locale = 'en-US',             -- Number format locale
    symbol = '$',                 -- Currency symbol
    position = 'suffix',          -- 'prefix' or 'suffix'
    minimumFractionDigits = 0,    -- Minimum decimal places
    maximumFractionDigits = 0,    -- Maximum decimal places
},

Language / Localization

Customize all HUD text:

lang = {
    hud = {
        job = 'Job',
        cash = 'Cash',
        bank = 'Bank',
        weather = 'Weather',
        time = 'Time',
        serverId = 'Server ID',
        statusTitle = 'Status',
        voiceLabel = 'Voice',
    },

    status = {
        health = 'Health',
        armour = 'Armor',
        hunger = 'Hunger',
        thirst = 'Thirst',
        stress = 'Stress',
        oxygen = 'Oxygen',
    },

    voice = {
        active = 'Active',
        inactive = 'Inactive',
        modes = {
            [0] = 'Muted',
            [1] = 'Normal',
            [2] = 'Shouting',
        }
    },

    vehicle = {
        speedUnitKph = 'KPH',
        speedUnitMph = 'MPH',
        belt = 'BELT',
        fuel = 'FUEL',
        odometer = 'ODOMETER',
        seatbeltOn = 'SEATBELT ON',
        seatbeltOff = 'SEATBELT OFF',
    },

    minimap = {
        directions = {
            N = 'N', NE = 'NE', E = 'E', SE = 'SE',
            S = 'S', SW = 'SW', W = 'W', NW = 'NW',
        }
    },

    settings = {
        hudResetMessage = '[nox-hud] HUD positions have been reset.',
        speedUnitSetMessage = '[nox-hud] Speed unit set to %s.',
        minimapPosMenuTitle = 'Minimap Position',
        topLeft = 'Top Left',
        topRight = 'Top Right',
        bottomLeft = 'Bottom Left',
        bottomRight = 'Bottom Right',
    }
}

Resolution Presets

Edit resolutions.lua to add custom screen resolution presets:

return {
    {
        screenx = 1920,
        screeny = 1080,
        sizex = 250,
        sizey = 190,
        posx = 0.006,
        posy = 0.010,
    },
    {
        screenx = 2560,
        screeny = 1440,
        sizex = 300,
        sizey = 220,
        posx = 0.006,
        posy = 0.010,
    },
    -- Add more resolutions as needed
}

Resolution Parameters

Last updated: January 28, 2026