Configuration

Overview

• shared/config.lua: global toggles, damage, stance, progressive recoil, skill rules, admin panel, test range and the default weapon profiles
• shared/vanilla_damage.lua: base damage of each weapon, used to turn a target Damage into an engine modifier
• server/config_server.lua: Discord webhooks

The admin panel (/recoil) edits weapon profiles, global settings and skill rules in game and saves them to the database. Saved values override shared/config.lua. Weapon profiles can be reset from the panel; saved global settings and skill rules keep overriding the file.

General

1Config.Debug = false
2Config.Language = 'en'
3Config.ClassicRecoil = true
4Config.DisablePistolPunch = true

• Debug: prints extra load information to the server console
• Language: language file to load from the locales/ folder
• ClassicRecoil: adds GTA's own vertical recoil on top of the camera kick, scaled by each weapon's ClassicRecoilAmt
• DisablePistolPunch: blocks the pistol-whip controls while a configured weapon is held, so firing never triggers a punch

Damage System

The engine modifier is Damage / VanillaDamage[hash], clamped between MinModifier and MaxModifier.

1Config.DamageSystem = {
2    Enabled = true,
3    DefaultDamage = 10,
4    MinModifier = 0.001,
5    MaxModifier = 10.0,
6}

• Enabled: false applies no modifier
• DefaultDamage: target damage for a profile without Damage
• MinModifier, MaxModifier: clamp range of the modifier

PvP

1Config.PvP = {
2    DisableHeadshotKills = true,
3}

• DisableHeadshotKills: headshots deal normal damage instead of an instant kill. Applied on spawn and on every ped change

Skill Rules

Each rule lowers recoil by how many ranks of a skill type the player has unlocked in ml_skills.

1Config.SkillRules = {
2    {
3        Id = 'all_weapons',
4        Enabled = true,
5        Scope = 'all',
6        Classes = {},
7        Weapons = {},
8        Category = 'personal',
9        SkillType = 'betterAccuracy',
10        Affects = {
11            Vertical = true,
12            Horizontal = true,
13            Sway = true,
14            Progressive = false,
15            Shake = false,
16        },
17        Ranks = { 0.92, 0.84, 0.76, 0.68 },
18    },
19}

• Id: unique name of the rule
• Enabled: turns the rule on or off
• Scope: 'all' for every weapon, 'class' for the classes in Classes (pistol, smg, rifle, shotgun, sniper, lmg, heavy, melee), 'weapons' for the names in Weapons. When several rules match, the most specific wins: a weapon list beats a class, a class beats all
• Category, SkillType: the ml_skills category and skill type whose unlocked ranks are counted
• Affects: which parts of the recoil the multiplier scales
• Ranks: multiplier for 1, 2, 3 and more unlocked ranks. More ranks than entries use the last one. Values are clamped between 0 and 2

Stance

1Config.Stance = {
2    Enabled = true,
3    CrouchMultiplier = 0.7,
4    MovementMultiplier = 1.3,
5    RunningMultiplier = 2.0,
6}

• CrouchMultiplier: applied while crouched. Below 1.0 steadies the aim
• MovementMultiplier: applied while walking
• RunningMultiplier: applied while running or sprinting

Progressive Recoil

1Config.ProgressiveRecoil = {
2    Enabled = true,
3    IncrementPerShot = 0.1,
4    MaxMultiplier = 2.5,
5    ResetTime = 400,
6}

• IncrementPerShot: added to the multiplier for each shot of a burst
• MaxMultiplier: ceiling of the climb
• ResetTime: milliseconds without shooting that reset the burst

Aim Fix

1Config.AimFix = {
2    Enabled = true,
3    ShakeDuration = 250,
4}

• Enabled: turns on the aim sway of each weapon's AimSway. With false, AimSway has no effect
• ShakeDuration: length of the sway burst when the player starts aiming, in milliseconds

Panel Limits

