AFKControl (1.21 - 26.2)

AFKControl
Modern, accurate and lightweight AFK management for Paper servers.

AFKControl is an AFK detection and status plugin designed to distinguish meaningful player activity from passive or accidental movement.

Traditional AFK plugins often rely almost entirely on position changes. This can produce false activity when players are moved by water, pistons, vehicles, server mechanics or other external forces.

AFKControl takes a smarter approach. It can prioritize intentional camera movement, interactions, chat, commands and other configurable activity sources while filtering tiny camera jitter and suspiciously large position changes.

More info: carjavplugins.com

AFKControl is an AFK detection and status plugin. It does not kick players by default.

Features

Smart AFK Detection

• Automatic AFK detection after a configurable inactivity period
• Camera-based activity detection using yaw and pitch thresholds
• Accumulated camera movement detection
• Slow, intentional camera turns are recognised correctly
• Tiny camera jitter can be ignored
• Optional position-based movement detection
• Configurable maximum movement distance per event
• Debounce protection against micro-movement spam
• Activity cooldown system for better performance
• Automatic recovery when players return from excluded worlds or gamemodes

Manual AFK Management

• Toggle your own AFK status with /afk or /away
• Check your own AFK status
• Check another player's AFK status
• List all currently AFK players
• Staff commands to set or remove another player's AFK status
• Manual AFK remains available to players with automatic-detection bypass

Filters and Permissions

• World whitelist and blacklist support
• Gamemode whitelist and blacklist support
• Permission-based automatic AFK bypass
• Separate permissions for every command
• Optional permission-only AFK broadcasts
• Administrative parent permission

Player Feedback

• Configurable AFK title and subtitle
• Configurable AFK action bar with live duration
• Configurable sounds
• Join and leave AFK broadcasts
• Private status messages
• MiniMessage formatting support
• Clean title and action-bar formatting without forced chat prefixes

How Activity Detection Works
AFKControl can detect several types of meaningful player activity:

• Camera movement
• Block interaction
• Entity interaction
• Inventory interaction
• Chat messages
• Commands
• Item usage
• Combat activity
• Optional player movement
  Camera movement is measured using configurable yaw and pitch thresholds.

Position-based detection is disabled by default because position changes are not always caused by the player. Water currents, pistons, vehicles, plugins and other mechanics can move a player without representing real activity.

Commands
/afk
/away
/afk status [player]
/afk list
/afk set <player>
/afk unset <player>
/afk reload
/afk help

Command Description
/afk Toggle your own AFK status
/away Alias of /afk
/afk status Check your current AFK status
/afk status <player> Check another player's AFK status
/afk list List currently AFK players
/afk set <player> Manually mark a player as AFK
/afk unset <player> Remove a player's AFK status
/afk reload Reload configuration and messages
/afk help Display the available commands

Permissions
Permission Description Default
afkcontrol.toggle Toggle your own AFK status manually true
afkcontrol.status Check your own AFK status true
afkcontrol.status.others Check another player's AFK status op
afkcontrol.list List currently AFK players op
afkcontrol.set Set another player as AFK op
afkcontrol.unset Remove another player's AFK status op
afkcontrol.reload Reload the plugin configuration op
afkcontrol.see-broadcast Receive permission-restricted AFK broadcasts true
afkcontrol.bypass Ignore automatic AFK detection false
afkcontrol.admin Includes the main administrative permissions op

Bypass Behaviour
afkcontrol.bypass only disables automatic AFK detection.

Players with this permission can still:

• Use /afk
• Use /away
• Be manually marked as AFK by staff
• Leave a manually assigned AFK state normally

PlaceholderAPI
PlaceholderAPI is optional.

When PlaceholderAPI is installed, the following placeholders are available:

Placeholder Description
%afkcontrol_is_afk% Returns whether the player is currently AFK
%afkcontrol_afk_players_count% Returns the number of currently AFK players
%afkcontrol_afk_time% Returns a readable AFK duration
%afkcontrol_afk_stopwatch% Returns AFK duration in MM:SS format
%afkcontrol_afk_seconds% Returns AFK duration in seconds
%afkcontrol_afk_since% Returns the timestamp when AFK started

Recommended Activity Configuration

activity:
reset-on-move: false
reset-on-look: true

look-yaw-threshold: 12.0
look-pitch-threshold: 8.0
look-debounce-millis: 500

activity-cooldown-millis: 300
max-move-distance-per-event: 5.0

We recommend keeping reset-on-move disabled unless your server specifically requires position-based activity detection.

This prevents passive movement caused by water, pistons, vehicles or external server mechanics from incorrectly resetting the AFK timer.

Maximum Movement Distance
When movement detection is enabled, AFKControl can ignore unusually large position changes:

activity:
max-move-distance-per-event: 5.0

Movement greater than this distance within one movement event is treated as a possible teleport or artificial displacement.

World and Gamemode Filters
AFKControl supports whitelist and blacklist filtering for:

• Worlds
• Gamemodes
  Players excluded by these filters are not automatically marked as AFK.

When a player returns to a tracked world or gamemode, AFKControl starts a fresh inactivity period instead of reusing an old timer accumulated while the player was excluded.

The same protection applies when an automatic-detection bypass permission is added or removed.

Messages and Visual Feedback
AFKControl includes configurable:

• Chat messages
• AFK broadcasts
• Titles
• Subtitles
• Action bars
• Sounds
• Time formats
• Prefixes
• MiniMessage formatting
  The AFK action bar can display a live timer and is shown immediately when the player becomes AFK.

Multi-Language Support
Included languages:

• English
• Spanish
• Brazilian Portuguese
  The active language can be selected in the configuration.

Message files can be edited directly and reloaded using:

/afk reload

Performance
AFKControl is designed to remain lightweight even on active servers.

• Minimal runtime player state
• One efficient scheduled AFK check
• Debounced camera detection
• Activity cooldown protection
• No database operations
• No periodic file writes
• No mandatory external dependencies
• Thread-safe handling of asynchronous chat activity
• Player state is cleaned when players disconnect
• Configuration can be reloaded without restarting the server

Requirements

• Java 21
• PlaceholderAPI — optional