JustAFK

JustAFK is a lightweight, server-side AFK plugin for Bukkit-compatible Minecraft servers.

It detects inactive players through movement input, provides manual and administrative AFK controls, announces AFK state changes, and can display the current AFK duration directly in the TAB player list.

JustAFK focuses on being simple, configurable, and easy to run. It does not use NMS, databases, client mods, or external runtime libraries.

JustAFK is completely server-side. Players do not need to install anything on their clients.

Compatibility notice: The latest version, JustAFK 1.1.0, requires Minecraft 1.21.3 or newer and Java 21 or newer.

Servers below Minecraft 1.21.3 can continue using JustAFK 1.0.1, which supports older server versions but uses the previous position-based AFK detection.

Why use JustAFK?

• Lightweight input-aware AFK detection
• Global plugin enable/disable control
• Independently configurable automatic AFK detection
• Manual AFK command for every player
• Administrative control over other online players
• Configurable inactivity timeout
• Configurable AFK announcements
• Optional TAB player-list prefix
• AFK duration shown in minutes or hours
• AFK state preserved during knockback and external movement
• AFK state and duration preserved through death and respawn
• Player-list name preservation for compatibility with formatting plugins
• Immediate configuration saving through commands
• Command tab completion
• Folia-aware scheduling
• No NMS, databases, or external runtime dependencies
• Compatible with permission managers such as LuckPerms
• Completely server-side

JustAFK only marks players as AFK. It does not kick, freeze, teleport, punish, or restrict them.

Preview

Player list	Chat announcements

Compatibility

JustAFK 1.1.0

JustAFK 1.1.0 uses the player-input API introduced in modern Minecraft server versions.

Platform	Supported versions	Status
Paper	1.21.3–26.2	Supported and recommended; Paper 26.2 is the primary development target
Purpur	1.21.3–26.2	Supported Paper fork
Folia	1.21.3–26.2	Uses native Folia schedulers where a server build is available
Spigot	1.21.3–26.2	Compatibility-compiled against Spigot 1.21.3
CraftBukkit	1.21.3–26.2	Supported through the Bukkit API
Sponge	Not supported	Uses a different plugin API and lifecycle
BungeeCord, Velocity, Waterfall	Not supported	Proxy platforms; install JustAFK on the backend server instead

Version 1.1.0 is built against Paper 26.2 build 84 and compatibility-compiled against Spigot 1.21.3.

Both compilations must produce identical class files before the project build passes.

The JAR uses Java 21 bytecode. The server may require a newer Java version depending on its Minecraft version. For example, Paper 26.2 requires Java 25.

The api-version is set to 1.21.3, causing unsupported older servers to refuse to load the plugin instead of failing later when the movement-input API is used.

Older Minecraft versions

Servers below Minecraft 1.21.3 should continue using JustAFK 1.0.1.

Platform	JustAFK 1.0.1 compatibility
Paper	1.8.8–26.2
Purpur	1.14.1–26.2
Folia	1.19.4–26.2
Spigot / CraftBukkit	1.8.8–26.2, best-effort

JustAFK 1.0.1 uses Java 8-compatible bytecode and remains available for servers that cannot upgrade to Minecraft 1.21.3.

However, version 1.0.1 does not include:

• Input-aware activity detection
• Protection against AFK removal caused by knockback or external movement
• The global enabled option
• The independent automatic-afk-enabled option

Version 1.0.1 detects activity through position changes. A slime, mob, arrow, explosion, water current, or another external force may therefore reset the inactivity timer or remove AFK.

The supported version ranges do not mean that every intermediate server release has been individually runtime-tested.

How AFK detection works

By default, a player is marked as AFK after 300 seconds, or five minutes, without movement input.

JustAFK 1.1.0 detects the following inputs:

• Forward
• Backward
• Left
• Right
• Jump
• Sneak
• Sprint

When one of these inputs is detected:

• The inactivity timer is restarted
• An AFK player immediately becomes active
• The AFK TAB prefix is removed
• The configured active announcement is sent

JustAFK combines two detection methods:

• PlayerInputEvent detects immediate input changes and short key presses
• Player#getCurrentInput() polling keeps the player active while a movement input remains held

Automatic detection runs once per second. This keeps the timer responsive without checking every server tick.

A held key or client-side movement toggle continues to count as activity while the server reports that input as active.

External movement

Position changes do not count as activity unless the player is also sending movement input.

An AFK player therefore remains AFK when moved by:

