> ## 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.

# Adding House Locations

> Learn how to add robbable house locations to the config/houses.lua file

## What Are House Locations?

House locations are the physical spots on the map where players can initiate house robberies. These are the door coordinates and settings for each individual house, not the interior layouts (which are configured in presets).

## Configuration Structure

The houses configuration is organized into two main categories based on interior type:

```lua theme={null}
Config.Houses = {
    ["Shells"] = {},
    ["IPLs"] = {}
}
```

<Info>
  **Shells** use external shell systems (like K4MB1), while **IPLs** use GTA's built-in interior systems. Both categories support the exact same configuration parameters, so you can use all features regardless of interior type.
</Info>

## Adding a New House

To add a new house location, create an entry under either `["Shells"]` or `["IPLs"]` with a unique house name as the key.

### Basic Structure

```lua theme={null}
Config.Houses = {
    ["Shells"] = {
        ["House Name"] = {
            ["Tier"] = 1,
            ["DoorCoords"] = vector3(0.0, 0.0, 0.0),
            ["SilentDispatch"] = false,
            ["SilentDispatchChance"] = 50,
            ["AlarmRemovesDispatch"] = false,
            ["ScoutingExp"] = 10,
            ["EnableAlarmProp"] = true,
            ["EnableLasers"] = false,
            ["ScoutingTablet"] = true,
            ["PedsSpawnRegardlessOfTime"] = false
        }
    },
    ["IPLs"] = {
        ["House Name"] = {
            ["Tier"] = 4,
            ["DoorCoords"] = vector3(0.0, 0.0, 0.0),
            ["SilentDispatch"] = false,
            ["SilentDispatchChance"] = 50,
            ["AlarmRemovesDispatch"] = false,
            ["ScoutingExp"] = 10,
            ["EnableAlarmProp"] = true,
            ["EnableLasers"] = false,
            ["ScoutingTablet"] = true,
            ["PedsSpawnRegardlessOfTime"] = false,
            ["ScoutingSpots"] = {
                ["ScoutingForTenantCount"] = {
                    ["Coords"] = vector4(0.0, 0.0, 0.0, 0.0),
                    ["Label"] = "Eavesdrop",
                    ["Animation"] = {Dict = "cover@move@base@core", Anim = "high_idle_r_peek"},
                    ["Icon"] = "fas fa-ear-listen"
                },
                ["ScoutingForTime"] = {
                    ["Coords"] = vector4(0.0, 0.0, 0.0, 0.0),
                    ["Label"] = "Peek through window",
                    ["Animation"] = {Dict = "cover@peek@ai@1h@high@_a", Anim = "peek_r_corner"},
                    ["Icon"] = "fas fa-eye"
                }
            }
        }
    }
}
```

<Warning>
  Both Shells and IPLs support all the same parameters including `EnableAlarmProp` and `EnableLasers`. The categorization is purely organizational based on your tier's interior type.
</Warning>

## Configuration Parameters

### Basic Settings

<ParamField path="Tier" type="number" required>
  The tier level of this house. Must match a tier configured in `config/tiers.lua`
</ParamField>

<ParamField path="DoorCoords" type="vector3" required>
  The coordinates of the house door where players initiate the robbery
</ParamField>

<ParamField path="SilentDispatch" type="boolean">
  If `true`, sends a dispatch alert without triggering the alarm when someone enters. Useful for remote houses far from the city
</ParamField>

<ParamField path="SilentDispatchChance" type="number">
  The chance (in percentage) that a silent dispatch will be sent when someone enters. Only applicable if `SilentDispatch` is enabled.
</ParamField>

<ParamField path="AlarmRemovesDispatch" type="boolean">
  If `true`, completing the alarm step inside prevents police dispatch from being sent
</ParamField>

<ParamField path="ScoutingExp" type="number">
  Experience points awarded for scouting this house
</ParamField>

<ParamField path="ScoutingTablet" type="boolean">
  If `true`, allows using a tablet to scout the house remotely instead of physical scouting spots
</ParamField>

