> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dietrich-development.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Setup

> Install and configure the weapon controller - progression curves, weapon stats, and modifiers

## Installation

<Steps>
  <Step title="Download">
    Get the latest release from our [Tebex store](https://tebex.dietrich-development.com) and download it from your [Keymaster](https://portal.cfx.re/assets/granted-assets)
  </Step>

  <Step title="Extract">
    Extract the script folder to your server's `resources` directory
  </Step>

  <Step title="Configure">
    Add `ensure spooni_weaponController` to your `server.cfg`
  </Step>

  <Step title="Customize">
    Configure the `config.lua` file to match your server's progression system
  </Step>
</Steps>

## Configuration

The script is configured through the `config.lua` file. Here are the main configuration sections:

### Basic settings

```lua theme={null}
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:

```lua theme={null}
-- 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:

```lua theme={null}
-- 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
```

<Note>
  The `reloadSpeedFactor` controls the time for disabling firing after reload, not the animation delay.
</Note>

### Damage modifiers

Configure per-weapon damage multipliers:

```lua theme={null}
-- 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:

```lua theme={null}
-- 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

```lua theme={null}
-- 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

```lua theme={null}
PerkCurve = {
    interpolation = "linear",
    -- Stats progress linearly from start to finish values
}
```

<Info>
  Linear progression provides consistent improvement across all skill levels, suitable for balanced progression systems.
</Info>

### Exponential progression

```lua theme={null}
PerkCurve = {
    interpolation = "exponential",
    expPower = 2.0,  -- Quadratic curve
    -- Stats improve rapidly at higher levels
}
```

<Info>
  Exponential progression creates more dramatic improvements at higher skill levels, rewarding dedicated players.
</Info>

### Custom progression

```lua theme={null}
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
        }
    }
}
```

<Warning>
  Custom progression requires defining values for each level you want to override. Levels not specified will use linear interpolation.
</Warning>

## Language configuration

Customize notification messages in `language.lua`:

```lua theme={null}
Language = {
    reloadFailed = "Reload failed!",
    reloadFailedMsg = "Maybe next time Cowboy, keep learning!",
}
```

## Usage examples

### Balanced linear progression

```lua theme={null}
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

```lua theme={null}
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

```lua theme={null}
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

<Info>
  The script is optimized for performance with several key features:
</Info>

* **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

<AccordionGroup>
  <Accordion title="Progression not working">
    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.
  </Accordion>

  <Accordion title="Weapon modifiers not applying">
    Confirm weapon hash names are correct, check that damage and recoil modifiers are properly formatted, and verify the weapon exists on your server.
  </Accordion>

  <Accordion title="Reload mechanics not working">
    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.
  </Accordion>

  <Accordion title="Performance issues">
    Disable debug mode, reduce the number of custom value overrides, and ensure progression ranges are reasonable for your server population.
  </Accordion>

  <Accordion title="Custom progression errors">
    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.
  </Accordion>
</AccordionGroup>

## Framework integration

The script includes built-in support for multiple frameworks:

<CodeGroup>
  ```lua VORP Core theme={null}
  -- Automatically detected when vorp_core is running
  -- No additional configuration required
  ```

  ```lua RSG Core theme={null}
  -- Automatically detected when rsg-core is running
  -- No additional configuration required
  ```

  ```lua Custom Framework theme={null}
  -- Set in config.lua
  Config.Framework = 'custom'

  -- Requires additional configuration in frameworkBridge.lua
  -- See framework bridge documentation for details
  ```
</CodeGroup>

## Support

If you encounter issues or need assistance:

<Columns cols={2}>
  <Card title="Discord support" icon="discord" href="https://discord.gg/4jhQsPr6pe">
    Join our Discord community for support and updates.
  </Card>

  <Card title="Developer reference" icon="book" href="/scripts/weapon-controller/developers">
    API details and configuration hooks for this script.
  </Card>
</Columns>