Initializing

Secure Protocol Active

v1.1.5

Configuration Reference

All configuration lives in config.lua, which is escrow_ignore-listed — you always have full access to it.

Framework

MBT.Framework = "ESX"   -- "ESX" or "QB"
MBT.ESXLegacy = true    -- true = ESX Legacy, false = old ESX

Option	Type	Default	Description
`MBT.Framework`	`string`	`"ESX"`	`"ESX"` for any ESX version, `"QB"` for QBCore.
`MBT.ESXLegacy`	`boolean`	`true`	When using ESX: `true` for ESX Legacy (uses `exports['es_extended']:getSharedObject()`), `false` for old ESX (uses the event method). Ignored for QBCore.

Refresh Rates

MBT.RefreshStats  = 0.5   -- seconds
MBT.RefreshStatus = 5     -- seconds

Option	Type	Default	Description
`MBT.RefreshStats`	`number`	`0.5`	How often (in seconds) health, armor, oxygen and weapon data are read from the game engine and sent to the NUI.
`MBT.RefreshStatus`	`number`	`5`	How often (in seconds) hunger, thirst and stress are read from the framework and sent to the NUI.

HUD Toggle Key

MBT.OpenKey         = "PAGEDOWN"
MBT.OpenHudOnStart  = true
MBT.DefaultHUDTrigger = true

Option	Type	Default	Description
`MBT.OpenKey`	`string`	`"PAGEDOWN"`	Key bound to the `openPlayerHud` command via `RegisterKeyMapping`. Any key from the FiveM keyboard reference is valid.
`MBT.OpenHudOnStart`	`boolean`	`true`	When `true`, the HUD automatically opens on the first player spawn.
`MBT.DefaultHUDTrigger`	`boolean`	`true`	When `true`, `showLogoHud(true)` is called automatically when the HUD system finishes loading.

MBT.EnableHudMenuCommand = true
MBT.EnableHudMenuKey     = false

Option	Type	Default	Description
`MBT.EnableHudMenuCommand`	`boolean`	`true`	Registers the `/hudmenu` command that opens the drag-to-position settings panel.
`MBT.EnableHudMenuKey`	`string\|false`	`false`	If set to a key string (e.g. `"F6"`), a hotkey is also bound to `/hudmenu`. Requires `EnableHudMenuCommand = true`.

Admin Style Command

MBT.AllowedRole     = "admin"
MBT.GetStyleCommand = "getDefHudStyle"

Option	Type	Default	Description
`MBT.AllowedRole`	`string`	`"admin"`	ESX/QB permission group allowed to run the style dump command.
`MBT.GetStyleCommand`	`string`	`"getDefHudStyle"`	Name of the admin command that outputs the current element positions as a `DefaultStyle` table (copied to clipboard). Paste the result into `MBT.Preferences.DefaultStyle` to change the default layout for all players.

Minimap

MBT.RoundMinimap         = true
MBT.MinimapHiddenOnFoot  = true
MBT.MinimapZoom          = 0.24
MBT.MinimapVehicleZoom   = 1150

Option	Type	Default	Description
`MBT.RoundMinimap`	`boolean`	`true`	Replaces the square GTA radar texture with a circular one.
`MBT.MinimapHiddenOnFoot`	`boolean`	`true`	When `true`, the minimap is hidden while the player is on foot and only shown when in a vehicle.
`MBT.MinimapZoom`	`number`	`0.24`	Zoom level used for the minimap component position (`SetMinimapComponentPosition`). Lower = more zoomed in.
`MBT.MinimapVehicleZoom`	`number`	`1150`	Radar zoom level applied when the player enters a vehicle (`SetRadarZoom`).

Weapon HUD

MBT.WeaponHUD       = true
MBT.HideDefaultAmmo = true

Option	Type	Default	Description
`MBT.WeaponHUD`	`boolean`	`true`	Shows the weapon icon and ammo counters when the player is armed.
`MBT.HideDefaultAmmo`	`boolean`	`true`	Suppresses GTA's native ammo display every frame (`DisplayAmmoThisFrame(false)`).

Voice Handler

MBT.VoiceHandler = "pma"   -- "pma" / "saltychat" / false

Value	Behaviour
`"pma"`	Listens to `pma-voice:setTalkingMode` (range) and `pma-voice:radioActive` (talking state).
`"saltychat"`	Listens to `SaltyChat_TalkStateChanged` (talking) and `SaltyChat_VoiceRangeChanged` (range).
`false`	No built-in integration; populate `MBT.StatusRetriever.getMicStatus` manually.

Max Health

