> For the complete documentation index, see [llms.txt](https://docs.xandtech.fr/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.xandtech.fr/home/xtimerewards/readme.md).

# Introduction

XTimeRewards is a Paper plugin that rewards players for their playtime and engagement: threshold-based **milestones** (daily/weekly/monthly/yearly/lifetime), **daily login streaks** with a freeze-protection item, **leaderboards** with automatic period-end payouts, a timeout-based **AFK detector**, and a voluntary **reward-earning AFK mode**. Everything is menu-driven, fully customizable through YAML, and works standalone or across a network of servers sharing one MySQL database.

## What's in here

* [**Playtime & Milestones**](https://docs.xandtech.fr/home/xtimerewards/features/playtime-and-milestones.md) — daily/weekly/monthly/yearly/lifetime playtime tracking, with custom reset times, and a fully configurable milestone/reward system (`milestones.yml`) supporting command, message, item, economy, and PlaceholderAPI reward types — plus your own via the developer API.
* [**Daily Login Streaks**](https://docs.xandtech.fr/home/xtimerewards/features/streaks.md) — consecutive-day login tracking with its own reward tiers (`streaks.yml`), a physical, consumable **Streak Freeze** item that protects a streak through one missed day (optionally player-craftable), and full admin management.
* [**Leaderboards & Leaderboard Rewards**](https://docs.xandtech.fr/home/xtimerewards/features/leaderboards.md) — `/top` and `/streaktop`, plus automatic, cross-server-safe payouts to the top ranks the instant a period rolls over (`leaderboard-rewards.yml`), with a customizable server-wide broadcast.
* [**AFK Detection**](https://docs.xandtech.fr/home/xtimerewards/features/afk-detection.md) — timeout-based idle detection with configurable chat/boss bar/title/action bar warnings and cosmetic effects; can pause playtime accrual or track AFK time separately.
* [**AFK Mode**](https://docs.xandtech.fr/home/xtimerewards/features/afk-mode.md) — an opt-in `/afk` mode that teleports a player to a fixed point and grants configured rewards on a timer until they leave, with an optional daily reward cap, player invisibility, and randomly-appearing bonus items.
* [**Discord Integration**](https://docs.xandtech.fr/home/xtimerewards/features/discord.md) — webhook notifications for leaderboard results, lifetime milestones, and new streak records.
* [**Admin Tools**](https://docs.xandtech.fr/home/xtimerewards/features/admin-tools.md) — a full per-player admin GUI, a chronological reward-history log, multi-account (shared-IP) detection with in-game alerts, and a data-export command (YAML/JSON/CSV).
* [**Menus & GUI Customization**](https://docs.xandtech.fr/home/xtimerewards/features/menus.md) — every menu (playtime, leaderboard, streak, AFK mode, admin views) is defined in its own YAML file: layout, items, custom heads, live-refreshing counters, all editable without touching code.
* Bundled in **8 languages** out of the box (English, French, Spanish, German, Portuguese (Brazil), Italian, Russian, Chinese (Simplified)), with automatic per-player locale selection.
* A public [**Developer API**](https://docs.xandtech.fr/home/xtimerewards/reference/developer-api.md) for other plugins to read playtime/rank data or register custom reward types.

## Requirements

* Paper (or a Paper fork) `1.21.x` or newer — API version `26.2`.
* Java 21+ (the plugin itself is built and tested against Java 25).

Everything else is optional:

| Plugin                                                                                  | Needed for                                                             |
| --------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| [Vault](https://www.spigotmc.org/resources/vault.34315/) + any Vault-compatible economy | The `economy` reward type                                              |
| [PlaceholderAPI](https://www.spigotmc.org/resources/placeholderapi.6245/)               | The `%xtimerewards_*%` placeholders, and the `placeholder` reward type |

None of these are required to run XTimeRewards — each integration only activates if the corresponding plugin is actually installed.

## Where to start

New to XTimeRewards? Read [Installation & Setup](https://docs.xandtech.fr/home/xtimerewards/getting-started/getting-started.md) first. From there:

* Setting up rewards? Start with [Playtime & Milestones](https://docs.xandtech.fr/home/xtimerewards/features/playtime-and-milestones.md), then [Daily Login Streaks](https://docs.xandtech.fr/home/xtimerewards/features/streaks.md) and [Leaderboards & Leaderboard Rewards](https://docs.xandtech.fr/home/xtimerewards/features/leaderboards.md).
* Setting up AFK handling? See [AFK Detection](https://docs.xandtech.fr/home/xtimerewards/features/afk-detection.md) (passive) and [AFK Mode](https://docs.xandtech.fr/home/xtimerewards/features/afk-mode.md) (opt-in, reward-earning).
* Managing existing players? See [Admin Tools](https://docs.xandtech.fr/home/xtimerewards/features/admin-tools.md) and the [Permissions](https://docs.xandtech.fr/home/xtimerewards/reference/permissions.md) reference.
* Customizing the look of the menus? See [Menus & GUI Customization](https://docs.xandtech.fr/home/xtimerewards/features/menus.md).
