AFKStatus - Simple AFK Detection for Servers

AFKStatus is a lightweight, server-side mod for Minecraft, built on the NeoForge and Forge mod loader. It automatically tracks player activity and marks users as AFK (Away From Keyboard) when they stop moving or chatting for a configurable period. Players can also manually toggle AFK status using a simple /afk command.

Features

Automatic AFK detection
Detects inactivity by tracking movement and chat activity. Players are marked as AFK after a configurable timeout and broadcasted as such.

Manual AFK toggle
/afk command lets players manually set or clear AFK status.

Customizable timeouts
Set the AFK trigger delay and optional kick timeout via config.

Optional auto-kicking
Automatically kicks players who stay AFK beyond a set time.

Custom messages and colors
System messages are customizable, including color options.

Scoreboard integration
Uses Minecraft's team system to visually tag AFK players with [AFK].

Server-only
No client-side installation required. Just drop the mod into your server's mods/ folder.

Configuration

After the first server launch, a configuration file (afkstatus-server.toml) is created in your config/ directory.

afkTriggerTimer — Minutes of inactivity before a player is market afk.
Default: 5
Range: 1-60 minutes

afkKickTimer — Minutes after being AFK before being kicked.
Default: 0 (disabled)
Range: 0-120 minutes

kickMessage — Kick message that is shown to the player once he is kicked.

systemMessages — Whether to broadcast AFK status changes.
Default: false
Options: true / false

checkIntervalTick — How often to check AFK status.
(20 ticks = 1 second)
Default: 20
Range: 1-1200 ticks

messageColor — Messages color.
Default: yellow

detection.enabled — If true, mouse look (camera rotation) counts as activity.
Default: false

detection.thresholdDegrees — Minimum change in yaw/pitch required to count as activity.
Default: 5
Range: 1-45 degrees

Valid colors: black, dark_blue, dark_green, dark_aqua, dark_red, dark_purple, gold, gray, dark_gray, blue, green, aqua, red, light_purple, yellow, white

bypassEnabled
Bypasses afk players for sleep percentage

Blacklist

AFKStatus includes a flexible blacklist system to exclude specific players from the automatic AFK kick functionality. This is useful for server staff, trusted players, or bots that need to remain connected despite inactivity.

Storage: Blacklist entries are saved as JSON file (afk_blacklist.json) inside config/AFKStatus/ directory.
Commands: Admins can change the blacklist in-game using /afk blacklist subcommands.
Behaviour:
- Blacklisted players are tracked for AFK status and tagged normally.
- Blacklisted players will not be kicked for being AFK, regardless of the configured kick timer.

Commands

/afk — Toggles your AFK status. Automatically broadcasts status changes to others.

/afk help— Shows the help instructions for AFKStatus commands.

Commands below require administrator permissions

/afk blacklist add — Adds a player to the AFK blacklist. Blacklisted players can go AFK but will not be kicked automatically.

/afk blacklist remove — Removes a player from the AFK blacklist.

/afk blacklist list — Lists all players currently on the AFK blacklist.

afk blacklist reload — Reloads blacklist from disk, useful if edited manually.

This lets players manually indicate they’re AFK or return without moving or chatting.