Configuration Files

This section covers the various configuration files that allow you to customize the heist system to match your server's needs. Each file controls different aspects of the system, from basic settings t

config.lua

The main configuration file controls general settings, framework integrations, and defines items and weapons.

General Settings

Setting	Type	Description
debug	Boolean	Enables debug mode with additional console output
dev_mode	Boolean	Enables developer mode with testing features
lang	String	Language setting (e.g., 'en')
notify	String	Notification system to use ('ox', 'default', 'qb', 'esx', 'nd')
doorlock	String	Door lock system to use ('auto', 'ox', 'qb', 'jaksam')
old_ox_doorlock	Boolean	Support for older versions of ox_doorlock
custom_dispatch	Boolean	Whether to use custom dispatch code in bridge/client/utils.lua
custom_loot	Boolean	Whether to use custom loot code in bridge/server/utils.lua

Police Jobs

Define which job identifiers are considered police for heist requirements.

police_jobs = {
    police = true,
    sheriff = true,
    -- Add more police job identifiers here
},

Items Configuration

Example:

items = {
    gas_mask = {
        item = 'gas_mask', -- Item name in your inventory system, or false to disable
        command = 'gmask', -- Command to use the item, or false to disable
        onUse = function()
            local model = GetEntityModel(cache.ped)
            if model == `mp_m_freemode_01` then -- male
                exports['sh-heists']:ToggleGasMask(52, 10) -- clothingId, colorId
            else -- female
                exports['sh-heists']:ToggleGasMask(71, 0) -- clothingId, colorId
            end
        end
    },
    heist_bag = {
        item = 'duffel_bag', -- Or false to disable
        command = 'hbag', -- Or false to disable
        onUse = function()
            exports['sh-heists']:ToggleBag(82, 0) -- clothingId, colorId
        end
    },
}

Weapons Classification

The weapons section categorizes weapon hashes into types for requirement checks.

Available weapon categories:

• 'melee'

• 'handgun'

• 'rifle'

• 'smg'

• 'lmg'

• 'shotgun'

• 'sniper'

• 'heavy'

• 'throwable'

• 'other'

Example:

weapons = {
    [`weapon_pistol`] = 'handgun',
    [`weapon_combatpistol`] = 'handgun',
    [`weapon_assaultrifle`] = 'rifle',
    [`weapon_smg`] = 'smg',
    -- Add more weapons with their categories
}

Clothing Configuration

The clothing section defines which clothing items are considered bags and which glove types are available.

clothing = {
    bags = {
        male = {
            [44] = true, [45] = true, -- Valid bag clothing IDs for male
            [81] = true, [82] = true
        },
        female = {
            [44] = true, [45] = true, -- Valid bag clothing IDs for female
            [81] = true, [82] = true
        }
    },
    no_gloves = {
        male = {
            [0] = true, [1] = true,
            -- IDs for male characters without gloves
        },
        female = {
            [0] = true, [1] = true,
            -- IDs for female characters without gloves
        }
    }
}

alerts.lua

This file contains presets for police alerts triggered during heists.

Alert Properties

Property	Type	Description
title	String	Title of the alert notification
msg	String	Message text (can include %s placeholders)
code	String	Police code (e.g., '10-XX')
flash	Integer	Flash duration for notification
blip	Table	Configuration for map blip

Blip Properties

Property	Type	Description
sprite	Integer	Icon ID for the map blip
scale	Float	Size of the blip
colour	Integer	Color ID of the blip
flashes	Boolean	Whether the blip flashes
text	String	Text displayed when selecting the blip
time	Integer	Duration in milliseconds before blip disappears
sound	Integer	Sound ID to play when alert appears

Example:

Example

return {
    default = {
        title = 'Bank Robbery in Progress',
        msg = 'A %s robbing at %s',
        code = '10-XX',
        flash = 0,
        blip = {
            sprite = 431,
            scale = 1.2,
            colour = 49,
            flashes = true,
            text = '911 - Robbery in Progress',
            time = (5*60*1000),
            sound = 1
        }
    },
    
    -- You can add more custom alert presets
    jewelry_store = {
        title = 'Jewelry Store Robbery',
        msg = 'Silent alarm triggered at %s',
        code = '10-90',
        -- Other properties
    }
}

Dispatch System Compatibility

The comments in the alerts.lua file indicate which dispatch scripts support each property:

• core = core_dispatch (supports title, code, blip sprite, blip scale)

• rcore = rcore_dispatch (supports title, code, blip properties except time and sound)

• qs = qs-dispatch (supports all properties)

• cd = cd_dispatch (supports all properties)

• ps = ps-dispatch (supports all properties except flash)

• origen = origen_police (supports message)

documents.lua

This file configures the document/briefing system that provides players with information about heists.

Menu Settings

Setting	Type	Description
enabled	Boolean	Whether the menu for document system is enabled
command	String/Boolean	Command to open briefings, or false to disable
key	String/Boolean	Keyboard key to open briefings, or false to disable
zone	Table/Boolean	Target zone configuration, or false to disable zone

Example

