Contracts System

What Are Contracts?

Contracts are optional side tasks that players can accept from NPCs located around the map. These contracts add variety to house robberies by giving players specific objectives like breaking objects, stealing items, or littering. Contracts spawn randomly inside houses and reward players upon completion.

Contracts are configured in config/contracts.lua and provide an additional layer of gameplay beyond standard house robberies.

Global Configuration

Basic Settings

boolean

required

Enable or disable the entire contracts system. When disabled, contract NPCs won’t spawn and contracts won’t appear in houses.

boolean

default:"false"

If true, reward amounts are hidden in the contract acceptance dialog. Players won’t see the exact payout until they complete the contract.

Required Items

Configure which items players need to complete different contract types:

string or boolean

default:"melee"

Item required to break objects. Use "melee" to allow any melee weapon, a specific item name, or false for no requirement.

string or boolean

default:"bag"

Item required to steal objects. Set to a specific item name or false for no requirement.

string or boolean

default:"false"

Item required for littering contracts. Set to a specific item name or false for no requirement.

string or boolean

default:"x_burner"

Item required to take pictures of completed contracts. Using "x_burner" is recommended for immersion with the messaging system.

Example:

["RequiredItems"] = {
    ["Break Objects"] = "melee",
    ["Steal Objects"] = "bag",
    ["Littering"] = false,
    ["TakingPictures"] = "x_burner"
}

Contract NPCs

NPCs are the characters players interact with to accept and turn in contracts. You can set up multiple npc coords which allows the npc to spawn randomly at one of the locations instead of always spawning in one spot.

NPC Configuration

string

required

The ped model to use for the contract NPC. Example: "g_m_y_korean_01"

vector4

required

Position and heading where the NPC spawns

string

Scenario animation for the NPC (standing, sitting, etc.). Example: "WORLD_HUMAN_STAND_IMPATIENT_UPRIGHT"Use this OR Animation, not both.

table

Custom animation for the NPC with Dict and Anim propertiesUse this OR Scenario, not both.

You can use either Scenario (simpler, just a scenario name) or Animation (more control with dict/anim), but not both at the same time.

Example with Scenario:

["Peds"] = {
    {
        ["PedModel"] = "g_m_y_korean_01",
        ["Coords"] = vector4(1023.52, -1870.82, 30.89, 359.91),
        ["Scenario"] = "WORLD_HUMAN_STAND_IMPATIENT_UPRIGHT"
    }
}

Example with Animation:

["Peds"] = {
    {
        ["PedModel"] = "g_m_y_korean_01",
        ["Coords"] = vector4(-22.72, -1250.14, 29.23, 359.6),
        ["Animation"] = {Dict = "anim@amb@casino@hangout@ped_male@stand@02b@idles", Anim = "idle_a"}
    }
}

Dialog Configuration

Customize the text that appears when players interact with contract NPCs.

Initial Dialog

string

required

The first message shown when approaching the NPC

string

required

Text for the accept button

string

required

Text for the decline button

Accepting Contracts

string

required

Message shown when viewing available contracts

string

required

Text for the accept contracts button

string

required

Text for the decline button

End Conversation

string

required

Final message after accepting contracts

string

required

Text for the goodbye button

Example:

["DialogTexts"] = {
    ["InitialDialog"] = {
        ["Content"] = "I have some contracts, would you like to take a look? I will give u a reward for each one you complete.",
        ["Confirm"] = "Sure",
        ["Cancel"] = "No, thanks, I'll think about it"
    },
    ["AcceptingContracts"] = {
        ["Content"] = "Here are the available contracts:",
        ["Confirm"] = "Accept Contracts",
        ["Cancel"] = "Maybe later"
    },
    ["EndConversation"] = {
        ["Content"] = "Bring back the items I asked for, or take a picture (Breaking or Littering) with your burner phone, then come back for your reward.",
        ["Confirm"] = "Will do, Goodbye"
    }
}

Contract Types

There are three types of contracts, each with unique mechanics and configuration options.

