[PAID] vsWeaponLevel [ESX & QBcore]

vsWeaponLevel – Weapon Skill & Recoil Training System for FiveM

Bring progression, skill development, and realistic weapon handling to your FiveM server.
vsWeaponLevel introduces a full weapon XP leveling system, allowing players to improve recoil control and accuracy by training at shooting ranges across the map.

Players earn experience, level up weapon categories, and unlock smoother, more controlled gun handling — just like real skill progression.

Showcase

Link to the Showcase Video

Why this system?

Most servers have static weapon behavior — every player shoots the same way.
With vsWeaponLevel, weapon mastery now has meaning:

• Skilled players become noticeably better
• Training takes time & effort
• Gunplay becomes more balanced and competitive
• No unfair advantages — everything is earned through gameplay

Key Features

• Works with ESX (old ESX compatibility included)
• Spawn multiple weapon training instructors anywhere on the map
• Skill progression system per weapon type
• Recoil & accuracy scale based on player level
• Players must pay to train → Perfect economy balance
• Fully customizable XP rewards, kill challenges, and time limits
• Max level system (default Level 5)
• Supports:
  • Handguns
  • SMGs
  • Shotguns
  • Assault Rifles
  • LMGs
  • Snipers
• Anti-Cheat Measure: Prevents switching weapons during training
• In-game notification messages included (customizable)

How Training Works

1. Player approaches Weapon Instructor NPC
2. Pays a training fee
3. Gets teleported to the Shooting Range
4. Must hit targets within a time limit
5. Earns XP based on performance
6. Levels up → Reduced Recoil & Shake

The higher the level, the more controlled the weapon feels.
Get this Script at our Store for just 14.99 € !

Config

Config = {}
Config.Framework = "esx" -- "esx" or "qb"

Config.EnableBlip = true -- enable/disable blip

Config.SpawnDistance = 3.0
Config.MarkerSize   = {x = 1.5, y = 1.5, z = 1.5}
Config.BlipName = "Weapon Instructor"

Config.Sprite      = 175
Config.Display     = 2
Config.Scale       = 0.8
Config.Colour      = 2

Config.Message = function(text)
  if Config.Framework == "esx" then
    ESX.ShowNotification(text)
  elseif Config.Framework == "qb" then
    QBCore.Functions.Notify(text, "primary")
  end
end

-- Update 1.05
Config.ClientFunction = true -- false = server function

Config.GiveWeapon = function(weapon)
  local ped = GetPlayerPed(-1)
  GiveWeaponToPed(GetPlayerPed(-1), GetHashKey(weapon), 999, false, true)
end

Config.RemoveWeapon = function(weapon)
  local ped = GetPlayerPed(-1)
  RemoveWeaponFromPed(ped, GetHashKey(weapon))
end
-- Update END -- 

Config.ArmoryStores = {
    WeaponStorePDM = {
        coords = vector3(13.5052, -1097.2141, 29.8347),
        txtPos = vector3(13.4211, -1097.2135, 30.7),
        heading = 164.0607,
        model = "mp_m_weapexp_01",
        id = 1,
    },
    WeaponStoreSouth = {
      coords = vector3(821.5058, -2163.8176, 29.6567),
      txtPos = vector3(821.5058, -2163.8176, 30.6567),
      heading = 356,
      model = "mp_m_weapexp_01",
      id = 2,
  },
}

Config.TrainingModel = "s_m_y_mime" -- The NPC Model you shoot https://docs.fivem.net/docs/game-references/ped-models/