MBT.MaxHealth = {
    ["Male"]   = 200,
    ["Female"] = 175,
}

Maximum health values for male and female freemode peds. Used to normalise the health bar to 0–100%. If your server uses custom health values, update these to match.

Preferences (Logo, Layout, Colors)

MBT.Preferences = {
    Logo = {
        ["FileName"] = "logo.png",
        ["Type"]     = "Image",   -- "Image" or "Video"
        ["Size"]     = 120,
    },
    DefaultStyle = {
        ["logo"]       = { 73,  57  },
        ["anchor"]     = { 115, 95, 1797, 937 },
        ["health"]     = { 38,  158 },
        ["armor"]      = { 107, 187 },
        ["hunger"]     = { 177, 158 },
        ["thirst"]     = { 204, 90  },
        ["stress"]     = { 12,  90  },
        ["oxygen"]     = { 177, 22  },
        ["microphone"] = { 109, 3   },
        ["server-id"]  = { 43,  28  },
    },
    MicrophoneTalkingColor = "#4ee70b",
    UseStress              = false,
}

Logo

Field	Type	Default	Description
`FileName`	`string`	`"logo.png"`	Filename inside `html/assets/`. Supports `.png`, `.gif`, `.webm`.
`Type`	`string`	`"Image"`	`"Image"` for static images and GIFs; `"Video"` for WebM files.
`Size`	`number`	`120`	Logo size in pixels.

DefaultStyle

Each key maps to an element's default position as { x, y } pixels from the anchor origin. The anchor entry is { left, top, right, bottom } and defines the drag area bounds.

To get the correct values for your layout, use the /getDefHudStyle admin command after positioning elements with /hudmenu.

Other fields

Field	Type	Default	Description
`MicrophoneTalkingColor`	`string`	`"#4ee70b"`	CSS hex colour the microphone icon turns when the player is actively talking.
`UseStress`	`boolean`	`false`	Set to `true` if your server has a stress system; enables the stress bar and activates `MBT.StatusRetriever.getStress`.

Status Retriever

MBT.StatusRetriever = {
    ["getHunger"]   = function(playerPed) ... end,
    ["getThirst"]   = function(playerPed) ... end,
    ["getMicStatus"] = function() ... end,
    ["getStress"]   = function(playerPed) ... end,
}

Key	Returns	Description
`getHunger`	`number` 0–100	Current hunger percentage. Default preset uses `esx_status`.
`getThirst`	`number` 0–100	Current thirst percentage. Default preset uses `esx_status`.
`getMicStatus`	—	Used only when `MBT.VoiceHandler = false`. Send `updateMicrophoneStatus` manually inside this function.
`getStress`	`number` 0–100	Used only when `MBT.Preferences.UseStress = true`. Return the current stress level from your stress system.

Weapons Table

MBT.Weapons = {
    [453432689] = { Type = 'handguns', Name = 'pistol' },
    -- ...
}

Maps GTA weapon hashes to their display type and icon name. The NUI uses Name to look up the weapon image from html/assets/weapons/<name>.png. The script ships with all vanilla GTA V weapons pre-configured. To add a custom weapon:

MBT.Weapons[YOUR_WEAPON_HASH] = { Type = 'handguns', Name = 'myweapon' }

Then place html/assets/weapons/myweapon.png in the assets folder.

Type value	Description
`'melee'`	Hides ammo counters; only the weapon icon is shown.
`'handguns'`, `'machinegun'`, `'assaultrifle'`, `'sniperrifle'`, `'shotgun'`, `'heavy'`	Shows clip + total ammo.

Notification Handler

MBT.HandleNotify = function(data)
    -- data.text  — key in MBT.Labels
    -- data.icon  — Font Awesome class string
    -- data.type  -- "info" / "error" / "success"
end

Replace the body with your server's notification system. Called for HUD-internal messages (settings saved, HUD reset, etc.). The default implementation uses ESX.ShowNotification / QBCore.Functions.Notify.

Labels

MBT.Labels = {
    ["must_open"]      = "HUD must be opened to open the settings menu",
    ["hud_refreshed"]  = "HUD has been refreshed",
    ["settings_saved"] = "The settings have been saved!",
    ["hud_reset"]      = "HUD has been reset!",
    ["check_console"]  = "Settings have been generated and are available on your OS clipboard [CTRL-V]",
}

All visible notification strings. Edit to translate or customise the messages shown by the HUD system.

Installation

Commands & Events

Was this page helpful?

Initializing

Secure Protocol Active

v1.1.5

Buy on Store

Configuration Reference

All configuration lives in config.lua, which is escrow_ignore-listed — you always have full access to it.

