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

# Carryable Props

> Configure props that can be carried and stored in vehicles

## Carryable Props System

The carryable props system allows players to physically carry items during robberies and store them in vehicle trunks. This guide covers how to configure the system and add new carryable props.

***

## Configuration Structure

The carryable props system is configured in `config/main.lua` with three main sections:

1. **CarryProps Settings** - Global enable/disable and vehicle interaction settings
2. **Props Definition** - Individual prop configurations with models and animations
3. **AllowedVehicleClasses** - Which vehicle types can store props

***

## Global Settings

<ParamField path="Enable" type="boolean" default="true">
  Enable or disable the entire carryable props system. When disabled, players cannot carry or store props in vehicles.
</ParamField>

<ParamField path="TrunkTargetOnly" type="boolean" default="true">
  When `true`, players must target the trunk specifically to store props. When `false`, targeting anywhere on the vehicle works.

  <Warning>
    Setting to `false` is recommended for vehicles without traditional trunks (motorcycles, front-engine vehicles).
  </Warning>
</ParamField>

<ParamField path="UnlockedVehiclesOnly" type="boolean" default="true">
  When `true`, players can only store props in unlocked vehicles. When `false`, props can be stored in any vehicle regardless of lock status.
</ParamField>

***

## Adding New Props

To add a new carryable prop, add an entry to the `Props` table within `Config.CarryProps`:

```lua theme={null}
Config.CarryProps = {
    ["Enable"] = true,
    ["TrunkTargetOnly"] = true,
    ["UnlockedVehiclesOnly"] = true,
    
    ["Props"] = {
        ["item_name_here"] = {
            Model = "prop_model_name",
            Bone = 24817,
            Offset = vec3(0.0, 0.0, 0.0),
            Rotation = vec3(0.0, 0.0, 0.0),
            Animation = {dict = "anim_dict", anim = "anim_name"}
        },
    },
}
```

### Prop Configuration Parameters

<ParamField path="item_name_here" type="string" required>
  The item name that matches your inventory item. This should be the exact item name from your items configuration (e.g., `x_television`, `x_microwave`).

  Must match the item names defined in your tier's `LootTable` or `HighValueItems` configuration.
</ParamField>

<ParamField path="Model" type="string" required>
  The prop model to attach to the player when carrying. Use GTA V prop models without the hash.

  Common prop models:

  * `prop_tv_03` - Television
  * `prop_coffee_mac_02` - Coffee maker
  * `v_res_printer` - Printer
  * `prop_microwave_1` - Microwave
  * `prop_el_guitar_01` - Electric guitar
  * `prop_rad_con_01` - Radio
  * `prop_boombox_01` - Boombox
</ParamField>

<ParamField path="Bone" type="integer" required>
  The player bone ID to attach the prop to. Determines which part of the body holds the prop.

  Common bones:

  * `24817` - Left hand carry (single-handed items)
  * `18905` - Two-handed carry (larger items)
  * `28422` - Right hand
  * `57005` - Head
</ParamField>

<ParamField path="Offset" type="vector3" required>
  Position offset from the bone attachment point using `vec3(x, y, z)` format.

  Adjust these values to position the prop correctly:

  * **X axis**: Left (-) / Right (+)
  * **Y axis**: Forward (+) / Backward (-)
  * **Z axis**: Up (+) / Down (-)

  Values typically range from -1.0 to 1.0 but may vary by prop size.
</ParamField>

<ParamField path="Rotation" type="vector3" required>
  Rotation angles for the prop using `vec3(pitch, roll, yaw)` format in degrees.

  Adjust these values to orient the prop correctly:

  * **Pitch**: Tilt forward/backward (0-360)
  * **Roll**: Rotate left/right (0-360)
  * **Yaw**: Spin clockwise/counterclockwise (0-360)
</ParamField>

<ParamField path="Animation" type="table" required>
  Animation to play while carrying the prop.

  Contains two required fields:

  * `dict` - Animation dictionary
  * `anim` - Animation name

  Common carry animations:

  * `anim@heists@box_carry@` / `idle` - Standard box carry
</ParamField>

***

## Vehicle Class Configuration

Control which vehicle types can store carryable props using `Config.AllowedVehicleClasses`:

```lua theme={null}
Config.AllowedVehicleClasses = {
    [VehicleClass.COMPACTS]        = true,
    [VehicleClass.SEDANS]          = true,
    [VehicleClass.SUVS]            = true,
    [VehicleClass.MOTORCYCLES]     = false,
    [VehicleClass.BOATS]           = false,
}
```

