Configuration Reference

All configuration is done in config.lua at the root of the resource. Every option is described below.

General Options

MBT.Debug = false

Option	Type	Default	Description
`MBT.Debug`	`boolean`	`false`	Prints debug messages to the client console. Useful when troubleshooting. Disable in production.
`MBT.DropWeaponOnDeath`	`boolean`	`true`	Drops the equipped weapon as a lootable `ox_inventory` item when the player dies.
`MBT.EnableSling`	`boolean`	`true`	Enables the visible weapon prop on the character. Set to `false` to disable the entire sling system.
`MBT.EnableFlashlight`	`boolean`	`true`	Syncs flashlight attachment state to weapon metadata. When `false`, flashlight components are ignored.
`MBT.Relog`	`boolean`	`true`	Set to `true` if you use `esx_multicharacter` with relog. Cleans up weapons when switching characters.

Jamming

Controls the weapon jamming system. Jamming is triggered when bullets fly near the player; the chance increases as weapon durability decreases.

MBT.Jamming = {
    ["Enabled"]   = true,
    ["Cooldown"]  = 5,
    ["Animation"] = {
        ["Dict"] = "anim@weapons@first_person@aim_rng@generic@pistol@singleshot@str",
        ["Anim"] = "reload_aim"
    },
    ["Chance"] = {
        [50] = 10,
        [40] = 15,
        [30] = 20,
        [20] = 25,
        [10] = 30
    }
}

Option	Type	Default	Description
`Enabled`	`boolean`	`true`	Enables or disables the jamming system entirely.
`Cooldown`	`number`	`5`	Seconds between possible jams on the same weapon.

Jam chance table

The Chance table maps durability thresholds to jam probabilities (in percent):

Durability	Jam chance
Below 50%	10%
Below 40%	15%
Below 30%	20%
Below 20%	25%
Below 10%	30%

When a weapon jams, firing is disabled and a skill check appears. The player must pass 3 easy checks to unjam the weapon.

Weapon Throw

Allows players to physically throw their equipped weapon. The weapon lands at a real position and becomes a lootable drop.

MBT.Throw = {
    ["Enabled"]   = true,
    ["Animation"] = {
        ["Dict"] = "melee@unarmed@streamed_variations",
        ["Anim"] = "plyr_takedown_front_slap"
    },
    ["Groups"] = {
        [`GROUP_MELEE`]   = { ["Allowed"] = true,  ["Multipliers"] = { ["X"] = 40.0, ["Y"] = 40.0, ["Z"] = 15.0 } },
        [`GROUP_PISTOL`]  = { ["Allowed"] = true,  ["Multipliers"] = { ["X"] = 20.0, ["Y"] = 20.0, ["Z"] = 15.0 } },

Option	Type	Default	Description
`Enabled`	`boolean`	`true`	Enables or disables the throw system.
`Animation.Dict`	`string`	—	Animation dictionary for the throw gesture.
`Animation.Anim`

Weapon groups

Each GROUP_* entry controls whether that weapon class can be thrown and how far:

Group	Allowed by default	Notes
`GROUP_MELEE`	✅	High throw force
`GROUP_PISTOL`	✅	Medium throw force
`GROUP_RIFLE`	✅	Lower force (heavier)
`GROUP_SMG`	✅	Medium throw force
`GROUP_SHOTGUN`

Multipliers control the physical force applied on throw (X, Y = horizontal, Z = vertical arc).

Holster Controls

The prompts shown when a weapon is being holstered/unholstered.

MBT.HolsterControls = {
    ["Confirm"] = { ["Label"] = "Confirm Holster", ["Input"] = "MOUSE_BUTTON", ["Key"] = "MOUSE_RIGHT" },
    ["Cancel"]  = { ["Label"] = "Cancel Holster",  ["Input"] = "keyboard",     ["Key"] = "BACK"        }
}

Key	Default	Description
`Confirm`	Right Mouse Button	Confirm unholster
`Cancel`	Backspace	Cancel holster action

Notifications

Customize how notifications are displayed. By default uses ox_lib notify:

MBT.Notification = function(data)
    lib.notify(data)
end

You can replace this with your own notification system. The data table always contains:

Field	Type	Description
`title`	`string`	Notification title
`description`	`string`	Notification body
`type`	`string`	`"success"`, , or

Notification labels

All in-game notification texts are defined in MBT.Labels and can be translated freely:

MBT.Labels = {
    ["has_jammed"]      = { ["title"] = "Jammed!",   ["description"] = "Your weapon has jammed! Check its state!", ["type"] = "error",   ["icon"] = "fa-solid fa-triangle-exclamation" },
    ["has_unjammed"]    = { ["title"] = "Unjammed!",  ["description"] = "You have unjammed your weapon!",          ["type"] = "success", ["icon"] = "fa-solid fa-person-rifle" },
    ["no_allowed_throw"]= { ["title"] = "Ops!",       ["description"] = "You are not able to throw this weapon!",  ["type"] = "error",   ["icon"] = "fa-solid fa-hand-fist" },
    ["Holster_Help"]    = "[RMOUSE] - Unholster [BACKSPACE] - Cancel"

Custom Weapon Positions per Job

You can override the weapon prop position and rotation for specific jobs (e.g. place a pistol on the hip for police).

MBT.CustomPropPosition = {
    ["police"] = {
        ["side"] = {
            ["Bone"] = 24816,
            ["Pos"] = {
                ["male"]   = { ["x"] = -0.12, ["y"] = 0.02, ["z"] = -0.20 },
                ["female"] = { ["x"] = -0.12, ["y"] = 0.02, ["z"] = -0.20 }
            },
            ["Rot"] = {
                ["male"]   = { ["x"] = 90.0, ["y"] = 20.0, ["z"] = 180.0 },

The job name must match exactly what your framework returns (e.g. "police", "ambulance"). The weapon type key ("side", "back", etc.) must match the type defined in data/weapons.lua for that weapon.

Separate male and female positions are supported. If your server uses only one gender, both entries can be identical.

Weapon Position Types

Weapon placement type is defined per weapon hash in data/weapons.lua. The available types are:

Type	Description
`side`	Holster position (hip/side)
`back`	Rifle/shotgun on the back
`back2`	Alternative back position
`melee`	Melee weapon position 1
`melee2`	Melee weapon position 2

To change where a specific weapon appears, edit its entry in data/weapons.lua:

-- data/weapons.lua
return {
    ["WEAPON_PISTOL"]    = { ["type"] = "side" },
    ["WEAPON_CARBINERIFLE"] = { ["type"] = "back" },
    -- ...
}

string