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:

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.