Skip to main content
A comprehensive weapon progression system that dynamically scales weapon damage, recoil, and accuracy based on player skill levels. Features include customizable progression curves, per-weapon modifiers, and realistic reload mechanics.
This script provides a sophisticated weapon progression system that rewards player skill and creates meaningful progression through customizable damage, accuracy, and recoil scaling.

​
Features

Skill-Based Progression

Weapon stats scale dynamically based on player skill levels, creating meaningful progression from novice to expert.

Customizable Curves

Support for linear, exponential, and custom progression curves to match your server’s progression style.

Per-Weapon Modifiers

Individual weapon damage and recoil multipliers for fine-tuned balance across different weapon types.

Realistic Reload Mechanics

Skill-based reload failure system with configurable failure rates and speed modifiers.

Accuracy & Recoil Control

Dynamic accuracy improvement and recoil reduction based on player skill progression.

Framework Integration

Compatible with VORP Core and RSG Core frameworks with modular framework bridge support.

​
Installation

1

Download

Get the latest release from our Tebex Store and download it from your Keymaster
2

Extract

Extract the script folder to your server’s resources directory
3

Configure

Add ensure spooni_weaponController to your server.cfg
4

Customize

Configure the config.lua file to match your server’s progression system

​
Configuration

The script is highly configurable through the config.lua file. Here are the main configuration sections:

​
Basic Settings

Config = {
    debug = true,  -- Enable debug mode for development

    -- Experience awarded per relevant action (e.g., shot fired)
    PerkExperience = {
        amount = 1,  -- Perk points gained per action
    },
}

​
Progression Curve Configuration

Define how weapon stats evolve from minimum to maximum skill level: 
-- Define how stats evolve from minLevel to maxLevel
PerkCurve = {
    minLevel = 0,      -- Lowest skill level
    maxLevel = 1000,   -- Highest skill level

    -- Choose interpolation type: "linear", "exponential", or "custom"
    interpolation = "linear",
    -- If exponential: power to raise t (e.g., 2 for quadratic curve)
    expPower = 2.0,

    -- If custom: supply a table of overrides per level
    -- Example: customValues = { [10] = { minAccuracy = 0.12, maxAccuracy = 2.0, ... }, ... }
    customValues = {},

    enableAccuracyAndRecoilModifier = true, -- Set to false to disable accuracy and recoil modifier completely
}

​
Weapon Statistics

Configure base and target values for each weapon stat: 
-- Base and target values for each stat (used for linear/exponential)
accuracy = { start = 0.20, finish = 0.00 },
maxAccuracy = { start = 2.50, finish = 1.00 },
accuracyGainSpeed = { start = 0.005, finish = 0.010 },

scopeRecoil = { start = 4.50, finish = 1.00 },

-- Reload mechanics
reloadFailDisabled = true,
reloadFailChance = { start = 0.5, finish = 0.0 }, -- 50%-0% chance to fail reload
reloadSpeedFactor = { start = 0.5, finish = 1.5 }, -- >1 = faster, <1 = slower
The reloadSpeedFactor controls the time for disabling firing after reload, not the animation delay.

​
Damage Modifiers

Configure per-weapon damage multipliers: 
-- Per-weapon damage multipliers (lower = weaker damage)
DamageModifiers = {
    [`WEAPON_BOW`]             = 0.5,
    [`WEAPON_MELEE_HATCHET`]   = 0.4,
    [`WEAPON_THROWN_TOMAHAWK`] = 0.5,
    -- Add more weapons as needed
}

-- Disable headshot damage modifier
DisableHeadshotDamage = true,

​
Recoil Configuration

Set global and per-weapon recoil settings: 
-- Global recoil step per shot multiplier
RecoilStep = 0.35,

-- Per-weapon recoil multipliers (higher = more recoil)
RecoilModifiers = {
    [`WEAPON_REPEATER_WINCHESTER`] = 1.0,
    [`WEAPON_RIFLE_BOLTACTION`]    = 2.5,
    -- Add more weapons as needed
}

​
Notification Settings

-- Reload failure notification
reloadFailedNotification = false,  -- If true, a notification will be shown when reload fails

​
Progression Types

The script supports three different progression curve types:

​
Linear Progression

PerkCurve = {
    interpolation = "linear",
    -- Stats progress linearly from start to finish values
}
Linear progression provides consistent improvement across all skill levels, suitable for balanced progression systems.

​
Exponential Progression

PerkCurve = {
    interpolation = "exponential",
    expPower = 2.0,  -- Quadratic curve
    -- Stats improve rapidly at higher levels
}
Exponential progression creates more dramatic improvements at higher skill levels, rewarding dedicated players.

​
Custom Progression

PerkCurve = {
    interpolation = "custom",
    customValues = {
        [10] = { 
            minAccuracy = 0.12, 
            maxAccuracy = 2.0,
            accuracyIncreaseSpeed = 0.008,
            maxScopeRecoil = 3.5,
            reloadFailChance = 0.4,
            reloadSpeedFactor = 0.8
        },
        [50] = { 
            minAccuracy = 0.08, 
            maxAccuracy = 1.5,
            -- Define specific values for level 50
        }
    }
}
Custom progression requires defining values for each level you want to override. Levels not specified will use linear interpolation.