menu = {
    enabled = true,
    command = 'briefing',
    key = 'K', -- See https://docs.fivem.net/docs/game-references/input-mapper-parameter-ids/keyboard/
    
    zone = {
        label = 'Open Briefings',
        pos = vector4(255.84, 141.28, 137.57, 75.39),
        distance = 1.5,
        qb_target = { min_z = 136.5, max_z = 138.5, length = 1.0, width = 1.0 },
        ox_target = { size = vec3(1.0, 1.0, 2.0) },
        debug = false 
    }
}

Document Presets

The presets table contains document entries that players can access. Each preset has:

Property	Type	Description
show_in_menu	Boolean	Whether to show in the briefing menu
title	String	Title of the document (supports Markdown)
description	String	Main content of the document (supports Markdown)
task	String/Boolean	Task description, or false to hide (supports Markdown)
items	String/Boolean	Required items listed as text, or false to hide (supports Markdown)
image	String/Boolean	Markdown image tag with URL, or false for no image

Example Document Preset:

Example

[1] = {
    show_in_menu = true,
    
    title = '**Pacific Standard Bank**',
    description = [[
        The Pacific Standard Public Deposit Bank is a public deposit bank, 
        located in Downtown Vinewood, Los Santos.
        The bank has two entrances, one at the intersection of Vinewood Boulevard and Alta Street, 
        and a second to the east exiting onto Vinewood Boulevard. 
        Just inside both entrances are banks of usable Automated Teller Machines.
    ]],
    task = 'Break in, drill safe, steal everything you can and escape.',
    items = '1x thermite, 2x torch, 3x drill, 1x electronickit',
    image = '![Pacific](https://static.wikia.nocookie.net/gtawiki/images/a/a5/PacificStandardPublicDepositBank-GTAV.png)'
}

gas.lua

This file defines the positions where gas effects appear when triggered during heists.

Each preset is an array of vector3 coordinates where gas clouds will spawn.

Example

return {
    [1] = { -- pacific bank
        vector3(263.54, 212.2, 101.68),
        vector3(256.05, 215.38, 101.68),
        vector3(248.75, 218.16, 101.68),
        vector3(257.2, 225.95, 101.88)
    },
    
    [2] = { -- another location
        vector3(x1, y1, z1),
        vector3(x2, y2, z2)
    }
}

lasers.lua

This file configures laser security systems that can be enabled during heists.

Laser Preset Structure

Each laser system consists of:

Property	Type	Description
origins	Vector3	Origin point for the laser beams
targets	Array	Array of Vector3 coordinates where lasers point to
settings	Table	Configuration for the laser system

Laser Settings

Setting	Type	Description
render_zone	Table	Zone where lasers are rendered
color	Array	RGBA color values for laser beams
travelTimeBetweenTargets	Array	Min/max time to move between targets
waitTimeAtTargets	Array	Min/max time to pause at targets
randomTargetSelection	Boolean	Whether to select targets randomly
name	String	Unique identifier for the laser system

Example:

Example

return {
    [1] = { -- Pacific bank laser system
        origins = vector3(262.181, 222.248, 104.463),
        targets = {
            vector3(263.523, 225.893, 100.683), 
            vector3(262.427, 222.594, 100.683),
            -- Additional target points
        },
        settings = {
            render_zone = { 
                pos = vector3(261.84, 224.42, 99.0), 
                radius = 11.0, 
                debug = false
            },
            color = { 255, 255, 255, 255 }, -- White lasers (RGBA)
            travelTimeBetweenTargets = {1.0, 1.0}, 
            waitTimeAtTargets = {0.0, 0.0}, 
            randomTargetSelection = false,
            name = "pacific_1"
        }
    }
}

webhooks.lua

This file configures Discord webhooks for logging different types of heist events.

Available Webhook Types

Webhook	Description
system	General system events and errors
entities	Entity spawning and deletion
cooldowns	Heist cooldown started/ended events
timers	Heist timer events
reset	Heist reset events
rewards	Items given as rewards
removed_items	Items removed from players
interaction	Player interactions with heist objects
functions	Function and event calls

Example:

return {
    system = 'https://discord.com/api/webhooks/your-webhook-url-here',
    entities = 'https://discord.com/api/webhooks/your-webhook-url-here',
    cooldowns = 'https://discord.com/api/webhooks/your-webhook-url-here',
    timers = 'https://discord.com/api/webhooks/your-webhook-url-here',
    reset = 'https://discord.com/api/webhooks/your-webhook-url-here',
    rewards = 'https://discord.com/api/webhooks/your-webhook-url-here',
    removed_items = 'https://discord.com/api/webhooks/your-webhook-url-here',
    interaction = 'https://discord.com/api/webhooks/your-webhook-url-here',
    functions = 'https://discord.com/api/webhooks/your-webhook-url-here',
}

Creating Discord Webhooks

To create a Discord webhook:

1. Open your Discord server settings

2. Navigate to "Integrations" > "Webhooks"

3. Click "New Webhook"

4. Name it appropriately (e.g., "Heist System Logs")

5. Select the channel where logs should appear

6. Copy the webhook URL

7. Paste into the corresponding field in webhooks.lua