# Configuration

## 🛠️ Configuration

***

### <mark style="color:yellow;">Shared Configuration (</mark><mark style="color:yellow;">`configs/shared.lua`</mark><mark style="color:yellow;">)</mark>

#### **Debug Configuration**

Controls debug output for the air drops system.

```lua
Shared.Debug = {
    Enabled = true,     -- Set to false to disable all debug prints
    Levels = {
        Info = true,    -- General information
        Success = true, -- Success operations
        Warning = true  -- Warning and potential issues
    }
}
```

* **Enabled**: Enables/disables all debug prints.
* **Levels**: Controls specific debug message types (Info, Success, Warning).

***

#### **Drop Presets Configuration**

Defines different categories of items that can be dropped in airdrops. Each preset contains a list of items with their spawn properties.

```lua
Shared.DropPresets = {
    ["food"] = { 
        { name = "bread", amount = {min = 1, max = 3}, chance = 75 },
        { name = "water", amount = {min = 1, max = 5}, chance = 20 },
        -- { name = "canned_food", amount = {min = 1, max = 3}, chance = 5 }
    },
    ["medical"] = {
        { name = "bandage", amount = {min = 1, max = 5}, chance = 33 },
        { name = "first_aid_kit", amount = {min = 1, max = 2}, chance = 33 },
        { name = "painkiller", amount = {min = 1, max = 10}, chance = 34 }
    },
    ["weapons"] = {
        { name = "weapon_pistol", amount = {min = 1, max = 1}, chance = 25 },
        { name = "weapon_rifle", amount = {min = 1, max = 1}, chance = 25 },
        { name = "ammo_9mm", amount = {min = 1, max = 150}, chance = 50 }
    },
}
```

**Structure Explanation:**

* **name**: The item identifier/name (must match your inventory system).
* **amount**: Min and max quantity range for the item.
  * **min**: Minimum amount to spawn.
  * **max**: Maximum amount to spawn.
* **chance**: Percentage chance (0-100) for the item to spawn.

**Note**: Each preset's chances should ideally sum to 100% for proper distribution.

***

#### **Mission Drop Configuration**

Defines special mission-based airdrops with specific loot tables and requirements.

```lua
Shared.MissionDrop = {
    { 
        name = "food", 
        chance = 50, 
        amount = {min = 1, max = 5}, 
        requiredItem = { 
            ["crate_key"] = 3,
            ["tools"] = 1
        }
    },
    { 
        name = "medical", 
        chance = 30, 
        amount = {min = 1, max = 5}, 
        requiredItem = false 
    },
    { 
        name = "weapons", 
        chance = 20, 
        amount = {min = 1, max = 5}, 
        requiredItem = { 
            ["crate_key"] = 1
        } 
    }
}
```

**Structure Explanation:**

* **name**: The drop preset category (references `Shared.DropPresets`).
* **chance**: Percentage chance for this mission drop type to occur.
* **amount**: Number of items from the preset to drop.
  * **min**: Minimum number of items.
  * **max**: Maximum number of items.
* **requiredItem**: Items required to open the crate (false = no requirements).
  * Key: Item name.
  * Value: Required quantity.

***

### <mark style="color:yellow;">Client Configuration (</mark><mark style="color:yellow;">`configs/client.lua`</mark><mark style="color:yellow;">)</mark>

#### **Guards Settings**

Configures NPC guards that protect the air drop zones.

```lua
Config.GuardsSettings = {
    amount = {
        min = 5,  -- Minimum number of guards to spawn
        max = 15  -- Maximum number of guards to spawn
    },
    modelsPresets = {
        { "s_m_y_armymech_01", "s_m_m_armoured_02", "mp_s_m_armoured_01" },
        { "s_m_y_blackops_01", "s_m_y_blackops_02", "s_m_y_blackops_03" },
        { "s_m_m_highsec_01", "s_m_m_highsec_02", "a_m_y_hasjew_01", "a_m_m_hasjew_01" },
        { "g_m_y_lost_02", "g_m_y_lost_01", "g_m_y_lost_03" },
        { "s_m_m_marine_01", "s_m_y_marine_01", "s_m_m_marine_02", "s_m_y_marine_02", "s_m_y_marine_03" },
    },
    weapons = {
        "WEAPON_PISTOL",
        "WEAPON_ASSAULTRIFLE",
        "WEAPON_SMG",
        "WEAPON_CARBINERIFLE",
        "WEAPON_COMBATPISTOL",
        "WEAPON_MICROSMG",
        "WEAPON_PUMPSHOTGUN",
        "WEAPON_ASSAULTSHOTGUN",
    }
}
```