1Config.Limits = {
2    Damage           = { min = 0, max = 1000 },
3    ClassicRecoilAmt = { min = 0, max = 5.0 },
4    VerticalRecoil   = { min = 0, max = 10.0 },
5    HorizontalRecoil = { min = 0, max = 5.0 },
6    ShakeIntensity   = { min = 0, max = 3.0 },
7    AimSway          = { min = 0, max = 5.0 },
8}

Range of each weapon value in the admin panel. Global settings saved from the panel are also clamped: stance multipliers 0 to 5, IncrementPerShot 0 to 2, MaxMultiplier 1 to 10, ResetTime 0 to 10000, ShakeDuration 0 to 5000 and MaxModifier up to 50.

Admin Panel

1Config.AdminPermissions = { 'command', 'admin', 'god', 'superadmin' }
2Config.OpenCommand = 'recoil'
3Config.Admin = {
4    MinimizeKey = 'F9',
5}
6Config.Theme = 'default'
7Config.UITheme = {
8    preset = nil,
9    colors = {
10        primary = nil,
11        accent = nil,
12        background = nil,
13        surface = nil,
14        text = nil,
15    },
16}

• AdminPermissions: permission groups, read through ml_bridge, that can open the panel and the test range
• OpenCommand: command that opens the panel
• Admin.MinimizeKey: hides and restores the panel while it is open. F3 to F12, a letter or a digit
• Theme: 'default', 'wasteland', 'cyberpunk', 'noir' or 'fantasy'
• UITheme: theme preset and single CSS hex colors of the panel. nil follows the shared theme set in ml_bridge

Test Range

1Config.TestRange = {
2    Enabled = true,
3    Coords = nil,
4    RoutingBucket = 4901,
5    TargetModel = nil,
6    TargetPed = 's_m_y_dealer_01',
7    Distances = { 10, 25, 50, 100 },
8    DefaultDistance = 25,
9    ClipAmmo = 250,
10    Tracers = true,
11    TracerCount = 12,
12}

Staff test a weapon profile from the panel in a private routing bucket. The weapon is handed over through the inventory on entry and taken back on exit.

• Enabled: false turns the test range off
• Coords: nil tests where the admin stands. A vec4 always tests at that spot
• RoutingBucket: private bucket used while testing
• TargetModel: optional prop next to the target frame
• TargetPed: frozen dummy beside the target. nil for none
• Distances, DefaultDistance: target distances offered, and the starting one
• ClipAmmo: rounds loaded on entry. Reserve ammo is unlimited while testing
• Tracers, TracerCount: draw a line from the muzzle to each impact, for the last shots

Weapon Profiles

Config.Weapons is keyed by weapon hash. The file ships 17 vanilla profiles across pistols, SMGs, shotguns, rifles, one MG and snipers. In the panel, staff can also add any weapon from the game roster or from your inventory, starting from its class defaults in shared/data/weapons.lua.

1Config.Weapons = {
2    [joaat('WEAPON_PISTOL')] = {
3        Damage = 26,
4        ClassicRecoilAmt = 0.5,
5        VerticalRecoil = 0.85,
6        HorizontalRecoil = 0.15,
7        ShakeName = 'PISTOL_RECOIL_SHAKE',
8        ShakeIntensity = 0.8,
9        AimSway = 0.8,
10    },
11}

• Damage: target damage, turned into an engine modifier against the vanilla value
• ClassicRecoilAmt: GTA vertical recoil used with Config.ClassicRecoil
• VerticalRecoil: upward camera pitch per shot
• HorizontalRecoil: sideways kick per shot, left or right at random
• ShakeName: camera shake preset. The panel accepts the 28 presets listed in shared/data/weapons.lua; other names are dropped when a profile is saved from the panel
• ShakeIntensity: shake strength per shot
• AimSway: hand sway while aiming, with Config.AimFix.Enabled
• SkillOverride: optional { RuleId = 'rule_id' } to force one skill rule for this weapon

The panel can export the current profiles as a Config.Weapons block to paste into the file.

Discord Webhooks

1ServerConfig.Webhooks = {
2    admin = '',
3    testrange = '',
4}

• admin: profile saves, resets, added weapons and settings changes from the panel
• testrange: test range sessions

Leave a webhook empty to disable that log.