AstroSimpleAFK Documentation

Requirements: Paper, Purpur, or Folia server running Minecraft 1.20+. Java 21+.

Small SMP (default-friendly)

Recommended for 10-30 player survival servers. Short timeout, gentle broadcasts.

afk-timeout-seconds: 180
broadcast-afk: true
broadcast-return: true
afk-prefix: "&7[AFK] "
broadcast-afk-message: "&7%player% is now AFK"
broadcast-return-message: "&7%player% is back"

Large public network

For 100+ player networks where chat is busy. Suppress broadcasts, keep prefix.

afk-timeout-seconds: 300
broadcast-afk: false
broadcast-return: false
afk-prefix: "&7[AFK] "

Skyblock with AFK pools

Long timeout because players intentionally idle at island spawns for resource gen.

afk-timeout-seconds: 900
broadcast-afk: true
broadcast-return: false
afk-prefix: "&8[idle] "

RPG / lore server (immersive)

Custom in-character message instead of bare AFK.

afk-timeout-seconds: 240
broadcast-afk: true
broadcast-return: true
afk-prefix: "&5✨ "
broadcast-afk-message: "&5%player% drifts off into thought..."
broadcast-return-message: "&5%player% returns to the world."

Config location

Hide AFK players from /list

Scenario: You run a public server. /list shows 30 online but half are AFK. Players join, see 30, log in, see chat dead, leave. You want only active players in the list.

1. Install AstroSimpleAFK with default config (180s timeout works).
2. Install a chat or tab plugin that respects the [AFK] prefix (TAB plugin filters on display name).
3. Configure your tab plugin to hide players whose name starts with the AFK prefix.
4. Verify by AFK-ing yourself with /afk and asking another player to run /list.

Give staff a visible status indicator

Scenario: Staff respond to tickets but step away frequently. Players keep messaging idle staff and get frustrated.

1. Set afk-timeout-seconds to 120 (faster than players).
2. Give staff a custom afk-prefix like '&c[AWAY] '.
3. Train staff to use /afk manually before stepping away.

Resource pack hub: detect long-idle disconnects

Scenario: On a creative hub, some players load the world and tab out for hours. You want to know who is actually building.

1. Set afk-timeout-seconds to 600 (10 minutes).
2. Enable broadcast-afk to get a chat signal when someone goes idle.
3. Pair with an anti-AFK plugin if you want to kick eventually (AstroSimpleAFK does not kick).

Tip: Use LuckPerms to manage permissions per player or group.

EssentialsX

EssentialsX has its own /afk command. By default AstroSimpleAFK takes precedence because it loads later. If you want EssentialsX /afk instead, set 'commands.afk:' in commands.yml to disable AstroSimpleAFK's command, or rename to /aafk.

LuckPerms

Use LuckPerms to grant astrosimpleafk.bypass to staff so they are never auto-AFK'd.

/lp group staff permission set astrosimpleafk.bypass true
/lp group default permission set astrosimpleafk.command true

TAB (NEZNAMY)

Reads the player display name including the AFK prefix. Configure TAB to color-code or sort AFK players to the bottom of the tab list.

DiscordSRV

AFK broadcasts go to chat by default, so DiscordSRV picks them up. Filter or route AFK messages to a dedicated channel via DiscordSRV's regex matcher.

PlaceholderAPI

AstroSimpleAFK does not register placeholders by default. If you need %afk_status%, ask in our Discord — it is on the roadmap.

Players still get marked AFK while typing in chat

Cause: The chat plugin sends async chat events that AstroSimpleAFK does not see, or chat is being intercepted before reaching the event bus.

Fix:

• Check that no other plugin cancels AsyncPlayerChatEvent before AstroSimpleAFK.
• Verify plugin load order — load AstroSimpleAFK after your chat plugin via 'load: STARTUP'.
• If using EssentialsX, ensure ess-chat is not cancelling events for AFK players in a loop.

[AFK] prefix shows in chat instead of just tab list

Cause: Your chat plugin reads the player display name and includes it in chat messages.

Fix:

• Configure your chat formatter to use %player% (raw name) instead of %displayname%.
• Or disable afk-prefix and rely on broadcasts alone.

Reload command does not work after editing config

Cause: Permissions plugin not loaded yet, or you are running /reload (deprecated) instead of /afk reload.

Fix:

• Run /afk reload, not /reload.
• Make sure your user has the astrosimpleafk.reload permission.
• If you OP'd yourself for testing, deop and re-op to refresh permissions.

Players are never marked AFK no matter how long they idle

Cause: Auto-clickers, AFK pools, or another plugin firing PlayerMoveEvent constantly.

Fix:

• Disable any anti-AFK plugin on your server.
• Check if your spawn world has falling sand or other entities triggering player moves.
• Test with a brand-new account in a closed room.

Will AstroSimpleAFK kick players who go AFK?

No. This plugin only detects and displays AFK status. If you need auto-kick, pair it with EssentialsX (afk-auto-kick), CMI's idle-kick, or NoCheatPlus' idle module. We deliberately keep this plugin scope-limited so you can choose your own kick policy.

How does it know I am AFK?

It listens to PlayerMoveEvent, AsyncPlayerChatEvent, PlayerCommandPreprocessEvent, and PlayerInteractEvent. Any of those reset the idle timer. If none fire for the configured timeout, the player is marked AFK.

Can I configure the AFK timeout per group with LuckPerms?

Not directly. Currently it is one global timeout. Per-group timeouts are on the roadmap and require a permission node like astrosimpleafk.timeout.<seconds>. Open an issue if you want this prioritized.

Does it support hex colors in the prefix?

Yes. Use the standard Bukkit hex format: '&#FF1F00' for red, '&#22D3EE' for cyan. The plugin runs the prefix through ChatColor.translateAlternateColorCodes before applying.

What is the performance overhead?

Negligible. The plugin schedules one async task per online player at 20 ticks (1 second) interval and only checks a timestamp. No DB writes, no network calls, no I/O. Tested on a 200-player server with 0.001% TPS impact.

Can I use this on Spigot or just Paper?

Built and tested on Paper 1.20+. Spigot 1.20+ should work because we only use Bukkit API, not Paper-specific methods. Bedrock-bridged servers (Geyser) are supported because Geyser players are normal Bukkit players to plugins.

Why is my /afk command being eaten by EssentialsX?

EssentialsX registers /afk in its plugin.yml. Bukkit picks whichever loads later by default. To force AstroSimpleAFK, edit your server commands.yml and add 'afk: astrosimpleafk:afk' to alias the unqualified /afk to ours. Or use the namespaced version /astrosimpleafk:afk.

Does it work with Folia?

We have not tested on Folia yet. The plugin uses thread-unsafe HashMaps for the idle-tracker, which would need conversion to ConcurrentHashMap for Folia. Track folia support in our GitHub issues.

Can I save AFK status across restarts?

No — AFK state is in-memory only and resets on restart. When a player rejoins after a restart, they start with a fresh timer. This is intentional: persisting AFK status across restarts has no real-world value and would require a database.

How do I unmark a player as AFK manually?

The player just has to move, chat, or run any command. There is no admin 'unafk' command in this version. If you need one, open a feature request — it is a small addition.

v1.0.02026-05-13

• Initial public release
• Configurable AFK timeout
• Tab list prefix display
• Broadcast on AFK and return
• /afk toggle command
• /afk reload command
• astrosimpleafk.bypass permission for staff