Categories

A category is a named group of contracts that rotates on its own timer. A contract is never shown to players on its own: it appears only when a category lists it and that category’s rotation picks it. Categories are how you pace content (hourly, daily, weekly, whole-wipe) and decide how many contracts a player can juggle at once.

Categories are stored in the contract_category_data.json data file and authored with the web editor.

Category themes

While default categories that ship with the plugin are pace-themed (hourly, daily, weekly, wipe), you can create your own custom categories to suit your server’s needs. For example, you could create 4 activity-themed categories that rotate every 6 hours: a PvP category, a gathering category, a crafting category, and a general category.

Fields

Field	Type	Description
name	string (non-empty)	The category name players see, e.g. “Daily Contracts”.
description	string	A short blurb for the category. May be empty.
contractIds	string[]	The ids of contracts in this category’s pool. Each rotation draws from this list.
rotation	object	The rotation timer and how many contracts go active each cycle (see below).
maxActiveContracts	map (permission → number)	Per-permission cap on how many of this category’s contracts a player can hold at once (see below).

Rotation

The rotation block decides when the category re-rolls and how many contracts it surfaces:

Field	Type	Default	Description
duration	number (-1 or > 0)	86400	How long a rotation lasts, in seconds. 86400 is one day. Set to -1 (or 0) for no rotation: the contracts stay active for the whole wipe.
minContractsAmount	integer (≥ 1)	3	Fewest contracts to activate each rotation.
maxContractsAmount	integer (≥ 1)	3	Most contracts to activate each rotation. Must be ≥ minContractsAmount.

Each rotation picks a random number of contracts between minContractsAmount and maxContractsAmount (inclusive), shuffles the pool, and activates that many. If the pool holds fewer contracts than the chosen number, every contract in the pool goes active. Set min equal to max for a fixed count every time.

Endless categories

A category with duration of -1 never rotates: its contracts are active for the entire wipe. This is how the default Wipe Contracts category works.

Dormant categories

A category with no active rotation and no contracts in its pool (or only ids that don’t match any contract) becomes dormant: it doesn’t start a new rotation and logs a console warning instead. It stays visible in the menu with no active contracts, and starts a rotation automatically the next time the plugin loads with a contract in its list. This avoids confusion when you add a category with no contracts, realize it, fix it by adding at least one contract to it and then wonder why it still doesn’t have any active contracts (because a rotation had started with no contracts).

Per-player cap

⭐ Premium

maxActiveContracts limits how many of this category’s contracts a single player can have active at the same time, keyed by permission. On the lite edition this cap is not enforced: every player is uncapped at the category level (the global cap still binds). Each key is a permission name (for example contracts.vip) and each value is the cap for players who hold it:

• A player gets the highest cap among the permissions they hold.
• A value of -1 means unlimited.
• If the map is empty, or a player holds none of the listed permissions, they are uncapped for this category.

{
  "categories": {
    "daily": {
      "name": "Daily Contracts",
      "description": "Achievable mid-effort contracts.",
      "contractIds": [
        "hunt_bears",
        "craft_ammo",
        "loot_crates"
      ],
      "rotation": {
        "duration": 86400,
        "minContractsAmount": 3,
        "maxContractsAmount": 5
      },
      "maxActiveContracts": {
        "contracts.use": 2,
        "contracts.vip": 5
      }
    }
  },
  "version": {
    "Major": 1,
    "Minor": 7,
    "Patch": 0
  }
}

This category rotates daily, surfaces three to five of its contracts each day, lets ordinary players hold two at once, and VIPs five.