AFKApi — EssentialsC API

API interface for interacting with EssentialsC's AFK system. Retrieve an instance via EssentialsCAPI.getAFKApi().

EssentialsCAPI api = APIProvider.getAPI();
if (api != null) {
    AFKApi afk = api.getAFKApi();

    // check if a player is AFK
    boolean isAfk = afk.isAFK(player);

    // record external activity so the timer resets
    afk.updateActivity(player);
}

Method Summary

void	setAFK(Player player, boolean afk, boolean broadcast) Sets the AFK state of a player, optionally broadcasting the change.
void	toggleAFK(Player player) Toggles the AFK state of a player.
boolean	isAFK(Player player) Returns whether the given player is currently AFK.
boolean	isAFK(UUID uuid) Returns whether the player identified by the given UUID is currently AFK.
Instant	getAFKStartTime(Player player) Returns the Instant at which the player entered AFK mode.
long	getAFKDurationSeconds(Player player) Returns how long the player has been AFK, in whole seconds.
String	getAFKDurationFormatted(Player player) Returns the AFK duration as a human-readable string (e.g. "3m 14s").
Set<Player>	getAFKPlayers() Returns a snapshot of all currently online AFK players.
int	getAFKCount() Returns the number of online players currently marked as AFK.
void	updateActivity(Player player) Manually records activity for the given player, removing their AFK status if set.

Method Detail

public void setAFK(Player player, boolean afk, boolean broadcast)

Sets the AFK state of a player.

If the player is already in the requested state, this method does nothing. When broadcast is true and broadcasting is enabled in the plugin config, all online players will receive the appropriate enter/leave message.

Parameters:

player	the player whose AFK state to change; must not be `null`
afk	`true` to mark the player as AFK, `false` to return them to active
broadcast	`true` to broadcast the state change to other online players

public void toggleAFK(Player player)

Toggles the AFK state of a player.

If the player is currently AFK they will be returned to active. If they are active they will be marked as AFK. The toggle always broadcasts to other online players. When toggling off AFK, the player's last-activity timestamp is reset to now so the auto-AFK timer restarts cleanly.

Parameters:

player the player to toggle; must not be null

public boolean isAFK(Player player)

Returns whether the given player is currently AFK.

Parameters:

player the player to check; must not be null

Returns:

boolean true if the player is AFK, false otherwise

public boolean isAFK(UUID uuid)

Returns whether the player identified by the given UUID is currently AFK.

This overload is useful when you only have a UUID and the player may or may not be online.

Parameters:

uuid	the UUID of the player to check; must not be `null`

Returns:

boolean true if the player is AFK, false otherwise

public Instant getAFKStartTime(Player player)

Returns the Instant at which the player entered AFK mode.

Parameters:

player the AFK player; must not be null

Returns:

Instant the instant the player went AFK, or null if the player is not AFK

public long getAFKDurationSeconds(Player player)

Returns how long the player has been AFK, in whole seconds.

Parameters:

player the AFK player; must not be null

Returns:

long	seconds since the player went AFK, or `0` if the player is not AFK

public String getAFKDurationFormatted(Player player)

Returns the AFK duration of the given player as a human-readable string.

The format depends on the elapsed time:

Less than 1 minute — "Xs"
1 minute or more — "Xm Ys"
1 hour or more — "Xh Ym Zs"

Parameters:

player the AFK player; must not be null

Returns:

String a formatted duration string, or "0s" if the player is not AFK

public Set<Player> getAFKPlayers()

Returns a snapshot of all currently online AFK players.

The returned set is not backed by the internal AFK state — modifications to it have no effect on the AFK system.

Returns:

Set<Player> an unmodifiable set of online players currently marked as AFK; never null, may be empty

public int getAFKCount()

Returns the number of online players currently marked as AFK.

Equivalent to getAFKPlayers().size() but slightly more efficient.

Returns:

int	the current AFK player count, `0` or greater

public void updateActivity(Player player)

Manually records activity for the given player and removes their AFK status if set.

Call this if your plugin performs an action on behalf of a player that should count as activity (e.g. a teleport initiated by your code). Has no effect if the player is offline.

Parameters:

player the player to record activity for; null is silently ignored

Interface AFKApi

Method Summary