Plugins / AfkGuard

Developer API

Developer API

Dependency Setup

Maven

<repositories>
    <repository>
        <id>jitpack.io</id>
        <url>https://jitpack.io</url>
    </repository>
</repositories>

<dependencies>
    <dependency>
        <groupId>com.github.TheCuouz</groupId>
        <artifactId>mc-afkguard</artifactId>
        <version>1.0.0</version>
        <scope>provided</scope>
    </dependency>
</dependencies>

Gradle (Kotlin DSL)

repositories {
    maven("https://jitpack.io")
}

dependencies {
    compileOnly("com.github.TheCuouz:mc-afkguard:1.0.0")
}

plugin.yml

Add AfkGuard as a soft dependency so your plugin loads after it but works even when it's absent:

name: MyPlugin
main: com.example.MyPlugin
version: 1.0.0
soft-depend:
  - AfkGuard

Getting the API Instance

AfkGuard registers AfkApi with Bukkit's ServicesManager. Always null-check — if AfkGuard is absent or not yet enabled, load() returns null.

import org.bukkit.Bukkit;

AfkApi api = Bukkit.getServicesManager().load(AfkApi.class);
if (api == null) {
    getLogger().warning("AfkGuard not found — AFK features disabled.");
    return;
}

API Method Reference

Querying AFK State

// Check if a player is currently AFK
boolean afk = api.isAfk(player);

// Get duration of current AFK session in milliseconds
// Returns 0 if the player is not AFK
long durationMillis = api.afkDuration(player.getUniqueId());

// Convert to seconds for display
long seconds = durationMillis / 1000;

Forcing State Changes

// Force mark a player as AFK (regardless of activity)
api.forceMarkAfk(player);

// Force mark a player as active (clears AFK flag)
api.forceMarkActive(player);

Warning: Force-marking a player as active does not teleport them back from the AFK zone if they were auto-teleported. Handle zone logic in your own plugin if needed.

AfkStateListener — Event Callbacks

Register a listener to be notified whenever a player's AFK state changes:

api.registerListener(new AfkStateListener() {

    @Override
    public void onAfk(Player player) {
        // Called when a player becomes AFK
        getLogger().info(player.getName() + " went AFK.");
        // Example: remove player from arena queue
        arenaManager.removeFromQueue(player);
    }

    @Override
    public void onActive(Player player, long afkDurationMillis) {
        // Called when a player returns from AFK
        // afkDurationMillis = how long they were AFK
        long seconds = afkDurationMillis / 1000;
        getLogger().info(player.getName() + " returned after " + seconds + "s AFK.");
        // Example: re-add player to queue
        arenaManager.addToQueue(player);
    }
});

Complete Integration Example

Here is a full example of a plugin that uses the AfkGuard API to pause a game when all players are AFK:

public class MyPlugin extends JavaPlugin {

    private AfkApi afkApi;

    @Override
    public void onEnable() {
        // Obtain the API
        afkApi = Bukkit.getServicesManager().load(AfkApi.class);

        if (afkApi != null) {
            registerAfkListener();
            getLogger().info("AfkGuard integration enabled.");
        } else {
            getLogger().warning("AfkGuard not found. AFK pausing disabled.");
        }
    }

    private void registerAfkListener() {
        afkApi.registerListener(new AfkStateListener() {

            @Override
            public void onAfk(Player player) {
                // Check if ALL players are now AFK
                boolean allAfk = Bukkit.getOnlinePlayers().stream()
                        .allMatch(p -> afkApi.isAfk(p));
                if (allAfk) {
                    GameManager.getInstance().pauseGame();
                    Bukkit.broadcastMessage("§7All players are AFK — game paused.");
                }
            }

            @Override
            public void onActive(Player player, long afkDurationMillis) {
                // Resume the game when any player comes back
                if (GameManager.getInstance().isPaused()) {
                    GameManager.getInstance().resumeGame();
                    Bukkit.broadcastMessage("§a" + player.getName()
                            + " is back — game resumed!");
                }
            }
        });
    }
}

Thread Safety

Warning: All AfkGuard API calls must be made from the main server thread. Calling API methods from async tasks (e.g., inside Bukkit.getScheduler().runTaskAsynchronously(...)) is not supported and may cause ConcurrentModificationException.

For async contexts, schedule a sync callback:

// Safe — switch back to main thread first
Bukkit.getScheduler().runTask(myPlugin, () -> {
    boolean afk = afkApi.isAfk(player);
    // ... handle result
});

API Quick Reference

Home · Commands & Permissions · PlaceholderAPI