1. Steal Objects Contracts

Players must steal specific items from houses and return them to the NPC.

string

required

Contract title shown in the UI

string

required

Contract description shown in the UI

string

required

Font Awesome icon for the contract. Example: "fas fa-briefcase"

string

required

Prop model that spawns in the house

table

required

Animation configuration with Dict and Anim properties OR Scenario property (use one or the other)

number

required

Seconds before the animation stops

boolean

required

If true, player turns to face the prop before interacting

table

Optional prop attached to player during animation with Model, Bone, Offset, and Rotation

table

required

Reward configuration including Exp, Type (money/item), Item, Amount (min/max), and MetaData

Example:

["Steal Objects"] = {
    ["Briefcase"] = {
        ["Label"] = "Snatch the Briefcase",
        ["Description"] = "Sneak in and grab the briefcase",
        ["Icon"] = "fas fa-briefcase",
        ["Model"] = "prop_ld_case_01",
        ["Animation"] = {Dict = "random@domestic", Anim = "pickup_low"},
        ["DelayUntilCancelled"] = 1,
        ["TurnToFaceProp"] = false,
        ["AnimationProp"] = {
            ["Model"] = "prop_ld_case_01",
            ["Bone"] = 57005,
            ["Offset"] = vector3(0.1, 0.0, -0.03),
            ["Rotation"] = vector3(-90.0, 0.0, 0.0)
        },
        ["Reward"] = {
            ["Exp"] = 20,
            ["Type"] = "money",
            ["Item"] = "",
            ["Amount"] = {min = 275, max = 300},
            ["MetaData"] = false
        }
    }
}

Example with Scenario instead of Animation:

["Steal Objects"] = {
    ["Documents"] = {
        ["Label"] = "Grab the Documents",
        ["Description"] = "Pick up the important papers",
        ["Icon"] = "fas fa-file",
        ["Model"] = "prop_paper_bag_small",
        ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
        ["DelayUntilCancelled"] = 2,
        ["TurnToFaceProp"] = false,
        ["Reward"] = {
            ["Exp"] = 15,
            ["Type"] = "money",
            ["Item"] = "",
            ["Amount"] = {min = 200, max = 250},
            ["MetaData"] = false
        }
    }
}

2. Break Objects Contracts

Players must break specific objects and take a picture as proof.

string

required

Prop model for the intact object

string

required

Prop model that replaces the intact object after breaking

string

required

Sound effect when breaking: "glass", "electronics", "thud", or false for no sound

table

required

Animation configuration for breaking the object including Animation (with Dict and Anim) OR Scenario, DelayUntilCancelled, TurnToFaceProp, and optional AnimationProp

table

required

Animation configuration for taking the picture including Animation (with Dict and Anim) OR Scenario, DelayUntilCancelled, TurnToFaceProp, and optional AnimationProp

Example:

["Break Objects"] = {
    ["Laptop"] = {
        ["Label"] = "Smash the Laptop's Screen",
        ["Description"] = "Teach this overpriced laptop a lesson.",
        ["Icon"] = "fas fa-laptop",
        ["Model"] = "prop_laptop_lester",
        ["BrokenModel"] = "gr_prop_gr_laptop_01c",
        ["Sound"] = "electronics",
        ["Animation"] = {
            ["Breaking"] = {
                ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                ["DelayUntilCancelled"] = 1,
                ["TurnToFaceProp"] = false
            },
            ["TakingPicture"] = {
                ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                ["DelayUntilCancelled"] = 4,
                ["TurnToFaceProp"] = false
            }
        },
        ["Reward"] = {
            ["Exp"] = 20,
            ["Type"] = "money",
            ["Item"] = "",
            ["Amount"] = {min = 275, max = 300},
            ["MetaData"] = false
        }
    }
}

3. Littering Contracts

Players must pick up an object, scatter litter, and take a picture as proof.

string

required

Prop model for the initial item to pick up

string

required

Prop model that spawns as scattered litter

string

