Agency-Hud

01 Configuration

Complete config.lua for Agency-Hud. All options documented via inline comments.

Config = {}

-- IMPORTANT:
-- Most settings in this file are fallback defaults only.
-- Manage live/global settings in-game with your configured admin command.

-- =============================================
-- SERVER SETTINGS
-- =============================================
Config.ServerName = "Agency Roleplay"        -- fallback only (use /agencyhudadmin)
Config.ServerTag  = ""                       -- fallback only (use /agencyhudadmin)
Config.ServerLogo = "logo.png"               -- fallback only (use /agencyhudadmin)
Config.ServerNameFont = "inter"              -- fallback only (use /agencyhudadmin)

-- =============================================
-- LOCALE / LANGUAGE
-- =============================================
-- Available: en, de, fr, es, it, pt, nl, pl, cs, sk, ru, tr, ro, hu, sv
Config.Locale = "en"                         -- fallback only (use /agencyhudadmin)

-- =============================================
-- COMMANDS
-- =============================================
-- You can freely rename these commands.
-- Use without slash, e.g. "ahud" not "/ahud"
Config.Commands = {
    Customizer = "ahud",
    Admin      = "agencyhudadmin",
}

-- =============================================
-- HUD DEFAULTS (fallback, global override via /agencyhudadmin)
-- =============================================
Config.DefaultHUD = {
    enabled      = true,
    scale        = 1.0,          -- 0.7 – 2.5
    opacity      = 1.0,          -- 0.1 – 1.0 (background opacity)
    themeMode    = "auto",       -- auto | dark | light (auto = white by day, dark by night)
    position     = "bottom-left",-- bottom-left | bottom-right | bottom-center
    colorAccent  = "#00d4ff",    -- primary accent colour
    colorBg      = "#0a0a1a",    -- background colour
    showHealth   = true,
    showArmor    = true,
    showHunger   = true,
    showThirst   = true,
    showStress   = false,
    showMoney    = true,
    showId       = true,
    showVoice    = true,
    showCompass  = true,
    showClock    = true,
    showStreet   = true,
    showStreetBg = true,
    showHudBg    = true,         -- player HUD panel background
}

-- =============================================
-- AGENCY-NOTIFY INTEGRATION
-- =============================================
-- Requires Agency-Notify resource to be running.
-- Uses exports['agency-notify']:Notify({...})
-- Falls back to legacy TriggerEvent, then chat message. https://agency-script.tebex.io/package/6937769
Config.AgencyNotifyIntegration = true

-- =============================================
-- AGENCY-SEATBELT INTEGRATION
-- =============================================
-- Requires Agency-Seatbelt resource to be running.
-- When enabled, seatbelt status is read from Agency-Seatbelt
-- via exports['agency-seatbelt']:isSeatbeltOn() instead of
-- the built-in K-key toggle. https://agency-script.tebex.io/package/6927501
Config.AgencySeatbeltIntegration = true   -- true = use Agency-Seatbelt, false = built-in toggle (K key)
Config.SeatbeltDefault = false            -- default displayed status while awaiting first update

-- =============================================
-- AGENCY-VEHICLEKEYS INTEGRATION
-- =============================================
-- Requires Agency-Vehiclekeys resource to be running.
-- When enabled, the built-in engine toggle (M key) is disabled;
-- engine control is handled by Agency-Vehiclekeys instead.
Config.AgencyVehiclekeysIntegration = true

-- =============================================
-- AGENCY-REPAIRKIT INTEGRATION
-- =============================================
-- Requires Agency-Repairkit resource to be running.
-- When enabled, vehicle HUD shows a damage/crack warning effect
-- based on engine damage level while driving.
Config.AgencyRepairkitIntegration = true

-- =============================================
-- AGENCY-PHONE INTEGRATION
-- =============================================
-- Requires Agency-Phone resource to be running.
-- When enabled, bottom-right HUD elements adapt while the phone is open.
Config.AgencyPhoneIntegration = true
Config.AgencyPhoneOffset = 120 -- base phone overlap width in px (for bottom-right HUD handling)

