> ## Documentation Index
> Fetch the complete documentation index at: https://docs.projectx.gg/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Tiers

> Learn how to configure robbery tiers in the config/tiers.lua file

## What Are Tiers?

Tiers are difficulty levels in the House Robbery V2 system. Each tier has different requirements, interiors, approaches, loot tables, and difficulty settings. Players progress through tiers by gaining experience and leveling up.

## Adding a New Tier

To add a new tier, create a new entry in the `Config.Tiers` table with a unique tier number as the key.

### Basic Structure

```lua theme={null}
Config.Tiers = {
    [1] = {
        ["Level"] = 1,
        ["Interior"] = "shell_name",
        ["Approach"] = {"approach1", "approach2"},
        ["RequiredItemForLockpicking"] = "item_name",
        ["ExpOnDone"] = 10,
        ["ExpForAllGroupMembers"] = false,
        ["LootableSpots"] = {},
        ["LootableProps"] = {},
        ["LootableCash"] = {},
        ["LootableSafes"] = {},
        ["LootableDisplays"] = {},
        ["LootablePaintings"] = {},
        ["LootableHighValueItems"] = {},
        ["Spots"] = {},
        ["Props"] = {},
        ["Cash"] = {},
        ["Display"] = {},
        ["Painting"] = {},
        ["Safe"] = {},
        ["HighValueItems"] = {},
        ["Tenants"] = {},
        ["Pets"] = {},
        ["LootTable"] = {}
    }
}
```

## Tier Configuration Options

### Basic Settings

<ParamField path="Level" type="number" required>
  Minimum level required to access this tier
</ParamField>

<ParamField path="Interior" type="string" required>
  Interior name (Shell or IPL) from the presets file. Must match exactly with a preset name
</ParamField>

<ParamField path="Approach" type="table or string" required>
  Available approaches for this tier. Can be a table of multiple approaches or a single string

  * `"gangster"` - Break in aggressively
  * `"door"` - Lockpick the door
  * `"locksmith"` - Pose as locksmith
  * `"maid"` - Pose as cleaning service
  * `"hacking"` - Hack security systems
  * `"payphone"` - Use payphone approach
  * `"valet"` - Valet service approach
</ParamField>

<ParamField path="RequiredItemForLockpicking" type="string or boolean" required>
  Item required to break into houses. Set to `false` for no requirement
</ParamField>

<ParamField path="ExpOnDone" type="number">
  Experience points awarded when completing the robbery
</ParamField>

<ParamField path="ExpForAllGroupMembers" type="boolean">
  If `true`, all group members receive XP. Requires a group system implementation
</ParamField>

### Lootable Arrays

These arrays reference the spot numbers from your preset file. The numbers correspond to the keys in your preset's loot sections.

<ParamField path="LootableSpots" type="table">
  Array of spot IDs that can spawn (e.g., `{1, 2, 3, 4}`)
</ParamField>

<ParamField path="LootableProps" type="table">
  Array of prop IDs that can spawn
</ParamField>

<ParamField path="LootableCash" type="table">
  Array of cash spot IDs that can spawn
</ParamField>

<ParamField path="LootableSafes" type="table">
  Array of safe IDs that can spawn
</ParamField>

<ParamField path="LootableDisplays" type="table">
  Array of display case IDs that can spawn
</ParamField>

<ParamField path="LootablePaintings" type="table">
  Array of painting IDs that can spawn
</ParamField>

<ParamField path="LootableHighValueItems" type="table">
  Array of high value item IDs that can spawn
</ParamField>

<Info>
  The IDs in these arrays must match the keys defined in your preset file. For example, if your preset has `["Props"]["1"]` and `["Props"]["2"]`, use `["LootableProps"] = {1, 2}`
</Info>

### Spots Configuration

<ParamField path="Spots.Enable" type="boolean" required>
  Enable or disable searchable spots in this tier
</ParamField>

<ParamField path="Spots.SpawnChance" type="number" required>
  Percentage chance (0-100) that spots will spawn
</ParamField>

<ParamField path="Spots.SpotCount" type="table" required>
  Range of spots that can spawn with `min` and `max` values. Must not exceed the number of `LootableSpots` configured
</ParamField>

### Props Configuration

<ParamField path="Props.Enable" type="boolean" required>
  Enable or disable props in this tier
</ParamField>

<ParamField path="Props.Outline" type="boolean" required>
  Enable visual outline on stealable props
</ParamField>

<ParamField path="Props.SpawnChance" type="number" required>
  Percentage chance (0-100) that props will spawn
</ParamField>

<ParamField path="Props.PropCount" type="table" required>
  Range of props that can spawn with `min` and `max` values
</ParamField>

### Cash Configuration