Sound effect when littering: "poop", "spill", "trash", or false for no sound

table

required

Animation for picking up the initial object (can use Animation with Dict/Anim OR Scenario)

table

required

Animation for scattering the litter (can use Animation with Dict/Anim OR Scenario)

table

required

Animation for taking the picture proof (can use Animation with Dict/Anim OR Scenario)

Example:

["Littering"] = {
    ["Cans"] = {
        ["Label"] = "Scatter cans",
        ["Description"] = "Scatter cans around like you own the place.",
        ["Icon"] = "fas fa-trash-can",
        ["Model"] = "v_ret_247_popcan2",
        ["LitteredModel"] = "prop_rub_litter_01",
        ["Sound"] = "trash",
        ["Animation"] = {
            ["Pickup"] = {
                ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                ["DelayUntilCancelled"] = 1,
                ["TurnToFaceProp"] = false
            },
            ["Litter"] = {
                ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                ["DelayUntilCancelled"] = 3,
                ["TurnToFaceProp"] = false
            },
            ["TakingPicture"] = {
                ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                ["DelayUntilCancelled"] = 4,
                ["TurnToFaceProp"] = false
            }
        },
        ["Reward"] = {
            ["Exp"] = 15,
            ["Type"] = "money",
            ["Item"] = "",
            ["Amount"] = {min = 200, max = 250},
            ["MetaData"] = false
        }
    }
}

Players must also take pictures of specific objects or situations. This is tied to Breaking and Littering contracts as proof of completion.

Reward Configuration

All contracts share the same reward structure:

number

required

Experience points awarded upon completion (if using an XP system)

string

required

Type of reward: "money" for direct cash or "item" for inventory items

string

Item name if Type = "item". Leave empty if Type = "money"

table

required

Reward amount with min and max values for randomization

boolean

required

If true, adds metadata to the reward item (used for marked money or item info)

Money Reward Example:

["Reward"] = {
    ["Exp"] = 20,
    ["Type"] = "money",
    ["Item"] = "",
    ["Amount"] = {min = 275, max = 300},
    ["MetaData"] = false
}

Item Reward Example:

["Reward"] = {
    ["Exp"] = 15,
    ["Type"] = "item",
    ["Item"] = "markedbills",
    ["Amount"] = {min = 1, max = 3},
    ["MetaData"] = true
}

Animation Props

Animation props are optional attachments that appear on the player during animations, making interactions more immersive.

string

required

Prop model to attach to the player

number

required

Bone ID where the prop attaches. Common bones:

57005 - Head
18905 - Left hand
60309 - Right hand
24817 - Weapon slot

vector3

required

Position offset from the bone attachment point

vector3

required

Rotation angles for the prop in degrees

Example:

["AnimationProp"] = {
    ["Model"] = "prop_ld_case_01",
    ["Bone"] = 57005,
    ["Offset"] = vector3(0.1, 0.0, -0.03),
    ["Rotation"] = vector3(-90.0, 0.0, 0.0)
}

Remove the entire AnimationProp table if you don’t want a prop to appear during the animation.

Adding Contracts to Presets

Contracts are linked to house presets. In your preset configuration, specify which contracts can spawn:

["Contracts"] = {
    ["ChanceOfSpawning"] = 100,
    ["PossibleContracts"] = {
        ["1"] = {
            ["Contract"] = "Briefcase",
            ["Type"] = "Steal Objects",
            ["PickupCoords"] = vector3(-764.00, 321.12, 199.17),
            ["PickupRotation"] = vector3(0.0, 0.0, 343.53)
        },
        ["2"] = {
            ["Contract"] = "Laptop",
            ["Type"] = "Break Objects",
            ["PickupCoords"] = vector3(-772.97, 328.25, 195.91),
            ["PickupRotation"] = vector3(0.0, 0.0, 227.85)
        },
        ["3"] = {
            ["Contract"] = "Cans",
            ["Type"] = "Littering",
            ["PickupCoords"] = vector3(-764.00, 321.12, 199.17),
            ["PickupRotation"] = vector3(0.0, 0.0, 343.53),
            ["LitteredCoords"] = vector3(-764.00, 321.12, 199.17),
            ["LitteredRotation"] = vector3(0.0, 0.0, 343.53)
        }
    }
}

