Create your first contract

It’s strongly recommended to use the web editor to manage your contracts, but if you want to write one by hand, this page shows you how. Keep in mind that data files are not meant to be edited by hand, so the shape and complexity of these JSON files were not designed to be user-friendly to edit like the config file.

A contract is a small bundle: one or more objectives to complete and one or more rewards to pay out. Contracts are stored in the contracts_data.json data file and surfaced to players by being listed in a category (contract_category_data.json).

Anatomy of a contract

Every contract has:

• title: the name players see. Required, non-empty.
• description: a short blurb. May be empty if the title says it all.
• objectives: a map of one or more objectives. At least one is required.
• rewards: a map of one or more rewards. At least one is required.
• progressionType: how the objectives unlock:
  • Independent: all objectives are active at once (the default).
  • Sequential: objectives must be completed in order; only the first incomplete one is active.
  • Progressive: like Sequential, but locked objectives are hidden in the menu.

Objectives and rewards are stored as keyed maps, not arrays. Each key is a unique id you choose; the key order is the display order.

A minimal example

This contract has a single objective: to kill five chickens. It then rewards the player with some cooked chicken, a bit of Economics cash, and some RP:

{
  "contracts": {
    "chicken_dinner": {
      "title": "Chicken Dinner",
      "description": "Hunt down chickens for an easy meal.",
      "progressionType": "Independent",
      "objectives": {
        "chicken_dinner_kill_chickens": {
          "type": "Kill",
          "title": "Kill chickens",
          "description": "Find and kill chickens around the island.",
          "conditions": {},
          "amountRequired": 5,
          "entities": ["chicken"]
        }
      },
      "rewards": {
        "chicken_dinner_reward_chicken": {
          "type": "Item",
          "title": "",
          "description": "",
          "eligiblePermissions": [],
          "item": "chicken.cooked",
          "quantity": 5
        },
        "chicken_dinner_reward_economics": {
          "type": "Economics",
          "title": "",
          "description": "",
          "eligiblePermissions": [],
          "amount": 25
        },
        "chicken_dinner_reward_server_rewards": {
          "type": "ServerRewards",
          "title": "",
          "description": "",
          "eligiblePermissions": [],
          "amount": 1
        }
      }
    }
  },
  "version": {
    "Major": 0,
    "Minor": 0,
    "Patch": 0
  }
}

A few things to note from the example:

• type selects which objective or reward this is, and which extra fields it needs.
• amountRequired is how many times the objective must be met; here, five kills.
• entities and item use Rust shortnames (chicken, chicken.cooked), not display names.
• Leaving a reward title empty uses that reward type’s default name.
• conditions is empty here; see Conditions to restrict when progress counts (e.g. only at night, only with a bow).

Make it appear in the menu

A contract isn’t shown until a category lists it. Add its id to a category’s contractIds in the categories file:

{
  "categories": {
    "hourly": {
      "contractIds": ["chicken_dinner", "..."]
    }
  }
}

Then reload the plugin or re-import your files. The contract joins that category’s rotation pool and will be a candidate to show up in the menu when that category rotates.

Oxide

o.reload Contracts

Carbon

c.reload Contracts

Adding a contract to an active rotation

The plugin isn’t designed to have it’s rotation pool modified on the fly and I highly recommend against it for your players’ experience. I recommend you either wait out the rotation or worst case, rotate the category with contracts.rotate_category <categoryId> (which will cause all players to lose progress on any in-progress contracts in that category, so heads up!).

If you want to add contracts to an active rotation without rotating the category, you can edit the active rotation file directly. Keep in mind, this file is a state file! state files are not meant to be edited at all and are only meant to be edited by the plugin itself:

1. Unload the plugin (important! Otherwise the following changes will be overwritten when the plugin unloads)
2. Add the new contract ID to the active rotation of your category in the contract_category_state_data.json file.
3. Reload the plugin.