Configuration and Scenarios

Detailed guide for editing shared settings, scenario files, and common heist changes

This page is based on the real script structure inside the resource.

The most important thing to understand is this:

config/main.lua controls the global system
config/heist.lua controls the heist menu entries and the main rules for each scenario
config/scenarios/<scenario>.lua controls the internal gameplay details of that one scenario

If you edit the wrong file, nothing will change in game.

Quick Answer Map

Use this first if you want the shortest possible answer:

If you want to change...

Edit here

Menu command, keybind, tablet item, police jobs, money options, credit system, clothing, locale

config/main.lua

Employer ped, employer spawn point, scenario card info, disable scenario, level, cops, max team, credits, scenario cooldown, player cooldown

config/heist.lua

Market item prices and payment methods

config/market.lua

Drone required item, prop model, max distance

config/drone.lua

Shared presets like cooldowns, durations, blips, models, animations, shared required items

config/scenarios/_shared.lua

Doors, guards, loot tables, drop zones, peds, robbery coordinates, special gameplay logic for one heist

config/scenarios/<scenario>.lua

Real File Structure

These are the files you will actually work with:

config/main.lua
config/heist.lua
config/market.lua
config/drone.lua
config/scenarios/_shared.lua
config/scenarios/atm_robbery.lua
config/scenarios/ammunation_robbery.lua
config/scenarios/bobcat_robbery.lua
config/scenarios/cargo_ship_robbery.lua
config/scenarios/fleeca_bank_robbery.lua
config/scenarios/house_robbery.lua
config/scenarios/money_truck_robbery.lua
config/scenarios/pacific_bank_robbery.lua
config/scenarios/paleto_bank_robbery.lua
config/scenarios/store_robbery.lua
config/scenarios/train_robbery.lua
config/scenarios/truck_robbery.lua
config/scenarios/vehicle_theft_robbery.lua
config/scenarios/vangelico_robbery.lua
config/scenarios/yacht_robbery.lua

Read This Before You Edit Anything

Use this simple rule:

If the change should affect the whole script, start with config/main.lua
If the change should affect the heist card in the menu, start conditions, cooldown, team size, credits, or level, go to config/heist.lua
If the change should affect the robbery's inside logic, loot, doors, guards, peds, or coordinates, go to config/scenarios/<scenario>.lua
If the change is inventory, target, notify, progressbar, dispatch, or framework adaptation, use the Script Integrations page

The safest workflow is always:

Decide exactly what you want to change.
Open the correct config file.
Change only one value.
Restart 0r-heistpack.
Test that exact change in game.

What Each Main Config File Does

`config/main.lua`

This is the global script config.

Important sections in the real source:

Config.locale
Config.inventoryImagesFolder
Config.heistMenu
Config.policeOptions
Config.levels
Config.infoBoxOptions
Config.moneyOptions
Config.dirtMoneyOptions
Config.creditSystem
Config.jobClothingOptions
Config.modernTextUI
Config.noMarkerAndOutline
Config.potentialHeistNotify
Config.debug

`config/heist.lua`

This is the most important file for normal server owners.

It controls:

Employer ped locations
Employer vehicle spawn points
The scenario list shown in the menu
Whether a scenario is active
Required level
Required cops
Maximum members
Required items to start
Scenario cooldown
Player cooldown
Credit cost
Completion rewards
Heist image
The infoTexts shown to players

`config/market.lua`

This controls the built-in market.

It defines:

Whether the market is enabled
Drone delivery behavior for purchased items
Allowed payment methods
Market item list and prices

`config/drone.lua`

This file controls the heist drone itself.

It defines:

Required drone item
Maximum usage distance
Drone prop model
Tablet model
Holding animation

`config/scenarios/_shared.lua`

This file is the shared preset file for all scenarios.

It contains reusable values for:

Blips
Max duration presets
Cooldown presets
Finish distances
Damage values
Animations
Common models
Carry positions
Shared required items like sticky bomb, grinder, and drill

`config/scenarios/<scenario>.lua`

Each of these files controls one robbery's internal gameplay.

Typical things changed here:

Locations
Loot tables
Guard positions
Doors
Interaction zones
Special required tools used inside that robbery
Reward pools for lootable objects
Prop models
Route points and drop points

If you want to disable a robbery or add a cooldown, do not start with config/scenarios/<scenario>.lua. Start with config/heist.lua.

Common Changes