See the Presets Guide for detailed preset configuration.

Complete Configuration Example

View Complete Contracts Configuration

Config.Contracts = {
    ["Enable"] = true,
    ["HideRewardsOnDialogs"] = false,
    
    ["RequiredItems"] = {
        ["Break Objects"] = "melee",
        ["Steal Objects"] = "bag",
        ["Littering"] = false,
        ["TakingPictures"] = "x_burner"
    },
    
    ["Peds"] = {
        {
            ["PedModel"] = "g_m_y_korean_01",
            ["Coords"] = vector4(1023.52, -1870.82, 30.89, 359.91),
            ["Scenario"] = "WORLD_HUMAN_STAND_IMPATIENT_UPRIGHT"
        }
    },
    
    ["DialogTexts"] = {
        ["InitialDialog"] = {
            ["Content"] = "I have some contracts, would you like to take a look? I will give u a reward for each one you complete.",
            ["Confirm"] = "Sure",
            ["Cancel"] = "No, thanks, I'll think about it"
        },
        ["AcceptingContracts"] = {
            ["Content"] = "Here are the available contracts:",
            ["Confirm"] = "Accept Contracts",
            ["Cancel"] = "Maybe later"
        },
        ["EndConversation"] = {
            ["Content"] = "Bring back the items I asked for, or take a picture (Breaking or Littering) with your burner phone, then come back for your reward.",
            ["Confirm"] = "Will do, Goodbye"
        }
    },
    
    ["PossibleContracts"] = {
        ["Steal Objects"] = {
            ["Briefcase"] = {
                ["Label"] = "Snatch the Briefcase",
                ["Description"] = "Sneak in and grab the briefcase",
                ["Icon"] = "fas fa-briefcase",
                ["Model"] = "prop_ld_case_01",
                ["Animation"] = {Dict = "random@domestic", Anim = "pickup_low"},
                ["DelayUntilCancelled"] = 1,
                ["TurnToFaceProp"] = false,
                ["AnimationProp"] = {
                    ["Model"] = "prop_ld_case_01",
                    ["Bone"] = 57005,
                    ["Offset"] = vector3(0.1, 0.0, -0.03),
                    ["Rotation"] = vector3(-90.0, 0.0, 0.0)
                },
                ["Reward"] = {
                    ["Exp"] = 20,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 275, max = 300},
                    ["MetaData"] = false
                }
            },
            ["Harddrive"] = {
                ["Label"] = "Retrieve the Harddrive",
                ["Description"] = "Steal the owner's harddrive",
                ["Icon"] = "fas fa-hard-drive",
                ["Model"] = "v_res_harddrive",
                ["Animation"] = {Dict = "anim@heists@ornate_bank@hack", Anim = "hack_loop"},
                ["DelayUntilCancelled"] = 1,
                ["TurnToFaceProp"] = false,
                ["AnimationProp"] = {
                    ["Model"] = "v_res_harddrive",
                    ["Bone"] = 57005,
                    ["Offset"] = vector3(0.1, 0.0, -0.03),
                    ["Rotation"] = vector3(-90.0, 0.0, 0.0)
                },
                ["Reward"] = {
                    ["Exp"] = 20,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 275, max = 300},
                    ["MetaData"] = false
                }
            }
        },
        ["Break Objects"] = {
            ["Laptop"] = {
                ["Label"] = "Smash the Laptop's Screen",
                ["Description"] = "Teach this overpriced laptop a lesson.",
                ["Icon"] = "fas fa-laptop",
                ["Model"] = "prop_laptop_lester",
                ["BrokenModel"] = "gr_prop_gr_laptop_01c",
                ["Sound"] = "electronics",
                ["Animation"] = {
                    ["Breaking"] = {
                        ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                        ["DelayUntilCancelled"] = 1,
                        ["TurnToFaceProp"] = false
                    },
                    ["TakingPicture"] = {
                        ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                        ["DelayUntilCancelled"] = 4,
                        ["TurnToFaceProp"] = false
                    }
                },
                ["Reward"] = {
                    ["Exp"] = 20,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 275, max = 300},
                    ["MetaData"] = false
                }
            },
            ["Phone"] = {
                ["Label"] = "Smash their Phone",
                ["Description"] = "Disconnect them from brainrot",
                ["Icon"] = "fas fa-phone-flip",
                ["Model"] = "prop_npc_phone",
                ["BrokenModel"] = "sf_prop_sf_art_phone_01a",
                ["Sound"] = "electronics",
                ["Animation"] = {
                    ["Breaking"] = {
                        ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                        ["DelayUntilCancelled"] = 1,
                        ["TurnToFaceProp"] = false
                    },
                    ["TakingPicture"] = {
                        ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                        ["DelayUntilCancelled"] = 4,
                        ["TurnToFaceProp"] = false
                    }
                },
                ["Reward"] = {
                    ["Exp"] = 20,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 275, max = 300},
                    ["MetaData"] = false
                }
            }
        },
        ["Littering"] = {
            ["Cans"] = {
                ["Label"] = "Scatter cans",
                ["Description"] = "Scatter cans around like you own the place.",
                ["Icon"] = "fas fa-trash-can",
                ["Model"] = "v_ret_247_popcan2",
                ["LitteredModel"] = "prop_rub_litter_01",
                ["Sound"] = "trash",
                ["Animation"] = {
                    ["Pickup"] = {
                        ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                        ["DelayUntilCancelled"] = 1,
                        ["TurnToFaceProp"] = false
                    },
                    ["Litter"] = {
                        ["Animation"] = {Dict = "anim@melee@machete@streamed_core@", Anim = "plyr_walking_attack_a"},
                        ["DelayUntilCancelled"] = 3,
                        ["TurnToFaceProp"] = false
                    },
                    ["TakingPicture"] = {
                        ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                        ["DelayUntilCancelled"] = 4,
                        ["TurnToFaceProp"] = false
                    }
                },
                ["Reward"] = {
                    ["Exp"] = 15,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 200, max = 250},
                    ["MetaData"] = false
                }
            },
            ["Stain"] = {
                ["Label"] = "Stain the floor",
                ["Description"] = "Paint the Floor with some spilled drink",
                ["Icon"] = "fas fa-wine-bottle",
                ["Model"] = "p_whiskey_bottle_s",
                ["LitteredModel"] = "p_oil_slick_01",
                ["Sound"] = "spill",
                ["Animation"] = {
                    ["Pickup"] = {
                        ["Animation"] = {Dict = "mp_common", Anim = "givetake1_b"},
                        ["DelayUntilCancelled"] = 1,
                        ["TurnToFaceProp"] = false,
                        ["AnimationProp"] = {
                            ["Model"] = "p_whiskey_bottle_s",
                            ["Bone"] = 57005,
                            ["Offset"] = vector3(0.1, 0.0, -0.03),
                            ["Rotation"] = vector3(-90.0, 0.0, 0.0)
                        }
                    },
                    ["Litter"] = {
                        ["Animation"] = {Dict = "anim@amb@clubhouse@tutorial@bkr_tut_ig3@", Anim = "machinic_loop_mechandplayer"},
                        ["DelayUntilCancelled"] = 1,
                        ["TurnToFaceProp"] = false,
                        ["AnimationProp"] = {
                            ["Model"] = "p_whiskey_bottle_s",
                            ["Bone"] = 57005,
                            ["Offset"] = vector3(0.15, 0.1, 0.0),
                            ["Rotation"] = vector3(60.0, 25.0, 180.0)
                        }
                    },
                    ["TakingPicture"] = {
                        ["Scenario"] = "WORLD_HUMAN_STAND_MOBILE",
                        ["DelayUntilCancelled"] = 4,
                        ["TurnToFaceProp"] = false
                    }
                },
                ["Reward"] = {
                    ["Exp"] = 15,
                    ["Type"] = "money",
                    ["Item"] = "",
                    ["Amount"] = {min = 200, max = 250},
                    ["MetaData"] = false
                }
            }
        }
    }
}

