> 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**](/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**](/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**](/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**](/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**](/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**](/home/xtimerewards/features/discord.md) — webhook notifications for leaderboard results, lifetime milestones, and new streak records.
* [**Admin Tools**](/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**](/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**](/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](/home/xtimerewards/getting-started/getting-started.md) first. From there:

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


---

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

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

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

```
GET https://docs.xandtech.fr/home/xtimerewards/readme.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

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