**Configuration Details:**

* **amount**: Random number of guards spawned per air drop.
  * **min**: Minimum guards (5).
  * **max**: Maximum guards (15).
* **modelsPresets**: Arrays of ped models for guard variety.
  * Each array represents a thematic group (military, blackops, security, gang, marines).
  * System randomly selects one preset per air drop for visual consistency.
* **weapons**: List of weapons guards can be equipped with.
  * Guards are randomly assigned weapons from this list.

***

### <mark style="color:yellow;">Server Configuration (</mark><mark style="color:yellow;">`configs/server.lua`</mark><mark style="color:yellow;">)</mark>

#### **Air Drop Zones**

Defines all possible locations where air drops can occur.

```lua
Config.AirDropZones = {
    { coords = vec3(-1215.0327, -1550.9435, 4.3715), radius = 2.0 },
}
```

* **coords**: vec3 coordinates (x, y, z) - the center point of the air drop zone.
* **radius**: The spawn radius around the coordinates (in meters). The air drop will spawn at a random location within this radius from the center point.

**To add more zones:**

```lua
Config.AirDropZones = {
    { coords = vec3(-1215.0327, -1550.9435, 4.3715), radius = 60.0 },   -- 60m spawn radius
    { coords = vec3(2500.0, 3700.0, 45.0), radius = 45.0 },  -- Sandy Shores - 45m radius
    { coords = vec3(-2000.0, 2500.0, 5.0), radius = 35.5 },  -- Paleto Bay - 35.5m radius
}
```

***

#### **Air Drop Stats**

Controls the behavior of falling air drops.

```lua
Config.AirDropStats = {
    fallTime = {
        min = 2000,  -- Minimum fall time in milliseconds
        max = 5000,  -- Maximum fall time in milliseconds
    }
}
```

* **fallTime**: How long the air drop takes to fall from the sky.
  * **min**: Minimum fall duration (2 seconds).
  * **max**: Maximum fall duration (5 seconds).
* **Note**: Actual fall time is randomized between min and max for each drop.

***

### <mark style="color:yellow;">Translation Configuration (</mark><mark style="color:yellow;">`configs/translation.lua`</mark><mark style="color:yellow;">)</mark>

Customize all user-facing text in the resource.

```lua
Shared.Lang = {
    ["weight_too_heavy"] = "Weight is too heavy for you, you need to unlock the skill first",
}
```

* Modify these strings to change the language or customize messages.
* Add your own language translations by following the same format.

***

### <mark style="color:yellow;">Customization</mark>

#### **Adding New Drop Presets**

Create custom loot categories for different scenarios:

```lua
Shared.DropPresets = {
    -- Existing presets...
    ["rare_items"] = {
        { name = "diamond", amount = {min = 1, max = 3}, chance = 10 },
        { name = "gold_bar", amount = {min = 2, max = 5}, chance = 30 },
        { name = "rare_artifact", amount = {min = 1, max = 1}, chance = 60 }
    },
    ["tools"] = {
        { name = "lockpick", amount = {min = 5, max = 15}, chance = 40 },
        { name = "advanced_lockpick", amount = {min = 1, max = 5}, chance = 30 },
        { name = "drill", amount = {min = 1, max = 2}, chance = 30 }
    },
}
```

***

#### **Adjusting Guard Difficulty**

**Easier (Fewer Guards):**

```lua
Config.GuardsSettings = {
    amount = {
        min = 2,
        max = 5
    },
    -- Keep weapons list minimal
    weapons = {
        "WEAPON_PISTOL",
        "WEAPON_COMBATPISTOL",
    }
}
```

**Harder (More Guards & Better Weapons):**

```lua
Config.GuardsSettings = {
    amount = {
        min = 15,
        max = 25
    },
    weapons = {
        "WEAPON_ASSAULTRIFLE",
        "WEAPON_CARBINERIFLE",
        "WEAPON_SPECIALCARBINE",
        "WEAPON_COMBATMG",
        "WEAPON_ASSAULTSHOTGUN",
    }
}
```

***

#### **Modifying Drop Chances**

Adjust the probability of different loot types:

**High-Value Drops (More Weapons/Medical):**