Config.Locales = {
  ["EnterShootingRange"] = "Press [E] to train your Skill!",
  ["KillsEarnedXP"] = "You successfully killed %d objects, you earned %d XP for it.",
  ["ShowKillHelpScreenText"] = "You killed: %d of %d, you have %.1f seconds left",
  ["TimeExceeded"] = "Time exceeded! You took too long.",
  ["AllreadyIngame"] = "You are allready in the Range!",
  ["MaxLevel"] = "Because you are the highest Level you didn't earned any XP!",
  ["SwitchedWeapon"] = "You are not allowed to use a different Weapon!",
  ["NotEnoughMoney"] = "You dont have enough money to enter the range!",
  ["StartingRange"] = "You paid %d$ to enter the range",
  
  -- UI Texte
  ["UI_HeaderTitle"] = "WeaponRange",
  ["UI_WeaponType_Handguns"] = "Handguns",
  ["UI_WeaponType_SMG"] = "SMG's",
  ["UI_WeaponType_Shotgun"] = "Shotgun",
  ["UI_WeaponType_AssaultRifle"] = "Assault Rifle",
  ["UI_WeaponType_LMG"] = "LMG's",
  ["UI_WeaponType_Sniper"] = "Sniper",
  ["UI_TrainCostLabel"] = "Train cost:",
  ["UI_TrainButton"] = "Train",
  ["UI_Level"] = "Level",
  ["UI_XP"] = "XP",
  ["UI_XPFormat"] = "XP: %d / %d",
  ["UI_XPMax"] = "MAX",
  ["UI_XPMaxFormat"] = "XP: MAX / MAX",
}


Config.MaxLevel = 5
Config.WeaponLevels = {
  [416676503] = { -- HandGuns

    [1] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.8, intensity = 0.1 },
    [2] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.6, intensity = 0.08 },
    [3] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.4, intensity = 0.05 },
    [4] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.2, intensity = 0.03 },
    [5] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.1, intensity = 0.01 },
},

[-957766203] = { -- SMG
    [1] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.8, intensity = 0.18 },
    [2] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.6, intensity = 0.15},
    [3] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.4, intensity = 0.10},
    [4] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.2, intensity = 0.08},
    [5] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.1, intensity = 0.05},
},

[860033945] = { -- Shotgun
  [1] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.8, intensity = 0.2 },
  [2] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.7, intensity = 0.16 },
  [3] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.65, intensity = 0.14 },
  [4] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.6, intensity = 0.12 },
  [5] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.3, intensity = 0.08 },
},

[970310034] = { -- Assault Rifle
    [1] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.8, intensity = 0.12 },
    [2] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.7, intensity = 0.10 },
    [3] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.6, intensity = 0.09 },
    [4] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.5, intensity = 0.07 },
    [5] = { version = 'MEDIUM_EXPLOSION_SHAKE', recoil = 0.35, intensity = 0.06 },
},

[1159398588] = { -- Light Machine Gun
  [1] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.5, intensity = 0.18 },
  [2] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.4, intensity = 0.16},
  [3] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.35, intensity = 0.14},
  [4] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.3, intensity = 0.12},
  [5] = { version = 'SMALL_EXPLOSION_SHAKE', recoil = 0.2, intensity = 0.05},
},

[-1212426201] = { -- Sniper

    [1] = { version = 'LARGE_EXPLOSION_SHAKE', recoil = 1.0, intensity = 0.3 },
    [2] = { version = 'LARGE_EXPLOSION_SHAKE', recoil = 0.7, intensity = 0.13 },
    [3] = { version = 'LARGE_EXPLOSION_SHAKE', recoil = 0.6, intensity = 0.11 },
    [4] = { version = 'LARGE_EXPLOSION_SHAKE', recoil = 0.5, intensity = 0.09 },
    [5] = { version = 'LARGE_EXPLOSION_SHAKE', recoil = 0.4, intensity = 0.05 },
},
}

