Documentation

This guide explains common terms and notations used throughout the heist documentation to help you understand how to use the configuration system effectively.

Understanding the Basics

Basic Data Types

• String: A sequence of characters (text) enclosed in quotes. Examples: 'Pacific Bank', "Place Thermite".

• Integer: A whole number without a decimal point. Examples: 1, 300, -5.

• Float: A number that contains a decimal point, used for precise measurements. Examples: 0.5, 15.75, -3.14.

• Boolean: A value that can only be true or false. Used for yes/no settings like locked = true.

• Vector: A position in the game world.

  • vector3 contains X, Y, Z coordinates: vector3(255.36, 223.98, 101.68)

  • vector4 adds a heading/rotation as the fourth number: vector4(255.36, 223.98, 101.68, 160.0)

• Hash: A game object identifier written with backticks. Example: `WEAPON_PISTOL`, `v_ilev_bk_vaultdoor`

Lua Tables

Many configuration parameters are organized in tables. A table is a collection of data that can hold different items. In Lua (the programming language used), tables are created using curly braces { }.

For example:

animation = { scenario = 'WORLD_HUMAN_GUARD_STAND' }

This is a table named animation containing one key-value pair where scenario is the key and 'WORLD_HUMAN_GUARD_STAND' is the value.

Common Notations in Documentation

• [n]: This indicates an array index or position number. For example, door_system[1] means the first door in the door system array. Arrays in Lua start counting from 1, not 0.

• Parameter Names with Dots: When you see something like timer.time_to_finish, the dot indicates a nested property. This means time_to_finish is a property of the timer table.

• { min, max }: When you see a range like { 5, 15 }, this typically means a random value between the minimum and maximum will be selected. Example: amount = { 5, 15 } means a random amount between 5 and 15.

Optional Parameters

• Parameters marked with "optional" or shown with a question mark don't need to be included in your configuration. The system will use default values instead. (WIP)

Understanding Configuration Structure

Heist configurations follow a hierarchical structure:

Heist
├── Basic Configuration (name, timer, police etc...)
├── Door System
├── On Reset Settings
├── Render Points
│   ├── Stages
│   │   ├── Stage 1
│   │   │   ├── Interaction 1 (zones, requirements, etc.)
│   │   │   ├── Interaction 2
│   │   │   └── ...
│   │   ├── Stage 2
│   │   └── ...
│   ├── NPCs
│   └── Vehicles
└── ...

Each level nests deeper into the configuration. For example, to define an interaction in stage 2, you would place it in render_points[1].stages[2][1], where:

• [1] is the first render point

• [2] is the second stage

• [1] is the first interaction in that stage

Function Syntax

When defining functions to execute, they follow this format:

{ 
    type = 'function', 
    name = 'function_name', 
    params = { 
        param1 = value1,
        param2 = value2
    }
}

Where:

• type is always 'function' (or 'event' for events)

• name is the name of the function to call

• params is a table containing parameters to pass to the function

Example Reading Guide

If you see in the documentation:

stage[m][o].zone.pos - 4D vector with coordinates and heading

This means:

1. In the stage with index m

2. In the interaction with index o

3. Look for the zone table

4. Inside that table, find the pos property

5. This property should be a vector4 containing X, Y, Z coordinates and a heading

Tips for Beginners

• Understand the Flow: The heist progresses through stages that are unlocked sequentially. Plan your heist's flow on paper before coding.

• Coordinates Matter: Always double-check your coordinates and headings. Small errors can place objects inside walls or make interactions unreachable.

• Test Individual Elements: When creating a complex heist, implement and test one element at a time rather than writing everything at once.

• Use the Examples: The example configurations provided contain working code patterns - copy and modify them for your needs.

• Backup Your Work: Always keep backups of your configuration files before making major changes.

• Indentation Helps: Use consistent indentation to make your config more readable. Each nested level should be indented further.

• Function Chains: For complex behavior, use a chain of functions in the on_complete handler to trigger multiple effects when an interaction is finished.

• Start Simple: Begin with just 1-2 stages and a few basic interactions, then expand your heist once you understand how everything works.

• Common Mistakes to Avoid:

  • Forgetting to unlock stages with unlock_stage

  • Missing required parameters (like forgetting to specify model for objects)

  • Using the wrong syntax for hashes (they need backticks: `model_name`)

  • Mismatched braces or parentheses causing syntax errors

• Debug Tips: If your heist isn't working correctly:

  • Check your syntax for errors (missing commas, extra braces, etc.)

  • Verify all object models exist in the game

  • Ensure doors and coordinates reference real locations

  • Confirm that stages unlock properly through the correct function calls