AFK Actions

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

- 🎨 Fully Customizable - Tracks player movement and chat activity - 🎨 Fully Customizable - Execute commands when players go AFK and when they return - 🎨 Fully Customizable - Built-in English and Turkish translations (fully customizable) - 🎨 Fully Customizable - OP and permission-based AFK immunity - 🎨 Fully Customizable - Server-wide notifications for AFK status changes - 🎨 Fully Customizable - Detailed logging for troubleshooting - 🎨 Fully Customizable - View, list, and reset player AFK status - 🎨 Fully Customizable - Lightweight with minimal server impact - 🎨 Fully Customizable - Every message and setting is configurable

---

📋 Requirements

- Java: 1.21+ - Java: 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`)

```yaml

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: ```yaml language: "en" # or "tr" ```

Then run: `/afkactions reload`

---

📖 How It Works

AFK Detection Flow

1. Return Commands → No movement or chat for configured time 2. Return Commands → Player is marked as AFK (3 minutes default) 3. Return Commands → Server notified: `{player} is now AFK!` (if enabled) 4. Return Commands → Additional waiting time before commands execute 5. Return Commands → After total time (10 minutes default), commands run 6. Return Commands → On movement/chat, AFK status clears 7. Return Commands → 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

```yaml 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

```yaml player-commands: - "server lobby"

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

Example 3: Spectator Mode + Return System

```yaml

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

```yaml

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)

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

Permission-based Exemption

Grant `afkactions.bypass` permission to exempt specific players:

LuckPerms Examples: ```bash

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:

```yaml 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:

```yaml 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: ```yaml console-commands: - "send {player} lobby" ```

Velocity: ```yaml 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

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

---

*Made with ❤️ for the Minecraft community*