<ParamField path="PedsSpawnRegardlessOfTime" type="boolean">
  If `true`, NPCs spawn even during the configured safe time window. By default, robbing during safe hours prevents NPC spawns
</ParamField>

### Security Features

<ParamField path="EnableAlarmProp" type="boolean">
  Enable the physical alarm box prop that can be disabled inside the house. Works for both Shells and IPLs
</ParamField>

<ParamField path="EnableLasers" type="boolean">
  Enable laser security systems inside the house. Works for both Shells and IPLs (must be configured in the preset)
</ParamField>

### Advanced Scouting (Optional)

You can define custom scouting spots around the house instead of using the tablet:

<ParamField path="ScoutingSpots.ScoutingForTenantCount" type="table">
  Spot to discover how many tenants are inside

  * `Coords` - Position and heading for the player
  * `Label` - Interaction text
  * `Animation` - Animation with `Dict` and `Anim` properties OR `Scenario` - Scenario name (use one or the other)
  * `Icon` - Font Awesome icon
</ParamField>

<ParamField path="ScoutingSpots.ScoutingForTime" type="table">
  Spot to discover the time remaining until alarm triggers

  * `Coords` - Position and heading for the player
  * `Label` - Interaction text
  * `Animation` - Animation with `Dict` and `Anim` properties OR `Scenario` - Scenario name (use one or the other)
  * `Icon` - Font Awesome icon
</ParamField>

**Example with Animation:**

```lua theme={null}
-- Add this to any house configuration (Shells or IPLs)
["ScoutingSpots"] = {
    ["ScoutingForTenantCount"] = {
        ["Coords"] = vector4(1385.0, 3660.0, 34.93, 180.0),
        ["Label"] = "Eavesdrop",
        ["Animation"] = {Dict = "cover@move@base@core", Anim = "high_idle_r_peek"},
        ["Icon"] = "fas fa-ear-listen"
    },
    ["ScoutingForTime"] = {
        ["Coords"] = vector4(1384.0, 3659.0, 34.93, 90.0),
        ["Label"] = "Peek through window",
        ["Animation"] = {Dict = "cover@peek@ai@1h@high@_a", Anim = "peek_r_corner"},
        ["Icon"] = "fas fa-eye"
    }
}
```

**Example with Scenario:**

```lua theme={null}
-- Add this to any house configuration (Shells or IPLs)
["ScoutingSpots"] = {
    ["ScoutingForTenantCount"] = {
        ["Coords"] = vector4(1385.0, 3660.0, 34.93, 180.0),
        ["Label"] = "Eavesdrop",
        ["Scenario"] = "WORLD_HUMAN_BINOCULARS",
        ["Icon"] = "fas fa-ear-listen"
    },
    ["ScoutingForTime"] = {
        ["Coords"] = vector4(1384.0, 3659.0, 34.93, 90.0),
        ["Label"] = "Peek through window",
        ["Scenario"] = "WORLD_HUMAN_STAND_IMPATIENT",
        ["Icon"] = "fas fa-eye"
    }
}
```

<Info>
  Scouting spots and scouting tablet can be used together or independently. If both are configured, players can choose their preferred method.
</Info>

## Shell Houses vs IPL Houses

### Shells

* Use external shell systems (K4MB1, LevLevLev, etc.)
* Generally for lower to mid-tier houses
* Support all features (alarm props, lasers, scouting, etc.)

### IPLs

* Use GTA V's built-in interiors
* Generally for higher-tier houses
* More detailed and realistic interiors
* Support all features (alarm props, lasers, scouting, etc.)

<Info>
  **Important**: Both Shells and IPLs support the exact same configuration parameters. The only difference is the interior system used by the tier. All features like `EnableAlarmProp`, `EnableLasers`, and `ScoutingSpots` work identically in both categories.
</Info>

<Warning>
  Make sure your house is added to the correct category based on what interior type the tier uses. Check your tier configuration in `config/tiers.lua` to see if it uses a Shell or IPL interior.
</Warning>

## Tips for Adding Houses

1. **Unique Names**: Each house must have a unique name. Use location-based naming like `"Sandy Shores 1"`, `"Vinewood Hills 12"`, etc.