<ParamField path="Cash.Enable" type="boolean" required>
  Enable or disable cash spawns in this tier
</ParamField>

<ParamField path="Cash.Outline" type="boolean" required>
  Enable visual outline on cash props
</ParamField>

<ParamField path="Cash.SpawnChance" type="number" required>
  Percentage chance (0-100) that cash will spawn
</ParamField>

<ParamField path="Cash.CashCount" type="table" required>
  Range of cash spots that can spawn with `min` and `max` values
</ParamField>

### Display Configuration

<ParamField path="Display.Enable" type="boolean" required>
  Enable or disable display cases in this tier
</ParamField>

<ParamField path="Display.SpawnChance" type="number" required>
  Percentage chance (0-100) that displays will spawn
</ParamField>

<ParamField path="Display.DisplayCount" type="table" required>
  Range of displays that can spawn with `min` and `max` values
</ParamField>

### Painting Configuration

<ParamField path="Painting.Enable" type="boolean" required>
  Enable or disable paintings in this tier
</ParamField>

<ParamField path="Painting.SpawnChance" type="number" required>
  Percentage chance (0-100) that paintings will spawn
</ParamField>

<ParamField path="Painting.PaintingCount" type="table" required>
  Range of paintings that can spawn with `min` and `max` values
</ParamField>

### Safe Configuration

<ParamField path="Safe.Enable" type="boolean" required>
  Enable or disable safes in this tier
</ParamField>

<ParamField path="Safe.SpawnChance" type="number" required>
  Percentage chance (0-100) that safes will spawn
</ParamField>

<ParamField path="Safe.SafeCount" type="table" required>
  Range of safes that can spawn with `min` and `max` values
</ParamField>

<ParamField path="Safe.Exp" type="number" required>
  Experience points awarded for cracking a safe
</ParamField>

<ParamField path="Safe.RewardCount" type="table" required>
  How many times the reward table is rolled with `min` and `max` values
</ParamField>

<ParamField path="Safe.Reward" type="table" required>
  Array of possible rewards with each entry containing:

  * `Name` - Item name
  * `Chance` - Percentage chance (total should equal 100)
  * `Amount` - Table with `min` and `max` item quantities
</ParamField>

### High Value Items Configuration

<ParamField path="HighValueItems.Enable" type="boolean" required>
  Enable or disable high value items in this tier
</ParamField>

<ParamField path="HighValueItems.Outline" type="boolean" required>
  Enable visual outline on high value items
</ParamField>

<ParamField path="HighValueItems.SpawnChance" type="number" required>
  Percentage chance (0-100) that high value items will spawn
</ParamField>

### Tenants Configuration

<ParamField path="Tenants.Enable" type="boolean" required>
  Enable or disable NPCs in this tier
</ParamField>

<ParamField path="Tenants.SpawnChance" type="number" required>
  Percentage chance (0-100) that tenants will spawn
</ParamField>

<ParamField path="Tenants.WeaponChance" type="number" required>
  Percentage chance (0-100) that a tenant will be armed
</ParamField>

<ParamField path="Tenants.RandomWeapons" type="table" required>
  Array of weapon hashes that can be given to armed tenants
</ParamField>

<ParamField path="Tenants.Count" type="table" required>
  Range of tenants that can spawn with `min` and `max` values. Maximum is 4 by default (increase in preset file if needed)
</ParamField>

### Pets Configuration

<ParamField path="Pets.Enable" type="boolean" required>
  Enable or disable pets in this tier
</ParamField>

<ParamField path="Pets.SpawnChance" type="number" required>
  Percentage chance (0-100) that pets will spawn
</ParamField>

<ParamField path="Pets.Count" type="table" required>
  Range of pets that can spawn with `min` and `max` values. Maximum is 2 by default (increase in preset file if needed)
</ParamField>

### Loot Table Configuration

The loot table defines what items can be found when searching different spot types.

<ParamField path="LootTable.LootPerSearch" type="table" required>
  How many different items can be obtained per search with `min` and `max` values
</ParamField>

<ParamField path="LootTable.FindingLootChance" type="number" required>
  Percentage chance (0-100) of finding loot when searching under normal conditions
</ParamField>

<ParamField path="LootTable.LootChanceAfterAlarmTriggered" type="number" required>
  Percentage chance (0-100) of finding loot after the alarm has been triggered
</ParamField>

<ParamField path="LootTable.Exp" type="table" required>
  Experience points range awarded per search with `min` and `max` values
</ParamField>

<ParamField path="LootTable[spot_type]" type="table" required>
  Each spot type (drawer, cabinet, closet, kitchen, etc.) has its own loot table with entries containing:

  * `Name` - Item name
  * `Chance` - Percentage chance (total for each spot type should equal 100)
  * `Amount` - Table with `min` and `max` item quantities
