> 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)
```

***

### **2. Framework Compatibility**

Automatic mode allows for the automatic detection of the framework you are using on your server.

Don't forget to create your shield item by following the pages below:

```lua
Config.Inventory = 'auto' -- auto, qb, esx, ox (you can modify this function on server/inventory.lua)
```

***

### **2. Shields Configuration**

Configure the available shields and customize their behavior using the `Config.Shields` table.

Each entry represents a shield model and its associated configuration.

```lua
Config.Shields = {
    ['ballistic_shield'] = {
        -- Shield configuration
    }
}
```

#### **2.1 Shield Type**

Define whether the shield is a vehicle or a prop.

```lua
type = 'vehicle', -- 'prop' or 'vehicle'
```

* `vehicle`: The shield is handled as a vehicle entity.
* `prop`: The shield is handled as a prop entity.

#### **2.2 Take Radius**

Set the maximum distance at which a player can interact with a shield.

```lua
takeRadius = 1.5,
```

The value is expressed in GTA V world units.

***

### **3. Shield Animations**

#### **3.1 Attachment Settings**

Configure how the shield is attached to the player's character.

```lua
animation = {
    attachBone = 57005,
    attachCoords = {0.0, -0.75, 0.95},
    attachRot = {0.0, 0.0, 0.0},
}
```

* `attachBone`: The bone ID used to attach the shield to the player.
* `attachCoords`: The positional offset of the shield relative to the selected bone, expressed as `{x, y, z}`.
* `attachRot`: The rotational offset of the shield, expressed as `{x, y, z}`.

Adjust these values to position and orient the shield correctly for each model.

#### **3.2 Animation Dictionary**

Define the animation played while holding the shield.

```lua
dict = 'wshield@hold@clip',
name = 'hold_clip',
flag = 50
```

* `dict`: The animation dictionary containing the animation.
* `name`: The animation name within the dictionary.
* `flag`: The animation playback flags.

Use animation dictionaries and names that are compatible with your installed resources.

***

### **4. Weapon Configuration**

#### **Weapon Settings**

Configure the weapon associated with a shield when weapon aiming is supported.

```lua
weapon = {
    hash = GetHashKey('WEAPON_PISTOL'),

    animation = {
        attachBone = 57005,
        attachCoords = {0.08, -0.42, -0.32},
        attachRot = {4.0, -90.0, -90.0},

        dict = 'shield@aim@clip',
        name = 'shield_clip',
        flag = 50
    }
}
```

* `hash`: The weapon hash used by the script.
* `animation`: The animation and attachment settings used when aiming with the weapon.

The weapon animation has its own attachment coordinates and rotation, allowing the shield to be repositioned while aiming.

***

### **5. Ped Movement Configuration**

#### **Movement Clipset**

Configure the movement style used by the player while carrying a shield.

```lua
pedMovementClipset = {
    dict = "move_m@casual@d",
}
```

* `dict`: The movement clipset dictionary applied to the player.

This option is useful for shields that require a specific movement style.

***

### **6. Vehicle Driving Configuration**

#### **Drive Mode**

Configure the driving speed associated with vehicle-based shields that support this feature.

```lua
driveMode = {
    speed = 5.0,
}
```

* `speed`: The configured driving speed.

The exact behavior depends on how the script implements the vehicle's driving mode.

***

### **7. Light and Flash Systems**

#### **7.1 Light System**

Enable or disable the light system for a shield.

```lua
lightSystem = true,
```

* `true`: Enables the light system using **Extra 1**.
* `false`: Disables the light system.

**Requirements:**

* The shield must be configured as a vehicle.
* The vehicle must use a **Non-ELS lighting system**.
* **Extra 1** must be assigned to the light system.

#### **7.2 Flash System**

Enable or disable the flash system for a shield.

```lua
flashSystem = true,
```

* `true`: Enables the flash system using **Extra 2**.
* `false`: Disables the flash system.

**Requirements:**

* The shield must be configured as a vehicle.
* The vehicle must use a **Non-ELS lighting system**.
* **Extra 2** must be assigned to the flash system.

Both settings can be configured independently for each shield. Ensure that the vehicle's extras are correctly configured for the systems to work as intended.

***

### **6. Key Bindings**

#### **Keys for Interactions**

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

```lua
Config.Keys = {
    TakeKey = 38, -- Key to drop water
    TakeKeyString = '~INPUT_PICKUP~', -- Key string to drop water
    
    PutInventoryKey = 47, -- Key to put the shield in inventory
    PutInventoryKeyString = '~INPUT_DETONATE~', -- Key string to put the shield in inventory

    TakePistolKey = 182, -- Key to take the pistol
    TakePistolKeyString = '~INPUT_CELLPHONE_CAMERA_FOCUS_LOCK~', -- Key string to take the pistol

    LightKey = 74, -- Key to switch the flashlight on the shield
    LightKeyString = '~INPUT_VEH_HEADLIGHT~', -- Key string to switch the flashlight on the shield

    FlashLightKey = 45, -- Key to toggle the flashlight mode
    FlashLightKeyString = '~INPUT_RELOAD~' -- Key string to toggle the flashlight mode
}
```

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