# 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/.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/.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/.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/.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 {% hint style="info" %} If you want to disable a robbery or add a cooldown, do not start with `config/scenarios/.lua`. Start with `config/heist.lua`. {% endhint %} ## Common Changes ## How Do I Disable One Scenario? Open `config/heist.lua`. Find the scenario key inside `heistScenarios`. Example: ```lua ["vangelico_robbery"] = { isActive = true, } ``` Change it to: ```lua ["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: ```lua ["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`: ```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: ```lua 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: ```lua ["vangelico_robbery"] = { requiredItems = { { itemName = "heistpack_drone", count = 1, label = "Heistpack Drone" }, }, }, ``` If you want Vangelico to also require a gas mask before starting: ```lua 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/.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`. ```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`. ```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: ```lua ["train_robbery"] = { rewards = { money = 5000, exp = 250, credits = 50, }, } ``` In the real script this is written as: ```lua 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/.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/.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/.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/.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: ```lua 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: ```lua 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: ```lua 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/.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: ```lua scenarioCooldown = SHARED_CONFIG.gameplay.cooldowns.medium ``` and you only want a shorter cooldown, change only the value: ```lua 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/.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.