# 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

```yaml
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

```yaml
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

```yaml
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:

```yaml
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:

```yaml
# 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!