How Do I Disable One Scenario?

Open config/heist.lua.

Find the scenario key inside heistScenarios.

Example:

["vangelico_robbery"] = {
    isActive = true,
}

Change it to:

["vangelico_robbery"] = {
    isActive = false,
}

This removes that heist from normal usage.

Use this when:

You do not want that heist on your server
You want to temporarily close one robbery
You are testing only one or two scenarios

How Do I Add Or Change A Scenario Cooldown?

Open config/heist.lua.

Each heist entry can use:

scenarioCooldown
playerCooldown

Both values are in minutes.

Example:

["vangelico_robbery"] = {
    scenarioCooldown = 30,
    playerCooldown = 10,
}

What they mean:

scenarioCooldown: blocks that heist globally for everyone after it ends
playerCooldown: blocks the players who joined from starting another heist for that period

The script also uses preset values from config/scenarios/_shared.lua:

SHARED_CONFIG.gameplay.cooldowns.short  -- 10
SHARED_CONFIG.gameplay.cooldowns.medium -- 30
SHARED_CONFIG.gameplay.cooldowns.long   -- 60

That means you can keep the shared preset style:

scenarioCooldown = SHARED_CONFIG.gameplay.cooldowns.medium

How Do I Change Required Items?

There are two different item layers.

1. Start items for entering the heist

Open config/heist.lua.

Example:

["vangelico_robbery"] = {
    requiredItems = {
        { itemName = "heistpack_drone", count = 1, label = "Heistpack Drone" },
    },
},

If you want Vangelico to also require a gas mask before starting:

requiredItems = {
    { itemName = "heistpack_drone", count = 1, label = "Heistpack Drone" },
    { itemName = "gasmask", count = 1, label = "Gas Mask" },
},

2. Items used during the robbery itself

These are usually inside config/scenarios/<scenario>.lua.

Real examples from the script:

ATM rope item: config/scenarios/atm_robbery.lua
ATM drill item: config/scenarios/atm_robbery.lua
House hacking device: config/scenarios/house_robbery.lua
Cargo ship anchor item: config/scenarios/cargo_ship_robbery.lua
Vangelico gas mask, drill, and painting rewards: config/scenarios/vangelico_robbery.lua

Important:

The item must also exist in your inventory system
The item name in config must match the real inventory item name exactly
If you use the tablet menu, heistpack_tablet must exist when item menu opening is enabled
The hacking device is used as weapon_hackingdevice in the real script

How Do I Change Police Requirements?

You can change police requirements in two places.

Global police settings

Open config/main.lua.

Config.policeOptions = {
    requiredCops = 0,
    requiredOnDuty = true,
    jobNames = { "police", "sheriff" },
}

This controls:

Which jobs count as police
Whether only on-duty police are counted
The global fallback police requirement

Per-scenario police requirement

Open config/heist.lua.

["pacific_bank_robbery"] = {
    requiredCops = 4,
}

If players should be able to start the heist with fewer officers online, lower that number.

If you want the heist to feel more restricted, raise that number.

How Do I Change Rewards?

Again, there are two reward layers.

1. Completion reward

Open config/heist.lua.

Real pattern:

["train_robbery"] = {
    rewards = {
        money = 5000,
        exp = 250,
        credits = 50,
    },
}

In the real script this is written as:

rewards = { exp = 250, money = 5000, credits = 50 }

These are the rewards players get when the scenario is completed.

2. Loot reward inside the robbery

Open the matching file in config/scenarios/<scenario>.lua.

Real examples:

config/scenarios/store_robbery.lua lootRewardItems, cashierRobbery.rewards, miniSafe.rewards
config/scenarios/vangelico_robbery.lua robbablePedOptions.rewards, lootableDisplayOptions.rewards, smashableCaseOptions.rewards
config/scenarios/atm_robbery.lua ropeOptions.rewards, hackingOptions.rewards, explodeOptions.rewards, drillOptions.rewards
config/scenarios/cargo_ship_robbery.lua lootRewardItems

Change only the part you actually want:

Money payout
XP reward
Credits reward
Loot item chance
Loot item quantity

If you change completion rewards in config/heist.lua, the robbery's internal loot does not change. If you change loot rewards in config/scenarios/<scenario>.lua, the final completion reward does not change.

How Do I Change Difficulty?

Difficulty in this pack is spread across multiple files.

Start with config/heist.lua for:

requiredCops
requiredItems
maxMemberCount
creditCost
scenarioCooldown
playerCooldown

Then use config/scenarios/<scenario>.lua for the real inside difficulty:

Guard count
Guard positions
Door behavior
Drop zones
Loot amount
Reward chance
Required drill, bomb, rope, hacking device, gas mask, grinder, anchor, and similar flow items
Finish distance

Real examples:

Vangelico difficulty is affected by gas flow, doors, peds, smashable cases, painting locations, and safe settings
Cargo ship difficulty is affected by guards, ship loot, boat spawn, helicopter usage, and big container delivery
Store robbery difficulty is affected by cashier logic, mini safe rewards, loot points, and carryable props
ATM difficulty is affected by rope, sticky bomb, drill, and hacking reward paths

How Do I Change A Location, Ped, Or Interaction Point?

Open the matching file in config/scenarios/<scenario>.lua.

The actual section names depend on the heist.

Real examples from the script:

Vangelico: poisonousGasOptions.dropZones, entranceDoorOptions.doors, robbablePedOptions.peds, lootableDisplayOptions.locations, paintingSmuggleOptions.locations
Store robbery: locations.standart, locations.custom, cashier, lootableCashRegisters, loots, miniSafe
Cargo ship: boatSpawn, captainCabinKey, helicopterSpawn, bigContainers, guards, loots
ATM: atmModels, modelPlantingOffsets

You are usually editing one of these:

Start point
Ped location
Door position
Loot interaction point
Delivery point
Search point
Helicopter or boat spawn
Guard spawn

Example shape:

vector3(123.45, -456.78, 78.90)

If you move a location:

Keep the coordinate format already used by the file
Move the linked zone, prop, scene coords, and marker if the file uses more than one position for the same action
Test the robbery from start to finish after changing coordinates

How Do I Change The Employer NPC Or Vehicle Spawn?

Open config/heist.lua.

This file contains:

blips.employer
blips.vehicle
employers

Real example:

employers = {
    {
        coords = vector4(736.0713, -1332.7180, 25.3363, 237.2058),
        pedModel = "s_m_m_movprem_01",
        vehicleSpawnPoints = {
            vector4(742.42, -1354.21, 25.68, 0.0),
        },
    },
},

Change this if you want to move the employer or change where employer-related vehicles spawn.

Open config/main.lua.

The menu supports 3 methods:

openWithCommand
openWithKey
openWithItem

Real default values in the script:

Command: heistmenu
Keybind: F10
Item: heistpack_tablet

You can also control:

allowedJobs
forbiddenJobs
requiredMinDistance
switchToIllegalPack

How Do I Change The Market?

Open config/market.lua.

This file controls:

Whether the market is enabled
Drone delivery settings
Cash / card / black money usage
Which items are sold
Item prices
Which scenario labels are shown in the UI

Real items already sold by default include:

heistpack_drone
gasmask
heistpack_drill
lockpick
weapon_hackingdevice
heavy_rope
weapon_stickybomb
heistpack_anchor
heistpack_grinder

How Do I Change Credits, Levels, Or Team Rules?

Open config/main.lua and config/heist.lua.

Use config/main.lua for:

Config.levels
Config.creditSystem

Use config/heist.lua for:

level
maxMemberCount
teamSize
creditCost

Important:

When Config.creditSystem.enabled = true, the normal level check is bypassed by the start logic
Credit cost is checked for all lobby members, not just the leader

How Do I Change `infoTexts`?

Open config/heist.lua.

Each heist entry has an infoTexts table. These texts are the instructions shown to players in the heist UI.

Example:

infoTexts = {
    "Go to the marked location.",
    "Open the safe door.",
    "Collect the loot.",
}

Use this if players are confused about the flow and you want clearer in-game guidance.

How Do I Temporarily Turn A Scenario Into Testing Mode?

For safe testing, do this:

In config/heist.lua, set the scenarios you do not need to isActive = false.
Lower requiredCops to 0.
Lower or remove creditCost.
Set scenarioCooldown = 0 and playerCooldown = 0 for the one you are testing.
Make sure the required items exist in your inventory.
Restart 0r-heistpack.
Test the robbery from the beginning to the end.

This is the fastest way to confirm whether your issue is configuration-related or integration-related.

What Should Stay In `config/scenarios/_shared.lua`?

Keep only reused presets there.

Examples:

Shared cooldown values
Shared max durations
Shared animations
Shared models
Shared required items
Shared carry positions