</ParamField>

<Warning>
  The total chance values for each spot type in the loot table must equal 100. For example, if you have 4 items in the `drawer` table, their chances could be 25, 25, 25, 25 or any combination that totals 100.
</Warning>

## Complete Example

Here's a complete tier configuration with all options:

```lua theme={null}
Config.Tiers = {
    [5] = {
        ["Level"] = 20,
        ["Interior"] = "EclipseTowersPenthouse2",
        ["Approach"] = {"valet", "maid", "hacking"},
        ["RequiredItemForLockpicking"] = "advancedlockpick",
        ["ExpOnDone"] = 10,
        ["ExpForAllGroupMembers"] = false,
        ["LootableSpots"] = {1, 2, 3, 4, 5},
        ["LootableProps"] = {1, 2, 3, 4, 5},
        ["LootableCash"] =  {1, 2},
        ["LootableSafes"] = {1},
        ["LootableDisplays"] = {1},
        ["LootablePaintings"] = {1, 2},
        ["LootableHighValueItems"] = {1},
        ["Spots"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["SpotCount"] = {min = 4, max = 5},
        },
        ["Props"] = {
            ["Enable"] = true,
            ["Outline"] = false,
            ["SpawnChance"] = 100,
            ["PropCount"] = {min = 5, max = 5},
        },
        ["Cash"] = {
            ["Enable"] = true,
            ["Outline"] = false,
            ["SpawnChance"] = 100,
            ["CashCount"] = {min = 2, max = 2},
        },
        ["Display"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["DisplayCount"] = {min = 1, max = 1},
        },
        ["Painting"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["PaintingCount"] = {min = 2, max = 2},
        },
        ["Safe"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["SafeCount"] = {min = 1, max = 1},
            ["Exp"] = 10,
            ["RewardCount"] = {min = 1, max = 1},
            ["Reward"] = {
                {Name = "fitbit", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "screwdriverset", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "bandage", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "plastic", Chance = 25, Amount = {min = 1, max = 1}},
            },
        },
        ["HighValueItems"] = {
            ["Enable"] = true,
            ["Outline"] = false,
            ["SpawnChance"] = 100,
        },
        ["Tenants"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["WeaponChance"] = 100,
            ["RandomWeapons"] = {"WEAPON_BAT", "WEAPON_KNIFE", "WEAPON_PISTOL"},
            ["Count"] = {min = 2, max = 2},
        },
        ["Pets"] = {
            ["Enable"] = true,
            ["SpawnChance"] = 100,
            ["Count"] = {min = 1, max = 1},
        },
        ["LootTable"] = {
            LootPerSearch = {min = 1, max = 1},
            FindingLootChance = 70,
            LootChanceAfterAlarmTriggered = 40,
            Exp = {min = 3, max = 4},
            ["drawer"] = {
                {Name = "screwdriverset", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "fitbit", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "lockpick", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "samsungphone", Chance = 25, Amount = {min = 1, max = 1}},
            },
            ["cabinet"] = {
                {Name = "bandage", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "painkillers", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "water_bottle", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "joint", Chance = 25, Amount = {min = 1, max = 1}},
            },
            ["closet"] = {
                {Name = "diamond", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "rolex", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "iphone", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "samsungphone", Chance = 25, Amount = {min = 1, max = 1}},
            },
            ["kitchen"] = {
                {Name = "fitbit", Chance = 25, Amount = {min = 1, max = 1}},
                {Name = "screwdriverset", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "bandage", Chance = 25, Amount = {min = 1, max = 2}},
                {Name = "plastic", Chance = 25, Amount = {min = 1, max = 1}},
            },
        },
    },
}
```

## Tips for Balancing Tiers

1. **Progressive Difficulty**: Higher tiers should have:
   * Higher level requirements
   * More armed tenants (`WeaponChance`)
   * Lower loot finding chances (`FindingLootChance`)
   * More valuable loot in safe rewards

2. **Spawn Chances**: Use spawn chances to create variety:
   * Not every robbery needs to have all features
   * Lower spawn chances for high-value items create rarity
   * Balance risk vs reward with tenant/pet spawn chances

3. **Loot Distribution**: Ensure the count ranges match your configured lootable arrays:
   * If `LootableSpots = {1, 2, 3}`, then `SpotCount` max should not exceed 3
   * Use empty arrays `{}` for features you want to disable

4. **Experience Points**: Balance XP rewards with difficulty:
   * Higher tiers should give more XP
   * Consider XP for individual actions (spots, safes) vs completion bonus

5. **Approaches**: Offer multiple approaches for higher tiers to give players options while lower tiers might have limited entry methods