Carryable Props

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:

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

Global Settings

Enable

boolean

default:"true"

Enable or disable the entire carryable props system. When disabled, players cannot carry or store props in vehicles.

TrunkTargetOnly

boolean

default:"true"

When true, players must target the trunk specifically to store props. When false, targeting anywhere on the vehicle works.

Setting to false is recommended for vehicles without traditional trunks (motorcycles, front-engine vehicles).

UnlockedVehiclesOnly

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.

Adding New Props

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

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

item_name_here

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.

Model

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

Bone

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

Offset

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.

Rotation

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)

Animation

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

Vehicle Class Configuration

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

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

Do not modify the VehicleClass table at the top of the config. This is a reference table used by the script.

Complete Examples

Example 1: Coffee Maker

["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

["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

["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

["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

Complete Carryable Props Configuration

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,
}

Tips for Adding Props

Finding Prop Models

Use a prop spawner resource to test different models in-game
Check the GTA V Props Database for prop names
Look at existing house interiors to find suitable props
Test props in-game before adding to production

Adjusting Attachment

Start with similar existing prop configurations as templates
Use small incremental changes (0.05-0.1) when adjusting offsets
Test both walking and running animations with the prop
Ensure props don’t clip through walls or the player model
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

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

Item Integration

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

Getting Started

Resources

Carryable Props System

Configuration Structure

Global Settings

Adding New Props

Prop Configuration Parameters

Vehicle Class Configuration

Available Vehicle Classes

Complete Examples

Example 1: Coffee Maker

Example 2: Television

Example 3: Electric Guitar

Example 4: Laptop

Full Configuration Example

Tips for Adding Props

Finding Prop Models

Adjusting Attachment

Animation Selection

Vehicle Storage Testing

Item Integration

Getting Started

Resources

​Carryable Props System

​Configuration Structure

​Global Settings

​Adding New Props

​Prop Configuration Parameters

​Vehicle Class Configuration

​Available Vehicle Classes

​Complete Examples

​Example 1: Coffee Maker

​Example 2: Television

​Example 3: Electric Guitar

​Example 4: Laptop

​Full Configuration Example

​Tips for Adding Props

​Finding Prop Models

​Adjusting Attachment

​Animation Selection

​Vehicle Storage Testing

​Item Integration

Carryable Props System

Configuration Structure

Global Settings

Adding New Props

Prop Configuration Parameters

Vehicle Class Configuration

Available Vehicle Classes

Complete Examples

Example 1: Coffee Maker

Example 2: Television

Example 3: Electric Guitar

Example 4: Laptop

Full Configuration Example

Tips for Adding Props

Finding Prop Models

Adjusting Attachment

Animation Selection

Vehicle Storage Testing

Item Integration