> For the complete documentation index, see [llms.txt](https://ultimaterewards.athelion.eu/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ultimaterewards.athelion.eu/placeholders.md).

# 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.md).

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.md">setting</a> enabled (<code>true</code>/<code>false</code>)</td></tr></tbody></table>
