> For the complete documentation index, see [llms.txt](https://docs.rytrak.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.rytrak.fr/scripts/advanced-shields-system/general-configuration.md).

# General Configuration

This guide helps you configure your script step by step using the `config.lua` file. Each section below details the available options to tailor the behavior of gas grenades, effects, and compatibility.

***

### **1. General Configuration**

#### **Language**

Set the language used by the script.

```lua
Config.Language = 'en' -- Available options: 'en' (English), 'fr' (French)
```

***

#### **Use Outdated Version**

Enable this option to suppress alert messages when using an older version of the script.

```lua
Config.UseOutdatedVersion = false -- Set to true if using an outdated script version.
```

***

### 2. Framework Compatibility

If you're using a framework like **ESX**, **QB**, or **OX Inventory**, enable this setting.

```lua
Config.UseFramework = false
```

* When `true`, the system uses the inventory (e.g., weapon usage) instead of command-based interactions.
* Setup instructions for each framework are available on:
  * [ESX Guide](https://docs.rytrak.fr/framework-compatibility/add-a-custom-weapon-on-esx)
  * [QBCore Guide](https://docs.rytrak.fr/framework-compatibility/add-a-custom-weapon-on-qbcore)
  * [OX Inventory Guide](https://docs.rytrak.fr/framework-compatibility/add-a-custom-weapon-on-ox-inventory)

***

### 3. Grenade Types Configuration

Each grenade has its own behavior and configuration.

#### 3.1 Tear Gas Grenade

<pre class="language-lua"><code class="lang-lua"><strong>Config.Grenade['tearGas']
</strong></code></pre>

* `weaponModel`: Hash name of the weapon.
* `weaponProp`: Prop model shown in-game.
* `weaponDisplay`: Wheel weapon name.
* `disableControl`: Disables sprint, vehicle entry, fight, and jump during exposure.
* `effects`:
  * `timecycle`: Visual effects applied.
  * `shakeCamera`: Screen shaking intensity and style.
* `smokeScale`: Size of the smoke cloud.
* `smokeDuration`: Duration in milliseconds (e.g., `50000`).
* `smokeParticles`: Defines the FX dictionary and particle.
* `gasMask`: Masks that grant immunity (see section 4).

**Compatibility**

* `pepperspray`: Enables sync with `r_pepperspray`.

```lua
Config.Grenade['tearGas'].compatibility = {
    enabled = false,
    resourceName = 'r_pepperspray',
    applyEffect = 'pepperspray' -- The pepperspray name in the config.lua file of the Advanced Pepper Spray script.
}
```

***

#### 3.2 Stun Grenade

<pre class="language-lua"><code class="lang-lua"><strong>Config.Grenade['stun']
</strong></code></pre>

* `weaponModel`: Hash name of the weapon.
* `weaponProp`: Prop model shown in-game.
* `weaponDisplay`: Wheel weapon name.
* `disableControl`: Disables sprint, vehicle entry, fight, and jump during exposure.
* `flashDuration`: Duration of blinding/stunning effect in milliseconds.
* `flashScale`: Intensity of the flash visual effect
* `flashSound`: Enable or disable flashbang sound effect
* `flashVolume`: Volume of the flashbang sound (0.0 to 1.0)
* `gasMask`: Masks that grant immunity (see section 4).

***

#### 3.3 Smoke Grenade

<pre class="language-lua"><code class="lang-lua"><strong>Config.Grenade['smoke']
</strong></code></pre>

* `weaponModel`: Hash name of the weapon.
* `weaponProp`: Prop model shown in-game.
* `weaponDisplay`: Wheel weapon name.
* `smokeScale`: Size of the smoke cloud.
* `smokeDuration`: Duration in milliseconds (e.g., `50000`).
* `smokeParticles`: Defines the FX dictionary and particle.

***

### 4. Gas Mask Protection

Prevents gas effects if players are wearing certain masks or accessories.

The structure is:

```lua
[PED_MODEL] = {
    [componentId] = {drawableId, drawableId}
}
```

* Example: `[5] = {2}` → Component 5 (mask) with drawable 2.
* Supports both male (`mp_m_freemode_01`) and female (`mp_f_freemode_01`) characters.
* See the documentation for component IDs.

***

### 5. UI Design

Customize the visual progress bar used during recovery animations (e.g., after gas exposure).

```lua
Config.Design = {
    ProgressBar = {
        color = {52, 152, 219}, -- RGB
        text = 'RECOVERY' -- Max 8 characters
    }
}
```

If `text` is empty, the bar will expand without label.

***

### **6. Key Bindings**

#### **Keys for Interactions**

Set the keys used for actions when `CommandEnabled` is set to false.

```lua
Config.Keys = {
    GrabAndDropKey = 289, -- Key to grab and release a person.
    GrabAndDropKeyString = '~INPUT_REPLAY_START_STOP_RECORDING_SECONDARY~', -- Key name for display.

    TaskEnterKey = 305, -- Key to put a person in the vehicle.
    TaskEnterKeyString = '~INPUT_REPLAY_STARTPOINT~' -- Key name for display.
}
```

*Refer to the* [*FiveM Control Reference*](https://docs.fivem.net/docs/game-references/controls/) *for a list of control codes.*

***

### **7. Language Library**

Edit the text displayed for different actions in multiple languages.