Skip to main content

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

Enable
boolean
required
Enable or disable the entire contracts system. When disabled, contract NPCs won’t spawn and contracts won’t appear in houses.
HideRewardsOnDialogs
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:
RequiredItems['Break Objects']
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.
RequiredItems['Steal Objects']
string or boolean
default:"bag"
Item required to steal objects. Set to a specific item name or false for no requirement.
RequiredItems['Littering']
string or boolean
default:"false"
Item required for littering contracts. Set to a specific item name or false for no requirement.
RequiredItems['TakingPictures']
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

Peds[n].PedModel
string
required
The ped model to use for the contract NPC. Example: "g_m_y_korean_01"
Peds[n].Coords
vector4
required
Position and heading where the NPC spawns
Peds[n].Scenario
string
Scenario animation for the NPC (standing, sitting, etc.). Example: "WORLD_HUMAN_STAND_IMPATIENT_UPRIGHT"Use this OR Animation, not both.
Peds[n].Animation
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

DialogTexts.InitialDialog.Content
string
required
The first message shown when approaching the NPC
DialogTexts.InitialDialog.Confirm
string
required
Text for the accept button
DialogTexts.InitialDialog.Cancel
string
required
Text for the decline button

Accepting Contracts

DialogTexts.AcceptingContracts.Content
string
required
Message shown when viewing available contracts
DialogTexts.AcceptingContracts.Confirm
string
required
Text for the accept contracts button
DialogTexts.AcceptingContracts.Cancel
string
required
Text for the decline button

End Conversation

DialogTexts.EndConversation.Content
string
required
Final message after accepting contracts
DialogTexts.EndConversation.Confirm
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.
Label
string
required
Contract title shown in the UI
Description
string
required
Contract description shown in the UI
Icon
string
required
Font Awesome icon for the contract. Example: "fas fa-briefcase"
Model
string
required
Prop model that spawns in the house
Animation
table
required
Animation configuration with Dict and Anim properties OR Scenario property (use one or the other)
DelayUntilCancelled
number
required
Seconds before the animation stops
TurnToFaceProp
boolean
required
If true, player turns to face the prop before interacting
AnimationProp
table
Optional prop attached to player during animation with Model, Bone, Offset, and Rotation
Reward
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.
Model
string
required
Prop model for the intact object
BrokenModel
string
required
Prop model that replaces the intact object after breaking
Sound
string
required
Sound effect when breaking: "glass", "electronics", "thud", or false for no sound
Animation.Breaking
table
required
Animation configuration for breaking the object including Animation (with Dict and Anim) OR Scenario, DelayUntilCancelled, TurnToFaceProp, and optional AnimationProp
Animation.TakingPicture
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.
Model
string
required
Prop model for the initial item to pick up
LitteredModel
string
required
Prop model that spawns as scattered litter
Sound
string
Sound effect when littering: "poop", "spill", "trash", or false for no sound
Animation.Pickup
table
required
Animation for picking up the initial object (can use Animation with Dict/Anim OR Scenario)
Animation.Litter
table
required
Animation for scattering the litter (can use Animation with Dict/Anim OR Scenario)
Animation.TakingPicture
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:
Reward.Exp
number
required
Experience points awarded upon completion (if using an XP system)
Reward.Type
string
required
Type of reward: "money" for direct cash or "item" for inventory items
Reward.Item
string
Item name if Type = "item". Leave empty if Type = "money"
Reward.Amount
table
required
Reward amount with min and max values for randomization
Reward.MetaData
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.
AnimationProp.Model
string
required
Prop model to attach to the player
AnimationProp.Bone
number
required
Bone ID where the prop attaches. Common bones:
  • 57005 - Head
  • 18905 - Left hand
  • 60309 - Right hand
  • 24817 - Weapon slot
AnimationProp.Offset
vector3
required
Position offset from the bone attachment point
AnimationProp.Rotation
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

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