Welcome to the Hangar Open Beta. Please report any issue you encounter on GitHub!

EzAfk

Smart detection - Vault cost - Custom sound - Admin GUI - PlaceholderAPI - Auto kick and more

EzAFK - Minecraft plugin for 1.7 - 1.21.*

Keep AFK management simple

EzAfk is a modern, lightweight AFK management plugin that keeps your staff informed while gently nudging idle players back into the action. Built for contemporary Paper and Spigot servers (1.7 – 1.21.*) and Java 21, it automates AFK detection, provides configurable staff tools, and integrates with the systems you already use, all without sacrificing performance.

Coming back from AFK screen in EzAFK Minecraft plugin

Feature highlights

Automatic AFK detection: Detect idle players after a configurable timeout, send chat or title messages, play optional animations, apply blindness, and broadcast status changes server-wide.
Staff workflow tools: Open the AFK player overview GUI and trigger customizable actions (kick, alert, teleport, run console commands) per-player from an intuitive menu.
Anti-bypass protections: Block common AFK bypass tricks with vehicle and water-flow checks, optionally gated behind the ezafk.bypass permission or WorldGuard regions.
Automatic punishments: Kick AFK players after configurable grace periods or only when the server is full, with personalized kick reasons.
AFK kick warnings: Send configurable chat and/or title warnings at multiple intervals before a player is kicked for being AFK, giving them a chance to return.
Economy-aware AFK: Optionally charge players using Vault-supported economies when they go or stay AFK, with recurring billing plus bypass permissions or WorldGuard regions.
EzEconomy integration: For best results, pair EzAfk with EzEconomy for modern, reliable Vault economy support!
Integrations that matter: Use the WorldGuard afk-bypass flag, track usage with bStats, receive console reminders when new releases are available, and surface AFK prefixes in the tab list without any external dependencies.
Custom display names & tab styling: Mirror AFK status in chat and name tags with configurable prefixes, suffixes, and formats that work with TAB or the built-in formatter.
Persistent storage: Optionally connect to MySQL to store the last active timestamp for every tracked player across restarts, plus per-player YAML totals for the AFK time leaderboard.
AFK analytics: Surface /afk time, /afk info, and /afk top so staff can investigate reports and highlight the most idle players with a cached leaderboard.
Player-friendly deterrents: Combine optional blindness and configurable animations to nudge players back to activity without being heavy-handed.
Built-in translations: Ship ready-to-use English, Spanish, Dutch, Russian, and Chinese message packs with automatic fallbacks and per-server overrides.

Commands

/afk: Toggle your own AFK state (alias of /ezafk).
/afk reload: Reload the configuration and refresh integrations.
/afk gui: Open the AFK player overview GUI (includes pagination and quick actions).
/afk toggle : Force another player's AFK state.
/afk bypass : Toggle the bypass flag for a player when afk.bypass.enabled is active.
/afk info : Review why a player was flagged AFK, how long they've been idle, and their last activity.
/afk time [player]: Show lifetime AFK totals for yourself or, with permission, another player.
/afk top: Display the cached AFK time leaderboard (also available via /afktop).

Aliases: /ezafk, /afk, /ea, /afktime, /afktop

Permissions

ezafk.reload: Allows using /afk reload.
ezafk.gui: Allows opening the overview GUI.
ezafk.gui.view-active: Allows viewing active (non-AFK) players in the GUI.
ezafk.gui.actions: Allows using the player action buttons in the GUI.
ezafk.toggle: Allows toggling other players' AFK state.
ezafk.bypass: Lets a player ignore the automatic AFK trigger when bypass checking is enabled.
ezafk.bypass.manage: Allows toggling bypass mode for other players via /afk bypass.
ezafk.economy.bypass: Exempts a player from economy charges when AFK costs are enabled.
ezafk.info: Allows viewing AFK reports for other players via /afk info.
ezafk.time: Allows checking your own AFK total.
ezafk.time.others: Allows checking someone else's AFK total with /afk time <player>.
ezafk.top: Allows viewing the AFK time leaderboard.

GUI overview

The GUI is available with the command /afk gui, the permission ezafk.gui, or OP status. Default buttons let staff kick, alert, or teleport to AFK players, and you can add extra items that run console commands with %player% and %executor% placeholders. Configure the layout in gui.yml.

ezafk-gui

Customizable admin actions

Beyond the preconfigured buttons, EzAfk lets you build your own action items directly in gui.yml. Each slot can execute one or more console or player commands, display custom icons, and include hover descriptions so staff understand what the action does. Combine placeholders such as %player%, %executor%, or %world% with permission checks to craft targeted moderation workflows—anything from warning messages to teleport chains or integrations with external moderation plugins.

Integrations

Tab list styling (built-in)

Enable the afk.tab-prefix.enabled setting to display a custom prefix or suffix whenever a player is marked AFK. Customize the prefix, suffix, and final format using placeholders like %prefix%, %player%, and %suffix%. EzAfk can either rely on the TAB plugin for formatting or use its own built-in implementation - choose your preferred behaviour with afk.tab-prefix.mode (options: auto, tab, or custom).

afk-tab

WorldGuard (> v1.2)

Enable the integration in config.yml to unlock the custom afk-bypass flag, allowing specific regions where players can idle without triggering punishments or economy charges.
Download WorldGuard

