# Getting started

**UltimateRewards** is a powerful and versatile Minecraft plugin that revolutionizes your server with a feature-rich reward system. Designed to fit seamlessly into any server setup—whether it’s a standalone server or a large network—it offers [over 20 customizable reward types](/configuration/rewards/reward-types), a fully configurable menu system, and tools that make accessing rewards simple and intuitive for players.

With its all-in-one design, **UltimateRewards** eliminates the need for additional plugins, providing a comprehensive reward system out of the box. The plugin includes an overview of all available features and rewards, paired with an easy-to-use configuration system that puts full customization in your hands.


# Addons

Available addons

In collaboration with [Taco Studio](https://www.tacostudios.net/), we create textured menus and stuff for the plugin, available on [our BuiltByBit profile](https://builtbybit.com/creators/athelion.212166).

{% tabs %}
{% tab title="Advent Calendar" %}

<figure><img src="https://iili.io/2Ye1Cba.png" alt=""><figcaption></figcaption></figure>

{% embed url="<https://builtbybit.com/resources/adventcalendar-custom-ui.55150/>" fullWidth="true" %}
{% endtab %}

{% tab title="AFK Reward" %}

<div data-full-width="true"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FqlpyvCCJ34jKAnybPa2y%2Fafk.gif?alt=media&amp;token=8de131d3-170c-4cba-85f6-28854ccbbf5b" alt=""><figcaption><p>AFK Reward preview</p></figcaption></figure></div>

{% embed url="<https://builtbybit.com/resources/afk-rewards-interactive-ui-with-progress.58127/>" %}
{% endtab %}

{% tab title="Soon" %}
Another UIs are coming soon!
{% endtab %}
{% endtabs %}


# Configs

Here, you'll find ready-made (predefined) configurations that you can use as-is or customize to suit your needs.    These configurations are available on our Discord server after verifying your plugin

Here, you'll find **FREE** predefined configurations that you can use as-is or customize to suit your needs. It serves as inspiration or as a ready-made config.

These configurations are available on [our Discord server](https://discord.gg/TfUC8uJ) after verifying your plugin purchase.

They are of premium quality, comparable to what others typically sell on the market for a fee.

* [**PLAYER LEVELS**](/configs/player-levels)
* [**PLAYER KITS**](/configs/player-kits)
* [**REFERRALS**](/configs/referrals)
* [**LOGINSTREAK**](/configs/loginstreak)


# Player Levels

This can be achieved with the %typ% reward type

A whole level system that rewards you for progress.\
**This can be achieved with the** [**MULTIPLE CUSTOM**](/configuration/rewards/reward-types/multiple-custom-reward) **reward type**

*Rewards are for illustrative purposes only and are subject to change.*

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FQNpJxwlOxUN7qOdjctA8%2Flevels%20preview.gif?alt=media&amp;token=b8ec9b4c-813b-42aa-86ad-5d666e69e1d7" alt=""><figcaption></figcaption></figure>


# Player Kits

Server kit system.\
**This can be achieved with the** [ONE\_TIME\_REWARD](/configuration/rewards/reward-types/one-time-reward) (or [TIME\_REWARD](/configuration/rewards/reward-types/time-reward) for kits with cooldown) **reward type**

*Kit contents are for illustrative purposes only and are subject to change.*

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FypwLhuwYASoLuNZQYygu%2Fkits.png?alt=media&amp;token=f26435d8-01c4-4048-8e54-f5d045b96001" alt=""><figcaption></figcaption></figure>


# Referrals

Rewards if a player brings other players/friends and they redeem their referral.\
**This can be achieved with the** [**REFERRAL**](/configuration/rewards/reward-types/referral-reward) **reward type**

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FrewcyzHzJjQjGCaVPfTI%2Freferrals.png?alt=media&amp;token=28ca7a75-0185-48b1-b1a4-c22519b505c8" alt=""><figcaption></figcaption></figure>


# Loginstreak

A reward that is set to reward the player when they join the server for a total of 31 days. If a player misses one day the entire progress resets and starts from day 1.\
**This can be achieved with the** [**STREAK FIXED**](/configuration/rewards/reward-types/streak-fixed-reward) **reward type**

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2Fd8oMiXzAQZvBlkwDmqVV%2FVideo%20bez%20n%C3%A1zvu_%20Vytvo%C5%99eno%20pomoc%C3%AD%20aplikace%20Clipchamp%20(7).gif?alt=media&amp;token=f30e0bd6-b4b9-48ee-a4c4-e8c39643487a" alt=""><figcaption><p>Loginstreak showcase</p></figcaption></figure>


# Installation

Installation guide

{% hint style="warning" %}
Minimum Requirements

* Java 8 (from version 2.12.1 Java 21)
* Server Version 1.8.8 +
  {% endhint %}

{% hint style="success" %}
From version 2.13.0 plugin also supports Folia
{% endhint %}

### Guide

{% stepper %}
{% step %}

### Obtain License

Visit [Spigot](https://www.spigotmc.org/resources/%E2%9A%A1-ultimaterewards-15-available-reward-types-1-8-1-20-4.108055/), [BuiltByBit](https://builtbybit.com/resources/ultimaterewards-15-types-of-rewards.27336/) or [Polymart](https://polymart.org/resource/ultimaterewards.4150) to acquire your copy of the plugin. Download the plugin's `.jar` file.
{% endstep %}

{% step %}

### Download Plugin

Once downloaded, navigate to your server's directory and locate the "plugins" folder.
{% endstep %}

{% step %}

### Insert Plugin

Place the downloaded `.jar` file directly into the `plugins` folder (not in subfolders).
{% endstep %}

{% step %}

### Start Server

Stop, start, or restart your server to initiate the plugin installation. You can do this through your server management interface or by using the appropriate server commands.

* For Bukkit/Spigot servers, use the command: `/stop`, `/start`, or `/restart`.
* For other server types, follow the specific stop/start/restart procedure applicable to your server.
  {% endstep %}

{% step %}

### Load Plugin

Allow the server to complete the loading process. Ensure that the plugin is loaded without any errors or conflicts.
{% endstep %}

{% step %}

### Configure Plugin

Once the server has successfully loaded, your plugin is ready to use! Verify its functionality and configure any necessary settings according to the plugin documentation.
{% endstep %}
{% endstepper %}

**Note**: If you encounter any issues during the setup process, refer to the plugin's documentation or [support](https://discord.gg/S3Sc6edVc3) channels for assistance.


# Global Configuration

Reference of every option in config.yml

`config.yml` holds the settings that apply to the whole plugin. Everything that belongs to a single reward is configured in that reward's own .yml file instead — see [Creating Reward](/configuration/rewards/creating-reward).

{% hint style="info" %}
After editing any .yml file, apply the changes with `/reward reload`.
{% endhint %}

## Database

| Key                             | Default                           | Description                                                   |
| ------------------------------- | --------------------------------- | ------------------------------------------------------------- |
| `backend`                       | `SQLITE`                          | `SQLITE`, `MYSQL`, `MARIADB` or `POSTGRESQL`                  |
| `mysql-host` / `mysql-port`     | `127.0.0.1` / `3306`              | Address of the database server                                |
| `mysql-database-name`           | `database`                        | Name of the database                                          |
| `mysql-table-name`              | `ultimaterewards_rewards`         | Table name, can be left as is                                 |
| `mysql-user` / `mysql-password` | —                                 | Credentials                                                   |
| `mysql-pool-settings-*`         | —                                 | HikariCP connection pool (pool size, idle, lifetime, timeout) |
| `mysql-properties`              | `useUnicode`, `characterEncoding` | Additional JDBC properties                                    |

{% hint style="warning" %}
A shared database is what makes network-wide data possible — `%ultimaterewards_playtime_global%` and cross-server reward states require MySQL, MariaDB or PostgreSQL. Existing data can be moved over with `/reward convert <type>`, see [Commands](/usage/commands).
{% endhint %}

## General

| Key                    | Default                        | Description                                                                                                      |
| ---------------------- | ------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| `update-checker`       | `true`                         | Checks for new versions of the plugin on startup                                                                 |
| `max-accounts-per-ip`  | `0`                            | How many accounts may claim rewards from one IP address (0 = no limit)                                           |
| `log-accounts`         | `true`                         | Logs all accounts of a connecting player into the console                                                        |
| `tab-argument-matcher` | `CONTAINING_ALL_CHARS_OF_TEXT` | How tab-completion filters arguments — `CONTAINING_TEXT`, `CONTAINING_ALL_CHARS_OF_TEXT` or `STARTING_WITH_TEXT` |
| `debug`                | `false`                        | Verbose logging, useful when reporting an issue                                                                  |

The layout of `/reward help` is controlled by `help-header`, `help-message-format` (`%syntax%`, `%description%`) and `help-footer`.

## Play-time

| Key                                      | Default   | Description                                                                                                                                   |
| ---------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `play-time-calculator`                   | `DEFAULT` | `DEFAULT` or `PLAYTIMES` (uses the PlayTimes plugin), see [own calculator](/api/setting-up-own-playtime-calculator)                           |
| `enable-afk-checker`                     | `true`    | AFK players do not accumulate play-time (requires Essentials or CMI), see [AFK Checkers](/configuration/rewards/reward-features/afk-checkers) |
| `worlds-with-disabled-playtime-tracking` | list      | Play-time is not tracked at all in these worlds                                                                                               |
| `first-time-join-required-play-time`     | `100`     | Minutes a player has to play in total before claiming anything (0 = disabled)                                                                 |
| `session-required-play-time`             | `10`      | Minutes a player has to play in the current session before claiming (0 = disabled)                                                            |
| `play-time-placeholder-format`           | —         | Format of `%ultimaterewards_playtime_local%` and `%ultimaterewards_playtime_session%`                                                         |
| `remaining-play-time-placeholder-format` | —         | Format of `%ultimaterewards_remaining_time_<reward>%`                                                                                         |
| `afk-time-placeholder-format`            | —         | Format of `%ultimaterewards_afk_session_time%`                                                                                                |

The formats accept `%days%`, `%hours%`, `%minutes%` and `%seconds%`.

{% hint style="warning" %}
Leave `play-time-calculation` at `MINUTES`.
{% endhint %}

## Menus

| Key                            | Default                   | Description                                                           |
| ------------------------------ | ------------------------- | --------------------------------------------------------------------- |
| `main-menu`                    | `main`                    | Menu opened by `/rewards`                                             |
| `background-item`              | `GRAY_STAINED_GLASS_PANE` | Background of the rewards GUI, `none` disables it                     |
| `close-menu-after-claiming`    | `false`                   | Close the menu after a reward is claimed (a reward can override this) |
| `check-for-full-inventory`     | `true`                    | Block claiming when the player's inventory is full                    |
| `available-rewards-menu-rows`  | `4`                       | Size of the `/reward available` menu                                  |
| `available-rewards-menu-slots` | `0–8`                     | Slots the available rewards are placed into                           |
| `input-type`                   | `ANVIL`                   | How text input is asked for — `ANVIL` or `CHAT`                       |
| `setting-no-permission-item`   | `BARRIER`                 | Item shown instead of a setting the player has no permission for      |

The progress bar rendered by `%ultimaterewards_progress_<reward>%` is styled with `progress-bar-symbol`, `progress-bar-completed-color`, `progress-bar-missing-color` and `progress-bar-length`.

Menus themselves are configured in [guis.yml](/configuration/menus/basics).

## Notifications & auto-claim

Defaults for new players — each of them can be toggled by the player afterwards, see [Reward Settings](/configuration/rewards/reward-settings):

| Key                            | Default | Description                                                  |
| ------------------------------ | ------- | ------------------------------------------------------------ |
| `join-notification-by-default` | `true`  | Notify about claimable rewards on join                       |
| `live-notification-by-default` | `true`  | Notify the moment a reward becomes available                 |
| `join-auto-claim-by-default`   | `false` | Claim available rewards automatically on join                |
| `live-auto-claim-by-default`   | `false` | Claim a reward automatically as soon as it becomes available |

Each of the events has its own section — `join-announcement`, `live-announcement`, `multiple-live-announcement`, `join-auto-claim` and `live-auto-claim` — where you can set:

* `delays` / `delay` — how many seconds after joining the message is sent,
* `command` — the command executed when the player clicks the announcement (`%reward%` is replaced by the reward),
* `sound` — `enabled`, `value`, `volume` and `pitch` of the sound played with the announcement.

```yaml
live-announcement:
  command: "reward claim %reward%"
  sound:
    enabled: true
    value: BLOCK_NOTE_BLOCK_HARP
    volume: 1.0
    pitch: 1.0
```

{% hint style="warning" %}
Sound names differ between Minecraft versions — make sure you use names valid for the version you run.
{% endhint %}

## Discord

| Key                         | Default          | Description                                                                                    |
| --------------------------- | ---------------- | ---------------------------------------------------------------------------------------------- |
| `discord-booster-role-name` | `Server Booster` | Role used by the [booster checker](/configuration/rewards/reward-features/reward-requirements) |
| `discord-log-channel`       | `none`           | Channel ID where claimed rewards are logged, `none` disables logging                           |

Both options require [DiscordSRV](/configuration/rewards/reward-features/discord-support).

## Placeholders

| Key                        | Default | Description                                                                                                           |
| -------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------- |
| `use-timer-in-placeholder` | `true`  | When `false`, `%ultimaterewards_cooldown_<reward>%` shows the `unavailable` text from lang.yml instead of a countdown |

The full list is on the [Placeholders](/placeholders) page.

## Commands

Every command of the plugin can be renamed, and its aliases changed, in the `commands:` section:

```yaml
commands:
  reward:
    name: reward
    aliases:
      - rw
  rewards:
    name: rewards
    aliases:
      - rws
```

The same applies to `referral`, `vote` and `playtime`. A full list of commands is on the [Commands](/usage/commands) page.

{% hint style="info" %}
Renaming a command requires a server restart, a reload is not enough.
{% endhint %}

## Other files

| File            | Contents                                                                                        |
| --------------- | ----------------------------------------------------------------------------------------------- |
| `lang.yml`      | All messages of the plugin                                                                      |
| `guis.yml`      | [Menus](/configuration/menus/basics)                                                            |
| `rewards/`      | One .yml file per [reward](/configuration/rewards/creating-reward)                              |
| `votes.yml`     | [Vote handling and per-vote rewards](/configuration/rewards/reward-types/per-vote-reward)       |
| `referrals.yml` | [Referral system](/configuration/rewards/reward-types/referral-reward)                          |
| `randoms.yml`   | [Random placeholders](/configuration/rewards/reward-features/randomization/random-placeholders) |
| `schedules.yml` | [Schedules & timers](/configuration/schedules-and-timers)                                       |

{% hint style="info" %}
The `10-percent` … `100-percent` keys at the end of config.yml are only used by an addon and can be ignored.
{% endhint %}


# Commands

All valid command syntaxes, their arguments and their permissions.

{% hint style="info" %}
Every command name and alias can be renamed in the `commands:` section of [config.yml](/usage/global-configuration). This page uses the default names.
{% endhint %}

| Command     | Alias        | Purpose                                                       |
| ----------- | ------------ | ------------------------------------------------------------- |
| `/reward`   | `/rw`        | Main command — opens the main menu and holds all sub-commands |
| `/rewards`  | `/rws`       | Opens the main menu                                           |
| `/referral` | `/ref`       | Referral system                                               |
| `/vote`     | `/uvote`     | Voting                                                        |
| `/playtime` | `/uplaytime` | Play-time                                                     |

{% hint style="success" %}
`ultimaterewards.admin` (and OP) unlocks **every** command on this page. The individual nodes below are only needed when you want to hand out partial access.
{% endhint %}

{% hint style="info" %}
All commands support tab-completion. How arguments are matched while typing is controlled by `tab-argument-matcher` in config.yml.

Optional arguments are wrapped in round brackets `( )`.
{% endhint %}

## Administration

| Syntax                   | Permission               | Description                                            |
| ------------------------ | ------------------------ | ------------------------------------------------------ |
| `/reward reload`         | `ultimaterewards.reload` | Reloads every .yml file of the plugin                  |
| `/reward convert <type>` | `ultimaterewards.admin`  | Copies stored data to another database backend         |
| `/reward about`          | `ultimaterewards.about`  | Version, platform and a list of currently active hooks |
| `/reward help`           | `ultimaterewards.admin`  | Lists every sub-command the sender is allowed to use   |

### Converting the database

When you want to move from SQLite to a real database server (or between servers), run the conversion **while still running on the old backend**:

```
/reward convert MYSQL
```

Valid types are `SQLITE`, `MYSQL`, `MARIADB` and `POSTGRESQL`.

{% hint style="warning" %}
Fill in the credentials of the **target** database in [config.yml](/usage/global-configuration) before running the command — the plugin connects to it directly. After a successful conversion, change `backend:` in config.yml and restart the server.
{% endhint %}

## Menu commands

The plugin offers the option to create a main GUI (its name is set by `main-menu` in config.yml) and individual sub-menus that may or may not be interconnected.

| Syntax                           | Permission                    | Description                           |
| -------------------------------- | ----------------------------- | ------------------------------------- |
| `/rewards` or `/reward`          | —                             | Opens the main menu                   |
| `/reward open <menu>`            | `ultimaterewards.open`        | Opens the specified menu              |
| `/reward open <menu> (<player>)` | `ultimaterewards.open.others` | Opens the specified menu for a player |

{% hint style="info" %}
Each menu can also register its own command through the `command:` key in [guis.yml](/configuration/menus/basics).
{% endhint %}

## Reward commands

| Syntax                                       | Permission                      | Description                                       |
| -------------------------------------------- | ------------------------------- | ------------------------------------------------- |
| `/reward claim <reward>`                     | —                               | Claims the reward                                 |
| `/reward claim <reward> (<player>)`          | `ultimaterewards.claim.others`  | Claims the reward for another player              |
| `/reward available`                          | `ultimaterewards.available`     | Opens a menu with everything currently claimable  |
| `/reward reset <player> <reward> (<streak>)` | `ultimaterewards.reset`         | Resets a reward (cooldown, streak, claimed state) |
| `/reward test <reward> (<streak\|day>)`      | `ultimaterewards.test`          | Executes the reward's actions without claiming it |
| `/reward toggle <setting>`                   | see below                       | Toggles one of the player's own settings          |
| `/reward toggle <setting> (<player>)`        | `ultimaterewards.toggle.others` | Toggles the setting for another player            |

### Resetting rewards

Besides a player name, `/reward reset` accepts wildcards:

| Argument                     | Meaning                                                |
| ---------------------------- | ------------------------------------------------------ |
| `/reward reset <player> ...` | Resets for that player (works for offline players too) |
| `/reward reset * ...`        | Resets for all **online** players                      |
| `/reward reset ** ...`       | Resets for **every** player in the database            |
| `/reward reset <player> *`   | Resets **all** rewards of that player                  |

The optional `<streak>` argument resets a specific streak step of streak-based rewards.

{% hint style="info" %}
The `*` and `**` player wildcards apply to a single reward at a time — combining them with the `*` reward wildcard only resets the first reward.
{% endhint %}

### Testing rewards

`/reward test` runs the reward's [actions](/configuration/rewards/reward-actions) immediately, ignoring cooldowns and checkers, which makes it the fastest way to verify a new configuration. For rewards that have streaks (streak rewards, advent calendar, pickable rewards…) the step has to be specified, e.g. `/reward test exampleStreakReward 3`.

{% hint style="info" %}
This command can only be executed in-game.
{% endhint %}

### Toggling settings

`<setting>` is one of the [reward settings](/configuration/rewards/reward-settings): `JOIN_NOTIFICATION`, `LIVE_NOTIFICATIONS`, `JOIN_AUTO_CLAIM`, `LIVE_AUTO_CLAIM`. Toggling a setting requires the permission belonging to that setting — the full list is on the [Reward Settings](/configuration/rewards/reward-settings) page.

## Referral commands

| Syntax                     | Permission                        | Description                            |
| -------------------------- | --------------------------------- | -------------------------------------- |
| `/referral`                | —                                 | Shows the referral help from lang.yml  |
| `/referral create`         | `ultimaterewards.referral.create` | Creates the player's own referral code |
| `/referral apply <player>` | `ultimaterewards.referral.apply`  | Activates someone else's referral code |
| `/referral reset <player>` | `ultimaterewards.admin`           | Clears whom the player was referred by |

The referral **code is always the name of the player who created it**. Applying it adds one use to the owner of the referral and rewards the player who applied it. Both sides' rewards, as well as the requirements for creating and applying, are configured in `referrals.yml` — see [Reward Requirements](/configuration/rewards/reward-features/reward-requirements).

## Vote commands

{% hint style="info" %}
The `/uvote` alias is registered as well, in case `/vote` conflicts with another plugin.
{% endhint %}

| Syntax                   | Permission              | Description                                                 |
| ------------------------ | ----------------------- | ----------------------------------------------------------- |
| `/vote`                  | —                       | Sends the `vote-command` message list from lang.yml         |
| `/vote proceed <player>` | `ultimaterewards.admin` | Processes a vote for the player manually (useful for tests) |
| `/vote reset <player>`   | `ultimaterewards.admin` | Resets the player's vote counter                            |

Vote handling itself (counting, announcements, per-vote rewards) is configured in [votes.yml](/configuration/rewards/reward-types/per-vote-reward).

## Play-time commands

| Syntax                     | Permission              | Description                           |
| -------------------------- | ----------------------- | ------------------------------------- |
| `/playtime reset <player>` | `ultimaterewards.reset` | Resets the player's tracked play-time |

{% hint style="warning" %}
Resetting play-time also resets the progress of every [play-time reward](/configuration/rewards/reward-types/play-time-reward) of that player.
{% endhint %}


# Rewards


# Creating Reward

## Setuping the reward

Rewards are located in the rewards folder, where each reward corresponds to one file. The file name then denotes the identifier of the reward.

### **General Settings**

{% hint style="info" %}
The tutorial is explained for the [Time Reward](/configuration/rewards/reward-types/time-reward), note that each reward type has its own properties in addition to the [shared properties](/configuration/rewards/reward-types#shared-properties) - you can set these properties for each of the [reward types](https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/reward-types).
{% endhint %}

1. **Enable Reward Claiming**

   ```yaml
   enabled: true
   ```

   * **enabled:** Set to `true` to allow rewards to be claimable.
2. **Reward Type**

   ```yaml
   type: time_reward
   ```

   * **type:** Specifies the type of reward. All reward type are listed [here](/configuration/rewards/reward-types). Use `time_reward` for time-based rewards.
3. **Reward Tag**

   ```yaml
   tag: Time Reward
   ```

   * **tag:** A label for the reward, used for identification.
4. (Optional) **Reward Command**

   ```yaml
   command: timereward
   ```

   * **command:** The command by which the reward can be claimed, /timereward in this case.

### **Cooldown Settings**

1. **Cooldown Duration**

   ```yaml
   cooldown: 24
   ```

   * **cooldown:** Number of units before the reward can be claimed again.
2. **Cooldown Unit**

   ```yaml
   unit: hours
   ```

   * **unit:** Unit of time for the cooldown (e.g., `hours`, `minutes`).
3. **General Cooldown Display Format**

   ```yaml
   cooldown-general-format: "%hours% hours"
   ```

   * **cooldown-general-format:** Format for displaying the general cooldown time.
4. **Specific Cooldown Display Format**

   ```yaml
   cooldown-format: '%hours%:%minutes%:%seconds%'
   ```

   * **cooldown-format:** Format for displaying the cooldown in reward GUIs.

### **Availability Settings**

1. (Optional) **Available After First Join**

   ```yaml
   available-after-first-join: false
   ```

   * **available-after-first-join:** Set to `true` to make the reward available immediately after a player's first join.
2. (Optional) **Live Reminder**

   ```yaml
   live-reminder-enabled: true
   ```

   * **live-reminder-enabled:** Notifies players when the reward is available.
3. (Optional) **Required Inventory Slots**

   ```yaml
   required-slots: 3
   ```

   * **required-slots:** Number of free inventory slots required to claim the reward.
4. (Optional) **Permission Requirement**

   ```yaml
   permission: ultimaterewards.exampleTimeReward
   ```

   * **permission:** Permission node required for the player to claim the reward.

### **Item and Display Settings**

{% hint style="info" %}
Each reward type has its own states, these can be found by viewing the [individual reward types](/configuration/rewards/reward-types).
{% endhint %}

* **Available Item Display**

  ```yaml
  available-item: CHEST_MINECART
  available-display-name: '&a&lTIME REWARD'
  available-lore:
    - '&7Can be obtained every &f%cooldown%'
    - ' '
    - '&7Contains:'
    - '&e ➪ 1x Diamond'
    - '&e ➪ 3x Gold Ingot'
    - '&e ➪ 6x Iron Ingot'
    - ' '
    - '&b► Click to claim'
  ```

  * **available-item:** Item displayed when the reward is claimable.
  * **available-display-name:** Display name for the available reward item.
  * **available-lore:** Lore description for the available reward item.
* **Unavailable Item Display**

  ```yaml
  unavailable-item: MINECART
  unavailable-display-name: "&7&lTIME REWARD"
  unavailable-lore:
    - '&7Available in:'
    - '&7%cooldown%'
  ```

  * **unavailable-item:** Item displayed when the reward is under cooldown.
  * **unavailable-display-name:** Display name for the unavailable reward item.
  * **unavailable-lore:** Lore description for the unavailable reward item.
* **No Permission Item Display**

  ```yaml
  no-permission-item: BARRIER
  no-permission-display-name: "&c&l&mTIME REWARD"
  no-permission-lore:
    - "&c ✕ Locked, requires"
    - "&c   %permission% permission"
  ```

  * **no-permission-item:** Item displayed when the player lacks permission.
  * **no-permission-display-name:** Display name for the no-permission reward item.
  * **no-permission-lore:** Lore description for the no-permission reward item.

### [**Reward Actions**](/configuration/rewards/reward-actions)

1. **Commands Executed on Reward Claim**

   ```yaml
   actions:
     80:
       - '[console] give %player% diamond 1'
       - '[console] give %player% gold_ingot 3'
       - '[console] give %player% iron_ingot 6'
       - '[console] say %player% claimed their %type% reward!'
       - '[title] &aClaimed'
       - '[subtitle] &aReward %type%'
       - '[message] &7Enjoy your claimed reward | New line!'
     20:
       - '[console] give %player% diamond 1'
       - '[console] give %player% gold_ingot 3'
       - '[console] give %player% iron_ingot 6'
       - '[console] say %player% claimed their %type% reward!'
       - '[title] &aClaimed'
       - '[subtitle] &aReward %type%'
       - '[message] &7Enjoy your claimed reward | New line!'
       - '[message] &a&lYou have been extra lucky today! Received 5 more diamonds!'
       - '[console] give %player% diamond 5'
   ```

   * **actions:** List of actions and commands executed when a reward is claimed. Find out more about the chances at [randomization](/configuration/rewards/reward-features/randomization)
     * **80:** Set of actions with 80% execution chance.
     * **20:** Actions with a 20% execution chance.

### [**Variants (Optional)**](/configuration/rewards/reward-features/reward-variants)

1. **Reward Variants**

   ```yaml
   variants:
     premium:
       permission: ultimaterewards.timeRewardExample.premium
       available-display-name: "&6&lPREMIUM TIME REWARD"
       available-lore:
         - '&7Can be obtained every &f%cooldown%'
         - ' '
         - '&7Contains:'
         - '&e ➪ 3x Diamonds'
         - '&e ➪ 12x Gold Ingots'
         - '&e ➪ 24x Iron Ingots'
         - ' '
         - '&6► Click to claim premium reward'
       actions:
         80:
           - '[console] give %player% diamond 3'
           - '[console] give %player% iron_ingot 12'
           - '[console] give %player% gold_ingot 24'
           - '[console] say %player% claimed their %type% reward!'
           - '[title] &aClaimed'
           - '[subtitle] &aReward %type%'
           - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
           - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
         20:
           - '[console] give %player% diamond 3'
           - '[console] give %player% iron_ingot 12'
           - '[console] give %player% gold_ingot 24'
           - '[console] say %player% claimed their %type% reward!'
           - '[title] &aClaimed'
           - '[subtitle] &aReward %type%'
           - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
           - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
           - '[message] &6&lYou have been extra lucky today! | Received 10 more diamonds!'
           - '[console] give %player% diamond 10'
   ```

   * **variants:** Optional reward variants based on player permissions.
     * **premium:** Example variant with specific permissions and actions.

## Linking (displaying) a reward in the menu

The created and set reward can be displayed in the menu. The [guis.yml](/configuration/menus/example-of-guis) file is used for this purpose.

Each reward can be assigned a position in the spcific menu. In the case of rewards that have more than one position (Advent Calendar, Streak Rewards, Pickable Reward, etc...) you can specify individual sub-rewards.


# Reward Types

The plugin offers various types of rewards for all types of occasions.

Each reward type comes with its own unique settings, along with shared parameters that are applicable to all rewards. The following is a list of currently available reward types, acknowledging the possibility of additional types being introduced in future versions:

* [**AFK REWARD**](/configuration/rewards/reward-types/afk-reward) <mark style="color:red;">**NEW**</mark>
* [**ADVENT CALENDAR**](/configuration/rewards/reward-types/advent-calendar)
* [**COUPON REWARD**](/configuration/rewards/reward-types/coupon-reward) *<mark style="color:yellow;">SOON</mark>*
* [**DISCORD REWARD**](/configuration/rewards/reward-types/discord-reward) *<mark style="color:yellow;">SOON</mark>*
* [**PICKABLE REWARD**](/configuration/rewards/reward-types/pickable-reward) <mark style="color:red;">**NEW**</mark>
* [**TIME REWARD**](/configuration/rewards/reward-types/time-reward)
* [**TIME FIXED REWARD**](/configuration/rewards/reward-types/time-fixed-reward)
* [**STREAK REWARD**](/configuration/rewards/reward-types/streak-reward)
* [**STREAK FIXED REWARD**](/configuration/rewards/reward-types/streak-fixed-reward)
* [**VOTE REWARD**](/configuration/rewards/reward-types/vote-reward)
* [**PER VOTE REWARD**](/configuration/rewards/reward-types/per-vote-reward)
* [**RENEWABLE VOTE REWARD**](/configuration/rewards/reward-types/renewable-vote-reward)
* [**STREAK VOTE REWARD**](/configuration/rewards/reward-types/streak-vote-reward)
* [**PLAY TIME REWARD**](/configuration/rewards/reward-types/play-time-reward)
* [**RENEWABLE PLAY TIME REWARD**](/configuration/rewards/reward-types/renewable-play-time-reward)
* [**REFERRAL REWARD**](/configuration/rewards/reward-types/referral-reward)
* [**RENEWABLE REFERRAL REWARD**](/configuration/rewards/reward-types/renewable-referral-reward)
* [**PURCHASABLE REWARD**](/configuration/rewards/reward-types/purchasable-reward)
* [**RE-PURCHASABLE REWARD**](/configuration/rewards/reward-types/re-purchasable-reward)
* [**ONE TIME REWARD**](/configuration/rewards/reward-types/one-time-reward)
* [**TIME LIMITED REWARD**](/configuration/rewards/reward-types/time-limited-reward)
* [**CUSTOM REWARD**](/configuration/rewards/reward-types/custom-reward)
* [**MULTIPLE CUSTOM REWARD**](/configuration/rewards/reward-types/multiple-custom-reward) <mark style="color:red;">**NEW**</mark>

{% hint style="info" %}
The value written into `type:` in the reward's .yml file is the type name in lower snake case, e.g. `type: time_reward`, `type: renewable_vote_reward`, `type: multiple_custom_reward`. The same names are used by `%ultimaterewards_available_{rewardType}%`.
{% endhint %}

### Shared Properties

These common parameters can be applied (by adding or removing the path to the .yml reward folder) to all rewards:

#### Basics

* `enabled` \[true/false] - whether the reward is active
* `type` \[text] - the reward type, see the list above
* `tag` \[text] - reward's tag, also available in actions as `%tag%` (defaults to the file name)
* `command` \[text] - the command by which the reward can be collected
* `permission` \[text] - limits the reward to players with this permission *(set to "" for no required permission)*
* `actions` \[list] - a list of actions that will be performed after the reward is activated\
  \- about actions is whole following [section](/configuration/rewards/reward-actions).

#### Requirements

* `disabled-worlds` \[list] - worlds where reward can't be obtained
* `required-slots` \[number] - how many free inventory slots a player needs to collect a reward
* `max-play-time` \[number] - time limit (in minutes) when the player can collect the reward, if he exceeds this limit - he cannot collect the reward anymore <mark style="color:red;">**NEW**</mark>
* `required-session-play-time` \[number] - how many minutes the player has to play **in the current session** before this reward can be collected (set to 0 to disable)
* `require-discord-sync` \[true/false] - the player will only be able to collect the reward if he has a synced account with your discord server (only with DiscordSRV plugin)
* `require-boosting-discord` \[true/false] - the player will only be able to collect the reward while boosting your Discord server (only with DiscordSRV plugin)

All of them are described in detail in [Reward Requirements](/configuration/rewards/reward-features/reward-requirements).

#### Notifications & auto-claim

* `exclude-from-reminders` \[true/false] - reward won't be included in reward available reminders
* `live-reminder-enabled` \[true/false] - enable live notification of reward availability (example: when a cooldown time reward runs out, the player is notified that they can collect it)
* `live-notification` \[list] - custom text of the live notification for this reward (falls back to lang.yml when not set)
* `included-in-auto-claim` \[true/false] - decides whether the reward should be automatically collected (if available) for the player
* `close-after-claiming` \[true/false] - decides if the menu should be closed after claiming the reward (rewrites the global setting from config.yml)

#### Appearance

Every reward state has its own item, display name and lore. The available states differ per reward type and are listed on each type's page; the ones shared by all rewards are:

* `available-item`, `available-display-name`, `available-lore` - shown while the reward can be claimed
* `available-glow` \[true/false] - adds the enchantment glow to the available item
* `no-permission-item`, `no-permission-display-name`, `no-permission-lore` - shown when the player lacks the reward's `permission`

{% hint style="info" %}
`claimable-item`, `claimable-display-name` and `claimable-lore` are still accepted as legacy names for the `available-*` keys.
{% endhint %}

#### Variants

* `variants` - permission-based overrides of display and actions, see [Reward Variants](/configuration/rewards/reward-features/reward-variants)


# Afk Reward

Different types of AFK rewards are available for different solutions. Multiple AFK rewards are supported, for example if you want to set one reward for 2 minutes and another for 5 minutes, simply set 2 rewards at the desired time and set different rewards.&#x20;

{% hint style="warning" %}
Be careful with progress-actions, they will overlap when multiple afk rewards are set to same region/world, so it is recommended to keep progress, enter and quit actions to one reward only.
{% endhint %}

* [**WORLD AFK REWARD**](/configuration/rewards/reward-types/afk-reward/world-afk-reward)
* [**AREA AFK REWARD**](/configuration/rewards/reward-types/afk-reward/area-afk-reward)
* [**REGION AFK REWARD**](/configuration/rewards/reward-types/afk-reward/region-afk-reward) ([WorldGuard](https://dev.bukkit.org/projects/worldguard) support)


# World Afk Reward

This reward rewards players who find themselves in a specific world in a repeating cycle.

* `world` \[text] - certain world where the rewarding should apply
* `required-time` \[number] - the amount of time the player will be rewarded after staying in the world (in minutes)
* `reset-on-leave` \[true/false] - should the timer start again when the player leaves and comes back
* `progress-actions`\[list] - actions proceeded to keep inform the the player that he is in afk area
* `entering-actions`\[list] - actions proceeded when the player has entered the afk world
* `quiting-actions`\[list] - actions proceeded when the player has left the afk world

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
#
# Each type of reward has different specifications.
# All currently supported types can be found on:
# https://revivalo.gitbook.io/ultimaterewards/
#
type: world_afk_reward
#
# Reward tag
#
tag: World Afk Reward
# World where the AFK time is computed
world: afk
# Required AFK time to obtain reward (in minutes)
required-time: 2
# Should the progress reset if the
# player leave the world?
reset-on-leave: true
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleWorldAfkReward
#
# When player has this permission,
# following properties will be shown.
#
# When the reward is currently claimable:
enter-actions:
  - "[subtitle] &aEntered AFK world!"
quit-actions:
  - "[subtitle] &cLeft AFK world"
progress-actions:
  - "[actionbar] &eNext Reward: %progress%"
#
# 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
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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% gold_nugget 1 '
  - '[sound] BLOCK_NOTE_PLING'
  - '[subtitle] &aYou have received a reward!'
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.exampleAreaAfkReward.premium
    actions:
      80:
        - '[console] give %player% gold_ingot 1'
        - '[subtitle] &eYou have received a premium reward!'
      20:
        - '[console] give %player% gold_ingot 1'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[message] &6&lWOW! You are a lucky player, received 1 diamond!'
        - '[console] give %player% diamond 1'
```

{% endcode %}


# Area Afk Reward

In the chosen area (region), the player receives periodically, as in [World Afk Reward](/configuration/rewards/reward-types/afk-reward/world-afk-reward), configured rewards.

### Area Selection Process

Before the selection be sure you have created the .yml file of the reward.\
Obtain the area (region) selection tool by:

* `/afkselection <rewardName>`

Then this tool is used to select two points bordering the area (region) by using the left button to select the first point (corner) and the right button to select the second point (corner) of the area (region). The selection is confirmed with the command:

* `/afkselection confirm <rewardName>`

{% embed url="<https://youtu.be/JmhWSjYhmnE>" %}
Video Tutorial
{% endembed %}

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
#
# Each type of reward has different specifications.
# All currently supported types can be found on:
# https://revivalo.gitbook.io/ultimaterewards/
#
type: area_afk_reward
#
# Reward tag
#
tag: Area Afk Reward
# Area (region) where the AFK time is computed.
area:
  first-corner-location:
  second-corner-location:
# Required AFK time to obtain reward (in minutes)
required-time: 2
# Should the progress reset if the
# player leave the world?
reset-on-leave: true
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleAreaAfkReward
#
# When player has this permission,
# following properties will be shown.
#
# When the reward is currently claimable:
enter-actions:
  - "[subtitle] &aEntered AFK area!"
quit-actions:
  - "[subtitle] &cLeft AFK area"
progress-actions:
  - "[actionbar] &eNext Reward: %progress%"
#
# 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
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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% gold_nugget 1 '
  - '[sound] BLOCK_NOTE_PLING'
  - '[subtitle] &aYou have received a reward!'
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.exampleAreaAfkReward.premium
    actions:
      80:
        - '[console] give %player% gold_ingot 1'
        - '[subtitle] &eYou have received a premium reward!'
      20:
        - '[console] give %player% gold_ingot 1'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[message] &6&lWOW! You are a lucky player, received 1 diamond!'
        - '[console] give %player% diamond 1'
```

{% endcode %}


# Region Afk Reward

The settings are identical with [World Afk Reward](/configuration/rewards/reward-types/afk-reward/world-afk-reward), except that instead of the world you set the regions from the [WorldGuard](https://dev.bukkit.org/projects/worldguard) plugin in which the AFK timer will be activated.

* `regions`\[list] - regions where AFK is applied

### Example Configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
#
# Each type of reward has different specifications.
# All currently supported types can be found on:
# https://ultimaterewards.athelion.eu/
#
type: region_afk_reward
#
# Reward tag
#
tag: Region Afk Reward
# Area (region) where the AFK time is computed.
regions:
  - "exampleRegion"
  - "anotherRegion"
# Required AFK time to obtain reward (in minutes)
required-time: 2
# Should the progress reset if the
# player leave the world?
reset-on-leave: true
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleRegionAfkReward
#
# When player has this permission,
# following properties will be shown.
#
# When the reward is currently claimable:
enter-actions:
  - "[message] &aEntered AFK area!"
quit-actions:
  - "[message] &cLeft AFK area"
progress-actions:
 # - "[actionbar] &eNext Reward: %progress%" actionbar is available only in 1.12< versions
  - "[subtitle] &eNext Reward: %progress%" # %progress% variable can be edited within config.yml
#
# Commands list that will be executed after player
# obtains this reward.
# All available actions can be found on
# https://ultimaterewards.athelion.eu/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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% gold_nugget 1 '
  - '[sound] BLOCK_NOTE_PLING'
  - '[subtitle] &aYou have received a reward!'
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.exampleRegionAfkReward.premium
    actions:
      80:
        - '[console] give %player% gold_ingot 1'
        - '[subtitle] &eYou have received a premium reward!'
      20:
        - '[console] give %player% gold_ingot 1'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[message] &6&lWOW! You are a lucky player, received 1 diamond!'
        - '[console] give %player% diamond 1'
```

{% endcode %}


# Advent Calendar

Advent calendar type daily rewards

An Advent calendar is a festive countdown to Christmas. It typically has 24 days, each concealing a reward. One reward is opened each day from December 1st to 24th, building anticipation for Christmas Day.

{% hint style="info" %}
To reset progress rewards for all players, use `/rw reset **`
{% endhint %}

* `month` \[text] - selects the active month for the reward
* `show-amount-as-days` \[true/false] - display the quantity of items based on the day of the month
* `recursive-claiming` \[true/false] - allows to claim previous days
* `recursive-claiming-permission` \[text] - players with this permission can claim recursively
* `starting-day` \[number] -starting on the day from which it is possible to collect (default 1st day)
* `ending-day` \[number] - ending day until which it is possible to collect (default 24th day)
* `days` \[list] - setting the length and content of each day of calendar

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: advent_calendar
#
# Reward tag
#
tag: Advent Calendar
# Set active month
month: DECEMBER
starting-day: 1
ending-day: 24
# Display the quantity of items
# based on the day of the month.
show-amount-as-days: true
# Allow recursive claiming
recursive-claiming: true
# Players with this permission
# can claim recursively
recursive-claiming-permission: adventcalendar.recursive
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleAdventCalendar
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN <1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player can claim this reward,
# it will be shown as this:
#
# %lore% will be replaced with each day's lore
# defined at the bottom of the page.
available-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTNlOWY0ZGJhZGRlMGY3MjdjNTgwM2Q3NWQ4YmIzNzhmYjlmY2I0YjYwZDMzYmVjMTkwOTJhM2EyZTdiMDdhOSJ9fX0=
available-display-name: '&a&lADVENT CALENDAR #%day%'
available-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&b► Ready to be claimed'
# When the player can't claim this reward right now,
# it will be shown as this:
unavailable-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzY1ZjNiYWUwZDIwM2JhMTZmZTFkYzNkMTMwN2E4NmE2MzhiZTkyNDQ3MWYyM2U4MmFiZDlkNzhmOGEzZmNhIn19fQ==
unavailable-display-name: '&c&lADVENT CALENDAR #%day%'
unavailable-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&c ► %day%.%month%. was claimed'
# The next day will be marked, and
# it will be shown as this:
upcoming-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvN2FmNmZhYjc2N2NhNGQ3ZGY2MjE3Yjg5NWI2NjdiY2FjYzUyNGQ0MDcwNjg2MTlmODE5YTA3MGYzZjYyOWNlMCJ9fX0=
upcoming-display-name: '&8&lADVENT CALENDAR #%day%'
upcoming-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&7► This reward will be'
  - '&7  available on %day%.%month%.'
# The claimed day will be shown as this:
claimed-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzMyOGRjZGUxNzNiZWZmOWYzZjQxYjkyMzIxM2ZjMWJiNzY3ODk2N2NjYjJlZGU3YTdjZjQwYjE4MzZiMWE3MyJ9fX0=
claimed-display-name: '&7&lADVENT CALENDAR #%day%'
claimed-lore:
  - '&7 This calendar day'
  - '&7 has already passed!'
#
# When the specified month does not
# match the current month, this setting appears.
#
inactive-month-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNTE4OWYzNDdmNDI0NTBjZDJhMmU5YjhhNTM5ODgwN2QyOGM3ZjQyNTRiZDk5YThhNDk5Y2U1NDM1MzIwOTU1In19fQ==
inactive-month-display-name: "&6&lADVENT CALENDAR #%day%"
inactive-month-lore:
  - ' '
  - '&e ► Reward will be available'
  - '&e   on %day%.%month%.'
#
# When the player doesn't have the reward's permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mADVENT CALENDAR #%day%"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Note that the rewards (actions) are only illustrative,
# and you can edit as you wish
#
# 1: # first day of month
#   actions: # List of actions executed after claiming a reward
#     - <| list of actions |>
# 2: # second day
#    <| another reward configuration |>
#
days:
  1:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 1st day!"
  2:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 2nd day!"
  3:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 3rd day!"
  4:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 4th day!"
  5:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 5th day!"
  6:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 6th day!"
  7:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 7th day!"
  8:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 8th day!"
  9:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 9th day!"
  10:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 10th day!"
  11:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 11st day!"
  12:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 12nd day!"
  13:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 13rd day!"
  14:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 14th day!"
  15:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 15th day!"
  16:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 16th day!"
  17:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 17th day!"
  18:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 18th day!"
  19:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 19th day!"
  20:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 20th day!"
  21:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 21st day!"
  22:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 22nd day!"
  23:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 23rd day!"
  24:
    lore:
      - '&7Contains:'
      - '&f 16x Netherite Ingots'
    actions:
      - "[console] give %player% netherite_ingot 16"
      - "[firework]"
      - "[subtitle] &aObtained 24th day!"

```

{% endcode %}


# Pickable Reward

The reward is designed in such a way that the player can select from the available options only some rewards whose content is not visible before claiming.

* `picks` \[number] - how many rewards a player can pick (collect)
* `pick-rewards` \[list] - individual rewards from which the player can choose

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FcWaeet6w9zwgH82YGDmH%2Fezgif-4-5e38157a48.gif?alt=media&amp;token=12b5e753-7f72-4dfe-9116-c325c02c5ffb" alt=""><figcaption><p>Preview</p></figcaption></figure>

### Example configuration

#### examplePickableReward.yml

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: pickable_reward
#
# Reward tag
#
tag: Pickable Reward
# How many picks the player has available.
picks: 3
# When will the reward be available again
# after claiming.
cooldown: 24
# Unit used for cooldown
unit: hours # So the cooldown is 24 hours
#
# Format which will be used to show the
# general cooldown of this reward.
#
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# when using the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
# Make the reward available for the player
# after their first join on the server.
available-after-first-join: true
# Notifies players that the reward is currently available
live-reminder-enabled: true
# How many free slots should the player have
# to be able to claim this reward.
required-slots: 3
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.examplePickableReward
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN 1.12 & 1.13 VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player has this permission,
# the following properties will be shown...
#
# When the reward is currently claimable:
available-item: LIME_STAINED_GLASS_PANE
available-display-name: '&b&lPICKABLE REWARD'
available-lore:
  - ' '
  - '&7Can contains:'
  - '&a ✓ Diamond'
  - '&a ✓ Iron Ingot'
  - '&a ✓ Coal'
  - '&a ✓ Netherite Ingot'
  - '&5 ✓ Mystery Reward'
  - ' '
  - '&e► Click to pick &8(%picks% pick(s) remain)'
# When the reward is under cooldown:
unavailable-item: RED_STAINED_GLASS_PANE
unavailable-display-name: "&7&lPICKABLE REWARD"
unavailable-lore:
  - '&7Available in:'
  - '&7%cooldown%'
# The claimed reward will be shown as this:
# The preview item will be displayed
claimed-display-name: '&7&lPICKABLE REWARD'
claimed-lore:
  - '&7 Claimed'
#
# On the other hand, when the player doesn't have this permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mPICKABLE REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Rewards that will be randomly placed for individual selection of them
# for individual selection (through menu) of them.
# All available actions and format examples can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
pick-rewards:
  1:
    preview-item: COAL
    display-name: "&8COAL :("
    lore:
      - "&7Obtained:"
      - "&e 1x Coal"
    actions:
      - "[console] minecraft:give %player% coal 1"
  2:
    preview-item: COAL
    display-name: "&8COAL :("
    lore:
      - "&7Obtained:"
      - "&e 1x Coal"
    actions:
      - "[console] minecraft:give %player% coal 1"
  3:
    preview-item: COAL
    display-name: "&8COAL :("
    lore:
      - "&7Obtained:"
      - "&e 1x Coal"
    actions:
      - "[console] minecraft:give %player% coal 1"
  4:
    preview-item: COAL
    display-name: "&8COAL :("
    lore:
      - "&7Obtained:"
      - "&e 1x Coal"
    actions:
      - "[console] minecraft:give %player% coal 1"
  5:
    preview-item: COAL
    display-name: "&8COAL :("
    lore:
      - "&7Obtained:"
      - "&e 1x Coal"
    actions:
      - "[console] minecraft:give %player% coal 1"
  6:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  7:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  8:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  9:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  10:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  11:
    preview-item: IRON_INGOT
    display-name: "&7IRONS :/"
    lore:
      - "&7Obtained:"
      - "&e 1x Iron Ingot"
    actions:
      - "[console] minecraft:give %player% iron_ingot 1"
  12:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  13:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  14:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  15:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  16:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  17:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  18:
    preview-item: DIAMOND
    display-name: "&bDIAMONDS!!!"
    lore:
      - "&7Obtained:"
      - "&e 1x Diamond"
    actions:
      - "[console] minecraft:give %player% diamond 1"
  19:
    preview-item: NETHERITE_INGOT
    display-name: "&dNETHERITE INGOTS :O"
    lore:
      - "&7Obtained:"
      - "&e 1x Netherite Ingot"
    actions:
      - "[console] minecraft:give %player% netherite_ingot 1"
  20:
    preview-item: NETHERITE_INGOT
    display-name: "&dNETHERITE INGOTS :O"
    lore:
      - "&7Obtained:"
      - "&e 1x Netherite Ingot"
    actions:
      - "[console] minecraft:give %player% netherite_ingot 1"
  21:
    preview-item: NETHERITE_INGOT
    display-name: "&dNETHERITE INGOTS :O"
    lore:
      - "&7Obtained:"
      - "&e 1x Netherite Ingot"
    actions:
      - "[console] minecraft:give %player% netherite_ingot 1"
  22:
    preview-item: NETHERITE_INGOT
    display-name: "&dNETHERITE INGOTS :O"
    lore:
      - "&7Obtained:"
      - "&e 1x Netherite Ingot"
    actions:
      - "[console] minecraft:give %player% netherite_ingot 1"
  23:
    preview-item: NETHERITE_INGOT
    display-name: "&dNETHERITE INGOTS :O"
    lore:
      - "&7Obtained:"
      - "&e 1x Netherite Ingot"
    actions:
      - "[console] minecraft:give %player% netherite_ingot 1"
  24:
    preview-item: TOTEM_OF_UNDYING
    display-name: "&6TOTEM OF UNDYING"
    lore:
      - "&7Obtained:"
      - "&e 1x Totem of Undying"
    actions:
      - "[console] minecraft:give %player% totem_of_undying 1"
  25:
    preview-item: TOTEM_OF_UNDYING
    display-name: "&6TOTEM OF UNDYING"
    lore:
      - "&7Obtained:"
      - "&e 1x Totem of Undying"
    actions:
      - "[console] minecraft:give %player% totem_of_undying 1"
  26:
    preview-item: TOTEM_OF_UNDYING
    display-name: "&6TOTEM OF UNDYING"
    lore:
      - "&7Obtained:"
      - "&e 1x Totem of Undying"
    actions:
      - "[console] minecraft:give %player% totem_of_undying 1"
  27:
    preview-item: FIREWORK
    display-name: "&5&lMYSTERY REWARD"
    lore:
      - "&7Obtained:"
      - "&d 1x  Spawner"
      - "&d 64x Experience Bottle"
      - "&d 16x Enchanted Golden Apple"
    actions:
      - "[broadcast] &5Player %player% just received &lMystery Reward&5 from Pickable Reward"
      - "[console] minecraft:give %player% spawner 1"
      - "[console] minecraft:give %player% experience_bottle 64"
      - "[console] minecraft:give %player% enchanted_golden_apple 16"
```

{% endcode %}

#### guis.yml

{% code fullWidth="true" %}

```yaml
pickableRewards:
  title: Pickable Rewards
  rows: 4
  content:
    '0': examplePickableReward:1
    '1': examplePickableReward:2
    '2': examplePickableReward:3
    '3': examplePickableReward:4
    '4': examplePickableReward:5
    '5': examplePickableReward:6
    '6': examplePickableReward:7
    '7': examplePickableReward:8
    '8': examplePickableReward:9
    '9': examplePickableReward:10
    '10': examplePickableReward:11
    '11': examplePickableReward:12
    '12': examplePickableReward:13
    '13': examplePickableReward:14
    '14': examplePickableReward:15
    '15': examplePickableReward:16
    '16': examplePickableReward:17
    '17': examplePickableReward:18
    '18': examplePickableReward:19
    '19': examplePickableReward:20
    '20': examplePickableReward:21
    '21': examplePickableReward:22
    '22': examplePickableReward:23
    '23': examplePickableReward:24
    '24': examplePickableReward:25
    '25': examplePickableReward:26
    '26': examplePickableReward:27
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'
```

{% endcode %}


# Time Reward

Cooldown-defined reward

A time reward is a periodically recurring reward with a certain cooldown that specifies how long it takes for the reward to become available again. In the configuration, we work with the following attributes:

* `cooldown`\[number] - specified in hours, this attribute indicates how long it takes for the reward to become available again
* `unit` \[hours/minutes/seconds] - unit used for cooldown
* `cooldown-format` \[text] - the format that is subsequently used in the placeholder for the cooldown of this reward
* `cooldown-general-format` \[text] - is used for the placeholder where the reward cooldown is formatted in %days%, %hours% and %minutes%. For example, if a reward has a cooldown of 2 days, it will return 2 for %days%, 48 for %hours% and 2880 for %minutes%
* `available-after-first-join` \[true/false] - specifies whether the reward is available on the player's first join or not, and forces the player to wait until the specified cooldown has ended.

The reward's display in the inventory can then be specified, with the reward being considered in several states:

* `available` state - the reward is currently obtainable
* `unavailable` state - the reward is under cooldown
* `no-permission` state - the player does not have permission for the reward

Custom configurations for the display name, lore, and material of the reward's item are available for all of these states.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: time_reward
#
# Reward tag
#
tag: Time Reward
# Claiming command, /timereward in this example
command: timereward
# When will the reward be available again
# after claiming.
cooldown: 24
# Unit used for cooldown
unit: hours # So the cooldown is 24 hours
#
# Format which will be used to show the
# general cooldown of this reward.
#
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# when using the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
# Make the reward available for the player
# after their first join on the server.
available-after-first-join: false
# Notifies players that the reward is currently available
live-reminder-enabled: true
# How many free slots should the player have
# to be able to claim this reward.
required-slots: 3
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleTimeReward
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN 1.12 & 1.13 VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player has this permission,
# the following properties will be shown...
#
# When the reward is currently claimable:
available-item: CHEST_MINECART
available-display-name: '&a&lTIME REWARD'
available-lore:
  - '&7Can be obtained every &f%cooldown%'
  - ' '
  - '&7Contains:'
  - '&e ➪ 1x Diamond'
  - '&e ➪ 3x Gold Ingot'
  - '&e ➪ 6x Iron Ingot'
  - ' '
  - '&b► Click to claim'
# When the reward is under cooldown:
unavailable-item: MINECART
unavailable-display-name: "&7&lTIME REWARD"
unavailable-lore:
  - '&7Available in:'
  - '&7%cooldown%'
#
# On the other hand, when the player doesn't have this permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mTIME REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions and format examples can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: [] - required value | () - optional value
#   [<actionType>] <command>
#
# Examples:
#   (<chance>):
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from randoms.yml file and use them in a command.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  100:
    - '[console] give %player% diamond 1'
    - '[console] give %player% gold_ingot 3'
    - '[console] give %player% iron_ingot 6'
    - '[console] say %player% claimed their %type% reward!'
    #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
    - '[message] &7Enjoy your claimed reward | New line!'
  20:
    - '[console] give %player% diamond 1'
    - '[console] give %player% gold_ingot 3'
    - '[console] give %player% iron_ingot 6'
    - '[console] say %player% claimed their %type% reward!'
    #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
    - '[message] &7Enjoy your claimed reward | New line!'
    - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
    - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
    - '[message] &a&lYou have been extra lucky today! Received 5 more diamonds!'
    - '[console] give %player% diamond 5'
#
# Variants for this reward can be added here.
# If you don't want any, delete the variants section.
#
# Which variant will be available for the player depends on their permission.
# You can add as many variants as you want.
#
variants:
  premium:
    permission: ultimaterewards.timeRewardExample.premium
    available-display-name: "&6&lPREMIUM TIME REWARD"
    available-lore:
      - '&7Can be obtained every &f%cooldown%'
      - ' '
      - '&7Contains:'
      - '&e ➪ 3x Diamonds'
      - '&e ➪ 12x Gold Ingots'
      - '&e ➪ 24x Iron Ingots'
      - ' '
      - '&6► Click to claim premium reward'
    actions:
      80:
        - '[console] give %player% diamond 3'
        - '[console] give %player% iron_ingot 12'
        - '[console] give %player% gold_ingot 24'
        - '[console] say %player% claimed their %type% reward!'
        #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
        - '[title] &aClaimed'
        - '[subtitle] &aReward %type%'
        - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
      20:
        - '[console] give %player% diamond 3'
        - '[console] give %player% iron_ingot 12'
        - '[console] give %player% gold_ingot 24'
        - '[console] say %player% claimed their %type% reward!'
        #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
        - '[title] &aClaimed'
        - '[subtitle] &aReward %type%'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
        - '[message] &6&lYou have been extra lucky today! | Received 10 more diamonds!'
        - '[console] give %player% diamond 10'
```

{% endcode %}


# Time Fixed Reward

Reward resetting at the exact moment

Unlike [Time Reward](https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/reward-types/time-reward) type, where you must wait until the next day to claim the reward starting from the time you claimed it the previous day. Here the reward resets at the exact time given without any cooldown.

The following are used to specify on which days the reward should be reset:

* `reset-days` - list of days and time when the reward is reset

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: time_fixed_reward
#
# Reward tag
#
tag: Time Fixed Reward
# Specify the days and time
# when the reward will reset.
reset-days:
  - MONDAY-18:00
  - TUESDAY-18:00
  - WEDNESDAY-18:00
  - THURSDAY-18:00
  - FRIDAY-18:00
  - SATURDAY-18:00
  - SUNDAY-18:00
# How many free slots should the player have
# to be able to claim this reward.
required-slots: 3
#
# Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleTimeFixedReward
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player has this permission,
# the following properties will be shown...
#
# When the reward is currently claimable:
available-item: CHEST_MINECART
available-display-name: '&a&lTIME FIXED REWARD'
available-lore:
  - '&7Reward resets &feveryday'
  - '&7at &f&l6:00 PM'
  - ' '
  - '&7Contains:'
  - '&e ➪ 1x Diamond'
  - '&e ➪ 3x Gold Ingot'
  - '&e ➪ 6x Iron Ingot'
  - ' '
  - '&b► Click to claim'
# When the reward is unavailable:
unavailable-display-name: '&c&lTIME FIXED REWARD'
unavailable-lore:
  - '&cReward resets &4everyday'
  - '&cat &4&l6:00 PM'
  - ' '
  - '&7Contains:'
  - '&8 ➪ 1x Diamond'
  - '&8 ➪ 3x Gold Ingot'
  - '&8 ➪ 6x Iron Ingot'
  - ' '
unavailable-item: MINECART
#
# On the other hand, when the player doesn't have this permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: '&a&lTIME FIXED REWARD'
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions and format examples can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: [] - required value | () - optional value
#   [<actionType>] <command>
#
# Examples:
#   (<chance>):
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from randoms.yml file and use them in a command.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  80:
    - '[console] give %player% diamond 1'
    - '[console] give %player% gold_ingot 3'
    - '[console] give %player% iron_ingot 6'
    - '[console] say %player% claimed their %type% reward!'
    #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
  20:
    - '[console] give %player% diamond 1'
    - '[console] give %player% gold_ingot 3'
    - '[console] give %player% iron_ingot 6'
    - '[console] say %player% claimed their %type% reward!'
    #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
    - '[message] &a&lYou have been extra lucky today! Received 5 more diamonds!'
    - '[console] give %player% diamond 5'
    - '[firework]'
```

{% endcode %}


# Streak Reward

Progressive unlocking reward

The streak reward is designed such that you can earn any number of rewards that follow one after the other, and it is necessary to collect the previous reward in order to unlock the next one.

This type of reward has also the following states, which are in addition to time-based rewards:

* `upcoming` state - this status represents the rewards that follow the current reward (locked until the previous reward is claimed)
* `claimed` state - this state is reached when the current streak level has already been claimed

Streak rewards can also be configured to reset the streak progress after a time period equal to twice its cooldown has elapsed or not, using the following attribute:

* `resetting` \[true/false] - if the reward should be reset, that is, if the reset time should be tracked (the time window in which the player must select the reward otherwise the streak resets to 0)
* `reset-after-completing` \[true/false] - if resetting is set to false then this can be used to specify whether the reward should be reset when the player reaches the last strike
* `reset-time` \[number] - determine the time a player has to claim a streak for a reward streak
* `numbering-type` \[text] - available types:
  * NORMAL (1, 2, 3, 4)
  * ROMAN (I, II, III, IV)
* `show-amount-of-the-streaks` \[true/false] - sets the individual streak level corresponding to the rewards' item to the amount of the item in the inventory (amount of item)
* `streaks` \[list] - setting the length and content of single streak reward.

  &#x20;  Each single streak then has the following properties

  * `lore` \[list] - reward's description
  * `actions` \[list] - a list of actions that will be performed after the streak is claimed

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: streak_reward
#
# Reward tag
#
tag: Streak Reward
# When will be the next streak available
# after claiming the previous one.
cooldown: 24
# Unit used for cooldown
unit: hours # So the cooldown is 24 hours
# You can set the numbering type. Available types:
#   - NORMAL
#   - ROMAN
numbering-type: ROMAN
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleStreakReward
#
# Format which will be used to show the
# general cooldown of this reward.
#
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# on the usage of the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
#
# If set to true, the streak progress will reset if
# the player misses the claim schedule.
#
resetting: true
#
# If resetting is set to false, you can specify
# whether it should be reset when the player reaches the final streak.
#
reset-after-completing: true
#
# Reset time indicates how long
# the player has to collect the current streak
# (default 24 hours)
#
reset-time: 24
# Notifies players that the reward is currently available
live-reminder-enabled: true
# Make the reward available for the player
# after their first join on the server.
available-after-first-join: true
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN <1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player can claim this reward,
# it will be shown as this:
#
# %lore% will be replaced with each streak's lore
# defined at the bottom of the page.
available-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTNlOWY0ZGJhZGRlMGY3MjdjNTgwM2Q3NWQ4YmIzNzhmYjlmY2I0YjYwZDMzYmVjMTkwOTJhM2EyZTdiMDdhOSJ9fX0=
available-display-name: '&a&lSTREAK REWARD #%number%'
available-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&b► Ready to be claimed'
# When the player can't claim this reward right now,
# it will be shown as this:
unavailable-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzY1ZjNiYWUwZDIwM2JhMTZmZTFkYzNkMTMwN2E4NmE2MzhiZTkyNDQ3MWYyM2U4MmFiZDlkNzhmOGEzZmNhIn19fQ==
unavailable-display-name: '&c&lSTREAK REWARD #%number%'
unavailable-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&c ► Available in:'
  - '&4   %cooldown%'
# The next streak reward will be marked, and
# it will be shown as this:
upcoming-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvN2FmNmZhYjc2N2NhNGQ3ZGY2MjE3Yjg5NWI2NjdiY2FjYzUyNGQ0MDcwNjg2MTlmODE5YTA3MGYzZjYyOWNlMCJ9fX0=
upcoming-display-name: '&8&lSTREAK REWARD #%number%'
upcoming-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&7► Claim rewards before'
  - '&7  to achieve this reward!'
# The claimed streak will be shown as this:
claimed-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzMyOGRjZGUxNzNiZWZmOWYzZjQxYjkyMzIxM2ZjMWJiNzY3ODk2N2NjYjJlZGU3YTdjZjQwYjE4MzZiMWE3MyJ9fX0=
claimed-display-name: '&7&lSTREAK REWARD #%number%'
claimed-lore:
  - '&7 Claimed'
#
# When the player doesn't have the reward's permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mSTREAK REWARD #%number%"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Sets the number of items in the GUI menu
# according to the corresponding streak.
#
show-amount-of-the-streaks: true
#
# A streak can have an optional length,
# generally, when creating a streak, you should follow
# this pattern:
#
# 1: # first streak
#   use-firework: <true/false> # optional value
#   actions: # List of actions executed after claiming a reward
#     - <| list of actions |>
# 2: # second streak
#    <| another streak reward configurations |>
#
streaks:
  1:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 1st streak!"
  2:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 2nd streak!"
  3:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 3rd streak!"
  4:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 4th streak!"
  5:
    lore:
      - '&7Contains:'
      - '&d 1x Netherite Ingot'
    actions:
      - "[console] give %player% netherite_ingot 1"
      - "[title] &bGreat Job!"
      - "[subtitle] &aObtained final streak!"
      - "[firework]"


```

{% endcode %}


# Streak Fixed Reward

Streak reward resetting at the exact moment

This type of reward, unlike the classic [Streak Reward](https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/reward-types/streak-reward), resets the reward at a specific time in the day specified by the parameter:

* `reset-time` \[number] - time of the day (in 24-hour clock format)

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: streak_fixed_reward
#
# Reward tag
#
tag: Streak Fixed Reward
# What time of the day to reset the reward.
# (18:00 -> 6:00 PM)
reset-time: '18:00'
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleStreakFixedReward
#
# Format which will be used to show the
# general cooldown of this reward.
#
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# on the usage of the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
#
# If set to true, the streak progress will reset if
# the player misses the claim schedule.
#
resetting: true
# Make the reward available for the player
# after their first join on the server.
available-after-first-join: true
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN <1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player can claim this reward,
# it will be shown as this:
#
# %lore% will be replaced with each streak's lore
# defined at the bottom of the page.
available-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTNlOWY0ZGJhZGRlMGY3MjdjNTgwM2Q3NWQ4YmIzNzhmYjlmY2I0YjYwZDMzYmVjMTkwOTJhM2EyZTdiMDdhOSJ9fX0=
available-display-name: '&a&lSTREAK FIXED REWARD #%number%'
available-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&b► Ready to be claimed'
# When the player can't claim this reward right now,
# it will be shown as this:
unavailable-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzY1ZjNiYWUwZDIwM2JhMTZmZTFkYzNkMTMwN2E4NmE2MzhiZTkyNDQ3MWYyM2U4MmFiZDlkNzhmOGEzZmNhIn19fQ==
unavailable-display-name: '&c&lSTREAK FIXED REWARD #%number%'
unavailable-lore:
  - '&8The reward is reset'
  - '&8every day at 18:00'
  - ' '
  - '%lore%'
  - ' '
  - '&c ► Available in:'
  - '&4   %cooldown%'
# The next streak reward will be marked, and
# it will be shown as this:
upcoming-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvN2FmNmZhYjc2N2NhNGQ3ZGY2MjE3Yjg5NWI2NjdiY2FjYzUyNGQ0MDcwNjg2MTlmODE5YTA3MGYzZjYyOWNlMCJ9fX0=
upcoming-display-name: '&8&lSTREAK FIXED REWARD #%number%'
upcoming-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&7► Claim rewards before'
  - '&7  to achieve this reward!'
# The claimed streak will be shown as this:
claimed-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzMyOGRjZGUxNzNiZWZmOWYzZjQxYjkyMzIxM2ZjMWJiNzY3ODk2N2NjYjJlZGU3YTdjZjQwYjE4MzZiMWE3MyJ9fX0=
claimed-display-name: '&7&lSTREAK FIXED REWARD #%number%'
claimed-lore:
  - '&7 Claimed'
#
# When the player doesn't have the reward's permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mSTREAK FIXED REWARD #%number%"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Sets the number of items in the GUI menu
# according to the corresponding streak.
#
show-amount-of-the-streaks: true
#
# A streak can have an optional length,
# generally, when creating a streak, you should follow
# this pattern:
#
# 1: # first streak
#   use-firework: <true/false> # optional value
#   actions: # List of actions executed after claiming a reward
#     - <| list of actions |>
# 2: # second streak
#    <| another streak reward configurations |>
#
streaks:
  1:
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 1st streak!"
  2:
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 2nd streak!"
  3:
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 3rd streak!"
  4:
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 4th streak!"
  5:
    use-firework: true
    lore:
      - '&7Contains:'
      - '&d 1x Netherite Ingot'
    actions:
      - "[console] give %player% netherite_ingot 1"
      - "[title] &bGreat Job!"
      - "[subtitle] &aObtained final streak!"


```

{% endcode %}


# Vote Reward

Reward for voting on voting sites

To claim a vote reward, a player is required to have a certain number of votes for the server, which means that the reward has a mandatory attribute:

* `required-votes` \[number] - the number required to achieve this reward.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: vote_reward
#
# Reward tag
#
tag: Vote Reward
#
# Permission which the player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleVote
#
# Required votes to achieve this reward.
#
required-votes: 20
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player achieves the required votes,
# this version of the reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lVOTE REWARD"
available-lore:
  - "&7You have collected"
  - "&7enough votes to obtain"
  - "&7this reward!"
  - " "
  - "&b► Click to claim!"
#
# Whereas when the player doesn't have enough required votes,
# this version of the reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lVOTE REWARD"
unavailable-lore:
  - "&7You need to collect"
  - "&7enough votes to be able to obtain"
  - "&7this reward!"
  - " "
  - "&4► Requires another %requiredVotes% votes"
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7&lVOTE REWARD"
claimed-lore:
  - "&7You have already"
  - "&7claimed this reward"
  - "&7for %votes% votes!"
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mVOTE REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: [] - required value | () - optional value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from randoms.yml file and use them in a command.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% diamond 1'
  - '[console] say %player% claimed their %type% reward!'
  - '[message] &7You have claimed the vote reward for |&7 20 votes! Keep up the great work.'
#  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'

```

{% endcode %}


# Renewable Vote Reward

Re-unlockable reward

The vote-based renewable reward system functions by players casting votes for a server. Once they reach a certain number of votes, they unlock specific rewards. After claiming the reward, the vote counter resets, and players must cast a new set of votes to access the subsequent reward. This cyclic system motivates players to consistently vote and support the server in order to continually earn and re-earn rewards.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: renewable_vote_reward
#
# Reward tag
#
tag: Renewable Vote Reward
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleRenewableVoteReward
#
# Required votes to achieve this reward.
#
required-votes: 5
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player achieves the required votes,
# this version of the reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lRENEWABLE VOTE REWARD"
available-lore:
  - "&7You have collected"
  - "&7enough votes to obtain"
  - "&7this reward!"
  - " "
  - "&b► Click to claim!"
#
# Whereas when the player doesn't have enough required votes,
# this version of the reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lRENEWABLE VOTE REWARD"
unavailable-lore:
  - "&7You need to collect"
  - "&7enough votes to be able to obtain"
  - "&7this reward!"
  - " "
  - "&4► Requires another %requiredVotes% votes"
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mRENEWABLE VOTE REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found on
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: [] - required value | () - optional value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from randoms.yml file and use them in a command.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% diamond 1'
  - '[console] say %player% claimed their %type% reward!'
  - '[message] &7You have claimed the vote reward for |&7 20 votes! Keep up the great work.'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# Per Vote Reward

Rewards per vote

Unlike the other vote reward types, a per-vote reward is granted for **every single vote** the server receives, immediately when the vote arrives. It is not configured in the `rewards` folder — all settings regarding voting live in **votes.yml**.

{% hint style="info" %}
Votes are received through [Votifier](https://www.spigotmc.org/resources/nuvotifier.13449/), so it has to be installed and configured on the server.
{% endhint %}

## Configuration

{% code fullWidth="true" %}

```yaml
# Enable vote handling and the vote command
enabled: true

# Determines whether incoming votes should be
# logged in the console for monitoring purposes.
log-incoming-votes: true

# Specifies whether votes should only be counted
# when the player is online.
count-only-when-online: false
# If it is set to false, it will proceed
# the vote even for unregistered players.
count-before-first-join: true

# Enables a per-vote reward system, allowing for
# customized rewards.
enable-per-vote-rewards: true

# Broadcast a message whenever a vote is received
announce-received-vote: true
received-vote-announcement:
  - "&b&lULTIMATEREWARDS&8 ► &7Player %player% has voted for our server on %service%"

per-vote-rewards:
  example:
    permission: ultimaterewards.votes.example
    required-slots: 1
    actions:
      - "[console] give %player% emerald 1"
  anotherExample:
    permission: ultimaterewards.votes.anotherExample
    actions:
      - "[message] Thanks for voting for us!"
      - "[console] give %player% diamond 1"
```

{% endcode %}

## Options

| Key                          | Description                                                                        |
| ---------------------------- | ---------------------------------------------------------------------------------- |
| `enabled`                    | Turns the whole vote handling (and the `/vote` command) on or off                  |
| `log-incoming-votes`         | Logs every received vote into the console                                          |
| `count-only-when-online`     | `true` counts only the votes of players who are currently online                   |
| `count-before-first-join`    | `true` also counts votes of players who have never joined the server               |
| `enable-per-vote-rewards`    | Turns the `per-vote-rewards` section on or off                                     |
| `announce-received-vote`     | Broadcasts `received-vote-announcement` on every received vote                     |
| `received-vote-announcement` | The broadcast text; `%player%` and `%service%` (name of the vote site) can be used |

### Per-vote reward entries

Each entry under `per-vote-rewards` is a separate reward:

| Key              | Description                                                                         |
| ---------------- | ----------------------------------------------------------------------------------- |
| `permission`     | Only players with this permission receive the entry — use it for rank-based bonuses |
| `required-slots` | How many free inventory slots the player needs                                      |
| `actions`        | The [actions](/configuration/rewards/reward-actions) executed for every vote        |

{% hint style="info" %}
A player receives **every** entry they have permission for, so entries stack. Give each rank its own permission if you want them to be exclusive.
{% endhint %}

## Related commands

| Syntax                   | Description                                              |
| ------------------------ | -------------------------------------------------------- |
| `/vote proceed <player>` | Processes a vote manually — the easiest way to test this |
| `/vote reset <player>`   | Resets the player's vote counter                         |

See [Commands](/usage/commands) for the full list.


# Streak Vote Reward

Progressive unlocking reward

Players progress in streaks based on their ability to consistently vote for the server within a specified timeframe. Their streaks advance as they successfully meet the designated number of votes required during this period.

This reward also has its own unique reward states:

* `upcoming` state - this status represents the rewards that follow the current reward (locked until the previous reward is claimed)
* `claimed` state - this state is reached when the current streak level has already been claimed

\
Relevant parameters:

* `reset-time` \[number] - determines the time window in which the player must collect a given number of votes to unlock the next streak
* `show-amount-of-the-streaks` \[true/false] - sets the individual streak level corresponding to the rewards' item to the amount of the item in the inventory (amount of item)
* `streaks` \[list] - setting the length and content of single streak reward

  &#x20; Each single streak then has the following properties

  * `data` \[number] - required votes to unlock the streak
  * `lore` \[list] - reward's description
  * `actions` \[list] - a list of actions that will be performed after the streak is claimed

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: streak_vote_reward
#
# Reward tag
#
tag: Streak Vote Reward
# You can set the numbering type. Available types:
#   - NORMAL
#   - ROMAN
numbering-type: NORMAL
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleStreakVoteReward
#
# How long does a player have to complete
# the necessary votes to unlock the current streak
#
reset-time: 24
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# on the usage of the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
#
# If set to true, the streak progress will reset if
# the player misses the claim schedule.
#
resetting: true
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN <1.12 & 1.13< VERSIONS!
# SO MAKE SURE YOU ARE USING VALID ITEM NAMES (DEFAULT ONES ARE USED FROM 1.13+ VERSIONS)
# OTHERWISE, THEY WILL BE REPLACED BY STONE IF AN INVALID NAME IS USED.
#
# When the player can claim this reward,
# it will be shown as this:
#
# %lore% will be replaced with each streak's lore
# defined at the bottom of the page.
available-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYTNlOWY0ZGJhZGRlMGY3MjdjNTgwM2Q3NWQ4YmIzNzhmYjlmY2I0YjYwZDMzYmVjMTkwOTJhM2EyZTdiMDdhOSJ9fX0=
available-display-name: '&a&lSTREAK VOTE REWARD #%number%'
available-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&b► Ready to be claimed'
# When the player can't claim this reward right now,
# it will be shown as this:
unavailable-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzY1ZjNiYWUwZDIwM2JhMTZmZTFkYzNkMTMwN2E4NmE2MzhiZTkyNDQ3MWYyM2U4MmFiZDlkNzhmOGEzZmNhIn19fQ==
unavailable-display-name: '&c&lSTREAK VOTE REWARD #%number%'
unavailable-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&c ► Required votes: &4%requiredVotes%'
  - '&c ► Remaining time: &4%cooldown%'
# The next streak reward will be marked, and
# it will be shown as this:
upcoming-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvN2FmNmZhYjc2N2NhNGQ3ZGY2MjE3Yjg5NWI2NjdiY2FjYzUyNGQ0MDcwNjg2MTlmODE5YTA3MGYzZjYyOWNlMCJ9fX0=
upcoming-display-name: '&8&lSTREAK VOTE REWARD #%number%'
upcoming-lore:
  - ' '
  - '%lore%'
  - ' '
  - '&7► Claim rewards before'
  - '&7  to achieve this reward!'
# The claimed streak will be shown as this:
claimed-item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvYzMyOGRjZGUxNzNiZWZmOWYzZjQxYjkyMzIxM2ZjMWJiNzY3ODk2N2NjYjJlZGU3YTdjZjQwYjE4MzZiMWE3MyJ9fX0=
claimed-display-name: '&7&lSTREAK VOTE REWARD #%number%'
claimed-lore:
  - '&7 Claimed'
#
# When the player doesn't have the reward's permission,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mSTREAK REWARD #%number%"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Sets the number of items in the GUI menu
# according to the corresponding streak.
#
show-amount-of-the-streaks: true
#
# A streak can have an optional length,
# generally, when creating a streak, you should follow
# this pattern:
#
# 1: # first streak
#   use-firework: <true/false> # optional value
#   actions: # List of actions executed after claiming a reward
#     - <| list of actions |>
# 2: # second streak
#    <| another streak reward configurations |>
#
streaks:
  1:
    data: 3
    lore:
      - '&7Contains:'
      - '&f 1x Coal'
    actions:
      - "[console] give %player% coal 1"
      - "[subtitle] &aObtained 1st streak!"
  2:
    data: 5
    lore:
      - '&7Contains:'
      - '&f 1x Iron Ingot'
    actions:
      - "[console] give %player% iron_ingot 1"
      - "[subtitle] &aObtained 2nd streak!"
  3:
    data: 7
    lore:
      - '&7Contains:'
      - '&f 1x Gold Ingot'
    actions:
      - "[console] give %player% gold_ingot 1"
      - "[subtitle] &aObtained 3rd streak!"
  4:
    data: 10
    lore:
      - '&7Contains:'
      - '&f 1x Diamond'
    actions:
      - "[console] give %player% diamond 1"
      - "[subtitle] &aObtained 4th streak!"
  5:
    data: 13
    lore:
      - '&7Contains:'
      - '&d 1x Netherite Ingot'
    actions:
      - "[console] give %player% netherite_ingot 1"
      - "[title] &bGreat Job!"
      - "[subtitle] &aObtained final streak!"
      - "[firework]"

```

{% endcode %}


# Play Time Reward

Reward for time spent in the game

As with vote rewards, this reward is conditional on a certain number of hours played:

* `required-hours` \[number] - the number of hours required to achieve this reward.
* `tracking` \[text] - Based on what the time played will evolve, options:
  * **LOCAL** (the time played is different for each server)
  * **GLOBAL** (time is calculated cross-server)
* `format` \[text] - The format used in the menu

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: play_time_reward
#
# Reward tag
#
tag: Play Time Reward
#
# Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.examplePlayTime
#
# Required play time (in minutes) to achieve this reward.
#
required-time: 720
# Format that replaces the %requiredTime% placeholder in the rewards menu
format: "%hours% hour(s) %minutes% minute(s)"
#
# Based on what the time played will evolve, options:
#   LOCAL (the time played is different for each server)
#   GLOBAL (time is calculated cross-server)
#
tracking: LOCAL
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves required play time,
# this version of reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lPLAY TIME REWARD"
available-lore:
  - "&7You have played"
  - "&7enough time to be able"
  - "&7obtain this reward!"
  - " "
  - "&b► Click to claim!"
#
# Whereas player doesn't have enough played time,
# this version of reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lPLAY TIME REWARD"
unavailable-lore:
  - "&7You need to spend enough"
  - "&7hours to be able obtain"
  - "&7this reward!"
  - " "
  - "&4► Requires another %requiredHours% hours"
#
# When player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7&lPLAY TIME REWARD"
claimed-lore:
  - "&7You have already"
  - "&7claimed this reward"
  - "&7for %hours% hours!"
#
# When player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mDAILY REWARD #1"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% diamond 1'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
  - '[sound] BLOCK_CHEST_OPEN'


```

{% endcode %}


# Renewable Play Time Reward

Re-unlockable reward

The play-time based renewable reward system operates on players accumulating hours within a game or platform. As they reach certain play-time thresholds, they unlock specific rewards. After claiming one, the play-time counter resets, and players must accumulate another required hours to access the next reward. This cycle continues, encouraging consistent engagement and gameplay to continually earn and re-earn rewards.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: renewable_play_time_reward
#
# Reward tag
#
tag: Renewable Play Time Reward
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleRenewablePlayTimeReward
#
# Required play time to achieve this reward.
#
required-time: 60
# Format that replaces the %requiredTime% placeholder in the rewards menu
format: "%minutes% minute(s)"
#
# Based on what the time played will evolve, options:
#   LOCAL (the time played is different for each server)
#   GLOBAL (time is calculated cross-server)
#
tracking: LOCAL
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves required play time,
# this version of reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lRENEWABLE PLAY TIME REWARD"
available-lore:
  - "&7You have played"
  - "&7enough time to be able"
  - "&7obtain this reward!"
  - " "
  - "&b► Click to claim!"
#
# Whereas player doesn't have enough played time,
# this version of reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lRENEWABLE PLAY TIME REWARD"
unavailable-lore:
  - "&7You need to spend enough"
  - "&7hours to be able obtain"
  - "&7this reward!"
  - " "
  - "&4► Requires another %requiredHours%"
#
# When player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mRENEWABLE PLAY TIME REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% diamond 1'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
  - '[sound] BLOCK_CHEST_OPEN'

```

{% endcode %}


# Referral Reward

Reward for referring players to the game

The player must achieve a given use of his referral.\
Referrals work through the player's nick. Anyone can use the `/referral create` command or the `[CREATE_REFERRAL]` action in the menu to create their. Players also need to have `ultimaterewards.referral.create` permission to be able create referral.\
\
Referrals can then be activated via the `/referral apply <player>` command or via the `[APPLY_REFERRAL]` action used in menu.\
\
It is also possible to limit when a player can create or apply a referral, more [here](https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/features/reward-requirements#checkers-for-affiliates).

* `required-uses` \[number] - the number of referral uses required to achieve this reward.

{% hint style="info" %}
The rewards a player gets after applying a referral are set in **referrals.yml**
{% endhint %}

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: referral_reward
#
# Reward tag
#
tag: Referral Reward
#
# Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleReferralReward
#
# Required referred players to achieve this reward.
#
required-uses: 5
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves the required number of referred players,
# this version of the reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a#1 &lREFERRAL"
available-lore:
  - '&8Referral reward unlocked'
  - '&8upon activation by 5 players.'
  - ' '
  - '&7Contains:'
  - '&e ➪ 16x XP Bottle'
  - ' '
  - '&b► Click to claim reward'
#
# Whereas the player doesn't have enough referred players,
# this version of the reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&4#1 &lREFERRAL"
unavailable-lore:
  - ' '
  - '&7Contains:'
  - '&7 ➪ 16x XP Bottle'
  - ' '
  - '&4► To unlock, you need to invite'
  - '&4  %players% more players!'
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7#1 &lREFERRAL"
claimed-lore:
  - ' '
  - '&7Contains:'
  - '&7 &m➪ 16x XP Bottle'
  - ' '
  - '&7 Already claimed'
  - '&7 for %uses% referrals!'
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c#1 &lREFERRAL"
no-permission-lore:
  - '&c ✕ Locked, requires'
  - '&c   %permission% permission'
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% experience_bottle 16'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# Renewable Referral Reward

Re-unlockable reward

The reward is identical to [Referral Reward](/configuration/rewards/reward-types/referral-reward) except that if the player withdraws the reward, it resets and can be withdrawn again (when the player reaches required number of referred players again)

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: renewable_referral_reward
#
# Reward tag
#
tag: Renewable Referral Reward
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleRenewableReferralReward
#
# Required referred players to achieve this reward.
#
required-uses: 3
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves the required number of referred players,
# this version of the reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a#1 &lRENEWABLE REFERRAL"
available-lore:
  - '&8Referral reward unlocked'
  - '&8upon activation by 5 players.'
  - ' '
  - '&7Contains:'
  - '&e ➪ 16x XP Bottle'
  - ' '
  - '&b► Click to claim reward'
#
# Whereas the player doesn't have enough referred players,
# this version of the reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&4#1 &lRENEWABLE REFERRAL"
unavailable-lore:
  - ' '
  - '&7Contains:'
  - '&7 ➪ 16x XP Bottle'
  - ' '
  - '&4► To unlock, you need to invite'
  - '&4  %players% more players!'
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7#1 &lRENEWABLE REFERRAL"
claimed-lore:
  - ' '
  - '&7Contains:'
  - '&7 &m➪ 16x XP Bottle'
  - ' '
  - '&7 Already claimed'
  - '&7 for %uses% referrals!'
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c#1 &lRENEWABLE REFERRAL"
no-permission-lore:
  - '&c ✕ Locked, requires'
  - '&c   %permission% permission'
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% experience_bottle 16'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# Purchasable Reward

Reward that can be bought

Rewards that a player can purchase with his balance or experience.

* `price` \[number] - required price to buy
* `economy` \[text] - used economy plugin (or experience)
  * available options:
    * **Vault**
    * **PlayerPoints**
    * **TokenManager**
    * **Experience** - will use player exp

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: purchasable_reward
#
# Reward tag
#
tag: Purchasable Reward
#
# Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.examplePurchasable
#
# Which economy plugin to use.
# Available options:
#   Experience - will use player exp
#   Vault
#   TokenManager
#   PlayerPoints
#
economy: Experience
#
# Required balance to buy this reward.
#
price: 315 # 315 experience = 15 levels (table with levels you can find here:
#                                        https://minecraft.fandom.com/wiki/Experience#Leveling_up)
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves the required amount of money,
# this version of reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lPURCHASABLE REWARD"
available-lore:
  - "&7You have enough experience"
  - "&7to obtain this reward!"
  - " "
  - "&7Contains:"
  - "&e 1x Totem Of Undying"
  - "&e 16x Golden Carrot"
  - " "
  - "&b► Click to claim for %amount% EXP"
#
# Whereas the player doesn't have enough required balance,
# this version of reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lPURCHASABLE REWARD"
unavailable-lore:
  - "&7You need to collect"
  - "&7enough experience to be able obtain"
  - "&7this reward!"
  - " "
  - "&7Contains:"
  - "&7 1x Totem Of Undying"
  - "&7 16x Golden Carrot"
  - " "
  - "&4► Requires another %amount% EXP"
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7&lPURCHASABLE REWARD"
claimed-lore:
  - "&7Contains:"
  - "&7 &m1x Totem Of Undying"
  - "&7 &m16x Golden Carrot"
  - " "
  - "&7 Already claimed"
  - "&7 for %amount% EXP!"
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mPURCHASABLE REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% golden_carrot 16'
  - '[console] give %player% totem_of_undying 1'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # MenuAction bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# Re-Purchasable Reward

Reward that can be bought repeatedly

Basically the same as [Purchasable Reward](/configuration/rewards/reward-types/purchasable-reward), but the reward can be collected repeatedly, even with cooldown:

* `cooldown`\[number] - specified in hours, this attribute indicates how long it takes for the reward to become available again
* `cooldown-format` \[text] - the format that is subsequently used in the placeholder for the cooldown of this reward
* `cooldown-general-format` \[text] - is used for the placeholder where the reward cooldown is formatted in %days%, %hours% and %minutes%. For example, if a reward has a cooldown of 2 days, it will return 2 for %days%, 48 for %hours% and 2880 for %minutes%
* `available-after-first-join` \[true/false] - specifies whether the reward is available on the player's first join or not, and forces the player to wait until the specified cooldown has ended.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable.
enabled: true
type: re_purchasable_reward
#
# Reward tag
#
tag: Re-Purchasable Reward
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleRePurchasableReward
# When will the reward be available again
# after claiming (number is in hours - 24 hours)
cooldown: 24
#
# Format which will be used to show the
# general cooldown of this reward.
#
cooldown-general-format: "%hours% hours"
#
# Format of the cooldown that will be displayed
# when using the %cooldown% placeholder in reward GUIs.
#
cooldown-format: '%hours%:%minutes%:%seconds%'
# Make the reward available for the player
# after their first join on the server.
available-after-first-join: false
# Notifies players that the reward is currently available
live-reminder-enabled: true
#
# Which economy plugin to use.
# Available options:
#   Experience - will use player exp
#   Vault
#   TokenManager
#   PlayerPoints
#
economy: Experience
#
# Required balance to buy this reward.
#
price: 160 # 160 experience = 10 levels (table with levels you can find here:
#                                        https://minecraft.fandom.com/wiki/Experience#Leveling_up)
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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 player achieves the required amount of money,
# this version of reward item is displayed in the inventory:
#
available-item: "LIME_DYE"
available-display-name: "&a&lRE-PURCHASABLE REWARD"
available-lore:
  - "&7You have enough experience"
  - "&7to obtain this reward!"
  - " "
  - "&7Can be obtained every &f%cooldown%"
  - " "
  - "&7Contains:"
  - "&e 12x Gold Ingot"
  - "&e 32x Carrot"
  - " "
  - "&b► Click to claim for %amount% EXP"
#
# Whereas the player doesn't have enough required balance,
# this version of reward item is displayed in the inventory:
#
unavailable-item: "RED_DYE"
unavailable-display-name: "&c&lRE-PURCHASABLE REWARD"
unavailable-lore:
  - "&7You need to collect"
  - "&7enough experience to be able obtain"
  - "&7this reward!"
  - " "
  - "&7Contains:"
  - "&7 12x Gold Ingot"
  - "&7 32x Carrot"
  - " "
  - "&4► Requires another %amount% EXP"
#
# When the player has already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&C&lRE-PURCHASABLE REWARD"
claimed-lore:
  - "&cContains:"
  - "&c &m12x Gold Ingot"
  - "&c &m32x Carrot"
  - " "
  - "&c You can purchase it for &4%amount% EXP"
  - "&c again in &4%cooldown%"
#
# When the player doesn't have permission for this reward,
# the following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mRE-PURCHASABLE REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
#
# Commands list that will be executed after the player
# obtains this reward.
# All available actions can be found at
# https://revivalo.gitbook.io/ultimaterewards/
#
# Format: () - optional value | [] - required value
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have a 50%
#         execution chance due to its property value
#
#   - [message] "&aYou have claimed your %type% reward!"
#       - this action will send the player a message
#         with the defined content
#
# You can also use the random placeholders
# from the randoms.yml file and use them in commands.
# Example:
#   - give %player% iron_ingot %exampleRandom%
#       - the placeholder will be replaced by
#         a random number from the defined interval in randoms.yml
#
actions:
  - '[console] give %player% carrot 32'
  - '[console] give %player% gold_ingot 12'
  - '[console] say %player% claimed his %type% reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # MenuAction bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# One Time Reward

Non-recurring reward

One-time rewards can be used as welcome bonuses or as rewards for special occasions. Like other rewards, they can be created, edited, or deleted during server runtime, so new rewards can easily be added for your players.

The only additional option is:

* `disappear` \[true/false] - whether the reward disappears from the corresponding reward GUI after it is claimed.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
type: one_time_reward
#
# Reward tag
#
tag: One Time Reward
# If set to true, reward will be removed from GUI
# after player claims it
disappear: false
#
# Permission which player must have to be
# able to obtain this reward
#
permission: ultimaterewards.oneTimeRewardExample
#
# When player has this permission,
# following properties will be shown.
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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: CHEST_MINECART
available-display-name: '&a&lWELCOME BONUS'
available-lore:
  - ' '
  - '&7Contains:'
  - '&e ➪ 1x Stone Sword'
  - '&e ➪ 1x Stone Axe'
  - '&e ➪ 1x Stone Pickaxe'
  - '&e ➪ 1x Stone Shovel'
  - '&e ➪ 16x Apple'
  - '&e ➪ 1x Red Bed'
  - ' '
  - '&b► Click to claim'
# When the reward is already claimed by player:
unavailable-display-name: "&7&lWELCOME BONUS"
unavailable-lore:
  - '&7Welcome bonus was already'
  - '&7claimed.'
unavailable-item: MINECART
#
# In the other hand when player doesn't have this permission,
# following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mWELCOME BONUS"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&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
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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% stone_sword 1'
  - '[console] give %player% stone_axe 1'
  - '[console] give %player% stone_pickaxe 1'
  - '[console] give %player% stone_shovel 1'
  - '[console] give %player% apple 16'
  - '[console] give %player% red_bed 1'
  - '[message] &aWelcome to the server, %player%! I hope these items will assist you in getting started.'
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.oneTimeRewardExample.premium
    available-display-name: "&6&lPREMIUM WELCOME BONUS"
    available-lore:
      - ' '
      - '&7Contains:'
      - '&e ➪ 1x Iron Sword'
      - '&e ➪ 1x Iron Axe'
      - '&e ➪ 1x Iron Pickaxe'
      - '&e ➪ 1x Iron Shovel'
      - '&e ➪ 32x Apple'
      - '&e ➪ 1x Red Bed'
      - ' '
      - '&6► Click to claim premium version'
      - '&6   of the reward'
    actions:
      - '[console] give %player% iron_sword 1'
      - '[console] give %player% iron_axe 1'
      - '[console] give %player% iron_pickaxe 1'
      - '[console] give %player% iron_shovel 1'
      - '[console] give %player% apple 32'
      - '[console] give %player% red_bed 1'
      - '[firework]'
      - '[message] &eWelcome to the server, %player%! I hope these items will assist you in getting started.'
```

{% endcode %}


# Time Limited Reward

Reward which is limited by time

The reward can only be collected on the given collection date by using the following properties:

* `starting-date` \[text] - date and time from which the reward can be collected
* `ending-date` \[text] - date and time by which the reward can be collected
* `date-format` \[text] - format of date which will be used in the lore

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
#
# Each type of reward has different specifications.
# All currently supported types can be found on:
# https://revivalo.gitbook.io/ultimaterewards/
#
type: time_limited_reward
#
# Reward tag
#
tag: Time Limited Reward
#
# Date from which the reward is available
# Format: <HOURS>:<MINUTES> <DAY>.<MONTH>.<YEAR>
#
starting-date: "18:00 04.03.2023"
#
# The date by which the reward can be collected
# Format: <HOURS>:<MINUTES> <DAY>.<MONTH>.<YEAR>
#
ending-date: "20:00 31.12.2025"

# If set to true, reward will be removed from GUI
# after player claims it
disappear: false
#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleTimeLimitedReward
#
# Date format which will be used
# in the reward lore:
#
date-format: "HH:mm MM.dd.yyyy"
#
# When player has this permission,
# following properties will be shown.
#
# NOTE THAT ITEM & SOUND NAMES ARE SLIGHTLY DIFFERENT BETWEEN >1.12 & 1.13< 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: CHEST_MINECART
available-display-name: '&a&lTIME LIMITED REWARD'
available-lore:
  - '&fReward is available'
  - '&f from: &2%startingDate%'
  - '&f to: &4%endingDate%'
  - ' '
  - '&7Contains:'
  - '&e ➪ 3x Diamond'
  - '&e ➪ 16x Experience bottle'
  - ' '
  - '&b► Click to claim'
# When the reward is already claimed by player:
claimed-item: MINECART
claimed-display-name: "&7&lTIME LIMITED REWARD"
claimed-lore:
  - '&7Welcome bonus was already'
  - '&7claimed.'
# When the reward isn't available for claiming
unavailable-item: MINECART
unavailable-display-name: "&4&lTIME LIMITED REWARD"
unavailable-lore:
  - '&cReward could be collected'
  - '&cby %endingDate%'
#
# In the other hand when player doesn't have this permission,
# following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mTIME LIMITED REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&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
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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 3'
  - '[console] give %player% experience_bottle 16'
  - '[message] &6Enjoy the rewards, %player%!'
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.timeLimitedReward.premium
    available-display-name: "&6&lPREMIUM TIME LIMITED REWARD"
    available-lore:
      - '&fReward is available'
      - '&f from: &2%startingDate%'
      - '&f to: &4%endingDate%'
      - ' '
      - '&7Contains:'
      - '&e ➪ 6x Diamond'
      - '&e ➪ 32x Experience Bottle'
      - ' '
      - '&6► Click to claim premium version'
      - '&6   of the reward'
    actions:
      - '[console] give %player% diamond 6'
      - '[console] give %player% experience_bottle 32'
      - '[firework]'
      - '[message] &6Enjoy the rewards, %player%!'
```

{% endcode %}


# Custom Reward

Reward based on meeting expressions

{% 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>


# Multiple Custom Reward

This reward is identical to the [Custom Reward](/configuration/rewards/reward-types/custom-reward), except that multiple requirements (expressions) can be used.

### Example configuration

{% code fullWidth="true" %}

```yaml
# Decides if rewards will be claimable
enabled: true
#
# Note that MULTIPLE_CUSTOM_REWARD will work only with
# PlaceholderAPI installed
#
type: multiple_custom_reward
#
# Reward tag
#
tag: Multiple Custom Reward
# Expression is used to determine if player can claim this reward.
# Returns true/false depending on the condition
#
# In this case, player must kill 30 skeletons and 50 spiders
# in order to claim this reward
requirements:
  1:
    expression: "%statistic_kill_entity:SKELETON% >= 30"
    remaining-expression: "30 - %statistic_kill_entity:SKELETON%"
  2:
    expression: "%statistic_kill_entity:SPIDER% >= 50"
    remaining-expression: "50 - %statistic_kill_entity:SPIDER%"

#
# (Optional) Permission which player must have to be
# able to obtain this reward.
#
permission: ultimaterewards.exampleMultipleCustomReward
# Notifies players that the reward is currently available
live-reminder-enabled: true
#
# When player has this permission,
# following properties will be shown.
#
# When the reward is currently claimable:
available-item: "LIME_DYE"
available-display-name: "&a&lMULTIPLE CUSTOM REWARD"
available-lore:
  - "&7You need to meet"
  - "&7following requirements:"
  - " "
  - " &f• Kill 30 Skeletons &a✓"
  - " &f• Kill 50 Spiders &a✓"
  - " "
  - "&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: "&c&lMULTIPLE CUSTOM REWARD"
unavailable-lore:
  - "&7You need to meet"
  - "&7following requirements:"
  - " "
  - " &f• Kill 30 Skeletons &4(%amount_1% left)"
  - " &f• Kill 50 Spiders &4(%amount_2% left)"
  - " "
#
# When player already claimed this reward:
#
claimed-item: "GRAY_DYE"
claimed-display-name: "&7&lMULTIPLE CUSTOM REWARD"
claimed-lore:
  - "&7You need to meet"
  - "&7following requirements:"
  - " "
  - " &f• Kill 30 Skeletons &a✓"
  - " &f• Kill 50 Spiders &a✓"
  - " "
  - "&7✓ Already claimed"
#
# Player doesn't have permission for this reward,
# following properties will be shown.
#
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mMULTIPLE CUSTOM REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&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
#   [<actionType>] (<chance>):<command>
#
# Examples:
#   - [console] 50:give %player% diamond 1
#       - this command will have 50%
#         execution chance due his property value
#
#   - [message] "&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] &7You have claimed multiple custom reward!'
  #  - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
  - '[title] &aClaimed'
  - '[subtitle] &aReward %type%'
```

{% endcode %}


# Coupon Reward

Coming soon


# Discord Reward

Coming soon

Soon


# Reward Settings

Per-player settings regarding rewards

Every player can turn the following four settings on and off. Each one has its own permission — without it the setting cannot be toggled and the item in the settings menu is replaced by `setting-no-permission-item` from config.yml.

| Setting              | Permission                          | Default in config.yml          | What it does                                                                                                      |
| -------------------- | ----------------------------------- | ------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| `JOIN_NOTIFICATION`  | `ultimaterewards.notification`      | `join-notification-by-default` | [Notifies](/configuration/rewards/reward-features/notifications) the player about claimable rewards on join       |
| `LIVE_NOTIFICATIONS` | `ultimaterewards.livenotifications` | `live-notification-by-default` | [Notifies](/configuration/rewards/reward-features/notifications) the player the moment a reward becomes available |
| `JOIN_AUTO_CLAIM`    | `ultimaterewards.joinautoclaim`     | `join-auto-claim-by-default`   | [Claims](/configuration/rewards/reward-features/auto-claim) all available rewards on join                         |
| `LIVE_AUTO_CLAIM`    | `ultimaterewards.liveautoclaim`     | `live-auto-claim-by-default`   | [Claims](/configuration/rewards/reward-features/auto-claim) a reward the moment it becomes available              |

## Toggling a setting

Settings can be toggled in three ways:

* by the player from a menu, using the `[toggle_join_notification]`, `[toggle_live_notifications]`, `[toggle_join_auto_claim]` and `[toggle_live_auto_claim]` [click actions](/configuration/menus/setting-menu),
* with the command `/reward toggle <setting>`,
* for another player with `/reward toggle <setting> <player>` (requires `ultimaterewards.toggle.others`).

{% hint style="info" %}
The defaults in [config.yml](/usage/global-configuration) only apply to players who have not changed the setting yet. The current state can be read with `%ultimaterewards_setting_enabled_{setting}%`.
{% endhint %}

## Excluding a reward

Whether a specific reward takes part in notifications and auto-claiming is decided per reward in its .yml file:

```yaml
exclude-from-reminders: false  # true = never appears in join/live notifications
live-reminder-enabled: true    # notify the moment this reward becomes available
included-in-auto-claim: true   # allow auto-claim to claim this reward
```


# Reward Actions

Action types of rewards

Each reward has its own set of actions that are executed upon claiming the reward.

The following pattern is valid for use: `[<action>] <statement>`

## Available actions

| Action        | What it does                                                                                   |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `[CONSOLE]`   | The statement is executed as a command from the console                                        |
| `[PLAYER]`    | The statement is executed as a command by the player                                           |
| `[MESSAGE]`   | Sends the text to the claiming player                                                          |
| `[BROADCAST]` | Sends the text to all online players                                                           |
| `[ANNOUNCE]`  | Same as `[BROADCAST]`                                                                          |
| `[TITLE]`     | Sends the primary title                                                                        |
| `[SUBTITLE]`  | Sends the secondary title                                                                      |
| `[ACTIONBAR]` | Shows the text in the action bar (<mark style="color:yellow;">1.12+ only</mark>)               |
| `[BOSSBAR]`   | Shows the text in a boss bar for a few seconds (<mark style="color:yellow;">1.12+ only</mark>) |
| `[SOUND]`     | Plays a sound for the player                                                                   |
| `[FIREWORK]`  | Launches a firework above the player                                                           |
| `[OPEN]`      | Opens the specified [menu](/configuration/menus/basics) for the player                         |

{% hint style="info" %}
`[TITLE]` and `[SUBTITLE]` are combined into a single title, so you can use both in one reward without them overwriting each other.
{% endhint %}

## Placeholders in actions

| Placeholder | Replaced by                                  |
| ----------- | -------------------------------------------- |
| `%player%`  | Name of the claiming player                  |
| `%type%`    | Identifier (file name) of the claimed reward |
| `%tag%`     | The reward's `tag` from its .yml file        |

On top of that you can use [random placeholders](/configuration/rewards/reward-features/randomization) and any [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) placeholder.

## Formatting

* **Multiple lines** — in `[MESSAGE]`, `[BROADCAST]` and `[ANNOUNCE]`, the `|` character splits the text into separate lines.
* **Sound parameters** — `[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1`. Both `volume` and `pitch` are optional.
* **Firework parameters** — `[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:2`. Colors are hexadecimal and separated by `;`, `type` is a Bukkit firework type (`BALL`, `BALL_LARGE`, `STAR`, `BURST`, `CREEPER`), `power` sets the flight duration. All three are optional.
* **Per-line chance** — prefixing a statement with `<chance>:` executes that single line only that often, e.g. `'[console] 10: give %player% netherite_ingot 1'`. See [Execution Chances](/configuration/rewards/reward-features/randomization/execution-chances).

{% hint style="warning" %}
Item and sound names differ between Minecraft versions — always use names valid for the version you run.
{% endhint %}

## Example

The following example is a demonstration of how to use actions in a real .yml file of a reward:

```yaml
actions:
    - '[console] give %player% diamond 1' # console will execute the give command for 1 diamond
    - '[console] give %player% iron_ingot %exampleRandom%' # console will execute the give command for random amount of iron ingots
    - '[console] give %player% gold_ingot 3' # console will execute give command for 3 gold ingots
    - '[console] say %player% claimed his %type% reward!' # console will execute say command with specified message
    - '[console] 10: give %player% netherite_ingot 1' # only executes in 10% of the claims
    - '[actionbar] &aSuccessfully claimed!' # '&aSuccessfully claimed' message will be shown in player's action bar
    - '[title] &aClaimed' # '&aClaimed' message will be printed in a title for the player
    - '[subtitle] &aReward %tag%' # the reward's tag will be printed in a subtitle for the player
    - '[message] &7Enjoy your reward! | &7See you tomorrow.' # two lines, split by |
    - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1' # The sound of the chest opening will be played for the player
    - '[bossbar] &aClaimed %type% reward' # Stated text will appear in boss bar for the claimer
    - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:2' # Launches firework with stated colors, type & power above the player
```


# Reward Features


# Auto Claim

Autoclaim is designed to automatically claim the available reward(s) for the player without the need to click or some interaction.

Is available in two variants:

* JOIN AUTO CLAIM
* LIVE AUTO CLAIM

\
**The reward must be marked as auto-claimable by adding** `included-in-auto-claim: true` **to its config.**

The player also needs to have this type of autoclaim enabled, using the /rw toggle command or in the [settings menu](/configuration/menus/setting-menu) if you have created one.\
\
Auto-claim also sets [requirements](/configuration/rewards/reward-features/reward-requirements) that if the player does not meet, the reward will not be claimed.


# Notifications

Notifications provide an overview of available rewards for claiming.\
Notifications can be turned off/on by the player in their settings (if they have permission to do so). Rewards can also be turned on or off by default (i.e. after the 1st player connection) in the **config.yml** by the following properties:

`join-notification-by-default` \[true/false]\
`live-notification-by-default` \[true/false]

Notifications can be binded to any command, playsound for the player and set delay. All this in **config.yml.**\
\
There are currently 2 types of notifications available

## Join Notification

When joining, the player receives a list of all the rewards he can select.

## Live Notifications

These notifications are sent to the player as soon as the reward is marked as available, e.g. when the reward cooldown expires, the player collects enough votes, plays the required playtime, etc.


# Reward NPC

Using a 3rd party NPC plugin, such as [Citizens2](https://www.spigotmc.org/resources/citizens.13811/) ([free download link](https://ci.citizensnpcs.co/)), and a holo plugin, such as [DecentHolograms](https://www.spigotmc.org/resources/decentholograms-1-8-1-21-3-papi-support-no-dependencies.96927/) can be created following.

* The NPC can be clicked on (using `/npc cmd` to bind `/rw claim` command on it) and the player can redeem the reward by clicking on that NPC
* The hologram uses the `%ultimaterewards_available_<rewardName>%` placeholder to display the reward status

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FHdb3NcifTAkTpYHTybR6%2Fshowcase1.gif?alt=media&amp;token=48cad008-88a7-4d92-bc93-5140fd154b19" alt=""><figcaption><p>Showcase</p></figcaption></figure>


# Discord Support

### Discord Synchronization

The [DiscordSRV](https://www.spigotmc.org/resources/discordsrv.18494/) plugin is used to synchronize the player with the discord server. This feature can also be used to eliminate the use of multiaccount to claim rewards. You can then specify with the <mark style="color:blue;">`require-discord-sync: true`</mark> (add this property to the .yml reward file) attribute whether an individual reward can only be claimed if the player has this synchronization enabled

### Discord Boosting

If you want to make the reward only for discord boosters, just mark the reward (add this property to the .yml reward file) as <mark style="color:blue;">`require-boosting-discord: true`</mark> and only those who boost your discord server will be able to claim it.

### Discord Logging

Logging of claiming rewards, discord channel where logs will be sent can be found in config.yml <mark style="color:blue;">`discord-log-channel: "<channelID>"`</mark>


# Reward Requirements

Before a player can claim a reward, they must pass through a series of toggleable checkers.\
Here is a list of these checkers:

{% hint style="info" %}
Every bypass permission listed below is also covered by `ultimaterewards.admin`, so operators and admins always pass the checker.
{% endhint %}

## Checkers for Rewards

* **Limit Accounts per IP**
  * Blocks claiming rewards if the number of accounts on one IP address exceeds a certain amount.
  * This is a global setting in config.yml using <mark style="color:blue;">`max-accounts-per-ip: <amount>`</mark> *(set to 0 to disable this checker)*
  * A logging system is in place for better management - when a player logs in, all his registered accounts are displayed in the console, you can toggle this by <mark style="color:blue;">`log-accounts: true/false`</mark> in config.yml
  * Bypass permission: `ultimaterewards.iplimit.bypass` or for certain amount use `ultimaterewards.iplimit.bypass.<amount>`
* **Permission Checker**
  * Checks if the claimer has stated permission.
  * Multiple permission can be used, see [Reward Variants](/configuration/rewards/reward-features/reward-variants)
  * Permission can be set per reward in reward's .yml using <mark style="color:blue;">`permission: "<text>"`</mark> *(set to "" for no required permission)*
* **Enough Inventory Slots Checker**
  * Cancels the claiming if the player doesn't have enough free inventory slots.
  * Can be specified per reward in it's .yml file by <mark style="color:blue;">`required-slots: <number>`</mark> property.
  * Independently of that, <mark style="color:blue;">`check-for-full-inventory: true`</mark> in config.yml blocks claiming for any player whose inventory is completely full.
* **Discord Account Synchronization Checker**
  * Verifies if the player has [synchronized](/configuration/rewards/reward-features/discord-support) their Discord account.
  * To specify that a reward requires synchronization, add <mark style="color:blue;">`require-discord-sync: true`</mark> to the reward’s .yml file.
  * Bypass permission: `ultimaterewards.discordSync.bypass`
* **Discord Account Is Boosting Checker**
  * This checker is used to check if the discord user boosts the discord server, if not, the player cannot claim the reward.
  * To specify that a reward requires user to boosting discord server, add\ <mark style="color:blue;">`require-boosting-discord: true`</mark> to the reward’s .yml file.
  * The name of the booster role is taken from <mark style="color:blue;">`discord-booster-role-name`</mark> in config.yml.
  * Bypass permission: `ultimaterewards.discordBoost.bypass`
* **Claiming in Disabled World(s) Checker**
  * Prevents claiming of rewards if the player is located within a designated disabled world.
  * Worlds can be specified per-reward by listing them in the <mark style="color:blue;">`disabled-worlds`</mark> section of the reward's .yml file.
  * Bypass permission: `ultimaterewards.disabledworld.bypass`
* **Enough Play-Time Checker**
  * Determines if the reward can be claimed based on the total time the player has spent on the server.
  * This can be configured in the config.yml file:\ <mark style="color:blue;">`first-time-join-required-play-time: <number>`</mark> *(set to 0 to disable this checker)*
  * Bypass permission: `ultimaterewards.firsttime.bypass`
* **Maximum Play-Time Checker**
  * Blocks claiming once the player has played longer than the reward allows — useful for newcomer rewards.
  * Can be specified per reward in it's .yml file by <mark style="color:blue;">`max-play-time: <minutes>`</mark> property.
  * Bypass permission: `ultimaterewards.maximumPlayTime.bypass`
* **Session Play-Time Checker**
  * Checks if the player has accrued the required amount of session time to claim a reward.
  * Globally in the config.yml file:\ <mark style="color:blue;">`session-required-play-time: <number>`</mark> *(set to 0 to disable this checker)*
  * Per reward in its .yml file:\ <mark style="color:blue;">`required-session-play-time: <minutes>`</mark> *(set to 0 to disable it for that reward)*
  * Bypass permission: `ultimaterewards.session.bypass`

## **Checkers for Affiliates**

1. **Referral Creation Required Time Checker**
   * Enables players to create their own referral after they have accumulated sufficient play-time.
   * Configuration can be set in referrals.yml using\ <mark style="color:blue;">`referral-create-required-play-time: <number>`</mark> (set to 0 to disable this checker)
   * Bypass permission: `ultimaterewards.requiredplaytime.bypass`
2. **Maximum Play-Time to Apply Referral Checker**
   * Disallows the activation of player referrals if the player has reached the maximum play-time.
   * This limit can be configured in referrals.yml using\ <mark style="color:blue;">`maximum-playtime-for-referred-player: <number>`</mark> (set to 0 to disable this checker)
   * Bypass permission: `ultimaterewards.maximumPlayTime.bypass`
3. **IP Checker**
   * Prevent referral activation if the applier and referrer have the same IP address.
   * This limit can be configured in referrals.yml using\ <mark style="color:blue;">`disable-activation-within-same-ip: <true/false>`</mark>
4. **Discord Synchronization Checker**
   * Allows applying a referral only to players with a synchronized Discord account.
   * This limit can be configured in referrals.yml using\ <mark style="color:blue;">`require-discord-sync: <true/false>`</mark>


# Reward Variants

Alias Multi-Rank support

Permissions can be used to determine which reward variant will be claimed by the player.

Take, for example, a reward with the [One Time Reward](/configuration/rewards/reward-types/one-time-reward) type. In this case, a player with the `ultimaterewards.oneTimeRewardExample` permission will have access to the given base reward option. If we want to offer more variants, we can define additional reward versions under the "variants" section.

Here’s an example configuration with multiple reward variants:

{% code fullWidth="true" %}

```yaml
#
# Variants for this reward can be added here,
# if you don't want any, delete the variants section
#
# Which variant will be available for player depends on permission
# You can add as many variants you want
#
variants:
  premium:
    permission: ultimaterewards.oneTimeRewardExample.premium
    available-display-name: "&6&lPREMIUM WELCOME BONUS"
    available-lore:
      - ' '
      - '&7Contains:'
      - '&e ➪ 1x Iron Sword'
      - '&e ➪ 1x Iron Axe'
      - '&e ➪ 1x Iron Pickaxe'
      - '&e ➪ 1x Iron Shovel'
      - '&e ➪ 32x Apple'
      - '&e ➪ 1x Red Bed'
      - ' '
      - '&6► Click to claim premium version'
      - '&6   of the reward'
    actions:
      - '[console] give %player% iron_sword 1'
      - '[console] give %player% iron_axe 1'
      - '[console] give %player% iron_pickaxe 1'
      - '[console] give %player% iron_shovel 1'
      - '[console] give %player% apple 32'
      - '[console] give %player% red_bed 1'
      - '[message] &eWelcome to the server, %player%! I hope these items will assist you in getting started.'
  mythic:
    permission: ultimaterewards.oneTimeRewardExample.mythic
    available-display-name: "&5&lMYTHIC WELCOME BONUS"
    available-lore:
      - ' '
      - '&7Contains:'
      - '&d ➪ 1x Diamond Sword'
      - '&d ➪ 1x Diamond Axe'
      - '&d ➪ 1x Diamond Pickaxe'
      - '&d ➪ 1x Diamond Shovel'
      - '&d ➪ 64x Apple'
      - '&d ➪ 1x Red Bed'
      - ' '
      - '&5► Click to claim mythic version'
      - '&5   of the reward'
    actions:
      - '[console] give %player% diamond_sword 1'
      - '[console] give %player% diamond_axe 1'
      - '[console] give %player% diamond_pickaxe 1'
      - '[console] give %player% diamond_shovel 1'
      - '[console] give %player% apple 64'
      - '[console] give %player% red_bed 1'
      - '[message] &eWelcome to the server, %player%! I hope these items will assist you in getting started.'
```

{% endcode %}

***

In the menu configuration (guis.yml), you can specify a reward variant by appending a suffix `:<variant>` to the reward name. If no variant is specified, the system will automatically select the variant that the player is eligible for based on their permissions.

Here how it would look like in guis.yml

{% code fullWidth="true" %}

```yaml
oneTimeRewards:
  title: "One Time Rewards Menu"
  rows: 4
  sound: BLOCK_NOTE_BLOCK_PLING
  content:
    11: exampleOneTimeReward  # Reward variant will be automatically determined based on the player's permissions
    13: exampleOneTimeReward:default # Reward variant will be set to default
    15: exampleOneTimeReward:mythic # Reward variant will be set to mythic
    31:
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        "&7Return to the main menu"
      action: '[open] main'

```

{% endcode %}


# Selectable Rewards

The player has the option to select their preferred reward from a list of available reward options. Once a reward is chosen, a cooldown is automatically applied to the other reward variants. This mechanic encourages strategic decision-making, as the player must consider the consequences of their choice and the timing of future opportunities to claim the other rewards.

{% hint style="info" %}
This can be used for every type of reward except for streak reward types
{% endhint %}

#### Example

<figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FyhHSFgUEcca6puwbPX2e%2FColectable%20Rewards%20(online-video-cutter.com).gif?alt=media&amp;token=018ba461-1ba4-4430-a945-84f1e4847061" alt=""><figcaption></figcaption></figure>

```yaml
enabled: true
type: time_reward
tag: Time Reward
cooldown: 24
cooldown-general-format: "%hours% hours"
cooldown-format: '%hours%:%minutes%:%seconds%'
available-after-first-join: false
live-reminder-enabled: true
required-slots: 3
permission: ultimaterewards.exampleTimeReward
available-item: CHEST_MINECART
available-display-name: '&a&lFIRST TIME REWARD'
available-lore:
  - '&7Can be obtained every &f%cooldown%'
  - ' '
  - '&7Contains:'
  - '&e ➪ 16x Gold Ingot'
  - ' '
  - '&e► Click to claim'
unavailable-display-name: "&7&lTIME REWARD"
unavailable-lore:
  - '&7Available in:'
  - '&7%cooldown%'
unavailable-item: MINECART
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mTIME REWARD"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
actions:
  100:
    - '[console] give %player% gold_ingot 16'
    - '[console] say %player% claimed their %type% reward!'
    #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
    - '[message] &7Enjoy your claimed reward | New line!'
  20:
    - '[message] &a&lYou have been extra lucky today! Received 5 more diamonds!'
    - '[console] give %player% diamond 5'
variants:
  second:
    permission: ultimaterewards.timeRewardExample.second
    available-display-name: "&6&lSECOND TIME REWARD"
    available-lore:
      - '&7Can be obtained every &f%cooldown%'
      - ' '
      - '&7Contains:'
      - '&e ➪ 24x Iron Ingots'
      - ' '
      - '&e► Click to claim'
    actions:
      100:
        - '[console] give %player% iron_ingot 24'
        - '[console] say %player% claimed their %type% reward!'
        #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
        - '[title] &aClaimed'
        - '[subtitle] &aReward %type%'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
  third:
    permission: ultimaterewards.timeRewardExample.third
    available-display-name: "&b&lTHIRD TIME REWARD"
    available-lore:
      - '&7Can be obtained every &f%cooldown%'
      - ' '
      - '&7Contains:'
      - '&e ➪ 2x Diamonds'
      - ' '
      - '&e► Click to claim'
    actions:
      100:
        - '[console] give %player% diamond 2'
        - '[console] say %player% claimed their %type% reward!'
        #    - '[actionbar] &aSuccessfully claimed!' # Action bar can be used only from 1.12 versions!
        - '[title] &aClaimed'
        - '[subtitle] &aReward %type%'
        - '[firework] colors:{FF0000;00FF00;0000FF},type:BALL_LARGE,power:3'
        - '[sound] BLOCK_CHEST_OPEN,volume:0.2,pitch:1'
```

In guis.yml:

```yaml
timeRewards:
  title: Time Rewards Menu
  sound: ANVIL_FALL
  rows: 4
  content:
    '11': exampleTimeReward:default
    '13': exampleTimeReward:second
    '15': exampleTimeReward:third
    '31':
      item: BARRIER
      name: '&cBack'
      lore:
      - '&7Return to the main menu'
      action: '[open] main'
```


# Randomization

The plugin offers to randomize rewards by defining chances of performed actions or using random placeholders, more about the options at:

{% content-ref url="/pages/SlLQ9db5wyL9Qj9uWj3z" %}
[Execution Chances](/configuration/rewards/reward-features/randomization/execution-chances)
{% endcontent-ref %}

{% content-ref url="/pages/eza25MeIrh3YywErBiAY" %}
[Random Placeholders](/configuration/rewards/reward-features/randomization/random-placeholders)
{% endcontent-ref %}


# Execution Chances

### Individual chances

Each action line can be assigned a chance (0 - 100 represented as a percentage) at which the line will be executed. The chance is written directly after the action tag and followed by a colon.

#### Example

{% code fullWidth="false" %}

```yaml
actions:
 - "[console] 20:give %player% obsidian 2" # 20%  chance
 - "[console] 60:give %player% coal 1"     # 60%  chance
 - "[console] give %player% apple 16"      # 100% chance (no value = always)
```

{% endcode %}

{% hint style="info" %}
Individual chances are independent of each other — every line is rolled separately, so several of them (or none) can run in the same claim.
{% endhint %}

### Group chances

Each action section can be separated by percentages, where each percentage represents the probability that the corresponding section will be executed. The percentages determine how likely it is for a particular block of actions to run. When these sections are defined, the system will randomly select **exactly one** of the sections based on their assigned probabilities.

{% hint style="info" %}
The numbers are weights, so they work best when they add up to 100 — that way each one reads directly as a percentage.
{% endhint %}

#### Example

{% code fullWidth="false" %}

```yaml
actions:
  80: # 80% chance for execution
    - '[console] give %player% diamond 1'
    - '[console] give %player% iron_ingot %exampleRandom%'
    - '[console] give %player% gold_ingot 3'
    - '[console] say %player% claimed his %type% reward!'
    - '[actionbar] &aSuccessfully claimed!'
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
  20: # 20% chance for execution
    - '[console] give %player% diamond 1'
    - '[console] give %player% iron_ingot %exampleRandom%'
    - '[console] give %player% gold_ingot 3'
    - '[console] say %player% claimed his %type% reward!'
    - '[actionbar] &aSuccessfully claimed!'
    - '[title] &aClaimed'
    - '[subtitle] &aReward %type%'
    - '[message] &a&lYou have been extra lucky today! Received 5 more diamonds!'
    - '[console] give %player% diamond 5'
    - '[console] 10:give %player% netherite_ingot 1' # Individual chances can be used aswell
```

{% endcode %}


# Random Placeholders

Randomization refers to the ability to create custom placeholders (in the "randoms.yml" file) where you specify a numerical range from which a random number will be selected during command execution.

Let's consider this example configuration:

```yaml
placeholders:
   exampleRandom: 16-64 # Will return random number between 16 - 64
   anotherRandom: 10-10000 # Will return random number between 10 - 10,000
```

Now we can use the specified placeholders in the actions of any reward. Here's a demonstration example:

Suppose we have a reward called "Welcome Bonus" which gives the player a certain amount of apples. We want the amount of apples to be randomized within a certain range using the `exampleRandom` placeholder we defined earlier.

```yaml
enabled: true
type: one_time_reward
disappear: false
use-firework: true
permission: ultimaterewards.welcomeBonus
available-item: CHEST_MINECART
available-display-name: '&a&lWELCOME BONUS'
available-lore:
  - ' '
  - '&7Contains:'
  - '&e ➪ 16 - 64x Apple'
  - ' '
  - '&b► Click to claim'
unavailable-display-name: "&7&lWELCOME BONUS"
unavailable-lore:
  - '&7Welcome bonus was already'
  - '&7claimed.'
unavailable-item: MINECART
no-permission-item: BARRIER
no-permission-display-name: "&c&l&mWELCOME BONUS"
no-permission-lore:
  - "&c ✕ Locked, requires"
  - "&c   %permission% permission"
actions:
  - '[console] give %player% apple %exampleRandom%'
  - '[message] &aWelcome to the server, %player%! I hope these items will assist you in getting started.'
```

You can define as many custom placeholders as you need in the "randoms.yml" file, and use them in your commands to add some variability to your server gameplay.


# AFK Checkers

For play-time rewards

This mechanism is used to identify AFK (away from keyboard) players and ensure they do not receive playing time while inactive.\
It uses the system from [Essentials](https://essentialsx.net/downloads.html) or [CMI](https://www.spigotmc.org/resources/cmi-298-commands-insane-kits-portals-essentials-economy-mysql-sqlite-much-more.3742/) and does not automatically grant play-time progress towards rewards for AFK players.\
This option can be toggled in config.yml:

```yaml
enable-afk-checker: true
```

You can also configure (also in config.yml) whether the player can claim the reward immediately upon first connection or after a session waiting period. This helps prevent reward collection from multiple accounts.

```yaml
first-time-join-required-play-time: 100
session-required-play-time: 10
```

You can also set certain worlds in config.yml where time will not be added for the player at all.

```yaml
worlds-with-disabled-playtime-tracking:
  - 'afkworld'
  - 'someworld'
  - 'anotherworld'
```


# Menus


# Basics

To create your custom reward GUI, you can use the "guis.yml" file. You can modify individual menus at any time, add or remove rewards as needed.

### Click Actions

* `actions`
  * The given actions can be executed at any type of click
* `left-click-actions`
  * The given actions can be executed only when left clicked
* `right-click-actions`
  * The given actions can be executed only when right clicked

{% hint style="info" %}
`action` (singular) can be used as a shorthand when the item only needs a single click action.
{% endhint %}

You can also link and manipulate GUIs to specify which one should be opened using click actions. Currently available click actions are:

| Click action                  | What it does                                                         |
| ----------------------------- | -------------------------------------------------------------------- |
| `[OPEN] <menu>`               | Opens the specified menu                                             |
| `[CLOSE]`                     | Closes the currently opened menu                                     |
| `[MESSAGE] <text>`            | Closes the menu and sends the text to the player (`\|` splits lines) |
| `[CONSOLE] <command>`         | Dispatches the command through the console                           |
| `[PLAYER] <command>`          | Dispatches the command as the player                                 |
| `[SOUND] <sound>`             | Plays a sound, e.g. `BLOCK_NOTE_BLOCK_PLING,volume:0.1,pitch:1`      |
| `[APPLY]`                     | Opens the input menu for applying a referral                         |
| `[CREATE_REFERRAL]`           | Creates a referral for the player                                    |
| `[TOGGLE_JOIN_NOTIFICATION]`  | Toggles the join notification for the player                         |
| `[TOGGLE_LIVE_NOTIFICATIONS]` | Toggles live notifications for the player                            |
| `[TOGGLE_JOIN_AUTO_CLAIM]`    | Toggles join auto-claim for the player                               |
| `[TOGGLE_LIVE_AUTO_CLAIM]`    | Toggles live auto-claim for the player                               |

{% hint style="info" %}
The four toggle actions are described on the [Reward Settings](/configuration/rewards/reward-settings) page — each of them requires its own permission.

Text input for `[APPLY]` is taken either from an anvil GUI or from chat, depending on `input-type` in [config.yml](/usage/global-configuration).
{% endhint %}

### Menu Creation

Every menu has a required configuration consisting of '`title`', '`rows`', and '`content`'.

{% hint style="warning" %}
Make sure you use the item names appropriate for the version, if you use the wrong item name then the item will default to STONE
{% endhint %}

#### Menu keys

| Key              | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `title`          | Title of the inventory                                                 |
| `rows`           | Number of rows                                                         |
| `content`        | Items and rewards by slot number                                       |
| `inventory-type` | `CHEST` (default), `WORKBENCH`, `HOPPER`, `DISPENSER`, `BREWING`       |
| `filler`         | Item used to fill empty slots; use `none` or `air` to leave them empty |
| `sound`          | Sound played when the menu is opened                                   |
| `command`        | Registers a command that opens this menu                               |

#### Item keys

| Key                                                                 | Description                                                           |
| ------------------------------------------------------------------- | --------------------------------------------------------------------- |
| `item`                                                              | Material, base64 head texture or a [custom model](/colors-and-models) |
| `name`                                                              | Display name                                                          |
| `lore`                                                              | List of lore lines                                                    |
| `glowing`                                                           | `true` adds the enchantment glow                                      |
| `action` / `actions` / `left-click-actions` / `right-click-actions` | Click actions, see above                                              |

Here's an example of how you might set up a menu with these configurations:

```yaml
main:
  title: "Main Rewards Menu"
  rows: 5
  filler: GRAY_STAINED_GLASS_PANE
  inventory-type: CHEST # Available Types: CHEST, WORKBENCH, HOPPER, DISPENSER, BREWING
  content:
    13:
      item: CHEST
      name: "&aDaily Rewards"
      glowing: true
      lore:
        - '&7Menu with daily rewards'
        - ''
        - '&b► Click to open'
      action: '[open] dailyRewards'
    40:
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cClose"
      lore:
        - '&7Closes menu'
      actions: # Example of multiple click actions
        - "[close]"
        - "[message] You have closed the menu"
```

{% hint style="info" %}
As you may have noticed, a textured skull (base64) was used in this example. In addition, models from Oraxen, ItemsAdder plugin or your own custom model can also be used. More about this [here](/colors-and-models).
{% endhint %}

This example will create an inventory with 5 rows (45 slots), set its title to 'Main Rewards Menu', and then set content with the following positions:\
\
At position 13 in the inventory, a CHEST item is set with the specified parameters ('`name`', '`lore`', and '`left-click-actions`' & '`right-click-actions`' or '`actions`' for both click actions). The 'action' parameter specifies what will happen when the player clicks on this item in the inventory. In this case, it will open the example menu '**dailyRewards**'.

### Placing rewards in a menu

A slot can also hold a reward instead of a decorative item — write the reward's file name as the value of the slot. Rewards that consist of several steps (advent calendar, streak rewards, pickable rewards…) are referenced as `<reward>:<step>`.

```yaml
dailyRewards:
  command: "daily"
  title: "Daily Rewards Menu"
  rows: 4
  sound: BLOCK_NOTE_BLOCK_PLING
  content:
    13: exampleTimeReward       # a whole reward
    14: exampleStreakReward:3   # the third step of a streak reward
    31:
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - "&7Return to the main menu"
      action: '[open] main'
```

Each menu can be assigned with the `command` key a command that opens this menu. More complete examples are on the [Example of GUIs](/configuration/menus/example-of-guis) page.


# Example of GUIs

Example configuration for guis.yml

```yaml
main:
  title: Main Rewards Menu
  rows: 6
  content:
    '10':
      item: CHEST
      name: '&aTime Rewards'
      lore:
        - '&7Menu with time rewards'
        - ''
        - '&b► Click to open'
      action: '[open] timeRewards'
    '12':
      item: CHEST
      name: '&aTime Fixed Rewards'
      lore:
        - '&7Menu with time fixed rewards'
        - ''
        - '&b► Click to open'
      action: '[open] timeFixedRewards'
    '14':
      item: CHEST
      name: '&aStreak Rewards'
      lore:
        - '&7Menu with streak rewards'
        - ''
        - '&b► Click to open'
      action: '[open] streakRewards'
    '16':
      item: CHEST
      name: '&aStreak Fixed Rewards'
      lore:
        - '&7Menu with streak fixed rewards'
        - ''
        - '&b► Click to open'
      action: '[open] streakFixedRewards'
    '19':
      item: CHEST
      name: '&aVote Rewards'
      lore:
        - '&7Menu with vote rewards'
        - ''
        - '&b► Click to open'
      action: '[open] voteRewards'
    '21':
      item: CHEST
      name: '&aRenewable Vote Rewards'
      lore:
        - '&7Menu with renewable vote rewards'
        - ''
        - '&b► Click to open'
      action: '[open] renewableVoteRewards'
    '23':
      item: CHEST
      name: '&aPlay Time Rewards'
      lore:
        - '&7Menu with playtime rewards'
        - ''
        - '&b► Click to open'
      action: '[open] playTimeRewards'
    '25':
      item: CHEST
      name: '&aRenewable Play Time Rewards'
      lore:
        - '&7Menu with renewable play time rewards'
        - ''
        - '&b► Click to open'
      action: '[open] renewablePlayTimeRewards'
    '28':
      item: CHEST
      name: '&aReferral Rewards'
      lore:
        - '&7Menu with referral rewards'
        - ''
        - '&b► Click to open'
      action: '[open] referralRewards'
    '30':
      item: CHEST
      name: '&aRenewable Referral Rewards'
      lore:
        - '&7Menu with renewable referral rewards'
        - ''
        - '&b► Click to open'
      action: '[open] renewableReferralRewards'
    '32':
      item: CHEST
      name: '&aOne Time Rewards'
      lore:
        - '&7Menu with one-time rewards'
        - ''
        - '&b► Click to open'
      action: '[open] oneTimeRewards'
    '34':
      item: CHEST
      name: '&aCustom Rewards'
      lore:
        - '&7Menu with custom rewards'
        - ''
        - '&b► Click to open'
      action: '[open] customRewards'
    '37':
      item: CHEST
      name: '&aPurchasable Rewards'
      lore:
        - '&7Menu with purchasable rewards'
        - ''
        - '&b► Click to open'
      action: '[open] purchasableRewards'
    '39':
      item: CHEST
      name: '&aTime Limited Rewards'
      lore:
        - '&7Menu with time limited rewards'
        - ''
        - '&b► Click to open'
      action: '[open] timeLimitedRewards'
    '41':
      item: CHEST
      name: '&aAdvent Calendar'
      lore:
        - '&7Menu with advent calendar'
        - ''
        - '&b► Click to open'
      action: '[open] adventCalendar'
    '43':
      item: CHEST
      name: "&aStreak Vote Rewards"
      lore:
        - '&7Menu with streak vote rewards'
        - ''
        - '&b► Click to open'
      action: '[open] streakVoteRewards'
    '45':
      item: BARRIER
      name: '&cClose'
      lore:
        - '&7Closes the menu'
      actions:
        - '[message] &eYou have closed the main rewards menu'
        - '[close]'
    '46':
      item: REPEATER
      name: '&eSettings'
      lore:
        - '&7Menu with settings'
      action: '[open] settings'

streakFixedRewards:
  title: Streak Fixed Rewards Menu
  rows: 4
  sound: BLOCK_NOTE_BLOCK_BANJO
  content:
    '11': exampleStreakFixedReward:1
    '12': exampleStreakFixedReward:2
    '13': exampleStreakFixedReward:3
    '14': exampleStreakFixedReward:4
    '15': exampleStreakFixedReward:5
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

adventCalendar:
  title: Advent Calendar
  rows: 6
  command: "advent"
  sound: BLOCK_NOTE_BLOCK_BANJO
  content:
    '10': exampleAdventCalendar:1
    '11': exampleAdventCalendar:2
    '12': exampleAdventCalendar:3
    '13': exampleAdventCalendar:4
    '14': exampleAdventCalendar:5
    '15': exampleAdventCalendar:6
    '16': exampleAdventCalendar:7
    '19': exampleAdventCalendar:8
    '20': exampleAdventCalendar:9
    '21': exampleAdventCalendar:10
    '22': exampleAdventCalendar:11
    '23': exampleAdventCalendar:12
    '24': exampleAdventCalendar:13
    '25': exampleAdventCalendar:14
    '28': exampleAdventCalendar:15
    '29': exampleAdventCalendar:16
    '30': exampleAdventCalendar:17
    '31': exampleAdventCalendar:18
    '32': exampleAdventCalendar:19
    '33': exampleAdventCalendar:20
    '34': exampleAdventCalendar:21
    '39': exampleAdventCalendar:22
    '40': exampleAdventCalendar:23
    '41': exampleAdventCalendar:24
    '45':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

timeFixedRewards:
  title: Time Fixed Rewards Menu
  rows: 4
  sound: BLOCK_NOTE_BLOCK_BANJO
  content:
    '13': exampleTimeFixedReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

customRewards:
  title: Custom Rewards Menu
  rows: 4
  sound: BLOCK_NOTE_BLOCK_BANJO
  content:
    '13': exampleCustomReward
    '22':
      item: TORCH
      name: '&eNotice'
      lore:
        - '&6See: https://revivalo.gitbook.io/ultimaterewards/configuration/rewards/reward-types/custom-reward'
        - ''
        - '&7This reward is disabled'
        - '&7by default, you can simply enable it'
        - '&7by setting enabled: true'
      action: '[open] main'
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

purchasableRewards:
  title: Purchasable Rewards Menu
  rows: 4
  sound: BLOCK_NOTE_BLOCK_BANJO
  content:
    '13': examplePurchasableReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

referralRewards:
  title: Referral Rewards Menu
  rows: 4
  content:
    '13': exampleReferralReward
    '31':
      item: NAME_TAG
      name: "&aApply Referral"
      lore:
        - "&7State the players name and"
        - "&7receive the following rewards:"
        - ""
        - "&e1x Diamond" # Note that these rewards can be edited in config.yml
        - "&e1x Golden Apple"
        - " "
        - "&b► Click To Apply"
      action: '[apply]'
    '35':
      item: OAK_SIGN
      name: "&aCreate Own Referral"
      lore:
        - '&7Create your own referral to invite your friends.'
        - '&7By doing so, you will receive interesting rewards.'
        - '&7Invited players will also receive rewards.'
        - " "
        - "&b► Click To Create"
      action: '[create_referral]'
    '27':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

renewableReferralRewards:
  title: Renewable Referral Rewards Menu
  rows: 4
  content:
    '13': exampleRenewableReferralReward
    '31':
      item: NAME_TAG
      name: "&aApply Referral"
      lore:
        - "&7State the players name and"
        - "&7receive the following rewards:"
        - ""
        - "&e1x Diamond" # Note that these rewards can be edited in config.yml
        - "&e1x Golden Apple"
        - " "
        - "&b► Click To Apply"
      action: '[apply]'
    '35':
      item: OAK_SIGN
      name: "&aCreate Own Referral"
      lore:
        - '&7Create your own referral to invite your friends.'
        - '&7By doing so, you will receive interesting rewards.'
        - '&7Invited players will also receive rewards.'
        - " "
        - "&b► Click To Create"
      action: '[create_referral]'
    '27':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

streakRewards:
  title: Streak Rewards Menu
  rows: 4
  sound: BLOCK_NOTE_BLOCK_DIDGERIDOO
  content:
    '11': exampleStreakReward:1
    '12': exampleStreakReward:2
    '13': exampleStreakReward:3
    '14': exampleStreakReward:4
    '15': exampleStreakReward:5
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

voteRewards:
  title: Vote Rewards Menu
  rows: 5
  content:
    '13': exampleVoteReward
    '22':
      item: OAK_BUTTON
      name: '&eWhere to vote?'
      lore:
        - '&7Click to get all available'
        - '&7vote sites!'
      action: "[message] You can vote for us on: | &b► &f&nhttps://examplesite.com" # Use | to define a new line
    '40':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

renewableVoteRewards:
  title: Renewable Vote Rewards
  rows: 4
  content:
    '13': exampleRenewableVoteReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

streakVoteRewards:
  title: Streak Vote Rewards
  rows: 4
  content:
    '11': exampleStreakVoteReward:1
    '12': exampleStreakVoteReward:2
    '13': exampleStreakVoteReward:3
    '14': exampleStreakVoteReward:4
    '15': exampleStreakVoteReward:5
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

oneTimeRewards:
  title: One Time Rewards Menu
  rows: 4
  content:
    '13': exampleOneTimeReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

timeLimitedRewards:
  title: Time Limited Reward Menu
  rows: 4
  content:
    '13': exampleTimeLimitedReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

timeRewards:
  title: Time Rewards Menu
  sound: ANVIL_FALL
  rows: 4
  content:
    '13': exampleTimeReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: '&cBack'
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

playTimeRewards:
  title: Play Time Rewards
  rows: 4
  content:
    '13': examplePlayTimeReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

renewablePlayTimeRewards:
  title: Renewable Play Time Rewards
  rows: 4
  content:
    '13': exampleRenewablePlayTimeReward
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'

settings:
  title: Settings
  rows: 4
  content:
    '11':
      item: SLIME_BALL
      name: "&aLive Notifications"
      lore:
        - '&7Notifies you immediately of the reward'
        - '&7that can currently be collected.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_live_notifications]'
    '13':
      item: OAK_DOOR
      name: "&aJoin Notification"
      lore:
        - '&7When you connect to the server, it notifies'
        - '&7you what rewards are available for withdrawal.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_join_notification]'
    '15':
      item: REDSTONE_TORCH
      name: "&aAuto Claim"
      lore:
        - '&7Automatically claims available rewards.'
        - '&8&lNOTE:&8 In case of insufficient space in'
        - '&8 the inventory, the reward will not be collected.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_join_auto_claim]'
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'
```


# Setting Menu

The default setting menu is shown here.

```yaml
settings:
  title: Settings
  rows: 4
  content:
    '10':
      item: SLIME_BALL
      name: "&aLive Notifications"
      lore:
        - '&7Notifies you immediately of the reward'
        - '&7that can currently be collected.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_live_notifications]'
    '12':
      item: OAK_DOOR
      name: "&aJoin Notification"
      lore:
        - '&7When you connect to the server, it notifies'
        - '&7you what rewards are available for withdrawal.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_join_notification]'
    '14':
      item: REDSTONE_TORCH
      name: "&aAuto Claim"
      lore:
        - '&7Automatically claims available rewards upon joining'
        - '&8&lNOTE:&8 In case of insufficient space in'
        - '&8 the inventory, the reward will not be collected.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_join_auto_claim]'
    '16':
      item: REDSTONE_TORCH
      name: "&aLive Auto Claim"
      lore:
        - '&7Automatically claims available rewards'
        - '&8&lNOTE:&8 In case of insufficient space in'
        - '&8 the inventory, the reward will not be collected.'
        - ' '
        - '&eClick to toggle'
      action: '[toggle_live_auto_claim]'
    '31':
      item: eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvNjZkOGVmZjRjNjczZTA2MzY5MDdlYTVjMGI1ZmY0ZjY0ZGMzNWM2YWFkOWI3OTdmMWRmNjYzMzUxYjRjMDgxNCJ9fX0=
      name: "&cBack"
      lore:
        - '&7Return to the main menu'
      action: '[open] main'
```


# Schedules & Timers

This page explains how to create and manage scheduled and repeating tasks for your server. Users can configure tasks that execute commands at specific times or intervals.

### Configuration File: `schedules.yml`

The `schedules.yml` file defines all scheduled and repeating tasks.

#### Example Structure

```yaml
schedules:
  daily_reward:
    enabled: true
    type: fixed
    time: "12:00" # 12:00 PM
    days: [MONDAY, WEDNESDAY, FRIDAY] # Only runs on these days
    actions:
      - "[console] say Daily reward executed!"

  xp:
    enabled: false
    type: repeatable
    interval: 300 # Every 300 seconds (5 minutes)
    actions:
      commands:
      - "[console] xp give %player% 5"
      - "[message] &aYou have received 5 Level XP!"
    variants:
      double_xp:
        permission: ultimaterewards.doublexp
        actions:
        - "[console] xp give %player% 10"
        - "[message] &aYou have received 10 Level XP!"

  hourly_announcement:
    enabled: true
    type: repeatable
    interval: 3600 # Every 3600 seconds (1 hour)
    actions:
      - "[console] broadcast A new challenge has started!"

  midnight_reset:
    enabled: true
    type: fixed
    time: "00:00" # Midnight
    actions:
      - "[console] say Midnight reset triggered!"
```

### Behavior

#### Fixed Tasks

* If no `days` are specified, the task runs **every day** at the given `time`.
* If `days` are specified, the task runs **only on those days** at the given `time`.

#### Repeatable Tasks

* Executes for **all online players** at the specified `interval`.
* Runs continuously at the defined interval unless manually disabled.

### Explanation of Fields

* **`type`**: Defines whether the task is executed at a specific time (`fixed`) or at regular intervals (`repeatable`).
* **`time`** *(only for fixed tasks)*: Specifies the execution time in `HH:mm` format.
* **`days`** *(optional, only for fixed tasks)*: If provided, the task will only execute on the specified days; otherwise, it runs daily.
* **`interval`** *(only for repeatable tasks)*: Defines the time interval in seconds between task executions.
* **`actions`**: A list of commands that will be executed when the task is triggered.
* `variants`: Permission based [variant(s)](/configuration/rewards/reward-features/reward-variants) of repeatable task.


# Colors & Models

## **Custom Models**

For custom models, the following format can be used: `CustomModel[<material>]{<ID>}`

### Textured Skulls

You can also use textured head with **base64** value.\
Example value:

```
eyJ0ZXh0dXJlcyI6eyJTS0lOIjp7InVybCI6Imh0dHA6Ly90ZXh0dXJlcy5taW5lY3JhZnQubmV0L3RleHR1cmUvMjk5NjMzNzhmZmViZWM0MjBmNGM4YTU4YWQ2OTZhMTUxOGQ1N2VjNTZmOTA2OWU1YzkyMGQ2M2Q1ZWU0ZWZmMyJ9fX0
```

Or diretly use the head from [HeadDatabase](https://www.spigotmc.org/resources/head-database.14280/) plugin with following format:

```
hdb:<ID>
```

### Player's Skulls

To insert skull of the player simple use `skullofplayer` as an item.\
For custom texture you can use following format:\
`CustomSkull[PLAYER_HEAD]{<ID>}`

***

## Colors

### Colorizing classic text

```
&aLegacy text
```

Examples

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2F8fDChD3fcPzDd5TFCrAg%2Fimage.png?alt=media&amp;token=7a865a97-569e-4077-b98e-ab7d0bd2f622" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FqtY4GEo59bel2TkLu3y3%2Fimage.png?alt=media&amp;token=ed5f7a07-7885-4e0c-a5f6-893ad3700763" alt=""><figcaption></figcaption></figure></div>

### Colorizing gradient (Hex Usage)

```
<#FF6600>Gradient colorized text</#9DFF8A>
```

Examples

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FprWm99I7PwgakdZT8sD3%2Fimage.png?alt=media&amp;token=56ec0995-3c6c-4753-a211-0dab9b3327b2" alt=""><figcaption></figcaption></figure></div>

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FliKxcq42wFW081JZwH5L%2Fimage.png?alt=media&amp;token=99fa3ef1-c4d5-444b-a0c7-eec355c683f7" alt=""><figcaption></figcaption></figure></div>

### Colorizing gradient (Legacy Usage)

```
<&a>Gradient with legacy codes!</&c>
```

Examples

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2F5DhlO4TspmTUPvz0B5eV%2Fimage.png?alt=media&amp;token=95ffb0aa-0fbb-488d-a501-3ac41c575a2f" alt=""><figcaption></figcaption></figure></div>

### Colorizing gradient (Changing format in gradient text)

```
<#FF6600>&lBold text &nUnderlined Text</#9DFF8A>
```

Examples

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2F3A1zqPNX9Zrtvc1EI1rY%2Fimage.png?alt=media&amp;token=0e03f1d3-8d8b-46a7-b4b7-69c8123b722d" alt=""><figcaption></figcaption></figure></div>

### Colorizing gradient (Creating exception in gradient text)

(Create color exception, and continue in gradient)

```
<#FF6600>Colorized text &cEXCEPTION &rcontinue in gradient!</#9DFF8A>
```

Examples

<div align="left"><figure><img src="https://1098473219-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FpSgzS2uHYglFnW7ZooUu%2Fuploads%2FUQRQVGXGBBqVRzQZEWAW%2Fimage.png?alt=media&amp;token=bcb54f56-5051-4064-be89-583c889714ec" alt=""><figcaption></figcaption></figure></div>


# Placeholders

Every placeholder the plugin registers in PlaceholderAPI.

The plugin registers the placeholders below, which can be used anywhere [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/) is supported — in reward lore, menus, actions, scoreboards, holograms and other plugins.

{% hint style="info" %}
`{reward}` is the file name of the reward (without `.yml`), `{rewardType}` one of the [reward types](/configuration/rewards/reward-types).

While a player's data is still being loaded, placeholders return the `loading` message from lang.yml.
{% endhint %}

## Rewards

<table data-full-width="true"><thead><tr><th width="404">Placeholder</th><th>Description</th></tr></thead><tbody><tr><td><code>%ultimaterewards_state_{reward}%</code></td><td>State of the reward, e.g. available, unavailable, upcoming, locked</td></tr><tr><td><code>%ultimaterewards_cooldown_{reward}%</code></td><td>Remaining cooldown of the reward. When <code>use-timer-in-placeholder</code> is <code>false</code> in config.yml, the <code>unavailable</code> text from lang.yml is shown instead</td></tr><tr><td><code>%ultimaterewards_progress_{reward}%</code></td><td>Draws the progress bar of the reward (styling is set by the <code>progress-bar-*</code> keys in config.yml)</td></tr><tr><td><code>%ultimaterewards_available%</code></td><td>Number of rewards the player can claim right now</td></tr><tr><td><code>%ultimaterewards_available_{rewardType}%</code></td><td>Number of claimable rewards of one type only, e.g. <code>%ultimaterewards_available_time_reward%</code></td></tr><tr><td><code>%ultimaterewards_claimed_of_{rewards}%</code></td><td>How many rewards of a comma-separated list the player has already claimed, e.g. <code>%ultimaterewards_claimed_of_reward1,reward2%</code>. Suitable for non-cooldown rewards (custom, one-time and similar)</td></tr><tr><td><code>%ultimaterewards_collected_{reward}%</code></td><td>How many times the player has claimed this specific reward</td></tr><tr><td><code>%ultimaterewards_total_collected%</code></td><td>How many rewards the player has claimed in total</td></tr><tr><td><code>%ultimaterewards_current_streak_{reward}%</code></td><td>The player's current streak of a streak-based reward</td></tr><tr><td><code>%ultimaterewards_remaining_time_{reward}%</code></td><td>Play-time still missing before the reward unlocks (play-time reward types only). Formatted by <code>remaining-play-time-placeholder-format</code> in config.yml</td></tr></tbody></table>

## Play-time

<table data-full-width="true"><thead><tr><th width="404">Placeholder</th><th>Description</th></tr></thead><tbody><tr><td><code>%ultimaterewards_playtime_local%</code></td><td>Time spent on the current server, formatted by <code>play-time-placeholder-format</code> in config.yml</td></tr><tr><td><code>%ultimaterewards_playtime_local_in_hours%</code></td><td>Time spent on the current server, in whole hours</td></tr><tr><td><code>%ultimaterewards_playtime_local_in_minutes%</code></td><td>Time spent on the current server, in whole minutes</td></tr><tr><td><code>%ultimaterewards_playtime_local_formatted_{format}%</code></td><td>Time spent on the current server in a format defined inline — see below</td></tr><tr><td><code>%ultimaterewards_playtime_global%</code></td><td>Total time spent on the network (requires a shared MySQL / MariaDB / PostgreSQL backend)</td></tr><tr><td><code>%ultimaterewards_playtime_session%</code></td><td>Play-time of the current session</td></tr><tr><td><code>%ultimaterewards_afk_session_time%</code></td><td>Time elapsed in the AFK area/world, formatted by <code>afk-time-placeholder-format</code> in config.yml</td></tr></tbody></table>

### Inline play-time format

`%ultimaterewards_playtime_local_formatted_{format}%` lets you define the format directly in the placeholder instead of relying on config.yml. Because `%` and spaces cannot appear inside a placeholder, they are written as `#` and `_`:

| Written as                                                       | Renders as |
| ---------------------------------------------------------------- | ---------- |
| `%ultimaterewards_playtime_local_formatted_#hours#h_#minutes#m%` | `12h 30m`  |
| `%ultimaterewards_playtime_local_formatted_#days#_days%`         | `3 days`   |

Available units are `#days#`, `#hours#`, `#minutes#` and `#seconds#`.

## Referrals & votes

<table data-full-width="true"><thead><tr><th width="404">Placeholder</th><th>Description</th></tr></thead><tbody><tr><td><code>%ultimaterewards_referrals%</code></td><td>Total number of activations of the player's referral code</td></tr><tr><td><code>%ultimaterewards_referred_to%</code></td><td>Name of the player whose referral this player applied</td></tr><tr><td><code>%ultimaterewards_total_votes%</code></td><td>Total number of the player's votes</td></tr></tbody></table>

## Player settings

<table data-full-width="true"><thead><tr><th width="404">Placeholder</th><th>Description</th></tr></thead><tbody><tr><td><code>%ultimaterewards_setting_enabled_{setting}%</code></td><td>Whether the player has the given <a href="/configuration/rewards/reward-settings">setting</a> enabled (<code>true</code>/<code>false</code>)</td></tr></tbody></table>


# API

Developer API

{% content-ref url="/pages/U4jZaW3QA5sIR5UkYGFJ" %}
[Events](/api/events)
{% endcontent-ref %}

{% content-ref url="/pages/NLEcnJRFIJhKxBwq6xSO" %}
[Examples](/api/examples)
{% endcontent-ref %}


# Events

Bukkit events fired by the plugin that your own plugin can listen to.

All events live in the `eu.athelion.ultimaterewards.api.event` package and are fired on the Bukkit event bus, so they are registered the usual way with `@EventHandler`.

| Event                       | Cancellable | Fired when                                                      | Useful methods                                                      |
| --------------------------- | ----------- | --------------------------------------------------------------- | ------------------------------------------------------------------- |
| `PlayerPreClaimRewardEvent` | yes         | Right before a reward is claimed, before any action is executed | `getClaimer()`, `getClaimedReward()`, `getRewardActionsToExecute()` |
| `PlayerClaimedRewardEvent`  | no          | After a reward has been successfully claimed                    | `getClaimer()`, `getClaimedReward()`                                |
| `ReminderReceiveEvent`      | yes         | Before a player receives a reward reminder                      | `getReceiver()`, `getAvailableRewards()`                            |
| `ReferralCreateEvent`       | yes         | A player is creating their own referral code                    | `getCreator()`                                                      |
| `ReferralApplyEvent`        | yes         | A player is applying someone else's referral code               | `getApplier()`, `getReferrer()`                                     |
| `UserLoadedEvent`           | no          | A player's data has finished loading                            | `getUser()`                                                         |
| `UserUnloadEvent`           | no          | A player's data is being unloaded (on quit)                     | `getUser()`                                                         |

{% hint style="warning" %}
`UserLoadedEvent` can be fired asynchronously — check `isAsync()` before touching the Bukkit API from the handler.
{% endhint %}

{% hint style="info" %}
`PlayerPreClaimRewardEvent` hands you the list of actions that are about to run. Modifying that list changes what the player actually receives; cancelling the event stops the claim entirely.
{% endhint %}

See [Examples](/api/examples) for a working listener.


# Examples

How to get object of specified reward

### Getting a reward

Also you can get the reward and parse it as valid type.\
like in this example, where I take a reward called 'exampleTimeReward':

```java
final Optional<Reward> rewardOptional = UltimateReward.getRewardByName("exampleTimeReward");
if (rewardOptional.isPresent()) {
    TimeReward timeReward = (TimeReward) rewardOptional.get();
}
```

### Checking if reward exists

```java
boolean exists = UltimateReward.getRewardByName("rewardName").isPresent();
```

or you can also use the old method which is not allocating anything:

```java
boolean exists = UltimateReward.isReward("rewardName");
```


# Setting up own playtime calculator

The Custom Playtime Calculator Registration API allows you to integrate your own playtime calculation logic into the UltimateReward plugin.

#### Usage

1. **Implement Your Playtime Calculator**

   To create a custom playtime calculator, inherit from the `PlayTimeCalculator` interface and implement the `calculatePlayTime(Player player)` method. This method should contain your custom logic to calculate the playtime of the given player.<br>

   ```java
   import org.bukkit.entity.OfflinePlayer;

   public class MyOwnPlayTimeCalculator implements PlayTimeCalculator {
       @Override
       public float calculatePlayTime(OfflinePlayer player) {
           // Your custom logic to calculate player's playtime
       }
   }
   ```
2. **Register Your Calculator**

   After implementing your custom playtime calculator, register it with the UltimateReward plugin using the `registerPlayTimeCalculator()` method. This ensures that your custom logic is integrated into the playtime tracking system.

   ```java
   UltimateReward.registerPlayTimeCalculator(new MyOwnPlayTimeCalculator());
   ```

{% hint style="warning" %}
Method must return the play-time in **minutes**
{% endhint %}

**Example**

Here's a practical example demonstrating how to register a custom playtime calculator:

```java
import org.bukkit.entity.OfflinePlayer;

public class MyOwnPlayTimeCalculator implements PlayTimeCalculator {
    @Override
    public float calculatePlayTime(OfflinePlayer player) {
        // Example: return playtime in minutes
        return player.getStatistic(Statistic.PLAY_ONE_TICK) / 60.0 / 20.0; // Convert ticks to minutes
    }
}

// Register the custom playtime calculator
UltimateReward.registerPlayTimeCalculator(new MyOwnPlayTimeCalculator());
```

In this example, `MyOwnPlayTimeCalculator` calculates playtime based on Minecraft's built-in statistics, converting total playtime from ticks to minutes.


# TOS

Terms of Service

### Plugin Ownership

Do not decompile, resell, crack, or redistribute the plugin! The plugin may only be used on a server/network of which you are the owner. It is your responsibility to ensure that your staff does not leak the plugin, and it is imperative to keep your JAR file secure.

### Bugs, Issues & Support

If you encounter any issues, kindly refrain from leaving a one-star review. Bug fixes can be addressed promptly if you reach out to us directly. For support inquiries, [click here](https://discord.gg/TfUC8uJ) (make sure to review documentation before seeking assistance). If you're contacting support, please familiarize yourself with the support team policy.