2. **Tier Assignment**: Assign tiers based on:
   * Location difficulty (city vs remote)
   * Neighborhood wealth level
   * Desired loot quality

3. **Door Coordinates**: Stand at the house door and use `/vector4` or a similar command to get precise coordinates

4. **Silent Dispatch**: Enable for houses far from the city to give police more warning time

5. **Alarm Removal**: Consider enabling `AlarmRemovesDispatch` for higher-tier houses to reward skilled players who disable alarms

6. **Scouting Options**:
   * Tablet scouting, convenient if you dont want to set up physical spots
   * Physical scouting spots add realism and risk
   * Mix both for variety

7. **Laser Systems**: Only enable lasers for high-tier houses where the preset has laser configurations

## Example: Shell House

```lua theme={null}
["Shells"] = {
    ["Sandy Shores 1"] = {
        ["Tier"] = 1,
        ["DoorCoords"] = vector3(1385.09, 3659.43, 34.93),
        ["SilentDispatch"] = false,
        ["SilentDispatchChance"] = 50,
        ["AlarmRemovesDispatch"] = false,
        ["ScoutingExp"] = 10,
        ["EnableAlarmProp"] = true,
        ["EnableLasers"] = false,
        ["ScoutingTablet"] = true,
        ["PedsSpawnRegardlessOfTime"] = false
        ["ScoutingSpots"] = {
            ["ScoutingForTenantCount"] = {["Coords"] = vector4(1385.0, 3660.0, 34.93, 180.0), ["Label"] = "Eavesdrop", ["Animation"] = {Dict = "cover@move@base@core", Anim = "high_idle_r_peek"}, ["Icon"] = "fas fa-ear-listen"},
            ["ScoutingForTime"] = {["Coords"] = vector4(1384.0, 3659.0, 34.93, 90.0), ["Label"] = "Peek through window", ["Animation"] = {Dict = "cover@peek@ai@1h@high@_a", Anim = "peek_r_corner"}, ["Icon"] = "fas fa-eye"}
        }
    }
}
```

## Example: IPL House

```lua theme={null}
["IPLs"] = {
    ["El Burro Heights 1"] = {
        ["Tier"] = 4,
        ["DoorCoords"] = vector3(1193.4, -1622.28, 45.22),
        ["SilentDispatch"] = false,
        ["SilentDispatchChance"] = 50,
        ["AlarmRemovesDispatch"] = false,
        ["ScoutingExp"] = 10,
        ["EnableAlarmProp"] = true,
        ["EnableLasers"] = false,
        ["ScoutingTablet"] = true,
        ["PedsSpawnRegardlessOfTime"] = false
        ["ScoutingSpots"] = {
            ["ScoutingForTenantCount"] = {["Coords"] = vector4(1193.4, -1623.0, 45.22, 180.0), ["Label"] = "Eavesdrop", ["Animation"] = {Dict = "cover@move@base@core", Anim = "high_idle_r_peek"}, ["Icon"] = "fas fa-ear-listen"},
            ["ScoutingForTime"] = {["Coords"] = vector4(1192.5, -1622.0, 45.22, 90.0), ["Label"] = "Peek through window", ["Animation"] = {Dict = "cover@peek@ai@1h@high@_a", Anim = "peek_r_corner"}, ["Icon"] = "fas fa-eye"}
        }
    }
}
```

## Complete Example

Here's a complete configuration showing multiple houses across different tiers and types. This demonstrates proper organization and variety in house setups.

<Info>
  This example shows houses organized by neighborhood and tier progression. Notice how higher tiers often include `EnableAlarmProp` and `EnableLasers` for added difficulty.
</Info>

