Configuration

AFK Warden is configured in plugins/AFKWarden/config.yml, which the first start creates with a comment on every key. Times are in seconds. Edit the file and run /afkwarden reload; no restart is needed.

An invalid value is reset to its default, for that key only, and the console names the key, the value it found and the value it uses instead. If config.yml is not valid YAML on /afkwarden reload, the console says so and the previous settings stay in use.

A config.yml from an earlier version gets the settings added since on the next start, with their comments. Your values are never changed.

Timers #

Key	Default	What it does
`afk-after`	`300`	Seconds of inactivity before a player is marked AFK. Minimum 10.
`kick-after`	`1200`	Seconds of inactivity before the kick. Must be greater than `afk-after`. `0` turns the kick and the warning off; the AFK mark still works.
`warn-before-kick`	`60`	How many seconds before the kick the player is warned. `0` means no warning. Must be lower than `kick-after`.

Lowering kick-after never kicks anyone on the spot: a player already past the new value is warned first and kicked no sooner than warn-before-kick later (at most one minute).

Activity #

Key	Default	What it does
`activity-sensitivity`	`10.0`	Sensitivity of the activity check, above 0 and up to 180. Lower values make smaller movements count. Keep `10.0` unless support asks you to change it.
`count-chat-as-activity`	`true`	Chat keeps a player active.
`count-commands-as-activity`	`false`	Commands keep a player active. Off on purpose; the comment in `config.yml` explains why.

Exemptions #

Key	Default	What it does
`exempt-gamemodes`	`[SPECTATOR]`	Game modes that are never marked AFK, warned or kicked.
`exempt-worlds`	`[]`	Worlds that are never marked AFK, warned or kicked, by name, such as `[lobby, afk_world]`.

Players with the afkwarden.bypass permission, and ranks with bypass: true, are exempt too. Nobody else is, not even operators.

Announcements and kicks #

Key	Default	What it does
`broadcast-afk-status`	`true`	Tell everyone when a player goes AFK and when they are back.
`use-titles`	`true`	Also show a title on the player's screen for the AFK mark and the warning.
`commands-on-kick`	`[]`	Console commands run right before the kick. `%player%` is replaced by the player's name. A line that fails is logged and never stops the kick.

commands-on-kick:
  - "say %player% was kicked for being AFK"

Per-rank settings #

With LuckPerms installed, the ranks section gives LuckPerms groups their own settings. The bundled file ships this example commented out; remove the # in front of the lines to use it, keeping the indentation:

ranks:
  vip:
    afk-after: 600
    kick-after: 2400
  staff:
    bypass: true

Keys are LuckPerms group names. Each rank accepts afk-after, kick-after, warn-before-kick and bypass; any key you leave out uses the global value. bypass: true means never marked AFK, never warned and never kicked.
Which rank applies: among a player's groups, direct or inherited, only the ones listed here count, and the one with the highest LuckPerms weight wins (lp group <name> setweight <n>; a group without a weight counts as 0). On a tie, the one listed first wins. A player with no listed group gets the global values.
The same rules as the global keys apply to each rank. An invalid value falls back to the global value of that key, and the console names the rank, the key and both values.
Changes apply by themselves: promotions, expired temporary groups, world changes and /afkwarden reload are picked up at once. /afkwarden status <player> shows the rank that applies, and so does %afkwarden_rank%.
Free applies the first entry of the section, in file order (an entry with bypass: true counts too), and ignores the rest: players whose ranks are only among the ignored entries get the global values. The console names the ignored entries at startup and on every reload, and /afkwarden status and /afkwarden license status show them. Pro applies every entry. Nothing is deleted: with Pro, every entry applies again.
Without LuckPerms the section is ignored, and one line at startup says so.

Staff who should never be kicked

Give them the afkwarden.bypass permission rather than a rank with bypass: true: the permission works on every tier, whatever the order of your ranks.

EssentialsX #

