Install and first steps

Download #

Before you install, check the requirements: Spigot or Paper 1.16.5 – 26.3, and Java 8 or newer. Folia is not supported.

Install #

1. Put AFKWarden-1.0.0.jar in your server's plugins/ folder.

2. Restart the server. Do not use /reload.

3. Watch the console. When it starts, AFK Warden prints a small banner that ends with its version and tier (with banner: false in config.yml, only that last line):

      _   ___ _  __
     /_\ | __| |/ /
    / _ \| _|| ' <
   /_/ \_\_| |_|\_\  Warden
   AFK Warden v1.0.0 · Free · coolapps.fyi

The first start creates config.yml, messages_en.yml and messages_es.yml in plugins/AFKWarden/. Players are tracked from that moment, with the default timers: AFK after 5 minutes, a warning at 19 and the kick at 20. There is no database to install.

Commands in this guide are written for the game, with a slash (/afkwarden list). In the server console, type them without the slash (afkwarden list). The short alias /afkw works in place of /afkwarden (/afkw list).

First steps #

1. Start with AFK marks only #

For the first few days, let AFK Warden mark players without kicking anyone. In plugins/AFKWarden/config.yml:

kick-after: 0

Run /afkwarden reload (the idle timers are kept), watch /afkwarden list for a few days, then set the kick timer you want, in seconds (1200 is 20 minutes).

2. Keep the vanilla idle kick off #

Keep player-idle-timeout=0 in server.properties, so the server does not run a second, weaker idle kick of its own.

3. Exempt your staff #

Nobody is exempt by default, not even operators, and essentials.afk.kickexempt has no effect on AFK Warden. Give afkwarden.bypass to whoever should never be marked AFK, warned or kicked. With LuckPerms, from the console:

lp group staff permission set afkwarden.bypass true

Game modes and worlds can be exempt too (exempt-gamemodes, exempt-worlds; spectators are exempt as shipped). See Configuration.

4. EssentialsX #

With EssentialsX installed, AFK Warden pushes its AFK status into Essentials, so the tab-list AFK marker, sleeping and item pickup follow it. 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. When it starts, AFK Warden logs one warning line for each of these settings that is not applied yet. Details in Configuration.

5. Timers per rank (optional) #

With LuckPerms, the ranks section of config.yml gives ranks their own timers, or lets them bypass the plugin:

ranks:
  vip:
    afk-after: 600
    kick-after: 2400

Free applies the first entry of the section, Pro every entry. See Per-rank settings.

6. Pro (optional) #

Activate your key in the console with afkwarden license activate <key>; the answer arrives a moment later. See Licensing and payment.

Updating #

AFK Warden asks Modrinth for a newer release shortly after the server starts and then once a day. When there is one, the console says so, and staff with afkwarden.admin get a line in chat when they join. It never downloads anything by itself: to update, replace the jar in plugins/ with the new one and restart the server. update-check: false in config.yml turns the check off.

When a new version adds settings, your config.yml gets them on the next start, appended with their comments. Your values are never changed.