AFK Actions

A powerful and feature-rich AFK detection plugin for Paper/Purpur servers that automatically manages idle players with customizable commands and multi-language support.

---

🌟 Features

• 🎯 Automatic AFK Detection - Tracks player movement and chat activity
• ⚙️ Dual Command System - Execute commands when players go AFK and when they return
• 🌍 Multi-Language Support - Built-in English and Turkish translations (fully customizable)
• 🛡️ Smart Exemptions - OP and permission-based AFK immunity
• 📢 Broadcast System - Server-wide notifications for AFK status changes
• 🔧 Debug Mode - Detailed logging for troubleshooting
• 📊 Management Commands - View, list, and reset player AFK status
• ⚡ High Performance - Lightweight with minimal server impact
• 🎨 Fully Customizable - Every message and setting is configurable

---

📋 Requirements

• Minecraft: 1.21+
• Server: Paper, Purpur, or any Paper-based server
• Java: 21+

---

🎮 Commands

All commands are under the main /afkactions command (alias: /afk)

Command	Permission	Description
/afkactions	-	Show help menu
/afkactions help	-	Show available commands
/afkactions reload	afkactions.reload	Reload configuration and language files
/afkactions status <player>	afkactions.status	View detailed AFK status of a player
/afkactions list	afkactions.list	List all currently AFK players
/afkactions reset <player>	afkactions.reset	Reset a player's AFK status

---

🔐 Permissions

Admin Permissions

Permission	Default	Description
afkactions.*	op	Grants all AFK Actions permissions
afkactions.reload	op	Reload plugin configuration
afkactions.status	op	View player AFK status
afkactions.list	op	List all AFK players
afkactions.reset	op	Reset player AFK status

Exemption Permission

Permission	Default	Description
afkactions.bypass	false	Exempts player from AFK system - Never marked as AFK

---

⚙️ Configuration

Main Config (config.yml)

# AFK Actions Plugin Configuration
# All times are in seconds

# Language (en = English, tr = Turkish)
language: "en"

# Debug mode - Shows detailed logs in console (default: false)
debug: false

# AFK detection time - Player will be marked as AFK after this time of inactivity (seconds)
afk-detection-time: 180

# Command execution time - Commands will run after player has been AFK for this long (seconds)
command-execution-time: 600

# Exemption settings
exemptions:
  # Should OPs be exempt from the AFK system?
  ignore-ops: true
  # Players with afkactions.bypass permission are automatically exempt

# Broadcast settings
broadcast:
  # Should AFK status be broadcast to the server?
  afk-enabled: true
  # Should return from AFK be broadcast to the server?
  return-enabled: true

# Commands to run when player becomes AFK
# Commands to run as the player (do not include /)
# Available placeholder: {player}
player-commands:
  - "server lobby"

# Commands to run from console (do not include /)
# Available placeholder: {player}
console-commands:
  - "kick {player} You have been AFK for too long!"

# Commands to run when player returns from AFK
# Commands to run as the player (do not include /)
# Available placeholder: {player}
return-player-commands:
  - "spawn"

# Commands to run from console (do not include /)
# Available placeholder: {player}
return-console-commands:
  - "tell {player} Welcome back!"
  - "effect give {player} minecraft:speed 10 1"

---

🌍 Language Files

The plugin creates customizable language files in plugins/AFKActions/:

English (messages_en.yml)

Turkish (messages_tr.yml)

All messages including broadcasts, commands, and errors are fully translatable!

Change language:

language: "en"  # or "tr"

Then run: /afkactions reload

---

📖 How It Works

AFK Detection Flow

1. Player goes idle → No movement or chat for configured time
2. AFK Status → Player is marked as AFK (3 minutes default)
3. Broadcast → Server notified: {player} is now AFK! (if enabled)
4. Wait Period → Additional waiting time before commands execute
5. Command Execution → After total time (10 minutes default), commands run
6. Player Returns → On movement/chat, AFK status clears
7. Return Broadcast → Server notified: {player} is no longer AFK! (if enabled)
8. Return Commands → Optional commands execute immediately upon return

