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

PreviousInstallation GuideNextConfiguration Files

Last updated