# Configuration

This configuration file allows you to set up different settings and options for your FiveM server. 

***

### Overview

#### Framework Selection

* **`Config.framework`**\
  Determines the roleplay framework used. Can be either `QB` (QBCore) or `ESX` (ESX Framework).\
  **Default**: `"QB"`
* **`Config.language`**\
  Sets the language used in menus and notifications. Currently set to English.\
  **Default**: `English`
* **`Config.debug`**\
  Enables console prints for debugging. Setting it to `true` will show debug messages in the console.\
  **Default**: `false`

***

#### Backup Codes

The **backup codes** are predefined configurations for different types of backup units. Each backup unit can include the following parameters:

* **`name`**\
  The identifier for the backup code (e.g., "CODE1", "CODE2", etc.).
* **`car`**\
  The vehicle model used by the backup unit (e.g., "police3", "fbi", etc.).
* **`livery`**\
  The livery for the vehicle. It is set to `0` by default.
* **`outfit`**\
  The outfits that backup NPCs will wear. Can be a list of outfits (e.g., `{"COP1", "COP2"}`). If set to `null`, no outfit is assigned.
* **`useCustomModel`**\
  If set to `true`, the NPCs will use a custom model as defined by `customModel`. If set to `false`, the default NPC models will be used.
* **`customModel`**\
  Specifies the custom NPC model to use when `useCustomModel` is set to `true`.
* **`weaponDriver`**\
  The weapon that the driver will carry.
* **`weaponPassenger`**\
  The weapon that the passenger will carry.
* **`health`**\
  The health of the NPC backup unit.
* **`precision`**\
  The shooting accuracy (from 0 to 100) of the NPC backup unit.
* **`drivingSpeed`**\
  The target driving speed for the NPC driver.
* **`combatStyle`**\
  The combat behavior of the NPC. Can be `"defensive"` or `"offensive"`.
* **`pursuitStyle`**\
  The driving and pursuit style of the backup during chases. Can be `"aggressive"`, `"ramming"`, `"boxing"`, `"tactful"`, or `"stayback"`.
* **`gradelevel`**\
  The minimum LEO job grade level required to request this backup.
* **`reinforcementgradelevel`**\
  The minimum LEO job grade level required to request this backup as an additional reinforcement unit.
* **`description`**\
  A description of the backup unit.

***

#### Example Backup Codes

1. **Local Police Backup**\
   A basic police backup unit with a vehicle and police NPCs.

   ```lua
   {   
       name = "CODE1",
       car = "police3",
       outfit = {"COP1", "COP2"},
       health = 200,
       precision = 85,
       drivingSpeed = 50.0,
       combatStyle = 'defensive',
       pursuitStyle = 'stayback',
       gradelevel = 1,
       reinforcementgradelevel = 2,
       description = "Local Police Backup"
   }
   ```
2. **FBI Support**\
   A higher-level backup unit that deploys FBI agents with specialized weapons and higher health.

   ```lua
   {   
       name = "CODE2",
       car = "fbi",
       outfit = {"AGENT1", "AGENT2"},
       health = 250,
       precision = 99,
       drivingSpeed = 100.0,
       combatStyle = 'offensive',
       pursuitStyle = 'stayback',
       gradelevel = 2,
       reinforcementgradelevel = 3,
       description = "FBI Support"
   }
   ```
3. **NOOSE Response Team**\
   A SWAT unit with higher health, precision, and combat capabilities.

   ```lua
   {   
       name = "CODE3",
       car = "riot",
       outfit = "SWAT",
       health = 450,
       precision = 95,
       drivingSpeed = 180.0,
       combatStyle = 'offensive',
       pursuitStyle = 'stayback',
       gradelevel = 3,
       reinforcementgradelevel = 4,
       description = "NOOSE Response Team"
   }
   ```
4. **Military Reinforcement**\
   A military backup unit with combat vehicles and high health.

   ```lua
   {   
       name = "CODE4",
       car = "crusader",
       outfit = {"MARINE1", "MARINE2"},
       health = 600,
       precision = 90,
       drivingSpeed = 70.0,
       combatStyle = 'offensive',
       pursuitStyle = 'stayback',
       gradelevel = 4,
       reinforcementgradelevel = 4,
       description = "Military Reinforcement"
   }
   ```