Key	Default	What it does
`sync-with-essentials`	`true`	Push the AFK status into EssentialsX when it is installed: the tab-list AFK marker, `sleep-ignores-afk-players`, `disable-item-pickup-while-afk` and `%essentials_afk%` follow AFK Warden.

Essentials must stop judging AFK on its own, otherwise the two plugins disagree. In plugins/Essentials/config.yml:

auto-afk: -1
auto-afk-timeout: -1        # called auto-afk-kick in older EssentialsX versions
cancel-afk-on-move: false
cancel-afk-on-interact: false
cancel-afk-on-fish: false   # not present in older EssentialsX versions
cancel-afk-on-chat: true
broadcast-afk-message: false

Then run ess reload in the console.

cancel-afk-on-chat stays on, so a player who typed /afk by hand can come back by chatting. broadcast-afk-message: false avoids a second "is back" announcement: AFK Warden makes its own.
AFK Warden never overrides a manual /afk: it only clears the Essentials AFK status it set itself.
When the plugin is disabled, or sync-with-essentials is switched off by a reload, every Essentials AFK status AFK Warden set is cleared, so nobody stays stuck as AFK.
EssentialsX 2.18 and newer are supported. Without EssentialsX nothing changes, except that there is no tab-list marker.

Messages #

Key	Default	What it does
`language`	`en`	`en` or `es`: which `messages_<language>.yml` the plugin uses.

Every on-screen text lives in plugins/AFKWarden/messages_en.yml and messages_es.yml, in MiniMessage format: named and hex colours (<red>, <#ff8800>), gradients, bold and italics, on Spigot and Paper alike.

afk-enter: "<prefix><yellow>You are now AFK."
kick-warning: "<prefix><red>You will be kicked for inactivity in <time>."

Set a message to "" to turn it off: nothing is sent, not even an empty line.
A key you delete falls back to the bundled text.
Click and hover tags are accepted but have no effect, and the kick screen shows hex colours as the nearest of the 16 standard colours.
Each file lists the placeholders it accepts at the top, such as <player> and <time>.

Console and updates #

Key	Default	What it does
`banner`	`true`	Print the AFK Warden banner in the console when the plugin starts. `false` prints its last line only (version, tier and website).
`update-check`	`true`	Ask Modrinth for a newer release shortly after start and then once a day, and say so in the console and, when they join, to staff with `afkwarden.admin`. Nothing is ever downloaded or installed. `false` turns the check off.

License #

Key	Default	What it does
`license.key`	`""`	Your Pro key. Empty means Free. `afkwarden license activate <key>` saves it here, comments kept.

The AW_LICENSE_KEY environment variable, when set, takes precedence over license.key (handy on hosting panels). See Licensing and payment.

Usage statistics #

Key	Default	What it does
`telemetry.enabled`	`true`	Sends us a small anonymous usage report about a minute after start and then once an hour: versions, player counts (numbers only), how many ranks are set up and how many apply, whether LuckPerms, EssentialsX and PlaceholderAPI are in use, the language and the license tier; never player names, UUIDs or IP addresses. `false` sends nothing, on Free and Pro.

/afkwarden telemetry shows the exact data of the last report and its report id. What we keep and for how long: privacy policy.

Files #

Everything AFK Warden keeps is in plugins/AFKWarden/:

File	What it holds
`config.yml`	The settings on this page.
`messages_en.yml`, `messages_es.yml`	The on-screen texts.
`install.properties`	Random identifiers of this installation. Do not share it.
`license.json`	With a store key: the result of the last license check, sealed against editing.

Reloading #

/afkwarden reload re-reads config.yml and the messages file and applies them without a restart. The idle timers are kept, so nobody gets a fresh start, and every player's rank is resolved again. A changed license.key is picked up too (the old key's activation is released first), and telemetry.enabled and update-check take effect at once. If either file is not valid YAML, the command says so and the previous settings and messages stay in use.

Never use the server's own /reload. Restart the server to update the plugin.