# Config

## Smash & Grab Developer & Configuration Guide

This document explains how to configure the script and how the open-source logic files work for custom integrations.

***

### **1. Configuration Files**

### **Shared Configuration** (`shared.lua`)

These settings affect both the server and the client.

#### **General Settings**

* **`SpawnChance`**: (Decimal 0.0 to 1.0) The probability that a vehicle will spawn with loot inside. `0.5` means a 50% chance.
* **`Debug`**: (Boolean) Enables extra logging in the console. Set to `false` for production.
* **`DefaultLootIdx`**: (Integer) The index of the loot table used by default (e.g., `1` for Duffel Bag).

#### **Loot Configuration**

The `Loot` table defines what players can find. Each entry includes:

* **`label`**: The name displayed in-game for this loot type.
* **`models`**: A list of 3D models (props) that can appear inside the vehicle.
* **`rewards`**: A list of items that can be found.
  * `item`: The internal name of the item (e.g., `'money'`).
  * `chance`: Percentage chance (0-100) to find this item.
  * `min` / `max`: The range of the amount given to the player.

### **Client Configuration** (`client.lua`)

These settings control the player's experience and local script behavior.

#### **Debug Visuals**

* **`DebugBlips`**: (Boolean) If true, shows icons on the map for all vehicles currently containing loot.
* **`DebugBlipSprite` / `Colour` / `Scale` / `Name`**: Customizes how these debug icons look on the map.

#### **Detection & Interaction**

* **`ScanRadius`**: (Float) The distance around the player to search for vehicles. Higher values use more CPU.
* **`ScanIntervalMs`**: (Milliseconds) How often the script scans for nearby loot vehicles.
* **`TargetDistance`**: (Float) How close the player must be to the vehicle window to see the "Smash" prompt.

#### **Timing**

* **`SmashDurationMs`**: (Milliseconds) Time it takes to smash the window.
* **`LootDurationMs`**: (Milliseconds) Time it takes to grab the bag after smashing.

#### **Police & Dispatch**

* **`Dispatch`**: (Boolean) Enables or disables automatic police alerts when a window is smashed.

#### **Vehicle Restrictions**

* **`blacklistClasses`**: A list of vehicle class IDs that are prevented from spawning loot (e.g., bikes, boats, planes).

#### **Visuals & Animations**

* **`AttachBone`**: The vehicle bone where the loot bag is attached (e.g., `'seat_pside_f'` for front passenger seat).
* **`AttachOffset` / `AttachRot`**: Fine-tunes the position and rotation of the bag inside the car.
* **`SmashAnim` / `LootAnim`**: Defines the dictionary and clip names for the player's animations.

#### **Requirements**

* **`RequiredItem`**: (String or `false`) The item name required to smash a window (e.g., `'weapon_crowbar'`).
* **`RequiredHoldOnHands`**: (Boolean) If true, the `RequiredItem` must be the active weapon in the player's hands.
* **`WindowIndex`**: (Integer) Which window is targeted (usually `1` for the front passenger).

#### **UI Labels**

* **`SmashLabel` / `LootLabel`**: The text shown on the interaction prompt.
* **`SmashProgressLabel` / `LootProgressLabel`**: The text shown on the progress bar during actions.
* **`DispatchTitle` / `DispatchCode`**: Information sent to the police dispatch system.

***

### **2. Client Logic** (`client/cl_open.lua`)

*This file handles the interaction system and player-side actions.*

#### **Interaction.Add(netId, veh)**

Adds the "Eye" (Target) interaction to the vehicle.

* **Smash Interaction**: Only shows if the window is intact and the player has the required item.
* **Loot Interaction**: Only shows after the window is smashed and a bag is present.

#### **Interaction.OnSmash(netId, veh)**

Triggered when a player selects "Smash window".

* **Dispatch**: Calls `Bridge.Dispatch.SendAlert`. You can modify this to use your own dispatch system.
* **Minigames**: Line 90 is a placeholder where you can insert a minigame (e.g., a skill check) before the progress bar starts.
* **Execution**: Runs the animation and progress bar, then smashes the physical window.

#### **Interaction.OnLoot(netId, veh)**

Triggered when a player selects "Grab bag".

* **Anti-Spam**: Uses `pendingLoot` to prevent multiple triggers.
* **Success**: Triggers the server event `os_smash_grab:server:lootVehicle` after the progress bar finishes.

***

### **3. Server Logic** (`server/sv_open.lua`)

*This file handles the actual distribution of items.*

#### **giveLoot(\_src, \_lootIdx, \_lootDef)**

The core function that calculates and grants rewards.

* **Logic**: It loops through the `rewards` defined in `shared.lua`.
* **Randomization**: For each item, it rolls `math.random(100)`. If it's less than or equal to the `reward.chance`, it calculates a random count between `min` and `max`.
* **Bridge Integration**: Uses `Bridge.Inventory.AddItem` to give the item. This is compatible with ESX, QB-Core, and Ox Inventory via the `community_bridge`.

***

### **4. Customization Tips**

#### **Adding a Minigame**

In `cl_open.lua`, inside `Interaction.OnSmash`, you can wrap the progress bar in a minigame export:

```lua
local success = exports['my_minigame']:StartGame()
if success then
    -- Proceed with progress bar and smashing
end
```

#### **Changing the Dispatch**

If you don't use a standard dispatch, modify the `Bridge.Dispatch.SendAlert` block in `cl_open.lua` (Lines 75-89) to match your script's export.