API interface for interacting with EssentialsC's punishment system. Bans and
mutes are stored in YAML files (bans.yml / mutes.yml)
and checked entirely in memory after load. All methods are synchronous and safe
to call on the main thread.
Data classes BanEntry, MuteEntry, and IpBanEntry live in the
net.godlycow.org.essc.api.punishment sub-package.
Retrieve an instance via EssentialsCAPI.getPunishmentApi().
PunishmentApi punish = APIProvider.getAPI().getPunishmentApi();
if (punish.isBanned(player.getUniqueId())) {
BanEntry entry = punish.getBanEntry(player.getUniqueId());
player.sendMessage("Banned by: " + entry.banner());
}
// issue a 1-day ban
long expires = System.currentTimeMillis() + 86400000L;
punish.banPlayer(player.getUniqueId(), player.getName(), "Hacking", "Admin", expires);
Data classes BanEntry and MuteEntry live in the
net.godlycow.org.essc.api.punishment sub-package.
Bans
| void | banPlayer(UUID uuid, String name, String reason, String banner, long expires) Issues a ban for the given player. |
| void | unbanPlayer(UUID uuid) Removes the ban for the given player. |
| boolean | isBanned(UUID uuid) Returns whether the given player is currently banned. |
| BanEntry | getBanEntry(UUID uuid) Returns the BanEntry for the given player, or null if not banned. |
| List<BanEntry> | getAllBans() Returns a list of all currently active ban entries. |
| List<BanEntry> | getActiveBans() Returns only active (non-expired) ban entries. |
IP Bans
| void | banIp(String ip, String reason, String banner, long expires) Issues an IP ban. |
| void | unbanIp(String ip) Removes the ban for the given IP. |
| boolean | isIpBanned(String ip) Returns whether the given IP is currently banned. |
| IpBanEntry | getIpBanEntry(String ip) Returns the IpBanEntry for the given IP, or null if not banned. |
| List<IpBanEntry> | getActiveIpBans() Returns a list of all currently active IP ban entries. |
| List<IpBanEntry> | getAllIpBans() Returns a list of all IP ban entries including expired ones. |
Mutes
| void | mutePlayer(UUID uuid, String name, String reason, String muter, long expires) Issues a mute for the given player. |
| void | unmutePlayer(UUID uuid) Removes the mute for the given player. |
| boolean | isMuted(UUID uuid) Returns whether the given player is currently muted. |
| MuteEntry | getMuteEntry(UUID uuid) Returns the MuteEntry for the given player, or null if not muted. |
| List<MuteEntry> | getAllMutes() Returns a list of all currently active mute entries. |
Issues a ban for the given player. Writes the ban to bans.yml immediately. If the player is online they will not be kicked automatically — use Player#kick() after calling this method.
| uuid | the UUID of the player to ban; must not be null |
| name | the player's current name; must not be null |
| reason | the ban reason; must not be null |
| banner | the name of the staff member or console issuing the ban; must not be null |
| expires | the Unix timestamp (milliseconds) when the ban expires, or -1 for permanent |
Removes the ban for the given player. Has no effect if the player is not currently banned.
Parameters:| uuid | the UUID of the player to unban; must not be null |
Returns whether the given player is currently banned. Expired temporary bans are removed automatically when this method is called.
Parameters:| uuid | the UUID of the player to check; must not be null |
| boolean | true if the player has an active ban |
Returns the BanEntry for the given player, or null if the player is not banned. Expired bans are cleaned up automatically before this returns.
| uuid | the UUID of the player to look up; must not be null |
| BanEntry | the active BanEntry, or null if the player is not banned |
Returns a list of all currently active ban entries. Expired bans encountered during iteration are removed automatically. The returned list is a snapshot.
Returns:| List<BanEntry> | all active BanEntry records; never null, may be empty |
Returns a list of all currently active (non-expired) ban entries. Expired bans encountered during iteration are removed automatically.
Returns:| List<BanEntry> | active BanEntry records; never null, may be empty |
Issues an IP ban. Writes to bans.yml immediately. Online players with this IP will not be kicked automatically.
| ip | the IP address to ban; must not be null |
| reason | the ban reason; must not be null |
| banner | the name of the staff member or console issuing the ban; must not be null |
| expires | the Unix timestamp (milliseconds) when the ban expires, or -1 for permanent |
Removes the IP ban for the given address. Has no effect if the IP is not currently banned.
Parameters:| ip | the IP address to unban; must not be null |
Returns whether the given IP address is currently banned. Expired temporary IP bans are removed automatically when this method is called.
Parameters:| ip | the IP address to check; must not be null |
| boolean | true if the IP has an active ban |
Returns the IpBanEntry for the given IP, or null if the IP is not banned. Expired IP bans are cleaned up automatically before this returns.
| ip | the IP address to look up; must not be null |
| IpBanEntry | the active IpBanEntry, or null if the IP is not banned |
Returns a list of all currently active IP ban entries. Expired IP bans encountered during iteration are removed automatically.
Returns:| List<IpBanEntry> | active IpBanEntry records; never null, may be empty |
Returns a list of all IP ban entries including expired ones. The returned list is a snapshot.
Returns:| List<IpBanEntry> | all IpBanEntry records; never null, may be empty |
Issues a mute for the given player. Writes the mute to mutes.yml immediately. Chat messages from this player will be blocked by EssentialsC's mute listener automatically.
| uuid | the UUID of the player to mute; must not be null |
| name | the player's current name; must not be null |
| reason | the mute reason; must not be null |
| muter | the name of the staff member or console issuing the mute; must not be null |
| expires | the Unix timestamp (milliseconds) when the mute expires, or -1 for permanent |
Removes the mute for the given player. Has no effect if the player is not currently muted.
Parameters:| uuid | the UUID of the player to unmute; must not be null |
Returns whether the given player is currently muted. Expired temporary mutes are removed automatically when this method is called.
Parameters:| uuid | the UUID of the player to check; must not be null |
| boolean | true if the player has an active mute |
Returns the MuteEntry for the given player, or null if the player is not muted. Expired mutes are cleaned up automatically before this returns.
| uuid | the UUID of the player to look up; must not be null |
| MuteEntry | the active MuteEntry, or null if the player is not muted |
Returns a list of all currently active mute entries. Expired mutes encountered during iteration are removed automatically. The returned list is a snapshot.
Returns:| List<MuteEntry> | all active MuteEntry records; never null, may be empty |