### Available Vehicle Classes

| Class             | Recommended | Notes                           |
| ----------------- | ----------- | ------------------------------- |
| `COMPACTS`        | `true`      | Small cars with trunks          |
| `SEDANS`          | `true`      | Standard 4-door vehicles        |
| `SUVS`            | `true`      | Large vehicles with cargo space |
| `COUPES`          | `true`      | 2-door sports cars              |
| `MUSCLE`          | `true`      | Classic muscle cars             |
| `SPORTS_CLASSICS` | `true`      | Vintage sports cars             |
| `SPORTS`          | `true`      | Modern sports cars              |
| `SUPER`           | `true`      | Supercars                       |
| `MOTORCYCLES`     | `false`     | No storage capacity             |
| `OFF_ROAD`        | `true`      | Trucks and off-road vehicles    |
| `INDUSTRIAL`      | `true`      | Work vehicles                   |
| `UTILITY`         | `true`      | Utility trucks                  |
| `VANS`            | `true`      | Cargo vans                      |
| `CYCLES`          | `false`     | Bicycles                        |
| `BOATS`           | `false`     | Watercraft                      |
| `HELICOPTERS`     | `false`     | Aircraft                        |
| `PLANES`          | `false`     | Aircraft                        |
| `SERVICE`         | `false`     | Service vehicles                |
| `EMERGENCY`       | `false`     | Police/EMS/Fire                 |
| `MILITARY`        | `false`     | Military vehicles               |
| `COMMERCIAL`      | `false`     | Commercial trucks               |
| `TRAINS`          | `false`     | Trains                          |
| `OPEN_WHEEL`      | `false`     | F1 style cars                   |

<Warning>
  Do not modify the `VehicleClass` table at the top of the config. This is a reference table used by the script.
</Warning>

***

## Complete Examples

### Example 1: Coffee Maker

```lua theme={null}
["x_coffeemaker"] = {
    Model = "prop_coffee_mac_02",
    Bone = 24817,
    Offset = vec3(0.02, 0.43, 0.03),
    Rotation = vec3(91.0, 0.0, -265.0),
    Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
}
```

Small appliance carried in left hand with standard box carry animation.

### Example 2: Television

```lua theme={null}
["x_television"] = {
    Model = "prop_tv_03",
    Bone = 18905,
    Offset = vec3(0.25, 0.3, 0.4),
    Rotation = vec3(235.0, 95.0, 15.0),
    Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
}
```

Large item requiring two-handed carry position with adjusted rotation for screen visibility.

### Example 3: Electric Guitar

```lua theme={null}
["x_electricguitar"] = {
    Model = "prop_el_guitar_01",
    Bone = 18905,
    Offset = vec3(0.15, 0.0, 0.1),
    Rotation = vec3(-10.0, 15.0, 190.0),
    Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
}
```

Long item with custom rotation to prevent clipping through the player model.

### Example 4: Laptop

```lua theme={null}
["x_laptop"] = {
    Model = "prop_laptop_01a",
    Bone = 24817,
    Offset = vec3(0.10, 0.35, 0.0),
    Rotation = vec3(90.0, 0.0, -90.0),
    Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
}
```

Compact electronic device carried in one hand.

***

## Full Configuration Example

