Parameters

This documentation explains all the parameters available for configuring heists in the system. Each parameter is explained with its purpose, data type, and examples.

Basic Configuration

The top-level configuration of a heist defines its fundamental properties.

Parameter	Type	Description
name	String	The display name of the heist shown to players

table.insert(Heists, {
    name = 'Pacific Bank',
    -- other parameters...
})

Timer Settings

Timer settings control the cooldown and duration of the heist.

Parameter	Type	Description
timer.time_to_finish	Integer	Maximum time in minutes players have to complete the heist
timer.cooldown_timer	Integer	Time in minutes before the heist can be started again
timer.group	String	Optional group name for shared cooldowns between heists

timer = {
    time_to_finish = 30, -- minutes
    cooldown_timer = 120, -- minutes
    group = 'fleeca' -- Optional: all heists in this group share cooldown
}

Police Requirements

Defines how many police officers must be online for the heist to start.

Parameter	Type	Description
police.required	Integer	Number of police officers required to be online

police = {
    required = 4, -- 4 officers required
},

Blips

Parameter	Type	Description
blips[n].label	String
blips[n].coords	Vector3
blips[n].sprite	Integer
blips[n].colour	Integer
blips[n].alpha	Integer
blips[n].scale	Float

[1] = { 
    label = 'Humane Labs', 
    coords = vector3(3538.84, 3764.62, 29.92),
    sprite = 499, 
    colour = 1, 
    alpha = 250, 
    scale = 1.0 
}

Door System

The built-in door system for controlling vault doors and other special door objects.

Parameter	Type	Description
door_system[n].coords	Vector3	3D coordinates of the door
door_system[n].render_id	Integer	ID of the render point this door belongs to
door_system[n].heading.open	Float	Door heading when open (in degrees)
door_system[n].heading.closed	Float	Door heading when closed (in degrees)
door_system[n].speed	Float	Optional: Speed of the door animation (default: 0.5)
door_system[n].door	Hash	Model hash of the door object
door_system[n].open	Boolean	Whether the door starts open

door_system = {
    [1] = {
        coords = vector3(254.15, 225.12, 101.88), 
        render_id = 1,
        heading = { open = 10.0, closed = 159.96 }, 
        speed = 0.5,
        door = `v_ilev_bk_vaultdoor`,
        open = false
    },
},

On Reset Options

Actions to perform when a heist resets after completion or failure.

Parameter	Type	Description
on_reset.doorlocks	Array	Array of door IDs to lock when the heist resets
on_reset.functions	Array	Array of functions to call when the heist resets

on_reset = {
    -- Lock these doors when heist resets
    doorlocks = { 1, 2, 3 },
    
    -- Execute these functions on reset
    functions = {
        { type = 'function', name = 'laser', params = { preset_id = 1, toggle = 0 } },
        { type = 'function', name = 'alarm_stop' },
    }
},

Render Points

Render points define areas where heist components are active and visible.

Parameter	Type	Description
render_points[n].zone.pos	Vector3	Center position of the render zone
render_points[n].zone.type	String	Shape type: 'sphere' or 'box'
render_points[n].zone.radius	Float	Radius of sphere zone (if type is 'sphere')
render_points[n].zone.size	Vector3	Size of box zone (if type is 'box')
render_points[n].zone.rotation	Float	Rotation of box zone in degrees (if type is 'box')

render_points = {
    [1] = { 
        zone = { 
            pos = vector3(263.42, 225.36, 101.68), 
            type = 'sphere', 
            radius = 40.0 
        },
        -- Stages, NPCs, etc. go here
    }
},

Stages and Interactions

Stages define the sequential progression of a heist, with each stage containing interaction points.

Stage Configuration

Parameter	Type	Description
render_points[n].stages[m]	Table	Stage with index m containing interactions

Interaction Configuration

Parameter	Type	Description
render_points[n].stages[m][o].zone	Table	Interaction zone configuration
render_points[n].stages[m][o].require	Table	Requirements to interact with this point
render_points[n].stages[m][o].scene	Table	Animation scene to play
render_points[n].stages[m][o].minigame	Table	Optional minigame configuration
render_points[n].stages[m][o].object	Table	Optional object to spawn at this location
render_points[n].stages[m][o].on_start	Table	Functions to call when interaction starts
render_points[n].stages[m][o].on_complete	Table	Functions to call when interaction completes