• Entity collisions
• Pets or mobs pushing the player
• Slimes
• Zombie attacks
• Skeleton arrows
• Knockback
• Explosions
• Flowing water
• Bubble columns
• Pistons
• Shulkers
• Gravity or falling
• Passive vehicle movement
• Server or plugin teleports
• Death
• Respawn

These events do not restart the inactivity timer or reset the displayed AFK duration.

If the player sends movement input while receiving knockback or another external force, the player is considered active because movement input is being received from the client.

Looking around with the mouse does not reset the timer.

AFK sessions

AFK states are session-based:

• Death does not reset the AFK state
• Respawn does not reset the AFK state
• External movement does not reset the AFK state
• Movement input removes the AFK state
• Manually turning AFK off starts a fresh inactivity period
• Disconnecting removes the tracked session
• Reconnecting starts a new session and resets the AFK state

Plugin operating modes

Plugin enabled

The default global state is:

enabled: true

When enabled, JustAFK operates normally according to the remaining configuration.

The setting can be changed at runtime:

/justafk set enabled on
/justafk set enabled off

Plugin disabled

When enabled is set to false:

• Player activity is no longer tracked
• Automatic AFK detection stops
• /afk no longer changes AFK states
• Administrative AFK changes are disabled
• Existing plugin-managed AFK states are cleared
• Player-list prefixes managed by JustAFK are restored
• AFK announcements stop
• AFK duration updates stop

The configuration commands remain available:

• /justafk
• /justafk help
• /justafk status
• /justafk reload
• /justafk set ...

This allows administrators to inspect, configure, reload, and enable the plugin again without restarting the server.

Re-enabling JustAFK starts a fresh activity-tracking session for online players.

Automatic AFK enabled

Automatic AFK detection is enabled by default:

automatic-afk-enabled: true

Players are automatically marked as AFK after the configured inactivity timeout.

Automatic AFK disabled

Automatic AFK detection can be disabled independently:

automatic-afk-enabled: false

It can also be changed at runtime:

/justafk set automatic-afk on
/justafk set automatic-afk off

When automatic AFK detection is disabled:

• Inactivity does not place players into AFK automatically
• Players can still use /afk
• Administrators can still control another player's AFK state
• Movement input still removes a manually applied AFK state
• Announcements continue to work for manual AFK changes
• The player-list prefix continues to work for manual AFK states

This allows JustAFK to operate exclusively as a manual AFK plugin.

AFK duration

The optional TAB prefix displays how long the player has been marked as AFK.

Examples:

• A newly AFK player displays 0m
• Five minutes displays 5m
• Fifty-nine minutes displays 59m
• One hour displays 1h
• Two hours displays 2h

Minutes are shown below 60 minutes. From 60 minutes onwards, the duration is shown in whole hours.

The default format is:

&7[AFK {duration}]&r 

This produces a grey prefix before the player's existing player-list name.

JustAFK preserves the existing player-list name instead of replacing it with the account name.

If another plugin updates the TAB name while the player is AFK, JustAFK adopts the new value as its base. It also avoids overwriting newer changes made by other formatting plugins when removing the AFK prefix.

Commands

Command	Default access	Permission	Description
/afk	All players	justafk.use	Toggle your own AFK state.
/afk <player>	Operators	justafk.use and justafk.others	Toggle an online player's AFK state.
/afk <player> on	Operators	justafk.use and justafk.others	Mark an online player as AFK.
/afk <player> off	Operators	justafk.use and justafk.others	Remove an online player's AFK state.
/afk <player> toggle	Operators	justafk.use and justafk.others	Toggle an online player's AFK state explicitly.
/justafk	Operators	justafk.config	Show the command help.
/justafk help	Operators	justafk.config	Show the command help.
/justafk status	Operators	justafk.config	Display the active configuration.
/justafk reload	Operators	justafk.config	Reload config.yml.
/justafk set enabled <on|off>	Operators	justafk.config	Enable or disable JustAFK globally.
/justafk set automatic-afk <on|off>	Operators	justafk.config	Enable or disable automatic AFK detection.
/justafk set timeout <seconds>	Operators	justafk.config	Change the automatic AFK timeout.
/justafk set announcements <all|ops|none>	Operators	justafk.config	Change the announcement audience.
/justafk set playerlist <on|off>	Operators	justafk.config	Enable or disable the TAB prefix.

The /jafk alias can be used instead of /justafk.

Running /afk <player> without on, off, or toggle defaults to toggle.