<Accordion title="Complete Carryable Props Configuration">
  ```lua theme={null}
  Config.CarryProps = {
      ["Enable"] = true,
      ["TrunkTargetOnly"] = true,
      ["UnlockedVehiclesOnly"] = true,

      ["Props"] = {
          ["x_coffeemaker"] = {
              Model = "prop_coffee_mac_02",
              Bone = 24817,
              Offset = vec3(0.02, 0.43, 0.03),
              Rotation = vec3(91.0, 0.0, -265.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_television"] = {
              Model = "prop_tv_03",
              Bone = 18905,
              Offset = vec3(0.25, 0.3, 0.4),
              Rotation = vec3(235.0, 95.0, 15.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_printer"] = {
              Model = "v_res_printer",
              Bone = 18905,
              Offset = vec3(0.3, 0.0, 0.25),
              Rotation = vec3(-75.0, -5.0, 35.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_microwave"] = {
              Model = "prop_microwave_1",
              Bone = 24817,
              Offset = vec3(-0.20, 0.43, 0.05),
              Rotation = vec3(91.0, 0.0, -265.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_electricguitar"] = {
              Model = "prop_el_guitar_01",
              Bone = 18905,
              Offset = vec3(0.15, 0.0, 0.1),
              Rotation = vec3(-10.0, 15.0, 190.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_laptop"] = {
              Model = "prop_laptop_01a",
              Bone = 24817,
              Offset = vec3(0.10, 0.35, 0.0),
              Rotation = vec3(90.0, 0.0, -90.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
          ["x_boombox"] = {
              Model = "prop_boombox_01",
              Bone = 18905,
              Offset = vec3(0.27, 0.0, 0.2),
              Rotation = vec3(-80.0, 0.0, 0.0),
              Animation = {dict = "anim@heists@box_carry@", anim = "idle"}
          },
      },
  }

  VehicleClass = {
      COMPACTS = 0,
      SEDANS = 1,
      SUVS = 2,
      COUPES = 3,
      MUSCLE = 4,
      SPORTS_CLASSICS = 5,
      SPORTS = 6,
      SUPER = 7,
      MOTORCYCLES = 8,
      OFF_ROAD = 9,
      INDUSTRIAL = 10,
      UTILITY = 11,
      VANS = 12,
      CYCLES = 13,
      BOATS = 14,
      HELICOPTERS = 15,
      PLANES = 16,
      SERVICE = 17,
      EMERGENCY = 18,
      MILITARY = 19,
      COMMERCIAL = 20,
      TRAINS = 21,
      OPEN_WHEEL = 22,
  }

  Config.AllowedVehicleClasses = {
      [VehicleClass.COMPACTS]        = true,
      [VehicleClass.SEDANS]          = true,
      [VehicleClass.SUVS]            = true,
      [VehicleClass.COUPES]          = true,
      [VehicleClass.MUSCLE]          = true,
      [VehicleClass.SPORTS_CLASSICS] = true,
      [VehicleClass.SPORTS]          = true,
      [VehicleClass.SUPER]           = true,
      [VehicleClass.MOTORCYCLES]     = false,
      [VehicleClass.OFF_ROAD]        = true,
      [VehicleClass.INDUSTRIAL]      = true,
      [VehicleClass.UTILITY]         = true,
      [VehicleClass.VANS]            = true,
      [VehicleClass.CYCLES]          = false,
      [VehicleClass.BOATS]           = false,
      [VehicleClass.HELICOPTERS]     = false,
      [VehicleClass.PLANES]          = false,
      [VehicleClass.SERVICE]         = false,
      [VehicleClass.EMERGENCY]       = false,
      [VehicleClass.MILITARY]        = false,
      [VehicleClass.COMMERCIAL]      = false,
      [VehicleClass.TRAINS]          = false,
      [VehicleClass.OPEN_WHEEL]      = false,
  }
  ```
</Accordion>

***

## Tips for Adding Props

### Finding Prop Models

1. Use a prop spawner resource to test different models in-game
2. Check the [GTA V Props Database](https://forge.plebmasters.de/) for prop names
3. Look at existing house interiors to find suitable props
4. Test props in-game before adding to production

### Adjusting Attachment

1. Start with similar existing prop configurations as templates
2. Use small incremental changes (0.05-0.1) when adjusting offsets
3. Test both walking and running animations with the prop
4. Ensure props don't clip through walls or the player model
5. Check prop visibility from third-person camera angles

### Animation Selection

The `anim@heists@box_carry@` dictionary with `idle` animation works for most props, but consider alternatives:

* **Heavy items**: Use slower, more strained animations
* **Fragile items**: Use careful, steady animations
* **Long items**: Ensure animation supports the prop length
* **One-handed items**: Use animations with free hand movement

### Vehicle Storage Testing

1. Test with locked and unlocked vehicles if `UnlockedVehiclesOnly = true`
2. Verify trunk targeting works correctly with `TrunkTargetOnly = true`
3. Test with front-engine vehicles (some have front trunks)
4. Ensure props can be retrieved from trunks after storage
5. Check that disallowed vehicle classes properly reject storage

### Item Integration

1. Ensure item names match exactly between:
   * Carryable props configuration
   * Tier loot tables
   * Inventory items configuration
2. Add appropriate item images to your inventory
3. Set reasonable item weights for gameplay balance
4. Consider making carryable props non-stackable