> 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/afk-detection.md).

# AFK Detection

A timeout-based, passive system — completely separate from the opt-in, reward-earning [AFK Mode](/home/xtimerewards/features/afk-mode.md). A player is tracked "activity-based": movement, interacting, chatting, running commands, and clicking inventories all count as activity.

```yaml
afk:
  enabled: true
  timeout-seconds: 300
  pause-playtime: true
  track-afk-playtime: true
```

| Field                | Meaning                                                                                                                                                                                                                                                                            |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enabled`            | Master switch.                                                                                                                                                                                                                                                                     |
| `timeout-seconds`    | How long without any activity before a player is considered AFK.                                                                                                                                                                                                                   |
| `pause-playtime`     | While AFK, stop accruing normal daily/weekly/monthly/yearly/total playtime (and therefore pause milestone progress too) until active again.                                                                                                                                        |
| `track-afk-playtime` | Also track a separate lifetime "AFK time" counter. Only meaningful if you reference `{afk}`/`{afk_seconds}` in a menu or the `%xtimerewards_afk%`/`%xtimerewards_afk_formatted%` placeholders — leave `false` to skip the extra storage writes if you don't plan on displaying it. |

## Warning the player

Each channel below can be toggled independently. Messages accept `{player}`, `{afk_session}`/`{afk_session_seconds}` (current AFK streak) and `{afk}`/`{afk_seconds}` (lifetime AFK total, only meaningful if `track-afk-playtime` is on).

```yaml
afk:
  notify:
    enabled: true
    chat:
      enabled: true
      message: "<gray>You are now <yellow>AFK</yellow>. Move to become active again.</gray>"
    bossbar:
      enabled: false
      message: "<yellow>⏸ AFK</yellow> <gray>— move to stop</gray>"
      color: YELLOW      # PINK, BLUE, RED, GREEN, YELLOW, PURPLE, WHITE
      overlay: PROGRESS  # PROGRESS, NOTCHED_6, NOTCHED_10, NOTCHED_12, NOTCHED_20
      progress: 1.0
    title:
      enabled: true
      title: "<yellow>AFK</yellow>"
      subtitle: "<gray>Move to become active again</gray>"
    actionbar:
      enabled: false
      message: "<yellow>⏸ You are AFK</yellow> <gray>({afk_session})</gray>"
```

* `chat` — sent once, the moment the player becomes AFK.
* `bossbar` — shown continuously (kept alive, updated every `tracking.interval-seconds`) while AFK.
* `title` — re-sent continuously (every few seconds, so it never fades out) while AFK.
* `actionbar` — re-sent every tick while AFK.

## Cosmetic effects

```yaml
afk:
  effects:
    particle:
      enabled: false
      type: PORTAL   # any org.bukkit.Particle name
      count: 6
      offset-x: 0.3
      offset-y: 0.6
      offset-z: 0.3
    glow:
      enabled: true
```

`glow` adds a plain (non-configurable) colored outline via a scoreboard team.

{% hint style="info" %}
The glow color isn't customizable: it's a scoreboard-team effect, and a nametag/tablist plugin (TAB, etc.) commonly takes over **all** team assignment on a server, silently overriding any color XTimeRewards tries to set. Not worth the config surface for a purely cosmetic effect — if your tablist plugin conflicts, disable one or the other.
{% endhint %}

## Placeholders

`%xtimerewards_is_afk%`, `%xtimerewards_afk%` / `%xtimerewards_afk_formatted%` (lifetime), `%xtimerewards_afk_session%` / `%xtimerewards_afk_session_formatted%` (current streak, live from the moment they went idle) — see [PlaceholderAPI](/home/xtimerewards/reference/placeholderapi.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/afk-detection.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.