> For the complete documentation index, see [llms.txt](https://docs.xshyo.us/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xshyo.us/free-plugins/therewards/reward.md).

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.xshyo.us/free-plugins/therewards/reward.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.