---

💡 Use Cases & Examples

Example 1: Kick AFK Players

afk-detection-time: 300      # 5 minutes
command-execution-time: 600  # 10 minutes total

player-commands: []
console-commands:
  - "kick {player} You were AFK for too long!"

Example 2: Move to Lobby

player-commands:
  - "server lobby"

console-commands:
  - "tell {player} Moving you to lobby due to inactivity"

Example 3: Spectator Mode + Return System

# When AFK
console-commands:
  - "gamemode spectator {player}"
  - "tell {player} You are now in spectator mode (AFK)"

# When returning
return-console-commands:
  - "gamemode survival {player}"
  - "effect give {player} minecraft:regeneration 30 2"
  - "tell {player} Welcome back! Restored to survival mode"

Example 4: Economy/Reward System

# When returning from AFK
return-console-commands:
  - "eco give {player} 100"
  - "title {player} title {\"text\":\"Welcome Back!\",\"color\":\"gold\"}"
  - "title {player} subtitle {\"text\":\"Here's $100!\",\"color\":\"yellow\"}"

---

🛡️ Exemptions

OP Exemption (Config-based)

exemptions:
  ignore-ops: true  # OPs never go AFK

Permission-based Exemption

Grant afkactions.bypass permission to exempt specific players:

LuckPerms Examples:

# Exempt a single player
/lp user PlayerName permission set afkactions.bypass true

# Exempt VIP group
/lp group vip permission set afkactions.bypass true

# Exempt staff members
/lp group admin permission set afkactions.bypass true
/lp group moderator permission set afkactions.bypass true

---

🔍 Debug Mode

Enable debug mode for detailed logging:

debug: true

Console Output:

[AFKActions] [DEBUG] Executing 1 AFK player command(s) for PlayerName
[AFKActions] [DEBUG] AFK player command: server lobby
[AFKActions] [DEBUG] Executing 1 return console command(s) for PlayerName
[AFKActions] [DEBUG] Return console command: tell PlayerName Welcome back!

Perfect for troubleshooting command execution!

---

🎯 Placeholders

Currently supported placeholder:

• {player} - The player's name

Works in all command lists (player/console, AFK/return)

---

📊 Status Command Details

/afkactions status <player> shows:

• ✅ Player name
• 🔴 AFK status (AFK / Active)
• ⏰ Time since last activity
• ⚙️ Commands executed status
• ⏳ Time remaining until commands execute (if AFK)

Perfect for moderators to check player activity!

---

🎨 Customization Tips

Custom Messages

Edit language files in plugins/AFKActions/:

• messages_en.yml - English messages
• messages_tr.yml - Turkish messages

All colors use & codes: &a = green, &c = red, &e = yellow, etc.

Multiple Commands

You can add multiple commands per action:

console-commands:
  - "tell {player} You are AFK!"
  - "title {player} title {\"text\":\"AFK\",\"color\":\"red\"}"
  - "gamemode spectator {player}"
  - "tp {player} 0 100 0"

BungeeCord/Velocity Support

For network servers, use console commands:

BungeeCord:

console-commands:
  - "send {player} lobby"

Velocity:

console-commands:
  - "server {player} lobby"

---

🚀 Performance

• ✅ Lightweight - Checks run every second with minimal CPU usage
• ✅ Concurrent HashMaps - Thread-safe player tracking
• ✅ Efficient scheduling - Uses Bukkit's task system
• ✅ No database required - All data in memory
• ✅ Automatic cleanup - Player data removed on disconnect

---

📦 Installation

1. Download the latest version
2. Place JAR in your server's plugins folder
3. Restart or reload your server
4. Configure plugins/AFKActions/config.yml
5. Optional: Customize language files
6. Run /afkactions reload to apply changes

---

📝 License

This plugin is free to use and modify.

---

⭐ Credits

Developer: DevPanda (Efe Dönmez)
API: Paper 1.21+
Language: Kotlin

---

Made with ❤️ for the Minecraft community