```lua
Shared.MissionDrop = {
    { name = "food", chance = 10, amount = {min = 1, max = 3}, requiredItem = false },
    { name = "medical", chance = 40, amount = {min = 2, max = 6}, requiredItem = false },
    { name = "weapons", chance = 50, amount = {min = 1, max = 3}, requiredItem = { 
            ["crate_key"] = 1
        } 
    }
}
```

**Balanced Drops:**

```lua
Shared.MissionDrop = {
    { name = "food", chance = 33, amount = {min = 2, max = 5}, requiredItem = false },
    { name = "medical", chance = 33, amount = {min = 2, max = 5}, requiredItem = false },
    { name = "weapons", chance = 34, amount = {min = 1, max = 3}, requiredItem = { 
            ["crate_key"] = 2
        } 
    }
}
```

***

#### **Creating Locked vs Unlocked Crates**

Control which crates require items to open:

**All Crates Open (No Requirements):**

```lua
Shared.MissionDrop = {
    { name = "food", chance = 33, amount = {min = 1, max = 5}, requiredItem = false },
    { name = "medical", chance = 33, amount = {min = 1, max = 5}, requiredItem = false },
    { name = "weapons", chance = 34, amount = {min = 1, max = 5}, requiredItem = false }
}
```

**All Crates Locked:**

```lua
Shared.MissionDrop = {
    { name = "food", chance = 33, amount = {min = 1, max = 5}, requiredItem = { 
            ["crate_key"] = 1
        } 
    },
    { name = "medical", chance = 33, amount = {min = 1, max = 5}, requiredItem = { 
            ["crate_key"] = 1
        } 
    },
    { name = "weapons", chance = 34, amount = {min = 1, max = 5}, requiredItem = { 
            ["crate_key"] = 2,
            ["advanced_tools"] = 1
        } 
    }
}
```

***

### <mark style="color:yellow;">Advanced Configuration</mark>

#### **Creating Themed Guard Presets**

Customize guard appearance for different scenarios:

```lua
Config.GuardsSettings = {
    amount = { min = 5, max = 15 },
    modelsPresets = {
        -- Military Theme
        { "s_m_y_armymech_01", "s_m_m_armoured_02", "s_m_m_marine_01" },
        
        -- Police/SWAT Theme
        { "s_m_y_swat_01", "s_m_y_cop_01", "s_m_m_fibsec_01" },
        
        -- Gang Theme
        { "g_m_y_ballasout_01", "g_m_y_famca_01", "g_m_y_mexgang_01" },
        
        -- Private Security Theme
        { "s_m_m_highsec_01", "s_m_m_highsec_02", "mp_m_securoguard_01" },
    },
    weapons = {
        "WEAPON_ASSAULTRIFLE",
        "WEAPON_CARBINERIFLE",
        "WEAPON_SMG",
    }
}
```

***

#### **Dynamic Fall Time Based on Height**

Adjust fall times for different scenarios:

**Quick Drops (Low Altitude):**

```lua
Config.AirDropStats = {
    fallTime = {
        min = 1000,  -- 1 second
        max = 2000,  -- 2 seconds
    }
}
```

**Realistic Drops (High Altitude):**

```lua
Config.AirDropStats = {
    fallTime = {
        min = 5000,  -- 5 seconds
        max = 10000, -- 10 seconds
    }
}
```

**Cinematic Drops (Very Slow):**

```lua
Config.AirDropStats = {
    fallTime = {
        min = 8000,  -- 8 seconds
        max = 15000, -- 15 seconds
    }
}
```

***

### <mark style="color:yellow;">Troubleshooting</mark>

**Air drops not spawning:**

* ✅ Verify `Config.AirDropZones` contains valid coordinates.
* Check server console for errors during resource start.
* Ensure the triggering event/command is correctly configured.

**Guards not spawning:**

* Check `Config.GuardsSettings.amount` values are greater than 0.
* Verify ped model names in `modelsPresets` are valid GTA V models.
* Enable debug mode to see spawn messages.

**Players can't open crates:**

* Verify players have the required items defined in `Shared.MissionDrop.requiredItem`.
* Check item names match your inventory system exactly (case-sensitive).
* Ensure inventory has space for the dropped items.

**Items not being received:**

* ✅ Confirm items in `Shared.DropPresets` exist in your database/item configuration.
* Check item names match exactly (case-sensitive).
* Verify player inventory has sufficient weight capacity.
* Enable debug mode to see item distribution logs.

**Guards not attacking:**

* Check weapon names in `Config.GuardsSettings.weapons` are valid.
* Verify no conflicting resources affecting NPC behavior.

***


---

# 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://docs.devhub.gg/air-drops/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.