Tips for Creating Contracts

Balance Rewards

Steal Objects: Higher rewards as they require carrying items out
Break Objects: Medium-high rewards requiring breaking and photo proof
Littering: Lower rewards as they’re simpler tasks
Scale rewards based on contract difficulty and time investment

Choose Appropriate Props

Check the GTA V Props Database for prop names
Use recognizable models that fit the contract theme
Ensure broken models clearly show damage
Consider prop size for littering contracts (smaller = more realistic)

Animation Selection

Match animations to the action (punching for breaking, bending for picking up)
Keep DelayUntilCancelled values reasonable (1-4 seconds)
Use scenarios for simple standing animations
Test animations with different character models

Using Scenarios Instead: For simpler interactions, you can use scenarios instead of animations:

"WORLD_HUMAN_STAND_MOBILE" - Standing with phone
"WORLD_HUMAN_BINOCULARS" - Looking through binoculars
"WORLD_HUMAN_GUARD_STAND" - Standing guard
"WORLD_HUMAN_CLIPBOARD" - Writing on clipboard

Replace ["Animation"] = {Dict = "...", Anim = "..."} with ["Scenario"] = "SCENARIO_NAME"

Sound Effects

Glass: Picture frames, windows, glass items
Electronics: Phones, laptops, tablets, TVs
Thud: Heavy objects, furniture
Trash: Cans, garbage, paper
Spill: Liquids, drinks
Poop: Organic materials (use sparingly)

