> 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/features/playtime-and-milestones.md).

# Playtime & Milestones

XTimeRewards tracks five counters per player at all times: **daily**, **weekly**, **monthly**, **yearly**, and **lifetime (total)** playtime. Playtime shown to players (command, GUI, placeholders) is always live and second-accurate; it's only written to storage every `tracking.interval-seconds` (`config.yml`), so a crash never loses more than that one interval.

## Viewing playtime

* `/xtimerewards` (or `/playtime`, or whatever [custom alias](/home/xtimerewards/getting-started/getting-started.md#custom-command-names) you've configured) — opens the playtime menu if `playtime-menu.enabled` is `true` (`config.yml`), otherwise prints a plain-text summary.
* `/xtimerewards top [period] [page]` — the leaderboard for a given period (defaults to lifetime).

Both are backed by [customizable menus](/home/xtimerewards/features/menus.md) (`menus/playtime.yml`, `menus/top.yml`) when `playtime-menu.enabled` is on.

## Milestones (`milestones.yml`)

A milestone is a playtime threshold with a reward attached, organized under one of five sections: `daily`, `weekly`, `monthly`, `yearly`, or `total` (lifetime — the one-time "big achievement" tier, since it never resets).

```yaml
weekly:
  - id: weekly_5h
    display-name: "<green>5 hours this week"
    required-seconds: 18000
    auto-claim: true
    icon: CLOCK
    lore:
      - ""
      - "<yellow>REWARDS:"
      - "<gray> - $200"
    rewards:
      - type: economy
        value: "200"
```

| Field                 | Meaning                                                                                                                                                                                                       |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                  | Unique identifier — used by `/xtimerewards claim <id>` and in claim storage.                                                                                                                                  |
| `display-name`        | MiniMessage (or legacy `&a` / `&#RRGGBB`) text.                                                                                                                                                               |
| `required-seconds`    | Playtime threshold for that period.                                                                                                                                                                           |
| `required-permission` | Optional — only players holding this node are even eligible, letting you scope a milestone to a specific rank.                                                                                                |
| `auto-claim`          | `true` = granted the instant the threshold is crossed. `false` = the player must run `/xtimerewards claim <id>` or click it in the GUI.                                                                       |
| `icon`                | Bukkit `Material` name, used in the GUI.                                                                                                                                                                      |
| `lore`                | Optional extra MiniMessage lines shown under the built-in required-time/status lines. There's no automatic "here's what you get" line — write it by hand (as the example does) and edit/remove/reword freely. |
| `rewards`             | A list of reward entries (see below).                                                                                                                                                                         |

Crossing is detected as `previous < required <= current`, so it fires exactly once per period with no separate "already notified" bookkeeping.

## Reward types

Every reward-bearing file in the plugin (`milestones.yml`, `streaks.yml`, `leaderboard-rewards.yml`, `afk-mode-rewards.yml`) shares the same `rewards:` entry format:

| Type          | Fields                               | Behavior                                                                                                                                                                                                                                                                                                     |
| ------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `command`     | `value`                              | Run as console, with `%player%` substituted.                                                                                                                                                                                                                                                                 |
| `message`     | `value`                              | Sent to the player.                                                                                                                                                                                                                                                                                          |
| `item`        | `material`, `amount`, `name`, `lore` | Gives a real item straight to the player's inventory (drops it at their feet if full). `name`/`lore` are optional and support MiniMessage; `amount` defaults to `1`.                                                                                                                                         |
| `economy`     | `value`                              | Deposits `value` (a number) straight into the player's Vault-linked economy balance. Requires Vault **and** an economy plugin (EssentialsX, CMI, ...) actually registered with it — otherwise this type is never registered at all (check the console on startup) and entries using it are silently skipped. |
| `placeholder` | `value`                              | Resolves `value` as a PlaceholderAPI expression against the player and discards the result — for expansions that expose an "action" placeholder with a side effect baked in (some points/currency/quest plugins do this deliberately as an integration hook). Requires PlaceholderAPI.                       |

{% hint style="info" %}
Other plugins can register their own reward types via `XTimeRewardsAPI#registerRewardType` — see [Developer API](/home/xtimerewards/reference/developer-api.md). `streaks.yml` also adds one more type, `streak-freeze-item`, covered in [Daily Login Streaks](/home/xtimerewards/features/streaks.md).
{% endhint %}

## Claiming

* `auto-claim: true` milestones grant automatically the moment they're reached.
* `auto-claim: false` milestones need `/xtimerewards claim <id>`, or a click in the playtime menu — both go through the same validated path (re-checks progress/eligibility server-side rather than trusting the caller).

## Manual admin control

`/xtimerewards admin milestone <set|add|remove|reset> <player> <period> <seconds>` directly edits a player's playtime counters (see [Commands](/home/xtimerewards/reference/commands.md) for full syntax) — `add`/`remove` also adjust the lifetime total in lockstep so it stays consistent. From the per-player [admin GUI](/home/xtimerewards/features/admin-tools.md), left-click/right-click/shift-click on a milestone lock it, unlock it, or unlock-and-grant it.

## Placeholders & Discord

See [PlaceholderAPI](/home/xtimerewards/reference/placeholderapi.md) for `%xtimerewards_playtime_<period>%`, `%xtimerewards_rank_<period>%`, `%xtimerewards_next_milestone_name%` and friends. Lifetime milestone claims can also post a Discord embed — see [Discord Integration](/home/xtimerewards/features/discord.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/features/playtime-and-milestones.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.