Custom Rewards

A custom reward definition is a named console command you write once and reuse everywhere. Many plugins (Skill Tree, Heli Signals, XPerience) are rewarded by running a console command. Instead of retyping that command on every contract, define it once here, then add a Custom reward that references it by key with an amount.

The biggest advantage is reusable editing: fix the command in the definition and every contract that references it is fixed too, including contracts you exported months ago. The plugin looks up the definition when the reward is claimed, not when the contract is authored.

Custom reward definitions are stored in the custom_reward_data.json data file and authored with the web editor.

Shape

A definition has a display name, the command to run, an optional reverse command and unit label, and an optional icon, stored under a key you choose.

{
  "customRewards": {
    "SkillTreeXp": {
      "displayName": "Skill Tree XP",
      "displayNameTranslations": null,
      "command": "givexp {playerId} {amount} false",
      "reverseCommand": "givexp {playerId} -{amount} false",
      "unitLabel": "XP",
      "unitLabelTranslations": null,
      "icon": null,
      "iconColor": null,
      "iconRaw": false
    },
    "EasyHeliSignal": {
      "displayName": "Easy Heli Signal",
      "displayNameTranslations": null,
      "command": "hsgive easy {playerId} {amount}",
      "reverseCommand": null,
      "unitLabel": null,
      "unitLabelTranslations": null,
      "icon": null,
      "iconColor": null,
      "iconRaw": false
    },
    "Weed": {
      "displayName": "Weed",
      "displayNameTranslations": null,
      "command": "ganja.give weed low_quality {amount} {playerId}",
      "reverseCommand": null,
      "unitLabel": null,
      "unitLabelTranslations": null,
      "icon": null,
      "iconColor": null,
      "iconRaw": false
    }
  },
  "version": {
    "Major": 1,
    "Minor": 11,
    "Patch": 0
  }
}

The key (SkillTreeXp) is the identifier that Custom rewards reference. displayName is the text players see when a reward using the definition sets no title of its own, and displayNameTranslations holds optional per-language overrides for it (see Translating your content).

Fields

Field	Type	Description
`displayName`	string	Label shown on the reward when a usage sets no title. The record key stays the identifier Custom rewards reference.
`displayNameTranslations`	map \| null	Per-language overrides for displayName, mapping a language code (like "fr" or "zh-CN") to the translated text. Players whose language has no entry (matched case-insensitively, no region fallback) or a blank one see displayName instead. null when there are none.
`command`	string	The console command to run when the reward is claimed. Supports runtime placeholders such as {playerId} and {playerName}. Include {amount} to make every usage carry an amount that substitutes into it.
`reverseCommand`	string \| null	Console command that takes back what the main command gave, with the same placeholders. Runs only when claiming fails halfway and the rewards already given roll back. Null when the reward cannot be taken back.
`unitLabel`	string \| null	Short unit shown beside the amount, like "XP". Only valid when the command contains {amount}. Null shows the amount alone.
`unitLabelTranslations`	map \| null	Per-language overrides for unitLabel, mapping a language code (like "fr" or "zh-CN") to the translated text. Players whose language has no entry (matched case-insensitively, no region fallback) or a blank one see unitLabel instead. null when there are none.
`icon`	string \| null	Direct image URL for the icon on rewards using this definition. A reward's own icon beats it. Null (or omitted) keeps the default lightning icon, or the per-type Custom override from the plugin config when one is set.
`iconColor`	string \| null	Color for the icon, as hex (#rrggbb or #rrggbbaa), rgb() or rgba(). Null (or omitted) inherits the per-type or default color. Invalid colors warn at plugin load and render white.
`iconRaw`	boolean	Set true when the icon is a full-color image (a logo, custom art) so it renders in its own colors. When false the image renders as a solid color, which is right for monochrome icons.

Referencing a definition

A Custom reward on a contract or objective points at a definition with its reward field:

{
  "type": "Custom",
  "title": "",
  "description": "",
  "eligiblePermissions": [],
  "reward": "SkillTreeXp",
  "amount": 500,
  "icon": null,
  "iconColor": null,
  "iconRaw": false
}

When this reward is claimed, the plugin substitutes {amount} with 500 and runs givexp {playerId} 500 false on the server console.

Placeholders

The command and reverse command take every placeholder from the Command reward table, plus {amount}, which is replaced with the amount set on the reward that references the definition.

The reverse command

Console commands normally cannot be taken back, so a failure halfway through claiming a multi-reward contract would leave players keeping partial payouts. The optional reverseCommand fixes that: it declares how to undo the main command. When giving out rewards fails halfway during a claim, the plugin runs the reverse command for each command reward it already gave, with the same placeholder substitution, and the player can claim again later.

Leave it null when the reward cannot be undone. Plain Command rewards can carry their own reverseCommand too.

Missing definitions

A Custom reward can point at a definition that no longer exists, for example after a delete or a typo in a hand-edited file. In the editor this shows a warning, and export still works. On the server the plugin logs a warning at load and shows the reward as ineligible to every player, so the contract stays playable and only that reward is never granted.

Privacy