Framework

MBT.Framework = "ESX"   -- "ESX" or "QB"
MBT.ESXLegacy = true    -- true = ESX Legacy, false = old ESX

Option	Type	Default	Description
`MBT.Framework`	`string`	`"ESX"`	`"ESX"` for any ESX version, `"QB"` for QBCore.
`MBT.ESXLegacy`	`boolean`	`true`	When using ESX: `true` for ESX Legacy (uses `exports['es_extended']:getSharedObject()`), `false` for old ESX (uses the event method). Ignored for QBCore.

Refresh Rates

MBT.RefreshStats  = 0.5   -- seconds
MBT.RefreshStatus = 5     -- seconds

Option	Type	Default	Description
`MBT.RefreshStats`	`number`	`0.5`	How often (in seconds) health, armor, oxygen and weapon data are read from the game engine and sent to the NUI.
`MBT.RefreshStatus`	`number`	`5`	How often (in seconds) hunger, thirst and stress are read from the framework and sent to the NUI.

HUD Toggle Key

MBT.OpenKey         = "PAGEDOWN"
MBT.OpenHudOnStart  = true
MBT.DefaultHUDTrigger = true

Option	Type	Default	Description
`MBT.OpenKey`	`string`	`"PAGEDOWN"`	Key bound to the `openPlayerHud` command via `RegisterKeyMapping`. Any key from the FiveM keyboard reference is valid.
`MBT.OpenHudOnStart`	`boolean`	`true`	When `true`, the HUD automatically opens on the first player spawn.
`MBT.DefaultHUDTrigger`	`boolean`	`true`	When `true`, `showLogoHud(true)` is called automatically when the HUD system finishes loading.

MBT.EnableHudMenuCommand = true
MBT.EnableHudMenuKey     = false

Option	Type	Default	Description
`MBT.EnableHudMenuCommand`	`boolean`	`true`	Registers the `/hudmenu` command that opens the drag-to-position settings panel.
`MBT.EnableHudMenuKey`	`string\|false`	`false`	If set to a key string (e.g. `"F6"`), a hotkey is also bound to `/hudmenu`. Requires `EnableHudMenuCommand = true`.

Admin Style Command

MBT.AllowedRole     = "admin"
MBT.GetStyleCommand = "getDefHudStyle"

Option	Type	Default	Description
`MBT.AllowedRole`	`string`	`"admin"`	ESX/QB permission group allowed to run the style dump command.
`MBT.GetStyleCommand`	`string`	`"getDefHudStyle"`	Name of the admin command that outputs the current element positions as a `DefaultStyle` table (copied to clipboard). Paste the result into `MBT.Preferences.DefaultStyle` to change the default layout for all players.

Minimap

MBT.RoundMinimap         = true
MBT.MinimapHiddenOnFoot  = true
MBT.MinimapZoom          = 0.24
MBT.MinimapVehicleZoom   = 1150

Option	Type	Default	Description
`MBT.RoundMinimap`	`boolean`	`true`	Replaces the square GTA radar texture with a circular one.
`MBT.MinimapHiddenOnFoot`	`boolean`	`true`	When `true`, the minimap is hidden while the player is on foot and only shown when in a vehicle.
`MBT.MinimapZoom`	`number`	`0.24`	Zoom level used for the minimap component position (`SetMinimapComponentPosition`). Lower = more zoomed in.
`MBT.MinimapVehicleZoom`	`number`	`1150`	Radar zoom level applied when the player enters a vehicle (`SetRadarZoom`).

Weapon HUD

MBT.WeaponHUD       = true
MBT.HideDefaultAmmo = true

Option	Type	Default	Description
`MBT.WeaponHUD`	`boolean`	`true`	Shows the weapon icon and ammo counters when the player is armed.
`MBT.HideDefaultAmmo`	`boolean`	`true`	Suppresses GTA's native ammo display every frame (`DisplayAmmoThisFrame(false)`).

Voice Handler

MBT.VoiceHandler = "pma"   -- "pma" / "saltychat" / false

Value	Behaviour
`"pma"`	Listens to `pma-voice:setTalkingMode` (range) and `pma-voice:radioActive` (talking state).
`"saltychat"`	Listens to `SaltyChat_TalkStateChanged` (talking) and `SaltyChat_VoiceRangeChanged` (range).
`false`	No built-in integration; populate `MBT.StatusRetriever.getMicStatus` manually.

Max Health

MBT.MaxHealth = {
    ["Male"]   = 200,
    ["Female"] = 175,
}

Maximum health values for male and female freemode peds. Used to normalise the health bar to 0–100%. If your server uses custom health values, update these to match.