Flag name: afk-bypass

How to add the flag to your region?

/rg flag <region> afk-bypass allow

MySQL storage (> v1.3)

Store AFK player state in a central database. EzAfk automatically handles inserts, updates, and cleanup based on player UUIDs.

Metrics & updates

Anonymous usage statistics are collected via bStats, and the plugin optionally checks SpigotMC for updates during startup. Both features can be disabled through config.yml.

PlaceholderAPI (> v1.7)

Install PlaceholderAPI to expose EzAfk's placeholders. The expansion registers itself automatically when the plugin is detected, so no extra permissions or config toggles are required.

Simple Voice Chat integration (> v2.2)

Optionally play a custom MP3 sound to players when they go AFK, using the Simple Voice Chat mod and its API. Enable in config.yml under integration.voicechat, and place your sound file in plugins/EzAfk/mp3/ezafk-sound.mp3. The plugin will automatically detect and use the sound if Simple Voice Chat is installed. See the documentation for setup and troubleshooting tips.

Download Simple Voice Chat

Provided placeholders:

%ezafk_status% — Returns AFK or ACTIVE for the targeted player.
%ezafk_status_colored% — Returns the color-formatted status string (e.g., &cAFK).
%ezafk_since% — Seconds since the player was marked AFK. Empty when they are active.
%ezafk_last_active% — Seconds since the player last moved. Always available.
%ezafk_prefix% — The configured AFK prefix applied to their display name while AFK.
%ezafk_suffix% — The configured AFK suffix applied to their display name while AFK.
%ezafk_afk_count% — Total number of players currently marked as AFK.
%ezafk_active_count% — Total number of online players not marked as AFK.

Usage example:

&7Status: %ezafk_status_colored%
&7AFK for: %ezafk_since%s

Configuration

EzAfk ships with dedicated files to keep settings organized:

config.yml: Core AFK behaviour, broadcasts, display-name styling, TAB integration, and punishment logic.
gui.yml: Inventory size and per-slot actions for the staff GUI.
mysql.yml: Connection details for optional persistent storage.
messages_*.yml: Localised player-facing messages for English, Spanish, Dutch, Russian, and Chinese out of the box.

Core config (config.yml)

# Config for EzAfk 1.8.0
# GUI settings have moved to gui.yml.
# MySQL settings have moved to mysql.yml.
messages:
  language: en
afk:
  timeout: 300
  bypass:
    enabled: true
  broadcast:
    enabled: true
  title:
    enabled: true
  hide-screen:
    enabled: false
  animation:
    enabled: true
  storage:
    flush-interval-seconds: 30
  anti:
    infinite-waterflow: false
    infinite-vehicle: false
    flag-only: false
  tab-prefix:
    enabled: false
    mode: auto
    prefix: "&7[AFK] "
    suffix: ""
    format: "%prefix%%player%%suffix%"
  display-name:
    enabled: false
    prefix: "&7[AFK] "
    suffix: ""
    format: "%prefix%%player%%suffix%"
kick:
  enabled: false
  enabledWhenFull: false
  timeout: 600
  warnings:
    enabled: true
    intervals: [60, 30, 10]
    mode: both
unafk:
  broadcast:
    enabled: true
  title:
    enabled: true
  animation:
    enabled: true
economy:
  enabled: false
  bypass-permission: "ezafk.economy.bypass"
  cost:
    enter:
      enabled: true
      amount: 25.0
      require-funds: true
      retry-delay: 60
    recurring:
      enabled: false
      amount: 5.0
      interval: 300
      require-funds: true
      kick-on-fail: false
integration:
  worldguard: true
  tab: true
  spigot:
    check-for-update: true

GUI actions (gui.yml)

inventory-size: 9
actions:
  kick:
    slot: 0
    material: IRON_BOOTS
    display-name: "&cKick Player"
    type: KICK
    target-message: "&cYou were kicked for being AFK too long."
    feedback-message: "&aSuccessfully kicked %player%"
  alert:
    slot: 1
    material: PAPER
    display-name: "&eSend Alert"
    type: MESSAGE
    target-message: "&eYou are marked as AFK. Keep active to prevent getting kicked!"
    feedback-message: "&aSent alert to %player%"
  teleport:
    slot: 2
    material: COMPASS
    display-name: "&aTeleport to Player"
    type: TELEPORT
    feedback-message: "&aTeleported to %player%"

Database (mysql.yml)

enabled: false
host: "localhost"
port: 3306
database: "ezafk"
username: "root"
password: ""

Multiple language support

Every alert, warning, or confirmation shown to players can be tailored in the language-specific files under messages/. EzAfk bundles fully translated packs for English, Spanish, Dutch, Russian, and Simplified Chinese, and automatically falls back to English if a language is missing.

Set messages.language in config.yml to match one of the bundled codes (en, es, nl, ru, or zh) and the plugin will copy the corresponding file on first launch. Want to localise EzAfk for your own community? Copy one of the provided files, translate the values, drop it back into the messages/ folder, and point messages.language at your new filename (for example, messages_fr).

Messages include everything from AFK toggle confirmations and bypass notifications to GUI errors, blindness prompts, and tab-prefix text—making it easy to deliver a consistent experience in your players' preferred language.