Do not put heist-specific coordinates here unless you are intentionally editing the script architecture.

What To Do After Every Config Change

Always do these checks after editing:

Save the file
Restart 0r-heistpack
Watch console for the first error, not the last error
Start the exact scenario you edited
Confirm the changed behavior actually happened in game

If nothing changed, the usual reason is one of these:

You edited config/scenarios/<scenario>.lua when the real setting was in config/heist.lua
You edited config/heist.lua when the real setting was inside the scenario file
The scenario is disabled with isActive = false
The resource was not restarted
Your custom integration is failing before the scenario flow reaches your new config
You changed the structure of the table instead of just the value

Safest Editing Rule

Do not rename keys unless you are sure the script expects the new name.

If the file currently uses this:

scenarioCooldown = SHARED_CONFIG.gameplay.cooldowns.medium

and you only want a shorter cooldown, change only the value:

scenarioCooldown = 10

Do not rename keys like:

isActive
requiredCops
requiredItems
scenarioCooldown
playerCooldown
creditCost
rewards
infoTexts

unless you are also changing the script code itself.

Do I Need A Separate Page For Every Heist?

No. The goal of this page is to stop you from searching blindly.

Once you understand:

what belongs in config/main.lua
what belongs in config/heist.lua
what belongs in config/scenarios/<scenario>.lua
the difference between completion rewards and loot rewards
the difference between start requirements and in-scenario tool requirements

you can handle most balancing and scenario customization without extra documentation.

PreviousFAQ and Troubleshooting Next0R - Towtruck V2

Last updated 3 days ago

hashtagQuick Answer Map

hashtagReal File Structure

hashtagRead This Before You Edit Anything

hashtagWhat Each Main Config File Does

hashtagconfig/main.lua

hashtagconfig/heist.lua

hashtagconfig/market.lua

hashtagconfig/drone.lua

hashtagconfig/scenarios/_shared.lua

hashtagconfig/scenarios/<scenario>.lua

hashtagCommon Changes

hashtagHow Do I Disable One Scenario?

hashtagHow Do I Add Or Change A Scenario Cooldown?

hashtagHow Do I Change Required Items?

hashtag1. Start items for entering the heist

hashtag2. Items used during the robbery itself

hashtagHow Do I Change Police Requirements?

hashtagGlobal police settings

hashtagPer-scenario police requirement

hashtagHow Do I Change Rewards?

hashtag1. Completion reward

hashtag2. Loot reward inside the robbery

hashtagHow Do I Change Difficulty?

hashtagHow Do I Change A Location, Ped, Or Interaction Point?

hashtagHow Do I Change The Employer NPC Or Vehicle Spawn?

hashtagHow Do I Change The Heist Menu Access?

hashtagHow Do I Change The Market?

hashtagHow Do I Change Credits, Levels, Or Team Rules?

hashtagHow Do I Change infoTexts?

hashtagHow Do I Temporarily Turn A Scenario Into Testing Mode?

hashtagWhat Should Stay In config/scenarios/_shared.lua?

hashtagWhat To Do After Every Config Change

hashtagSafest Editing Rule

hashtagDo I Need A Separate Page For Every Heist?

Quick Answer Map

Real File Structure

Read This Before You Edit Anything

What Each Main Config File Does

`config/main.lua`

`config/heist.lua`

`config/market.lua`

`config/drone.lua`

`config/scenarios/_shared.lua`

`config/scenarios/<scenario>.lua`

Common Changes

How Do I Disable One Scenario?

How Do I Add Or Change A Scenario Cooldown?

How Do I Change Required Items?

1. Start items for entering the heist

2. Items used during the robbery itself

How Do I Change Police Requirements?

Global police settings

Per-scenario police requirement

How Do I Change Rewards?

1. Completion reward

2. Loot reward inside the robbery

How Do I Change Difficulty?

How Do I Change A Location, Ped, Or Interaction Point?

How Do I Change The Employer NPC Or Vehicle Spawn?

How Do I Change The Heist Menu Access?

How Do I Change The Market?

How Do I Change Credits, Levels, Or Team Rules?

How Do I Change `infoTexts`?

How Do I Temporarily Turn A Scenario Into Testing Mode?

What Should Stay In `config/scenarios/_shared.lua`?

What To Do After Every Config Change

Safest Editing Rule

Do I Need A Separate Page For Every Heist?