The target player must be online. Player names are matched exactly without case sensitivity.

When another person changes a player's AFK state, the target receives a private notification identifying who made the change.

Both /afk and /justafk include tab completion.

When JustAFK is globally disabled, only the help, status, reload, and configuration commands remain operational.

Permissions

Permission	Default	Description
justafk.use	Everyone	Allows players to use /afk on themselves.
justafk.others	Operators	Allows changing another online player's AFK state.
justafk.config	Operators	Allows access to all /justafk administrative commands.
justafk.admin	Operators	Grants all JustAFK permissions.

justafk.admin includes:

• justafk.use
• justafk.others
• justafk.config

Because the root /afk command requires justafk.use, a moderator who should manage other players needs both justafk.use and justafk.others.

LuckPerms examples

LuckPerms is optional. JustAFK uses the standard Bukkit permission system and works with permission plugins that manage Bukkit permissions.

Allow the default group to toggle its own AFK state:

/lp group default permission set justafk.use true

Allow a moderator group to manage other players:

/lp group moderator permission set justafk.use true
/lp group moderator permission set justafk.others true

Give an administrator group every JustAFK permission:

/lp group admin permission set justafk.admin true

Allow a staff group to manage the configuration without granting every permission:

/lp group staff permission set justafk.config true

Remove self-service AFK access from the default group:

/lp group default permission set justafk.use false

Replace default, moderator, admin, or staff with the group names used by your server.

The ops announcement audience refers to players who are actual Minecraft server operators. It does not include players merely because they have justafk.admin through LuckPerms.

Configuration

The default config.yml is:

# Enables or disables JustAFK as a whole.
# When disabled, only the help, status, reload, and configuration commands work.
enabled: true

# Marks inactive players as AFK automatically after the configured timeout.
# Manual AFK commands remain available when this is disabled.
automatic-afk-enabled: true

# Time without movement input before a player is marked as AFK.
# Movement input includes forward, backward, left, right, jump, sneak, and sprint.
# The default is 300 seconds (5 minutes).
inactivity-timeout-seconds: 300

announcements:
  # Available values: all, ops, none
  audience: all

player-list:
  # Adds a grey AFK duration before the player's existing tab-list name.
  enabled: true
  format: "&7[AFK {duration}]&r "

messages:
  # Legacy colour codes using '&' are supported.
  command-prefix: "&8[&7JustAFK&8]&r "
  became-afk: "&8[&7JustAFK&8]&r &7{player} is now AFK."
  became-active: "&8[&7JustAFK&8]&r &7{player} is no longer AFK."

Configuration options

Option	Default	Accepted values	Description
enabled	true	true or false	Enables or disables JustAFK globally.
automatic-afk-enabled	true	true or false	Enables or disables automatic AFK detection independently.
inactivity-timeout-seconds	300	A whole number of at least 1	Time without movement input before automatic AFK.
announcements.audience	all	all, ops, none	Controls who receives AFK entry and exit announcements.
player-list.enabled	true	true or false	Enables the TAB player-list prefix.
player-list.format	&7[AFK {duration}]&r	Text containing {duration}	Controls the prefix displayed before the existing player-list name.
messages.command-prefix	JustAFK prefix	Any text	Prefix used for command responses.
messages.became-afk	Default AFK message	Any text	Message sent when a player enters AFK.
messages.became-active	Default active message	Any text	Message sent when a player leaves AFK.

Configurations created by JustAFK 1.0.0 or 1.0.1 remain compatible.

When either new option is missing, it defaults to true. Existing configuration files do not need to be deleted or regenerated.

Announcement audiences

• all — sends announcements to every online player
• ops — sends announcements only to online server operators
• none — disables AFK announcements

The same audience is used for both entering and leaving AFK.

Placeholders

• {duration} is required in player-list.format
• {player} can be used in the AFK entry and exit messages

Legacy colour codes using & are supported.

Configuration commands validate and save their changes to config.yml immediately.

On server APIs that support YAML comment parsing, comments are preserved when configuration commands save the file.

When editing config.yml manually, run:

/justafk reload

Requirements

JustAFK 1.1.0

• Minecraft 1.21.3 or newer
• A supported Bukkit-compatible Java Edition server
• Java 21 or newer
• No client mod
• No runtime dependencies

The server may require a newer Java version depending on its Minecraft version. For example, Paper 26.2 requires Java 25.

JustAFK 1.0.1

