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

Key	Description
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

Key	Description
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

Condition	Description	Example
==	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

Action	Description	Example
[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
[previouspage]	Now you can advance to the previous page by creating a button in the custom items section.	[previouspage]
[nextpage]	Now you can advance to the next page by creating a button in the custom items section.	[nextpage]

📝 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:

Section	When it shows
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'
    - ''
    - ' &#6041FBDescription:'
    - '  &8● &fHere you can claim a basic'
    - '&f    reward every day.'
    - ''
    - ' &#6041FBInformation: '
    - '  &8● &fState: {state}'
    - '  &8● &fRequired: '
    - '{requirements}'
    - ''
    - ' &#6041FBRewards: '
    - '  &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'
    - ''
    - ' &#6041FBDescription:'
    - '  &8● &fHere you can claim a basic'
    - '&f    reward every day.'
    - ''
    - ' &#6041FBInformation: '
    - '  &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'
    - ''
    - ' &#6041FBDescription:'
    - '  &8● &fHere you can claim a basic'
    - '&f    reward every day.'
    - ''
    - ' &#6041FBInformation: '
    - '  &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'
    - ''
    - ' &#6041FBDescription:'
    - '  &8● &fHere you can claim a basic'
    - '&f    reward every day.'
    - ''
    - ' &#6041FBInformation: '
    - '  &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'
    - ''
    - ' &#6041FBDescription:'
    - '  &8● &fHere you can claim a basic'
    - '&f    reward every day.'
    - ''
    - ' &#6041FBInformation: '
    - '  &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!