Interaction Zone

Parameter	Type	Description
zone.a_type	String	Type of zone ('box_zone' is standard)
zone.infinite_use	Boolean	Makes interaction infinite to use
zone.label	String	Text displayed to the player for interaction
zone.pos	Vector4	Position (x,y,z) and heading of the interaction
zone.distance	Float	Maximum distance for interaction
zone.qb_target	Table	qb-target compatibility settings
zone.ox_target	Table	ox_target compatibility settings

[1] = { -- First interaction in stage 1
    zone = {
        a_type = 'box_zone',
        label = 'Place Thermite',
        infinite_use = false,
        pos = vector4(257.04, 219.85, 106.29, 342.86),
        distance = 1.3,
        qb_target = { min_z = 105.0, max_z = 107.3, length = 1.2, width = 0.9 },
        ox_target = { size = vec3(1.0, 1.2, 2.2) }
    },
    -- Other settings...
}

Requirements

Parameter	Type	Description
require.custom()	Function	Custom function, return true/false
require.job	String
require.time.min_hour	Integer
require.time.max_hour	Integer
require.armed.weapon	Hash
require.armed.type	String
require.item	Table	Single item required for interaction
require.items	Array	Multiple items required for interaction
require.bag	Boolean	Whether a bag is required (true) or prohibited (false)

require = {
    -- single item check
    item = { 
        name = 'thermite', remove = true 
    },
    
    -- multiple items check
    items = { 
        { name = 'thermite', remove = true, amount = 1 } 
    },
    
    --
    bag = false
}

Progressbar

progressbar.time	Integer
progressbar.label	String
progressbar.canCancel	Boolean
progressbar.dict	String
progressbar.anim	String
progressbar.flags	Integer

progressbar = {
    time = 5, -- seconds
    label = 'Test',
    canCancel = true,
    dict = 'aninm@heists@ornate_bank@hack',
    anim = 'hack_loop',
    flags = 1
}

Animation Scene

Parameter	Type	Description
scene.name	String	Name of the predefined animation scene
scene.offset	Vector3	Optional position offset for the animation
scene.pos	Vector3	Optional absolute position for the animation
scene.rot	Vector3	Optional rotation for the animation

scene = { 
    name = 'thermite2', 
    offset = vec3(0.32, 0.40, 0.0) 
}

Minigame

Parameter	Type	Description
minigame.name	String	Name of the minigame to play
minigame.difficulty	Integer	Works for 'lockpick' and 'small_drill'
minigame.speed	Float	Works with 'datacrack'
minigame.time	Integer	Works with 'blocks' (seconds), 'fingerprint' (seconds), 'fingerprint2' (minutes)
minigame.lives	Integer	Works with 'fingerprint'

minigame = { 
    name = 'datacrack'
}

Object

Parameter	Type	Description
object.model	Hash	Model hash of the object to spawn
object.delete	Boolean	Whether to delete the object after interaction

object = { 
    model = `hei_prop_hei_cash_trolly_01`, 
    delete = false 
}

Callback Functions

Parameter	Type	Description
on_start.functions	Array	Functions to call when interaction starts
on_complete.functions	Array	Functions to call when interaction completes
on_complete.rewards	Table	Rewards to give when interaction completes

on_complete = {
    functions = {
        { type = 'function', name = 'start_timer' },
        { type = 'function', name = 'unlock_stage', params = { stage_id = 2 } },
        { type = 'function', name = 'police_alert', params = { preset = 'default' } }
    },
    rewards = {
        items = {
            { name = 'gold_ring', chance = 100, amount = { 5, 15 } },
            { name = 'goldchain', chance = 90, amount = { 5, 15 } }
        }
    }
}

NPC Configuration

NPCs can be configured globally or individually for each heist.

Global NPC Settings

Parameter	Type	Description
npc.guards_friendly_with_police	Boolean	Whether guards and police are allied
npc.global_settings	Table	Default settings for all NPCs
npc.peds[n]	Table	Individual NPC settings