​
Language Configuration

Customize notification messages in language.lua: 
Language = {
    reloadFailed = "Reload failed!",
    reloadFailedMsg = "Maybe next time Cowboy, keep learning!",
}

​
Advanced Configuration

​
Helper Functions

The script includes built-in helper functions for developers: 
-- Linear interpolation helper
local function lerp(a, b, t)
    return a + (b - a) * t
end

-- Get interpolation factor based on curve type
local function getInterpT(curve, level)
    local minL, maxL = curve.minLevel, curve.maxLevel
    local range = maxL - minL
    local t = (range > 0) and ((level - minL) / range) or 0

    if curve.interpolation == "linear" then
        return t
    elseif curve.interpolation == "exponential" then
        return math.pow(t, curve.expPower or 1)
    elseif curve.interpolation == "custom" then
        return nil  -- custom values handled separately
    else
        return t  -- fallback to linear
    end
end

​
Getting Perk Values

Access perk values programmatically: 
-- Get perk values for a specific level
local perkValues = Config.GetPerk(playerLevel)
local accuracy = perkValues.minAccuracy
local recoil = perkValues.maxScopeRecoil

​
Usage Examples

​
Balanced Linear Progression

PerkCurve = {
    minLevel = 0,
    maxLevel = 1000,
    interpolation = "linear",
    
    accuracy = { start = 0.25, finish = 0.05 },
    maxAccuracy = { start = 3.0, finish = 1.2 },
    scopeRecoil = { start = 5.0, finish = 1.5 },
    reloadFailChance = { start = 0.6, finish = 0.1 },
    reloadSpeedFactor = { start = 0.6, finish = 1.3 }
}

​
Exponential Progression for Hardcore Servers

PerkCurve = {
    minLevel = 0,
    maxLevel = 1000,
    interpolation = "exponential",
    expPower = 2.5,
    
    accuracy = { start = 0.30, finish = 0.02 },
    maxAccuracy = { start = 4.0, finish = 0.8 },
    scopeRecoil = { start = 6.0, finish = 0.8 },
    reloadFailChance = { start = 0.8, finish = 0.05 },
    reloadSpeedFactor = { start = 0.4, finish = 1.8 }
}

​
Custom Weapon Balance

DamageModifiers = {
    [`WEAPON_BOW`] = 0.4,                    -- Weaker bow
    [`WEAPON_MELEE_HATCHET`] = 0.3,          -- Weak melee
    [`WEAPON_REPEATER_WINCHESTER`] = 0.8,    -- Balanced repeater
    [`WEAPON_RIFLE_BOLTACTION`] = 1.2,       -- Strong rifle
}

RecoilModifiers = {
    [`WEAPON_REPEATER_WINCHESTER`] = 0.8,    -- Low recoil
    [`WEAPON_RIFLE_BOLTACTION`] = 3.0,       -- High recoil
    [`WEAPON_BOW`] = 0.2,                    -- Minimal recoil
}

​
Performance Considerations

The script is optimized for performance with several key features:
  • Pre-computed Values: All perk values are calculated once at startup
  • Efficient Lookups: Direct table access for perk values
  • Configurable Checks: Debug mode can be disabled in production
  • Minimal Overhead: Lightweight calculations during gameplay

​
Performance Tips

  • Debug Mode: Disable Config.debug in production
  • Custom Values: Limit custom value overrides to essential levels
  • Weapon Lists: Keep damage and recoil modifier lists focused on commonly used weapons
  • Progression Range: Use reasonable min/max level ranges (0-1000 recommended)

​
Troubleshooting

Verify the progression curve is properly configured, check that skill levels are being awarded correctly, and ensure the script is properly started in your server.cfg.
Confirm weapon hash names are correct, check that damage and recoil modifiers are properly formatted, and verify the weapon exists in your server.
Check that reloadFailDisabled is set to false, verify reload failure chance values are between 0.0 and 1.0, and ensure the notification system is properly configured.
Disable debug mode, reduce the number of custom value overrides, and ensure progression ranges are reasonable for your server population.
Verify custom value syntax is correct, ensure all required stats are defined for each level, and check that level numbers are within the min/max range.

​
Framework Integration

The script includes built-in support for multiple frameworks: 
-- Automatically detected when vorp_core is running
-- No additional configuration required

​
Limitations

Be aware of the following limitations when configuring the script:
  • Weapon Compatibility: Only works with weapons that support the configured stats
  • Progression Range: Values outside min/max level range are clamped
  • Custom Values: Must define all required stats for each custom level
  • Reload Mechanics: Reload speed factor affects firing delay, not animation speed

​
Support

If you encounter issues or need assistance:

Discord Support

Join our Discord community for real-time support and updates.

Documentation

Check our general RedM scripting documentation for framework setup and best practices.
⌘I