Use version 1.0.1 for supported servers below Minecraft 1.21.3.

• Java 8-compatible plugin bytecode
• Position-based activity detection
• No input-aware AFK protection
• No global or automatic-AFK toggles

LuckPerms is supported through standard Bukkit permissions but is not required.

Installation

Minecraft 1.21.3 or newer

1. Download JustAFK-1.1.0.jar or the latest available release.
2. Place the JAR inside the server's plugins directory.
3. Start or restart the server.
4. Open plugins/JustAFK/config.yml to review the configuration.
5. Run /justafk reload after making manual configuration changes.
6. Configure additional permissions with LuckPerms if needed.

Minecraft versions below 1.21.3

1. Download JustAFK 1.0.1.
2. Place JustAFK-1.0.1.jar inside the server's plugins directory.
3. Start or restart the server.
4. Configure the plugin normally.

Do not install JustAFK 1.1.0 on a server below Minecraft 1.21.3.

When using BungeeCord, Velocity, or Waterfall, install JustAFK on each backend Bukkit-compatible server where AFK detection is required. Do not place it in the proxy's plugin directory.

Validation

JustAFK 1.1.0 has been validated through:

• 25 automated tests
• Individual tests for all seven movement-input flags
• Short input tap tests
• Held input polling tests
• Inactivity timeout tests
• External movement regression tests
• Global plugin disable tests
• Automatic-AFK disable tests
• Paper 26.2 primary compilation
• Spigot 1.21.3 compatibility compilation
• Paper and Spigot bytecode parity validation
• Java 21 bytecode validation
• Runtime dependency validation
• A successful manual test on a 26.2 server

The supported version range does not mean that every intermediate Minecraft or server-platform release has been individually runtime-tested.

Frequently asked questions

Does JustAFK kick inactive players?

No. JustAFK only marks players as AFK, announces state changes, and optionally displays a TAB prefix.

Do players need to install anything?

No. JustAFK is completely server-side.

Does looking around reset the timer?

No. Camera movement, yaw, and pitch do not count as movement input.

Does knockback remove AFK?

Not in JustAFK 1.1.0.

Knockback, entity pushes, arrows, explosions, water, and other external position changes do not remove AFK unless the player is also sending movement input.

JustAFK 1.0.1 uses position-based activity detection, so external movement may remove AFK on that version.

Does death reset AFK?

No. Death and respawn preserve the AFK state and its displayed duration.

Disconnecting and reconnecting starts a new session and resets the AFK state.

Does holding a movement key count as activity?

Yes. JustAFK periodically checks the current input, so an input that remains held continues to count as activity.

Can automatic AFK detection be disabled?

Yes. Set:

automatic-afk-enabled: false

Or run:

/justafk set automatic-afk off

Players can continue using manual AFK while automatic detection is disabled.

Can JustAFK be disabled without removing the JAR?

Yes. Set:

enabled: false

Or run:

/justafk set enabled off

Help, status, reload, and configuration commands remain available.

Can announcements be disabled?

Yes. Set announcements.audience to none or run:

/justafk set announcements none

Can the TAB prefix be disabled?

Yes. Run:

/justafk set playerlist off

Can messages and colours be customized?

Yes. Edit the message and player-list settings in config.yml. Legacy & colour codes are supported.

Which version should I use?

Use JustAFK 1.1.0 or newer on Minecraft 1.21.3 and newer.

Use JustAFK 1.0.1 on supported Minecraft versions below 1.21.3.

Which Java version do I need?

JustAFK 1.1.0 requires Java 21 or newer.

Your Minecraft server may require a newer version. Paper 26.2, for example, requires Java 25.

JustAFK 1.0.1 uses Java 8-compatible bytecode for compatibility with older servers.

Is every supported Minecraft version individually tested?

No.

JustAFK 1.1.0 is built against Paper 26.2 and compatibility-compiled against Spigot 1.21.3. It has also been manually tested on a 26.2 test server.

Compatibility with intermediate releases is based on the shared Bukkit API and build-time compatibility validation.

Does JustAFK require ProtocolLib, Vault, or PlaceholderAPI?

No. JustAFK has no external runtime dependencies.

Can JustAFK run on a proxy?

No. BungeeCord, Velocity, and Waterfall are proxy platforms.

Install JustAFK on the backend Paper, Purpur, Spigot, CraftBukkit, or Folia server instead.

Source and support

JustAFK is open source and licensed under the MIT License.

• Source code
• Issue tracker
• Releases