Preferences (Logo, Layout, Colors)

MBT.Preferences = {
    Logo = {
        ["FileName"] = "logo.png",
        ["Type"]     = "Image",   -- "Image" or "Video"
        ["Size"]     = 120,
    },
    DefaultStyle = {
        ["logo"]       = { 73,  57  },
        ["anchor"]     = { 115, 95, 1797, 937 },
        ["health"]     = { 38,  158 },
        ["armor"]      = { 107, 187 },
        ["hunger"]     = { 177, 158 },
        ["thirst"]     = { 204, 90  },
        ["stress"]     = { 12,  90  },
        ["oxygen"]     = { 177, 22  },
        ["microphone"] = { 109, 3   },
        ["server-id"]  = { 43,  28  },
    },
    MicrophoneTalkingColor = "#4ee70b",
    UseStress              = false,
}

Logo

Field	Type	Default	Description
`FileName`	`string`	`"logo.png"`	Filename inside `html/assets/`. Supports `.png`, `.gif`, `.webm`.
`Type`	`string`	`"Image"`	`"Image"` for static images and GIFs; `"Video"` for WebM files.
`Size`	`number`	`120`	Logo size in pixels.

DefaultStyle

Each key maps to an element's default position as { x, y } pixels from the anchor origin. The anchor entry is { left, top, right, bottom } and defines the drag area bounds.

To get the correct values for your layout, use the /getDefHudStyle admin command after positioning elements with /hudmenu.

Other fields

Field	Type	Default	Description
`MicrophoneTalkingColor`	`string`	`"#4ee70b"`	CSS hex colour the microphone icon turns when the player is actively talking.
`UseStress`	`boolean`	`false`	Set to `true` if your server has a stress system; enables the stress bar and activates `MBT.StatusRetriever.getStress`.

Status Retriever

MBT.StatusRetriever = {
    ["getHunger"]   = function(playerPed) ... end,
    ["getThirst"]   = function(playerPed) ... end,
    ["getMicStatus"] = function() ... end,
    ["getStress"]   = function(playerPed) ... end,
}

Key	Returns	Description
`getHunger`	`number` 0–100	Current hunger percentage. Default preset uses `esx_status`.
`getThirst`	`number` 0–100	Current thirst percentage. Default preset uses `esx_status`.
`getMicStatus`	—	Used only when `MBT.VoiceHandler = false`. Send `updateMicrophoneStatus` manually inside this function.
`getStress`	`number` 0–100	Used only when `MBT.Preferences.UseStress = true`. Return the current stress level from your stress system.

Weapons Table

MBT.Weapons = {
    [453432689] = { Type = 'handguns', Name = 'pistol' },
    -- ...
}

MBT.Weapons[YOUR_WEAPON_HASH] = { Type = 'handguns', Name = 'myweapon' }

Then place html/assets/weapons/myweapon.png in the assets folder.

Type value	Description
`'melee'`	Hides ammo counters; only the weapon icon is shown.
`'handguns'`, `'machinegun'`, `'assaultrifle'`, `'sniperrifle'`, `'shotgun'`, `'heavy'`	Shows clip + total ammo.

Notification Handler

MBT.HandleNotify = function(data)
    -- data.text  — key in MBT.Labels
    -- data.icon  — Font Awesome class string
    -- data.type  -- "info" / "error" / "success"
end

Labels

MBT.Labels = {
    ["must_open"]      = "HUD must be opened to open the settings menu",
    ["hud_refreshed"]  = "HUD has been refreshed",
    ["settings_saved"] = "The settings have been saved!",
    ["hud_reset"]      = "HUD has been reset!",
    ["check_console"]  = "Settings have been generated and are available on your OS clipboard [CTRL-V]",
}

All visible notification strings. Edit to translate or customise the messages shown by the HUD system.

Installation

Commands & Events

Was this page helpful?

Configuration Reference

Framework

Refresh Rates

HUD Toggle Key

Settings Menu (Hud Menu)

Admin Style Command

Minimap

Weapon HUD

Voice Handler

Max Health

Preferences (Logo, Layout, Colors)

Logo

DefaultStyle

Other fields

Status Retriever

Weapons Table

Notification Handler

Labels

Configuration Reference

Framework

Refresh Rates

HUD Toggle Key

Settings Menu (Hud Menu)

Admin Style Command

Minimap

Weapon HUD

Voice Handler

Max Health

Preferences (Logo, Layout, Colors)

Logo

DefaultStyle

Other fields

Status Retriever

Weapons Table

Notification Handler

Labels