Global Settings Example

global_settings = {
    stage = 1, -- spawn

    relationship = 3, -- 0 = Companion, 1 = Respect, 2 = Like, 3 = Neutral, 4 = Dislike, 5 = Hate

    skin = `s_m_m_security_01`, -- hash

    -- graphic settings
    blip = false,
    bloody_clothes = false,
    random_clothes = true,
    walk_style = false,
    animation = { scenario = 'WORLD_HUMAN_GUARD_STAND' },

    -- patrol
    walk_around = false,
    patrol_routes = false,

    -- combat settings
    weapon = `WEAPON_PISTOL`,
    firing_pattern = false,
    combat_range = 1,               -- 0 near, 1 medium, 2 far, 3 very far
    combat_movement = { 1, 3 },     -- 1 defensive, 2 agressive, 3 suicidal (flank)
    combat_ability = { 0, 2 },      -- 0 poor, 1 average, 2 profesional
    weapon_accuracy = { 35, 50 },   -- from 0 to 100

    always_fight = true,
    find_target = false,             -- ped tries to find target instantly after spawn

    -- vision and hearing
    hearing_range = 30.0, -- units
    seeing_range = 150.0, -- units
    alertness = 3, -- from 1 to 3 
    highly_perceptive = false,

    -- disable
    fire_resistance = false,
    disable_headshot = false,
    disable_speaking = false,
    disable_weapon_switch = false,
    disable_events = false,
    disable_ragdoll = true,
}

Individual NPC Settings

Parameter	Type	Description
npc.peds[n].pos	Vector4	Position and heading of the NPC
npc.peds[n].skin	Hash	Model hash of the NPC
npc.peds[n].stage	Integer	Stage when this NPC spawns
npc.peds[n].relationship	nteger	Relationship with player (0-5)
npc.peds[n].blip	Boolean
npc.peds[n].bloody_clothes	Boolean
npc.peds[n].random_clothes	Boolean
npc.peds[n].walk_style	Boolean
npc.peds[n].animation	Table	Animation or scenario for the NPC
npc.peds[n].walk_around	Boolean
npc.peds[n].patrol	Table	Patrol route configuration
npc.peds[n].weapon	Hash
npc.peds[n].firing_pattern	Boolean
npc.peds[n].combat_range	Integer
npc.peds[n].combat_movement	Table (min, max)
npc.peds[n].combat_ability	Table (min, max)
npc.peds[n].weapon_accuracy	Table (min, max)
npc.peds[n].always_fight	Boolean
npc.peds[n].find_target	Boolean
npc.peds[n].hearing_range	Float
npc.peds[n].seeing_range	Float
npc.peds[n].alertness	Integer
npc.peds[n].highly_perceptive	Boolean
npc.peds[n].fire_resistance	Boolean
npc.peds[n].disable_headshot	Boolean
npc.peds[n].disable_speaking	Boolean
npc.peds[n].disable_weapon_switch	Boolean
npc.peds[n].disable_events	Boolean
npc.peds[n].disable_ragdoll	Boolean
npc.peds[n].on_death	Table	This parameter is incompleted

Example

npc = {
    guards_friendly_with_police = true,
    
    global_settings = {
        stage = 1,
        relationship = 3,
        skin = `s_m_m_security_01`,
        weapon = `WEAPON_PISTOL`,
        always_fight = true,
        hearing_range = 30.0,
        seeing_range = 150.0,
        alertness = 3,
    },
    
    peds = {
        [1] = { 
            pos = vector4(241.3, 216.69, 106.29, 300.76),
            animation = { scenario = 'WORLD_HUMAN_GUARD_STAND' }
        },
        [2] = { 
            pos = vector4(252.58, 217.55, 101.68, 350.88), 
            stage = 3, 
            relationship = 5, 
            find_target = true 
        }
    }
}

Relationship Settings

Value	Description
0	Companion - Will help the player, never attack
1	Respect - Treats the player with high respect
2	Like - Generally positive toward the player
3	Neutral - Ignores the player, neither helping nor attacking, unless you aim on npc
4	Dislike - Will be hostile if provoked
5	Hate - Will attack on sight

Patrol Routes

