Reward
⚙️ Reward Configuration Guide
This section explains how to configure an individual reward in TheRewards plugin using a .yml
file.
Each reward is defined in its own YAML file located in the plugin's reward folder. Below is a full breakdown of the configuration fields.
🔖 Basic Information
name
Unique identifier for the reward.
countdown
Time in seconds before the player can claim the reward again.
oneTime
If true
, the reward can only be claimed once per player.
update
If true
, the GUI item will refresh automatically when the reward state changes.
requiredSlots
Amount of free inventory slots needed to claim the reward. Use -1
to ignore.
🔐 Permission Requirement
require_permission:
enabled: true
permission: rewards.example
message: '&cYou need permission to claim this reward.'
🎨 GUI Position
slot
Inventory slot number (or multiple separated by commas: 1,2,3
).
page
GUI page where the reward appears.
✅ Requirements (Conditions)
Requirements define whether the player can claim the reward. All comparisons are done using PlaceholderAPI values.
📌 Available Conditions
==
Equals (number only)
"%vault_eco_balance%" == 1000
!=
Not equal (number and text)
"%player_name%" != "Steve"
>=
Greater than or equal (number only)
"%statistic_hours_played%" >= 10
>
Greater than (number only)
"%player_level%" > 30
<=
Less than or equal (number only)
"%player_level%" <= 5
<
Less than (number only)
"%vault_eco_balance%" < 100
=
Equals (text only)
"%luckperms_primary_group%" = "vip"
<-
Contains (text only)
"%player_name%" <- "xShyo"
|-
Starts with (text only)
%player_name%" |- "B_"
-|
Ends with (text only)
%player_name%" -| "_"
📌 Example Block
requirements:
- placeholder: "%vault_eco_balance%"
condition: ">="
value: "1000"
success: "#4FFD4A ✔ You have enough money."
fail: "#FC3A3A ✖ You need at least $1000."
🛠️ Actions on Claim
Actions define what happens when a reward is claimed. You can mix as many as you want. They run in order.
📦 List of All Available Actions
[command]
Executes a command as console
[command] eco give {player} 500
[player]
Executes a command as player
[player] /spawn
[message]
Sends a private message
[message] &aReward claimed!
[broadcast]
Sends a global message
[broadcast] &e{player} claimed a reward!
[sound]
Plays a sound to the player
[sound] ENTITY_PLAYER_LEVELUP;1.0f;1.0f
[title]
Displays a title
[title] &aCLAIMED;&fReward received;10;20;10
[actionbar]
Shows actionbar message
[actionbar] &eYou got 10 coins!
[close]
Closes the player's inventory
[close]
[minimessage]
Sends MiniMessage to the player
[minimessage] <green>You claimed a reward!</green>
[minibroadcast]
Broadcasts MiniMessage globally
[minibroadcast] <gold>{player}</gold> claimed <green>VIP reward</green>
[chance=x]
Sets a probability for the following action(s)
[chance=50] [command] say Lucky player!
[log]
It will display a message on the server backend.
[log] server log
[firework]
Launches a firework with the desired configuration
[firework] colors=RED,BLUE;fade=WHITE;type=BALL_LARGE;power=2;flicker=true;trail=true
[permission]
Adds permissions to the player (Requires Vault)
[permission] server.permission
[!permission]
Remove player permissions (Requires Vault)
[!permission] server.permission
[opcommand]
Execute a command like op (Not recommended to use)
[opcommand] gamemode creative
📝 Use
{player}
to reference the player's name. ⏱ You can delay actions using<delay=ticks>
(e.g. 20 ticks = 1 second).
📌 Example Block
actionsOnClaim:
- '[command] eco give {player} 1000'
- '[player] /rewards'
- '[message] &aYou received your daily reward!'
- '[sound] ENTITY_EXPERIENCE_ORB_PICKUP;1.0f;1.0f'
- '[broadcast] &e{player} has claimed the Daily Reward!'
- '[title] &a&lREWARD;&fClaimed Successfully!;10;20;10'
- '[log] Server log'
- '[permission] example.permission'
- '[!permission] example.permission'
- '[firework] colors=RED,BLUE;fade=WHITE;type=BALL_LARGE;power=2;flicker=true;trail=true'
- '[actionbar] &a+1000 Coins'
- '[close]'
- '[chance=30] [command] crate givekey {player} vote 1'
📦 GUI Item States
Each item state shows differently based on the reward status:
available
When reward is claimable
incountdown
When waiting for cooldown
permission
When player lacks permission
onetime
When the reward is already claimed (one-time)
locked
When player doesn’t meet requirements
Each section includes:
material: CHEST_MINECART
amount: 1
model_data: 0
display_name: '&aReward Name'
glowing: false
item_flags:
- HIDE_ATTRIBUTES
lore:
- 'Line 1'
- '{state}'
- '{requirements}'
You can use placeholders like
{state}
,{requirements}
,{countdown}
in lore.
📄 Example Template
Here’s a basic reward structure to copy:
# Name of reward
name: reward-example
# Waiting time in seconds to claim the reward again
countdown: 300
# If true, reward can only be claimed once
oneTime: false
# Determines whether the reward should be updated in the reward inventory
update: false
# Do you require available slots to claim?
requiredSlots: -1
# Setting permissions to claim the reward
require_permission:
# Indicates whether a permit is required to claim the reward
enabled: true
# Permission required to claim
permission: rewards.example
# Message if you do not have permission
message: '&6&lREWARD &8| &cYou need the reward.example permission to claim.'
# Slot in the inventory where the reward is shown
# You can also use (,) to use more slots. 1,2,3
slot: '13'
# Inventory page where the reward is located
page: 1
# Requirements for claiming the reward
requirements:
# 🔹 Placeholder: Defines the variable to be used for comparison.
# It can be any value obtained from PlaceholderAPI, such as money, level, playtime, etc.
# Example: "%vault_eco_balance%" gets the player's balance.
- placeholder: "%vault_eco_balance%"
# 🔹 Condition: Specifies the condition that must be met to unlock the title.
# Depending on the data type, it can be a numerical or text-based comparison.
# For numerical values: >=, >, <=, <, ==, !=
# For text values: =, !=, <- (contains), |- (starts with), -| (ends with)
condition: ">="
# 🔹 Value: Specifies the value to compare with the placeholder.
# In this case, it checks if the player's balance is greater than or equal to 1000.
value: "1000"
# 🔹 Success: Message displayed in lore if the player meets the condition.
success: "#4FFD4A ✔ Enough money. &7[Completed]"
# 🔹 Fail: Message displayed in lore if the player does not meet the condition.
fail: "#FC3A3A ✖ You need at least $1000. &7[Not Completed]"
# 🔹 Example of a requirement based on played hours
- placeholder: "%statistic_hours_played%"
condition: ">="
value: "5"
success: "#4FFD4A ✔ Enough playtime. &7[Completed]"
fail: "#FC3A3A ✖ You need to play at least 5 hours. &7[Not Completed]"
# Actions performed when claiming the reward
actionsOnClaim:
##
## You can use {player} to get the name of the player or
##
## Remember to install PlaceholderAPI and load the expansion Player :
## /papi ecloud download Player or %player_name% will not work.
##
- '[command] eco give {player} 10000 <delay=40>' # Gives 10,000 coins to the player after 40 ticks
#- '[chance=50] [command] say Hi {player}' # With a 50% probability, the server says "Hi" to the player.
#- '[player] /rewards' # Execute the /rewards command as the player
#- '[message] &aYou have correctly claimed your reward' # Sends a confirmation message to the player
#- '[sound] BLOCK_NOTE_BLOCK_HARP;1.0f;1.0f' # Plays a sound to the player SOUND;YAW;PITCH
#- '[broadcast] &8» &eThe player &7{player} &ehas claimed his &7Basic &ereward using &7&o(&a/rewards&7)' # Public message announcing the reward
#- '[title] &a&lCLAIMED;&fsuccess;10;20;10' # Displays a title to the player
#- '[close]' # Closes the player's inventory
#- '[actionbar] &aYou have correctly claimed your reward' # Send a message in the actionbar to the player
# MiniMessage > https://docs.advntr.dev/minimessage/format.html#minimessage-format
#- '[minimessage] <MiniMessage>'
#- '[minibroadcast] <MiniMessage>'
# Configuration of the item that is displayed when the reward is available
available:
material: CHEST_MINECART # Item material
amount: 1 # Number of items (usually 1)
model_data: 0 # Model data to customize the item
display_name: '&aBasic Reward' # Item name
glowing: false # The item must be enchanted?
item_flags: # List of flags items to be applied
- HIDE_ATTRIBUTES
lore: # Item description
- '&8Daily Reward'
- ''
- ' យFBDescription:'
- ' &8● &fHere you can claim a basic'
- '&f reward every day.'
- ''
- ' យFBInformation: '
- ' &8● &fState: {state}'
- ' &8● &fRequired: '
- '{requirements}'
- ''
- ' យFBRewards: '
- ' &8● &610.000 &fCoins'
- ' &8● &ex16 Golden Apples'
- ' &8● &dx1 Enchanted Apples'
- ''
- '&e ► Click here to claim!'
# Configuration of the item to be displayed when the reward is counting down
incountdown:
material: MINECART
amount: 1
model_data: 0
display_name: '&cBasic Reward'
glowing: false
item_flags:
- HIDE_ATTRIBUTES
lore:
- '&8Daily Reward'
- ''
- ' យFBDescription:'
- ' &8● &fHere you can claim a basic'
- '&f reward every day.'
- ''
- ' យFBInformation: '
- ' &8● &fState: {state}'
- ' &8● &fWaiting Time: &a{countdown}'
- ' &8● &fRequired: '
- '{requirements}'
- ''
- '&c ► Oh! You still can''t claim'
# Configuration of the item to be displayed when the player does not have the required permission
permission:
material: TNT_MINECART
amount: 1
model_data: 0
display_name: '&cBasic Reward'
glowing: false
item_flags:
- HIDE_ATTRIBUTES
lore:
- '&8Daily Reward'
- ''
- ' យFBDescription:'
- ' &8● &fHere you can claim a basic'
- '&f reward every day.'
- ''
- ' យFBInformation: '
- ' &8● &fState: {state}'
- ' &8● &fRequired: '
- '{requirements}'
- ''
- '&c ► You need to have rank &fUser &c!'
# Configuration of the item to be displayed when the reward is a one-time reward
onetime:
material: HOPPER_MINECART
amount: 1
model_data: 0
display_name: '&cBasic Reward'
glowing: false
item_flags:
- HIDE_ATTRIBUTES
lore:
- '&8Daily Reward'
- ''
- ' យFBDescription:'
- ' &8● &fHere you can claim a basic'
- '&f reward every day.'
- ''
- ' យFBInformation: '
- ' &8● &fState: {state}'
- ' &8● &fRequired: '
- '{requirements}'
- ''
- '&c ► You can only claim this once!'
locked:
material: BARRIER
amount: 1
model_data: 0
display_name: '&cBasic Reward'
glowing: false
item_flags:
- HIDE_ATTRIBUTES
lore:
- '&8Daily Reward'
- ''
- ' យFBDescription:'
- ' &8● &fHere you can claim a basic'
- '&f reward every day.'
- ''
- ' យFBInformation: '
- ' &8● &fState: {state}'
- ' &8● &fRequired: '
- '{requirements}'
- ''
- '&c ► You need to have rank &fUser &c!'
file-version: 1
Need help building conditions or actions? Join our Discord or open an issue!
Last updated