Configuration and Scenarios

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:

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:

1. Decide exactly what you want to change.
2. Open the correct config file.
3. Change only one value.
4. Restart 0r-heistpack.
5. 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

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.

How Do I Change The Heist Menu Access?#

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:

1. In config/heist.lua, set the scenarios you do not need to isActive = false.
2. Lower requiredCops to 0.
3. Lower or remove creditCost.
4. Set scenarioCooldown = 0 and playerCooldown = 0 for the one you are testing.
5. Make sure the required items exist in your inventory.
6. Restart 0r-heistpack.
7. 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.