> For the complete documentation index, see [llms.txt](https://ultimaterewards.athelion.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ultimaterewards.athelion.eu/configuration/rewards/reward-types/custom-reward.md).

# Custom Reward

{% hint style="info" %}
By default, the example of this reward is disabled to avoid initial error because not all servers use PlaceholderAPI on which this reward is dependent.
{% endhint %}

The reward type works based on PAPI placeholders, where the reward is unlocked for the player when the certain expression is met - all comparisons (< > <= >= ==) are supported, both numbers and boolean values.

* `expression` \[text] - an evaluating expression that evaluates whether the reward is claimable
* `remaining-expression` \[text] - expression that calculates the remaining amount
* `required-rewards` \[list] - option to specify rewards which must be claimed before being able to claim these reward
  * `not-reached-item`
  * `not-reached-display-name`
  * `not-reached-lore`

List of all placeholders can be found here:\
<https://github.com/PlaceholderAPI/PlaceholderAPI/wiki/Placeholders>

{% hint style="warning" %}
Be sure that you have the PAPI extension downloaded.\
`/papi ecloud download Statistic` for this example
{% endhint %}

### Example configuration

<pre class="language-yaml" data-full-width="true"><code class="lang-yaml"># Decides if rewards will be claimable
enabled: true
type: custom_reward
#
# Reward tag
#
tag: Custom Reward
# Expression is used to determine if player can claim this reward.
# Returns true/false depending on the condition
#
# In this case, when player has 20 mob kills, he
# can claim this reward
expression: "%statistic_mob_kills% >= 20"
# Remaining expression is used to calculate missing amount
# for %amount% placeholder in unavailable-lore
remaining-expression: "20 - %statistic_mob_kills%"
required-rewards:
#
# Permission which player must have to be
# able to obtain this reward
#
permission: ultimaterewards.customRewardExample
#
# When player has this permission,
# following properties will be shown.
#
# NOTE THAT ITEM &#x26; SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 &#x26; 1.13&#x3C; VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONE ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE WILL BE REPLACED BY STONE IF INVALID NAME IS IN USE.
#
# When the reward is currently claimable:
available-item: "LIME_DYE"
available-display-name: "&#x26;a&#x26;lCUSTOM REWARD"
available-lore:
  - "&#x26;7You have collected"
  - "&#x26;7enough monster kills to be"
  - "&#x26;7able to obtain this reward!"
  - " "
  - "&#x26;b► Click to claim!"
#
# Whereas player doesn't have enough required kills,
# this version of reward item is displayed in inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&#x26;c&#x26;lCUSTOM REWARD"
unavailable-lore:
  - "&#x26;7You need to kill"
  - "&#x26;720 monsters to unlock"
  - "&#x26;7this reward!"
  - " "
  - "&#x26;4► Requires another %amount% monster kills"
# When player doesn't have claimed 'required-rewards', following
# property will be showed
<strong>not-reached-item: "YELLOW_DEY"
</strong>not-reached-display-name: "&#x26;e&#x26;lCUSTOM REWARD"
not-reached-lore:
  - " "
  - " &#x26;e► You need to claim these rewards: %requiredRewards%"
#
# When player already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&#x26;7&#x26;lCUSTOM REWARD"
claimed-lore:
  - "&#x26;7You have already"
  - "&#x26;7claimed this reward"
  - "&#x26;7for 20 monster kills!"
#
# Player doesn't have permission for this reward,
# following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&#x26;c&#x26;l&#x26;mCUSTOM REWARD"
no-permission-lore:
  - "&#x26;c ✕ Locked, requires"
  - "&#x26;c   %permission% permission"
#
# Commands list that will be executed after player
# obtains this reward.
# All available actions can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [&#x3C;actionType>] (&#x3C;chance>):&#x3C;command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&#x26;aYou have claimed your %type% reward!"
#       - this action will send player a message
#         with defined content
#
# You can also use the random placeholders
# from randoms.yml file and use it in command.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - placeholder will be replaced by
#         random number from defined interval in randoms.yml
#
actions:
  - '[console] give %player% diamond_sword 1'
  - '[console] say %player% claimed his %type% reward!'
  - '[message] &#x26;7You have claimed custom reward for |&#x26;7 20 monster kills!'
  #  - '[actionbar] &#x26;aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &#x26;aClaimed'
  - '[subtitle] &#x26;aReward %type%'
</code></pre>