Required Items

Set "melee" for break contracts to encourage weapon use
Require a bag for steal contracts to create more immersion
Use "x_burner" for pictures to integrate with burner phone system
Set to false if you want contracts accessible to everyone

Dialog Text

Keep initial dialog friendly and inviting
Make confirmation buttons clear (“Accept” vs “Decline”)
Provide instructions in the end conversation
Consider your server’s roleplay style and lore

Getting Started

Project X Bridge

Paid Resources

Free Resources

What Are Contracts?

Global Configuration

Basic Settings

Required Items

Contract NPCs

NPC Configuration

Dialog Configuration

Initial Dialog

Accepting Contracts

End Conversation

Contract Types

1. Steal Objects Contracts

2. Break Objects Contracts

3. Littering Contracts

Reward Configuration

Animation Props

Adding Contracts to Presets

Complete Configuration Example

Tips for Creating Contracts

Balance Rewards

Choose Appropriate Props

Animation Selection

Sound Effects

Required Items

Dialog Text

​What Are Contracts?

​Global Configuration

​Basic Settings

​Required Items

​Contract NPCs

​NPC Configuration

​Dialog Configuration

​Initial Dialog

​Accepting Contracts

​End Conversation

​Contract Types

​1. Steal Objects Contracts

​2. Break Objects Contracts

​3. Littering Contracts

​Reward Configuration

​Animation Props

​Adding Contracts to Presets

​Complete Configuration Example

​Tips for Creating Contracts

​Balance Rewards

​Choose Appropriate Props

​Animation Selection

​Sound Effects

​Required Items

​Dialog Text

What Are Contracts?

Global Configuration

Basic Settings

Required Items

Contract NPCs

NPC Configuration

Dialog Configuration

Initial Dialog

Accepting Contracts

End Conversation

Contract Types

1. Steal Objects Contracts

2. Break Objects Contracts

3. Littering Contracts

Reward Configuration

Animation Props

Adding Contracts to Presets

Complete Configuration Example

Tips for Creating Contracts

Balance Rewards

Choose Appropriate Props

Animation Selection

Sound Effects

Required Items

Dialog Text