***

#### Air Support Configuration

Air support is provided by different backup units. Air support can be activated with certain conditions:

* **`name`**\
  The identifier for the air support code.
* **`plane`**\
  The vehicle model used by the air unit (e.g., "polmav", "valkyrie2").
* **`attack`**\
  If set to `true`, the air support will engage in attacks; otherwise, it will act as a recon unit.
* **`precision`**\
  The shooting accuracy (from 0 to 100) of the air unit when attacking.
* **`gradelevel`**\
  The minimum LEO job grade level required to request this air support.
* **`description`**\
  A description of the air support unit.

***

#### Example Air Support Configurations

1. **Police Recon Maverick**\
   A police recon helicopter that does not attack.

   ```lua
   {   
       name = "AIR1",
       plane = "polmav",
       attack = false,
       precision = 60,
       gradelevel = 1,
       description = "Police Recon Maverick"
   }
   ```
2. **Tactical Assault Maverick**\
   A tactical assault helicopter used for offensive operations.

   ```lua
   {   
       name = "AIR2",
       plane = "polmav",
       attack = true,
       precision = 60,
       gradelevel = 2,
       description = "Tactical Assault Maverick"
   }
   ```
3. **Military-Grade Assault Helicopter**\
   A more advanced military helicopter with attack capabilities.

   ```lua
   {   
       name = "AIR3",
       plane = "valkyrie2",
       attack = true,
       precision = 60,
       gradelevel = 3,
       description = "Military-Grade Assault Helicopter"
   }
   ```

***

#### General Configurations

* **`Config.openMenu`**\
  The key bind to open the backup menu.\
  **Default**: `'PAGEUP'`
* **`Config.cooldownTime`**\
  The cooldown duration (in seconds) before another backup unit can be called.\
  **Default**: `35`
* **`Config.useMaxPolice`**\
  Enables or disables a maximum limit for the number of police players available to use the backup command.\
  **Default**: `false`
* **`Config.maxPolice`**\
  The maximum number of police players available for requesting backup.\
  **Default**: `5`
* **`Config.sufferHeadshot`**\
  Determines if NPC backup units will suffer headshot damage.\
  **Default**: `false`
* **`Config.ragdoll`**\
  Determines if NPC backup units can ragdoll when pushed or shot.\
  **Default**: `false`
* **`Config.NPCrespectPolice`**\
  Defines whether hostile NPCs will respect police units and avoid attacking them.\
  **Default**: `false`
* **`Config.customDrivingStyle`**\
  Defines a custom driving style for NPC backup units.\
  **Default**: `0`
* **`Config.maxSpawnDistance`**\
  The maximum spawn distance for backup units.\
  **Default**: `180`
* **`Config.backupDefaultFormation`**\
  The default formation for backup units.\
  **Default**: `0` (Freedom to move)

***

#### Air Support General Configurations

* **`Config.MaxHuntingDistance`**\
  The maximum distance within which air units can pursue targets.\
  **Default**: `300`
* **`Config.LimitedAirConnectionDistance`**\
  Determines if the air unit connection has a limited distance.\
  **Default**: `false`
* **`Config.MaxAirConnectionDistance`**\
  The maximum distance (in game units) for air unit camera connections.\
  **Default**: `1000`
* **`Config.heliPads`**\
  Defines a list of helipad locations for air support units.\
  **Default**: A set of predefined locations.

***

#### AI Response Protocol (`useAIResponse`)

```lua
Config.useAIResponse = "NEVER"  -- Core engagement logic
```

**What This Does**\
Dictates when AI units supplement human officers:

| Option        | Behavior                                                | Use Case                        |
| ------------- | ------------------------------------------------------- | ------------------------------- |
| `"ALWAYS"`    | AI responds to ALL crimes                               | Servers with minimal PD players |
| `"LOWPOLICE"` | Hybrid system activates when human officers < threshold | Balanced RP environments        |
| `"NEVER"`     | Pure player-driven policing                             | Hardcore RP servers             |

⚠️ **Pro Tip**: Use `"LOWPOLICE"` with `lowPolice = 0` to create AI backup only when no human officers are available.

***

#### 2. Response Tier System (`AIResponseSettings`)