<Accordion title="View Complete Configuration Example">
  ```lua theme={null}
  Config.Houses = {
      ["Shells"] = {
          ["Sandy Shores 1"] = {
              ["Tier"] = 1,
              ["DoorCoords"] = vector3(1385.09, 3659.43, 34.93),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
              
          },
          ["Sandy Shores 2"] = {
              ["Tier"] = 1,
              ["DoorCoords"] = vector3(1436.2, 3639.08, 34.95),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = false,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Rancho 1"] = {
              ["Tier"] = 1,
              ["DoorCoords"] = vector3(338.63, -1829.58, 28.34),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = false,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Chamberlain Hills 1"] = {
              ["Tier"] = 1,
              ["DoorCoords"] = vector3(-219.37, -1580.04, 34.87),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = false,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Alta 1"] = {
              ["Tier"] = 2,
              ["DoorCoords"] = vector3(115.67, -271.43, 46.33),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Burton 1"] = {
              ["Tier"] = 2,
              ["DoorCoords"] = vector3(-97.43, -357.71, 42.37),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Mirror Park 1"] = {
              ["Tier"] = 3,
              ["DoorCoords"] = vector3(1060.45, -378.2, 68.23),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["East Vinewood 1"] = {
              ["Tier"] = 3,
              ["DoorCoords"] = vector3(861.46, -509.1, 57.71),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = false,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Vinewood Hills 1"] = {
              ["Tier"] = 3,
              ["DoorCoords"] = vector3(-873.24, 562.68, 96.62),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["AlarmRemovesDispatch"] = false,
              ["ScoutingExp"] = 10,
              ["EnableAlarmProp"] = true,
              ["EnableLasers"] = true,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          }
      },
      ["IPLs"] = {
          ["El Burro Heights 1"] = {
              ["Tier"] = 4,
              ["DoorCoords"] = vector3(1193.4, -1622.28, 45.22),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = false,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false,
              ["ScoutingSpots"] = {
                  ["ScoutingForTenantCount"] = {["Coords"] = vector4(1193.4, -1623.0, 45.22, 180.0), ["Label"] = "Eavesdrop", ["Animation"] = {Dict = "cover@move@base@core", Anim = "high_idle_r_peek"}, ["Icon"] = "fas fa-ear-listen"},
                  ["ScoutingForTime"] = {["Coords"] = vector4(1192.5, -1622.0, 45.22, 90.0), ["Label"] = "Peek through window", ["Animation"] = {Dict = "cover@peek@ai@1h@high@_a", Anim = "peek_r_corner"}, ["Icon"] = "fas fa-eye"}
              }
          },
          ["El Burro Heights 2"] = {
              ["Tier"] = 4,
              ["DoorCoords"] = vector3(1245.47, -1626.94, 53.28),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = false,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Vespucci 1"] = {
              ["Tier"] = 4,
              ["DoorCoords"] = vector3(-1247.08, -1358.31, 7.82),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = false,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Richman 1"] = {
              ["Tier"] = 5,
              ["DoorCoords"] = vector3(-1629.96, 36.4, 62.94),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = true,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Richman 2"] = {
              ["Tier"] = 5,
              ["DoorCoords"] = vector3(-1570.71, 22.4, 59.55),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = true,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Vinewood Hills 10"] = {
              ["Tier"] = 6,
              ["DoorCoords"] = vector3(-339.93, 625.51, 171.36),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = true,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          },
          ["Vinewood Hills 11"] = {
              ["Tier"] = 6,
              ["DoorCoords"] = vector3(-446.17, 686.33, 153.11),
              ["SilentDispatch"] = false,
              ["SilentDispatchChance"] = 50,
              ["EnableAlarmProp"] = true,
              ["AlarmRemovesDispatch"] = false,
              ["EnableLasers"] = true,
              ["ScoutingExp"] = 10,
              ["ScoutingTablet"] = true,
              ["PedsSpawnRegardlessOfTime"] = false
          }
      }
  }
  ```
</Accordion>

## Testing Your Houses

After adding houses, test them to ensure:

1. **Door Coordinates**: Player can interact with the door properly
2. **Tier Match**: The house uses the correct interior for its tier
3. **Dispatch**: Silent dispatch works as intended for remote locations
4. **Scouting**: Tablet or physical scouting spots function correctly
5. **Security**: Alarm props and lasers spawn if enabled
6. **NPCs**: Tenants spawn according to time and configuration