AFK Detection

AntiAFKPlus uses multiple detection methods to determine whether a player is active. If any enabled method records activity, the player's inactivity timer resets to zero.

Detection Methods

Head Rotation (Primary)

The most reliable detection method. Monitors changes in the player's camera angle (yaw and pitch).

detection:
  head-rotation:
    enabled: true
    threshold: 3.0    # Minimum angle change in degrees

This method defeats most basic AFK bypasses (e.g., tape on the mouse) because it requires meaningful rotation changes above the threshold. Tiny jitters from auto-clickers or macro tools are filtered out.

Yaw wrap-around handling: The plugin correctly handles the yaw boundary at 360°/0°. For example, rotating from 359° to 1° is calculated as a 2° change, not 358°.

Bedrock players (Geyser / Floodgate): Bedrock clients send less precise head rotation data. The plugin detects Bedrock players by their username prefix (default: .) and multiplies the base threshold by a configurable sensitivity factor (default: 0.8). This means a base threshold of 3.0 becomes 2.4 for Bedrock players, making detection slightly more lenient to avoid false positives.

integrations:
  bedrock-sensitivity: 0.8
  bedrock-prefix: "."

Movement

Tracks player position changes (X, Y, Z coordinates).

detection:
  movement:
    enabled: true
    threshold: 0.5    # Minimum distance in blocks

The threshold prevents false positives from minor client-side rubber-banding. Players must move at least the configured distance between checks.

Block Interaction

Detects breaking or placing blocks.

detection:
  block-interaction:
    enabled: true

Chat

Monitors chat messages. Optionally includes commands.

detection:
  chat:
    enabled: true
    include-commands: true

When include-commands is true, executing any command (e.g., /help, /tp) also counts as activity.

Combat

Detects damage dealt or received by the player.

detection:
  combat:
    enabled: true

Both attacking entities and being attacked count as activity.

Inventory

Monitors inventory interactions — opening, clicking, and closing inventories.

detection:
  inventory:
    enabled: true

Additional Detection

The following events are also tracked internally under the movement detection category:

• Sneaking (toggling sneak)
• Jumping (upward Y movement > 0.4 blocks)

How Checks Work

Detection methods are split into two categories:

Snapshot-based (compared every check-interval seconds):

• Head rotation — compares camera angle between snapshots
• Movement — compares position between snapshots

Event-based (tracked in real-time via Bukkit listeners):

• Block interaction, chat, combat, inventory, sneaking, jumping

Every check-interval seconds (default: 30), the plugin takes a new snapshot and compares it to the previous one:

1. Head rotation — Has the camera angle changed by more than threshold degrees?
2. Position — Has the player moved more than threshold blocks?
3. Event-based methods fire immediately when the event occurs, resetting the timer in real-time.

If a player changes worlds, the movement distance is treated as infinite (Double.MAX_VALUE), so world changes always count as activity.

If no method detects activity between two check cycles, the player's idle time increases.

Choosing Detection Methods

For most servers, the default configuration works well. Here are some recommendations:

Exemptions

Players can be exempt from AFK detection through several mechanisms. The exemptions section in config.yml controls automatic exemptions:

exemptions:
  op-exempt: true             # OPs are never kicked
  join-grace-period: 60       # Seconds of immunity after joining
  spectator-exempt: true      # Spectator mode players are exempt
  vanished-exempt: true       # Vanished players (SuperVanish, PremiumVanish, Essentials, CMI) are exempt
  vehicle-exempt: false       # Players in vehicles (boats, minecarts) are exempt
  min-player-count: 0         # Don't enforce AFK kicks below this player count
  exempt-gamemodes: []        # List of gamemodes to exempt (e.g. ["CREATIVE", "ADVENTURE"])
  exempt-items: []            # Exempt players holding specific items

Additional exemption methods:

• Permission: antiafk.bypass — fully exempt from detection
• Per-group: Set timeout: -1 for a LuckPerms group
• Admin command: /antiafk exempt <player> [time] — temporary or permanent exemption

On-Return Behavior

When a player returns from being AFK, the plugin can perform several actions:

on-return:
  teleport-back: true         # Teleport player back to their original location (if teleported by an AFK action)
  message:
    enabled: true
    text: "&aWelcome back! You were AFK for %time%"
  cooldown: 0                 # Seconds before AFK detection restarts after returning

The teleport-back feature works with the teleport warning stage action — if a player was teleported to an AFK area, they'll be returned to their original location when they move again.

Folia Compatibility

AntiAFKPlus fully supports Folia, Paper's regionized multithreading server. The plugin automatically detects Folia at startup and uses region-aware scheduling:

• Per-player AFK checks run on the correct region thread
• Teleportation uses async teleport APIs
• All tasks use the entity scheduler instead of the global scheduler

No configuration changes are needed — the plugin adapts automatically. The folia-supported: true flag is declared in plugin.yml.

Debug Mode

Enable debug mode to see exactly what activity is being detected:

/antiafk debug

Console output example:

[AntiAFK] [Debug] Steve: Activity: head-rotation
[AntiAFK] [Debug] Steve: Activity: block-break
[AntiAFK] [Debug] Alex: Ignored (anti-bypass): sneak-spam