```lua
Config.AIResponseSettings = {   
    AIPoliceBackupCode = "CODE1",  -- Standard patrol units
    AISWATBackupCode = "CODE3",    -- Tactical response team
}
```

**Key Mechanics**

* `CODE1`: Routine response (patrol cars, non-lethal gear)
* `CODE3`: SWAT/NOOSE equivalent (armored vehicles, heavy weapons)
* *Configured in your backup code system* (see Advanced Setup section)

***

#### 3. Performance Optimization

```lua
Config.BoostAIcars = false  -- Vehicle handling modifier
```

**What Changes When Enabled**

| Setting | Driving Behavior                                               | Impact                                                       |
| ------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
| `true`  | <p>AI vehicles gain:<br>• +25% speed<br>• Better cornering</p> | <p>More challenging pursuits<br>(May affect low-end PCs)</p> |
| `false` | Native GTA driving AI                                          | Authentic PD chase experience                                |

***

#### 4. Staffing Thresholds

```lua
Config.lowPolice = 3  -- Officer capacity trigger
```

**Practical Example**

```
- Scenario: 2 human officers online 
+ AI Response: ACTIVE (until 3+ humans available)
```

\*Ideal for medium-population servers (50-75 players)\*

***

### Crime Handling System

#### 1. Automatic Crime Matrix

*Native GTA V Events → Penalty Mapping*

These are native GTA V events (like shooting, driving crazy, fighting, etc.) detected automatically when witnessed by NPCs.

You do NOT need to trigger these manually, they fire based on GTA behavior

| Crime Type   | Sample Event | Default Penalty |            |        |
| ------------ | ------------ | --------------- | ---------- | ------ |
| **Firearm**  | `GunFight`   | 3★              | 10min jail | $3,000 |
| **Vehicle**  | `PedRunOver` | 4★              | 12min jail | $4,000 |
| **Violence** | `PedKilled`  | 5★              | 20min jail | $8,000 |

📌You can find the full list of all supported shocking events here: [GTA Shocking Events Reference](https://pastebin.com/s7Y6KNd0)

***

#### 2. Custom Crime Integration

**For Script Developers**

```lua
-- Trigger from ANY script
exports["enyo-policebackup"]:SetPlayerWanted(
    stars,     -- 0-5 wanted level
    jailTime,  -- Minutes (applied if arrested)
    fineAmount -- $ Amount
)
```

**Bank Robbery Example**

```lua
-- After vault breach event
RegisterNetEvent('heist:success', function()
    exports["enyo-policebackup"]:SetPlayerWanted(5, 25, 15000)
end)
```

*This would trigger:*

* ⭐⭐⭐⭐⭐ Wanted level
* 25 minute jail sentence
* $15,000 fine

***

### AI Outfitting System

Outfit Configuration Guide

**Step-by-Step Creation**

1. **Dress Character**: Create desired appearance in-game
2. **Export Command**: Type `/exportoutfit4enyo`
3. **Paste Config**:

```lua
["SWAT"] = {
    gender = "male",
    clothing = {
        MASK = { clothingItem = 52, textureId = 0 },
        -- Additional components...
    }
}
```

***

#### Outfit Randomization Logic

```lua
UPPER = { 
    { clothingItem = 19, textureId = 0 }, -- 33% chance
    { clothingItem = 19, textureId = 1 }, -- 33% chance
    { clothingItem = 21, textureId = 0 }  -- 33% chance
}
```

**Biased Selection**

```lua
Config.biasedOutfitChance = true
```

*When enabled:*

* First item in list: 60% chance
* Other items: 20% each\
  \&#xNAN;*Creates semi-uniform squads while maintaining variety*

***

Response Code Structure

**Sample Backup Code Configuration**

```lua
Config.codes = {
    ["CODE1"] = {
        vehicles = {"police", "police2"},
        outfits = {"COP1", "COP2"}, -- From Config.outfits
        minUnits = 2,
        maxUnits = 4
    },
    ["CODE3"] = {
        vehicles = {"riot", "swatvan"},
        outfits = {"SWAT"},
        minUnits = 4,
        maxUnits = 8
    }
}
```

*Define response team compositions per escalation level*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://enyo-scripts.gitbook.io/documentations/fivem-scripts/ai-police-backup/configuration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.