Parameter	Type	Description
patrol.name	String	Unique name for this patrol route
patrol.anim	String	Animation to use between points
patrol.wait	Integer	Wait time in milliseconds at each point
patrol.positions	Array	Array of Vector3 positions to patrol

Example

patrol = {
    name = 'morgue1',
    anim = 'StandGuard',
    wait = 3000,
    positions = {
        vector3(273.71, -1341.55, 24.54),
        vector3(283.94, -1343.19, 24.54),
        vector3(264.38, -1351.57, 24.54)
    }
}

Vehicle Configuration

Vehicles can be spawned as part of a heist.

Parameter	Type	Description
vehicles[n].pos	Vector4	Position and heading of the vehicle
vehicles[n].model	Hash	Model hash of the vehicle
vehicles[n].locked	Boolean	Whether the vehicle is locked
vehicles[n].freeze	Boolean	Whether the vehicle is frozen in place
vehicles[n].stage	Integer	Stage when this vehicle spawns

Example

vehicles = {
    [1] = { 
        pos = vec4(412.01, -2066.75, 21.3, 142.27), 
        model = `mule`, 
        locked = true, 
        freeze = true, 
        stage = 1 
    }
}

Reward System

Rewards can be given for completing interactions.

Parameter	Type	Description
rewards.limit	Integer	Optional maximum number of rewards to give
rewards.items	Array	Array of possible item rewards

Item Rewards

Parameter	Type	Description
items[n].name	String	Name of the item to give
items[n].chance	Integer	Percentage chance of receiving this item (0-100)
items[n].amount	Array/Integer	Amount to give, either fixed or range {min, max}

Example

rewards = {
    limit = 2, -- Only give 2 rewards max, from the list
    items = {
        { name = 'gold_ring', chance = 100, amount = { 5, 15 } },
        { name = 'diamond_ring', chance = 50, amount = { 1, 2 } },
        { name = 'goldchain', chance = 80, amount = { 1, 2 } },
        { name = 'diamond_necklace', chance = 30, amount = { 1, 2 } }
    }
}

Function Calls

Functions are used in on_start, on_complete and on_reset to trigger specific actions.

Common Functions

Function Name	Parameters	Description
start_timer	None	Start the heist timer
unlock_stage	stage_id	Unlock the specified stage
unlock_render_zone	render_id	Unlock the specified render zone
doorlock	door_id, locked	Lock or unlock a door
door_system	index, open	Open or close a door in the door system
police_alert	preset	Alert police with a preset notification
alarm_start	pos, duration	Start an alarm at the position for duration in seconds
alarm_stop	None	Stop all alarms
laser	preset_id, toggle	Toggle laser system on/off
gas	preset_id, toggle	Toggle gas system on/off
set_ai_relationship	relationship	Set NPC relationship with player
update_model	coords, radius, model, newModel	Replace one model with another
restore_model	coords, radius, model, newModel	Restore replaced model
restore_all_models	None	Restore all replaced models
notify	text, type, time	Show notification to player
lock_interaction	stage_id, index	Disable an interaction point
native_waypoint	pos (vector2)	Default waypoint
blip_waypoint	pos (vector3), label	Blip waypoint
teleport	pos (vector3)	Teleport to position

start_timer

functions = {
    [1] = { type = 'function', name = 'start_timer' }
}

multiple functions

Event Calls

Events can be used to trigger custom client or server scripts.

Parameter	Type	Description
type	String	'event'
event_type	String	'client' or 'server'
name	String	Name of the event to trigger
params	Table	Parameters to pass to the event

Example

functions = {
    [1] = { 
        type = 'event', 
        event_type = 'client',
        name = 'sh-heists:cl:EnterSubmarine', 
        params = nil
    }
}

Vector Types

Type	Description
vector3(x, y, z) or vec3(x, y, z)	3D position
vector4(x, y, z, heading) or vec4(x, y, z, heading)	3D position with heading/rotation

Tips

1. Plan your heist flow before writing configurations

2. Test thoroughly at each stage of development

3. Use the examples as templates

4. Remember that stages must be unlocked sequentially

5. Double-check coordinates and headings

6. Always include at least one reward for players

7. Use meaningful relationship values for NPCs