Config.NeededXP = {
  [416676503] = {
    [1] = {trainCost = 100, neededXP = 200},  -- 10x for Level 2
    [2] = {trainCost = 200, neededXP = 600}, -- 30x for Level 3 
    [3] = {trainCost = 300, neededXP = 1500}, -- 150x for Level 4 
    [4] = {trainCost = 400, neededXP = 2500}, -- 100x for Level 5 (Hard)
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Handgun
  [-957766203] = {
    [1] = {trainCost = 100, neededXP = 200}, 
    [2] = {trainCost = 200, neededXP = 600},
    [3] = {trainCost = 300, neededXP = 1500},
    [4] = {trainCost = 400, neededXP = 2500},
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Submachine Gun
  [860033945] = {
    [1] = {trainCost = 100, neededXP = 200}, 
    [2] = {trainCost = 200, neededXP = 600},
    [3] = {trainCost = 300, neededXP = 1500},
    [4] = {trainCost = 400, neededXP = 2500},
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Shotgun
  [970310034] = {
    [1] = {trainCost = 100, neededXP = 200}, 
    [2] = {trainCost = 200, neededXP = 600},
    [3] = {trainCost = 300, neededXP = 1500},
    [4] = {trainCost = 400, neededXP = 2500},
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Assault Rifle
  [1159398588] = {
    [1] = {trainCost = 100, neededXP = 200}, 
    [2] = {trainCost = 200, neededXP = 600},
    [3] = {trainCost = 300, neededXP = 1500},
    [4] = {trainCost = 400, neededXP = 2500},
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Light Machine Gun
  [-1212426201] = {
    [1] = {trainCost = 100, neededXP = 200}, 
    [2] = {trainCost = 200, neededXP = 600},
    [3] = {trainCost = 300, neededXP = 1500},
    [4] = {trainCost = 400, neededXP = 2500},
    -- After this Level 5 / Config.MaxLevel
    [5] = {trainCost = 0, neededXP = 9999},

  }, -- Sniper
}

Config.PracticeTasks = {
  [416676503] = { -- Handgun
    [1] = {weapon = "WEAPON_COMBATPISTOL", needKills = 20, timeToKill = 2, timeForKills = 25, addXP = 20}, -- CombatPistol
    [2] = {weapon = "WEAPON_APPISTOL", needKills = 20, timeToKill = 3, timeForKills = 20, addXP = 20},  -- AP Pistol
    [3] = {weapon = "WEAPON_HEAVYPISTOL", needKills = 10, timeToKill = 1, timeForKills = 20, addXP = 10},-- Heavy Pistol
    [4] = {weapon = "weapon_pistol_mk2", needKills = 25, timeToKill = 2, timeForKills = 30, addXP = 25},-- SNS Pistol Mk II
    [5] = {weapon = "weapon_pistol_mk2", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 0},-- Pistol Mk II
  }, 
  [-957766203] = { -- SMG
    [1] = {weapon = "weapon_smg", needKills = 10, timeToKill = 2, timeForKills = 17, addXP = 10},
    [2] = {weapon = "weapon_smg_mk2", needKills = 20, timeToKill = 2, timeForKills = 25, addXP = 20},
    [3] = {weapon = "weapon_assaultsmg", needKills = 10, timeToKill = 1, timeForKills = 20, addXP = 10},
    [4] = {weapon = "weapon_combatpdw", needKills = 25, timeToKill = 2, timeForKills = 30, addXP = 25},
    [5] = {weapon = "weapon_machinepistol", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 0},
  }, -- Shotgun
  [860033945] = {
    [1] = {weapon = "weapon_pumpshotgun", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 10},
    [2] = {weapon = "weapon_sawnoffshotgun", needKills = 10, timeToKill = 2, timeForKills = 22, addXP = 10},
    [3] = {weapon = "weapon_assaultshotgun", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 15},
    [4] = {weapon = "weapon_bullpupshotgun", needKills = 20 , timeToKill = 3, timeForKills = 30, addXP = 20},
    [5] = {weapon = "weapon_heavyshotgun", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 0},
  }, -- Assault Rifle
  [970310034] = {
    [1] = {weapon = "weapon_assaultrifle", needKills = 10, timeToKill = 2, timeForKills = 17, addXP = 10},
    [2] = {weapon = "weapon_carbinerifle", needKills = 20, timeToKill = 2, timeForKills = 25, addXP = 20},
    [3] = {weapon = "weapon_carbinerifle_mk2", needKills = 10, timeToKill = 1, timeForKills = 20, addXP = 10},
    [4] = {weapon = "weapon_specialcarbine", needKills = 25, timeToKill = 2, timeForKills = 30, addXP = 25},
    [5] = {weapon = "weapon_assaultrifle", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 0},
  }, -- Light Machine Gun
  [1159398588] = {
    [1] = {weapon = "weapon_mg", needKills = 10, timeToKill = 2, timeForKills = 17, addXP = 10},
    [2] = {weapon = "weapon_combatmg", needKills = 20, timeToKill = 2, timeForKills = 25, addXP = 20},
    [3] = {weapon = "weapon_combatmg_mk2", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 80},
    [4] = {weapon = "weapon_gusenberg", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 80},
    [5] = {weapon = "weapon_gusenberg", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 0},
  }, -- Sniper
  [-1212426201] = {
    [1] = {weapon = "weapon_sniperrifle", needKills = 10, timeToKill = 5, timeForKills = 25, addXP = 15},
    [2] = {weapon = "weapon_heavysniper", needKills = 10, timeToKill = 4, timeForKills = 20, addXP = 20},
    [3] = {weapon = "weapon_marksmanrifle", needKills = 10, timeToKill = 4, timeForKills = 18, addXP = 20},
    [4] = {weapon = "weapon_sniperrifle", needKills = 10, timeToKill = 2, timeForKills = 20, addXP = 20},
    [5] = {weapon = "weapon_sniperrifle", needKills = 10, timeToKill = 2, timeForKills = 15, addXP = 0},
  }, -- Sniper
}

Config.SpawnCoords = {
  [1] =  {
    { x = 18.6349, y = -1075.6503, z = 29.7970, heading = 155.0607 },
    { x = 21.2300, y = -1080.5420, z = 29.7970, heading = 162.7372 },
    { x = 18.9792, y = -1082.7452, z = 29.7981, heading = 158.1568 },
    { x = 15.2697, y = -1090.8531, z = 29.7980, heading = 114.9778 },
    { x = 12.4202, y = -1091.0951, z = 29.7970, heading = 146.9039 },
    { x = 13.0738, y = -1086.4203, z = 29.7970, heading = 167.1453 },
    { x = 15.6001, y = -1083.4034, z = 29.7970, heading = 180.6670 },
    { x = 21.1563, y = -1079.3721, z = 29.7970, heading = 184.1642 },
    { x = 23.3779, y = -1077.8513, z = 29.7970, heading = 170.5842 },
    { x = 23.0387, y = -1073.6199, z = 29.7970, heading = 154.0821 },
    { x = 20.1846, y = -1074.3867, z = 29.7970, heading = 148.5763 },
    { x = 18.6046, y = -1071.0854, z = 29.7970, heading = 174.4680 },
    { x = 26.7876, y = -1073.6212, z = 29.7976, heading = 173.9891 },
  },
  [2] = {
    { x = 817.1430, y = -2172.8330, z = 29.6180, heading = 0.9895 },
    { x = 818.9539, y = -2170.4177, z = 29.6639, heading = 326.9233 },
    { x = 826.5889, y = -2168.5750, z = 29.6190, heading = 336.9417 },
    { x = 824.0486, y = -2172.3445, z = 29.6266, heading = 120.5459 },
    { x = 824.3030, y = -2178.9082, z = 29.6193, heading = 240.5508 },
    { x = 825.4547, y = -2183.0859, z = 29.6211, heading = 101.2726 },
    { x = 821.9552, y = -2181.2375, z = 29.6296, heading = 66.5013 },
    { x = 818.0636, y = -2184.2344, z = 29.6573, heading = 183.5794 },
    { x = 820.0837, y = -2189.8823, z = 29.6206, heading = 208.9715 },
    { x = 824.9965, y = -2188.7112, z = 29.6267, heading = 329.9187 },
    { x = 821.5027, y = -2184.4788, z = 29.7519, heading = 24.1283 },
  },
}

Optimization

• IDLE: 0.00ms

• RUNNING: 0.00ms

Further Information

SHOP: vsWeaponLevel

This resource is using the FiveM Asset Escrow system