Skip to content
Contractsv1.18.2

Rewards

A reward is what a contract pays out on completion. A contract needs at least one. The type field selects which reward it is and which fields it carries. Each per-type page in this section lists its complete field set, shared and type-specific alike.

Every reward shares title, description, an eligiblePermissions list that gates who can receive it, and a hidden flag that keeps it out of the menu.

Completing a contract puts its rewards in the player’s Contracts inventory. They are granted when the player claims them, from the contract’s Claim button or from the Contracts inventory. Nothing is granted automatically.

Set hidden to true to keep a reward out of the menu. Players don’t see it on the contract card, in the contract’s reward list or on the objective, but it still goes in the Contracts inventory and pays out when they claim. It also still counts for claiming: a contract, objective or prestige tier whose rewards are all hidden still shows its Claim button, just with no rewards listed, and its line in the Contracts inventory shows no reward icons.

This is handy for a side effect that isn’t really a reward, like adding the player to a chat group, next to the rewards you do want players to see:

"rewards": {
"scrap": {
"type": "Item",
"title": "",
"description": "",
"eligiblePermissions": [],
"hidden": false,
"item": "scrap",
"quantity": 250,
"skinId": null,
"itemName": null,
"itemNameTranslations": null
},
"hunter_chat_group": {
"type": "Command",
"title": "",
"description": "",
"eligiblePermissions": [],
"hidden": true,
"commands": ["oxide.usergroup add {playerId} hunters"],
"reverseCommands": ["oxide.usergroup remove {playerId} hunters"],
"icon": null,
"iconColor": null,
"iconRaw": false
}
}

During the reward distribution process, if an error occurs, the plugin will attempt to revert any rewards that were succesfully granted before the error.

If the plugin is able to revert all granted rewards, the player will be notified and the bundle stays in the Contracts inventory so they can claim again later. A full Rust inventory is handled the same way: everything is taken back and the bundle stays.

However, if the plugin is unable to revert any granted rewards or has granted unrevertible rewards (i.e. a Command reward), the player will be notified, but the bundle is removed and counts as claimed, and the rest of that bundle is lost. In this case, the player should contact an admin for assistance.

Command rewards and Custom rewards using a Command definition run console commands, and a fired command cannot be taken back on its own. Both can declare reverse commands that tell the plugin how to undo the commands, which makes them revertible like any other reward. Without one they stay unrevertible: once granted, if an error occurs later during the reward distribution process, the plugin will not attempt to revert rewards and the contract will be marked as claimed. A Custom reward using an Item definition gives items, so it is taken back like an Item reward. For this reason, the plugin grants natively revertible rewards first, then command-based rewards with reverse commands, and unrevertible ones last.

Not the rewards you’re looking for? Need something custom?

Section titled “Not the rewards you’re looking for? Need something custom?”

If the rewards below don’t fit your needs, think again! Most people overlook the the Command Reward type! If you need to reward your players with a feature backed by another plugin, that plugin most likely has a command that you would usually run yourself to give your players that feature (XP, battlepass points, leaderboard score, etc.). The Command Reward allows you to run that command for your players automatically when they complete a contract. You can even use placeholders in the command to customize it for each player!

When the same command shows up on many contracts, name it once as a custom reward definition and reference it with a Custom Reward. You write the command in one place, and every contract that references it stays in sync. The same goes for an item you pay on many contracts, like a server currency.