> For the complete documentation index, see [llms.txt](https://fb-scripts.gitbook.io/fb-scripts/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://fb-scripts.gitbook.io/fb-scripts/scripts/fb-blackmarket/configuration.md).

# Configuration

All settings are in `config.lua` (1237 lines). Here's a reference for every major section:

#### General Settings

```lua
Config.Framework = "auto"           -- Framework to use (auto/qbcore/esx/custom)
Config.Target = "qb-target"        -- Target system (qb-target/ox_target/qtarget/drawtext/custom)
Config.Language = "en"              -- Language code
Config.Debug = false                -- Enable debug prints (DISABLE in production!)
Config.OptimizePerformance = true   -- Optimizes tick loops (keep enabled)
Config.UpdateInterval = 1000        -- NPC render check interval (ms)
Config.MaxRenderDistance = 151      -- Max distance to render NPCs (meters)
Config.UseTarget = true             -- Use target system vs DrawText3D
Config.InteractionDistance = 2.5    -- Max distance for interaction
```

#### Payment Methods

```lua
Config.PaymentMethods = {
    cash = true,         -- Enable cash payments
    bank = true,         -- Enable bank payments
    blackMoney = false,  -- Enable dirty money payments
    crypto = false,      -- Enable crypto payments
    custom = false       -- Enable custom item-based currency
}
Config.CustomCurrencyItem = "fb-coin"  -- Item name for custom currency
```

#### Stock Management

```lua
Config.StockManagement = {
    Enabled = false,           -- Enable/disable stock system
    GlobalStock = true,        -- true = shared stock, false = per-player stock
    ResetOnRestart = true,     -- Reset stock when server restarts
    RestockAmount = "full",    -- "full" = max stock, "50%" = half stock
    SaveToDatabase = false,    -- Persist stock to MySQL (requires SQL import)
    RestockTime = 3600,        -- Auto-restock interval (seconds), 0 = disabled
    NotifyOnRestock = true     -- Notify online players when stock restocks
}
```

#### Level System

```lua
Config.LevelSystem = {
    StartingLevel = 1,
    StartingXP = 0,
    BaseXPPerLevel = 500,          -- Base XP needed for level 2
    CalculationMode = "multiplier", -- "multiplier" (geometric) or "linear"
    Multiplier = 1.2,              -- Each level needs 1.2x more XP
    Increment = 250,               -- (linear mode) flat XP increase per level
    XPScaling = 1,                 -- Legacy scaling factor

    -- Per-shop XP profiles (optional)
    Profiles = {
        vip_smuggler = {
            BaseXPPerLevel = 1000,
            Multiplier = 1.5,
            XPScaling = 2
        }
    }
}
```

#### Reputation Tiers

```lua
Config.ReputationTiers = {
    { minLevel = 1, name = "Street Dealer", color = "neutral" },
    { minLevel = 3, name = "Smuggler",      color = "blue" },
    { minLevel = 5, name = "Arms Broker",   color = "purple" },
    { minLevel = 8, name = "Kingpin",       color = "amber" }
}
```

#### Heat System

```lua
Config.HeatSystem = {
    Enabled = true,
    MaxHeat = 100,            -- Shop closes at this heat level
    HeatPerMinute = 15,       -- Heat gained per minute with police nearby
    DecayPerMinute = 5,       -- Heat lost per minute when police leave
    DetectionRadius = 100     -- Radius in meters to detect police
}
```

#### Economy System

```lua
Config.EconomySystem = {
    Enabled = true,
    MaxMarkup = 1.2    -- At max heat, prices are 1.2x (20% more)
}

Config.SupplyDemand = {
    Enabled = true,
    MaxDemandMarkup = 1.5,       -- Max demand-based markup (50% increase)
    DemandThreshold = 10,        -- Purchases before price starts increasing
    DemandDecayPerCycle = 2,     -- Demand decrease per decay cycle
    DecayInterval = 5            -- Minutes between decay cycles
}

Config.FlashSale = {
    Enabled = true,
    Interval = 30,         -- Minutes between flash sales
    Duration = 10,         -- Minutes each sale lasts
    MinDiscount = 10,      -- Minimum discount (%)
    MaxDiscount = 40,      -- Maximum discount (%)
    MaxItems = 3,          -- Max items on sale simultaneously
    NotifyPlayers = true,  -- Notify players about flash sales
    ExcludeVIP = true      -- Exclude VIP shop items from sales
}
```

#### Opening Hours

```lua
Config.OpeningHours = {
    Enabled = false,       -- Enable time restrictions
    StartHour = 22,        -- Opens at 22:00 (in-game time)
    EndHour = 6            -- Closes at 06:00 (in-game time)
}
```

#### Police Interrogation

```lua
Config.Interrogation = {
    Enabled = true,
    Duration = 10000,          -- Interrogation animation duration (ms)
    SuccessChance = 50,        -- % chance of successful interrogation
    MaxAttempts = 1,           -- Max attempts per NPC
    Cooldown = 20,             -- Seconds between interrogations
    ArrestDuration = 10000,    -- Arrest animation duration (ms)
    Jobs = { "police", "sheriff", "fbi" },  -- Jobs that can interrogate
    Animation = {
        dict = "missheist_agency2aig_2",
        anim = "chat_a"
    }
}
```

#### Anti-Cheat

```lua
Config.AntiCheat = {
    Enabled = true,
    WarnThreshold = 3,           -- Discord alert after this many violations
    KickThreshold = 10,          -- Auto-kick after this many (0 = disable)
    ViolationDecay = 300,        -- Reset violations after 5 minutes

    DiscordAlerts = { Enabled = true },

    RateLimits = {               -- Cooldowns in milliseconds
        purchaseItems = 2000,
        collectDelivery = 5000,
        interrogateNPC = 10000,
        searchVehicle = 5000,
        arrestSuspect = 10000,
        requestData = 1500,
        addHeat = 8000,
        completeTask = 1000,
        addTaskProgress = 1000
    }
}
```

#### Mask System

```lua
Config.MaskSystem = {
    Enabled = false,         -- Require mask to access blackmarket
    AllowedMasks = {}        -- Empty = any mask > 0 is valid, or specify IDs: {45, 46, 47}
}
```

#### Job Access

```lua
Config.JobSettings = {
    Enabled = false,
    Mode = "whitelist",      -- "whitelist" = only listed jobs, "blacklist" = everyone except listed
    Jobs = {
        ambulance = true,
        police = false
    }
}
```

#### Wandering System

```lua
Config.WanderingSystem = {
    Enabled = true,
    Interval = 1000    -- Minutes between location changes (0 = only on restart)
}
```

#### UI Settings

```lua
Config.UI = {
    ShowPeds = true,           -- Show NPC vendors
    MaxDistance = 10,           -- Close UI when walking this far from NPC
    CloseOnDeath = true,       -- Close UI on player death
    CloseOnDistance = true      -- Close UI when walking away
}

Config.Avatar = {
    Enable = true,
    Source = "mugshot"    -- "mugshot" (in-game headshot) or "default" (static icon)
}
```

#### Notifications

```lua
Config.Notifications = {
    Enabled = true,             -- Master toggle
    Purchase = true,            -- Purchase success alerts
    Delivery = true,            -- Delivery flow alerts
    LevelUp = true,             -- Level up notifications
    TaskComplete = true,        -- Task completion alerts
    PoliceInterrogation = true, -- Police interrogation alerts
    duration = 5000,            -- Notification duration (ms)
    type = "qb"                 -- Notification type
}
```

#### Inventory Images

```lua
Config.UseInventoryImages = true
Config.InventoryResource = "qb-inventory"
Config.InventoryImagePath = "nui://qb-inventory/html/images/"
Config.FallbackImagePath = "images/"
```

#### Tablet System

```lua
Config.TabletSystem = {
    Enabled = true,
    Tablets = {
        fb_bm_tablet = {
            Enabled = true,
            BreakMessage = "Your VIP tablet has been destroyed by the system!",
            MaxUses = 5,         -- Breaks after 5 uses
            HasDurability = true
        },
        fb_vipbm_tablet = {
            Enabled = true,
            BreakMessage = "Your tablet encryption has failed and it was destroyed!",
            MaxUses = 3,         -- Breaks after 3 uses
            HasDurability = true
        }
    }
}
```

#### Sound Configuration

```lua
Config.InteractionSound = "whatsupbody.mp3"
Config.SoundVolume = 0.4
Config.Sound3D = true
Config.SoundDistance = 3.5
Config.SoundDropoffStart = 0.5

Config.VoiceCues = {
    Enabled = true,
    Volume = 0.4,
    VIP = {
        Enter = { "vipsounds/vipenter1.mp3", "vipsounds/vipenter2.mp3", ... },
        Deal = { "vipsounds/vipdeal1.mp3", ... },
        Delivery = { "vipsounds/vipdelivery1.mp3", ... }
    },
    Default = {
        Enter = { "downtownsounds/entervoice1.mp3", ... },
        Exit = { "downtownsounds/exit1.mp3", ... },
        Delivery = { "downtownsounds/delivery1.mp3", ... }
    }
}
```

#### Adding Items

Add items to `Config.Items` in `config.lua`:

```lua
{
    name = "Heavy Pistol",            -- Display name
    spawnName = "weapon_heavypistol", -- Game item/weapon name
    price = 45000,                    -- Base price
    stock = 20,                       -- Initial stock (-1 = unlimited)
    category = "guns",                -- Category ID
    requiredLevel = 0,                -- Minimum level to purchase (0 = no restriction)
    image = "heavypistol.png",        -- Image filename
    shops = { "vip_smuggler" }        -- Optional: restrict to specific shops
}
```

#### Adding Vehicles

```lua
{
    name = "Sultan RS",
    spawnName = "sultanrs",
    price = 150000,
    stock = 2,
    category = "cars",
    requiredLevel = 1,
    isVehicle = true,         -- Required for vehicles
    isStolenVehicle = false,  -- true = no garage save, cheaper
    modsFull = false,
    shops = { "vip_smuggler" },

    appearance = {
        forceColor = true,
        livery = 0,
        bulletproofTires = false,
        windowTint = 1,
        colors = {
            { id = 0, name = "Black" }
        },
        mods = {
            engine = 3,        -- 0-4
            brakes = 2,        -- 0-3
            transmission = 2,  -- 0-3
            suspension = 3,    -- 0-4
            armor = 4,         -- 0-5
            turbo = true,      -- true/false
            headlights = false -- true/false (xenon)
        }
    }
}
```

#### Adding Categories

```lua
Config.Categories = {
    { id = "all",    label = "ui.all_items", default = true },
    { id = "guns",   label = "ui.guns" },
    { id = "cars",   label = "Cars" },
    { id = "ammos",  label = "ui.ammos" },
    { id = "others", label = "ui.others" }
}
```

{% hint style="info" %}
Labels starting with `ui.` are automatically looked up from the locale file.
{% endhint %}

#### Delivery System

```lua
Config.Delivery = {
    ItemDelivery = false,        -- Enable item delivery (false = instant)
    VehicleDelivery = false,     -- Enable vehicle delivery
    ShopSpecificDelivery = true, -- Use shop-linked delivery points
    QueueDeliveries = false,     -- Allow queuing multiple orders
    PoliceChance = 41,           -- % chance of police alert on collection
    MaxOrders = 3,               -- Max active orders per player
    MaxOrdersDuration = 60,      -- Max delivery time (minutes)
    Enabled = false,             -- Master toggle

    -- Per-shop overrides
    ShopOverrides = {
        vip_smuggler = {
            MaxOrders = 10,
            PoliceChance = 5,
            MaxOrdersDuration = 30
        }
    },

    DirectVehicle = {
        StolenMode = "spawn",    -- "spawn" = spawn near shop
        Garage = "pillboxgarage" -- Garage for purchased vehicles
    }
}
```

#### Adding Delivery Locations

```lua
Config.Delivery.Locations = {
    {
        ped = { x = -129.03, y = -30.81, z = 58.18, w = 352.31 },
        pedModel = "a_m_m_hillbilly_02",
        vehicle = { x = -130.06, y = -33.89, z = 57.99, w = 161.85 },
        vehicleModel = "burrito3",
        spawnDistance = 100,                  -- Render distance
        shops = { "vip_smuggler" },          -- Link to specific shop (optional)
        extraPeds = { ... }                  -- Additional guard NPCs (optional)
    }
}
```

***

### In-Game Admin Panel

FB-Blackmarket includes a **full-featured admin configuration panel** accessible in-game. This allows you to modify nearly all settings without editing `config.lua` directly.

#### How to Access

The admin panel is triggered via a Lua event from the server (typically bound to an admin command or permission check):

```lua
-- Example admin command (add to your admin script):
RegisterCommand('bmsettings', function(source)
    -- Add your permission check here
    TriggerClientEvent('fb-blackmarket:client:openSettings', source)
end, true)
```

#### Panel Sections

The admin panel is organized into **6 main categories**:

| Category                        | Sections                                                          | What You Can Configure                                            |
| ------------------------------- | ----------------------------------------------------------------- | ----------------------------------------------------------------- |
| **Core System & Interaction**   | General Settings, Interaction & UI, Sound System, Images, Tablets | Framework, target, performance, sounds, images, tablet durability |
| **Economy & Stock Management**  | Payment & Economy, Stock Management, Heat & Demand                | Payment methods, stock rules, heat, supply/demand, flash sales    |
| **Logistics & Delivery**        | Delivery System                                                   | Item delivery, vehicle delivery, police chance, delivery queue    |
| **Reputation & RPG Gameplay**   | Level & Reputation, Wandering System                              | XP formula, tiers, vendor movement                                |
| **Law Enforcement Interaction** | Police, Opening Hours                                             | Interrogation settings, work hours                                |
| **Security & Analytics**        | Anti-Cheat, Notifications, Discord                                | Rate limits, violation thresholds, notification toggles, webhook  |

#### Panel Features

* **🔄 Save Config** — Saves all changes to `config.lua` instantly
* **🔁 Restart Script** — Restarts the resource to apply changes (requires permission)
* **↩️ Reset to Default** — Reverts all settings to factory defaults
* **🔍 Auto-Detect** — Automatically detects your framework, target system, and inventory
* **📖 Interactive Guide** — Each setting has an expandable guide explaining what it does
* **🌐 Localized** — The admin panel UI translates to your configured language