-- =============================================
-- VEHICLE HUD DEFAULTS (fallback, global override via /agencyhudadmin)
-- =============================================
Config.DefaultVehicleHUD = {
    enabled      = true,
    vehStyle     = "minimal",      -- minimal | glass | sport | round
    vehPosition  = "bottom-right", -- bottom-right | bottom-center | bottom-left
    vehScale     = 1.0,            -- 0.5 - 4.0
    speedUnit    = "kmh",          -- kmh | mph
    showFuel     = true,
    showRPM      = true,  -- Always visible by default
    showGear     = true,
    showSeatbelt = true,
    showEngine   = true,
    showDamage   = true,         -- vehicle damage/crack warning effect
    showSpeedWarning = false,    -- AgencyAI speed warning visuals (per-player toggle)
    showVehBg    = true,         -- vehicle HUD panel background
    showAirAltitude = true,      -- aircraft altitude gauge
    showBoatWave = true,         -- boat swell / wave gauge
    colorAccent  = "#ff6b35",      -- accent colour for car HUD
    colorBg      = "#080814",      -- background colour for vehicle HUD
}

-- =============================================
-- VOICE INDICATOR / SYSTEM
-- =============================================
-- Shows a microphone status chip in the top-right brand card.
Config.PMAVoiceIndicator = true

-- Voice backend selection:
-- "auto"      -> prefer pma-voice, then saltychat, then keyboard fallback
-- "pma"       -> force pma-voice (falls back to keyboard if unavailable)
-- "saltychat" -> force SaltyChat (shows "not connected" when plugin is offline)
-- "keyboard"  -> always use built-in keyboard fallback mode
Config.VoiceSystem = "saltychat"

-- When enabled, HUD automatically falls back to another supported voice backend
-- if the preferred one is not running / not connected.
-- Supported auto-detect order: pma-voice -> saltychat -> keyboard fallback.
Config.VoiceAutoDetect = true

-- Keyboard fallback voice mode (used when no active voice backend is available).
Config.FallbackVoice = {
    Enabled = true,              -- allow local voice range cycle fallback
    CycleCommand = "ahudvoice",  -- command used for key mapping
    CycleKey = "Z",              -- default key (can be rebound by players)
    Ranges = { 3.0, 8.0, 15.0 }, -- whisper, normal, shout
    DefaultIndex = 2,            -- 1..#Ranges
    ShowCircle = true,           -- draw temporary voice circle when range changes/talking
    CircleDurationMs = 1400,     -- show circle after range switch
    CircleAlpha = 90,            -- 0..255
    CircleHeight = 0.26,         -- marker height
}

-- =============================================
-- AGENCYAI (smart HUD assists)
-- =============================================
Config.AgencyAI = {
    Enabled = true,

    LowFuel = {
        Enabled = true,          -- repeated warning when fuel is low
        Threshold = 15,          -- percent (0-100)
        RepeatMs = 35000,        -- warning repeat interval
        NotifyDuration = 5000,   -- Agency-Notify duration
    },

    SpeedWarning = {
        Enabled = false,         -- server default OFF
        ThresholdKmh = 140,      -- used when HUD unit = km/h
        ThresholdMph = 87,       -- used when HUD unit = mph
        RepeatMs = 22000,        -- warning repeat interval
        NotifyDuration = 4500,   -- Agency-Notify duration
    }
}

-- =============================================
-- FRAMEWORK INTEGRATION
-- =============================================
-- "auto"       → detected automatically at runtime (recommended)
-- "standalone" → no framework dependency
-- "esx"        → force ESX (es_extended)
-- "qbcore"     → force QBCore (qb-core)
-- "qbox"       → force Qbox (qbx_core)
-- "ox"         → force ox_core
-- "nd"         → force ND_Core (nd_core)
Config.Framework = "auto"

-- Framework money display toggle (all supported frameworks + standalone exports/statebags)
Config.ShowMoney = true

-- =============================================
-- MINIMAP
-- =============================================
Config.CustomMinimap    = false  -- fallback only (native minimap recommended)
Config.HideNativeMinimapVitals = true -- fallback only (use /agencyhudadmin)

-- =============================================
-- LOGO INVERSION
-- =============================================
-- If enabled, logo is forced white in dark mode / black in light mode.
Config.LogoInvertDarkMode  = true  -- fallback only (use /agencyhudadmin)
Config.LogoInvertLightMode = true  -- fallback only (use /agencyhudadmin)

-- =============================================
-- TIMEZONE / CLOCK
-- =============================================
-- "game"  → show GTA world clock (default, follows server-side SetClockTime)
-- "auto"  → show real server machine time (os.date on the FiveM server)
-- number  → UTC offset in hours, e.g. 2 for UTC+2, -5 for UTC-5
Config.Timezone = "game"  -- fallback only (use /agencyhudadmin)

-- =============================================
-- MISC
-- =============================================
Config.HUDUpdateInterval = 500   -- ms between HUD data refreshes
Config.DebugMode          = true   -- fallback only (use /agencyhudadmin)