Package me.kzlyth.api.ban

Klasse BanAPI

java.lang.Object
me.kzlyth.api.ban.BanAPI
public class BanAPI extends Object
API for banning and unbanning players in Zenith-Mod.

This API provides methods to ban players (regular and IP bans), ban using templates (custom bans), and unban players. All bans are automatically recorded in the history database with a case ID.

Features:

  • Regular bans and IP bans
  • Template-based bans with escalation support
  • Online and offline player banning
  • Unban functionality
  • Custom duration formats (e.g., "1d", "2h", "30m", "permanent")

Database Compatibility: All methods in this API are fully compatible with H2, SQLite, MySQL, and MariaDB databases. The API automatically adapts to the configured database type from the configuration file.

Important Notes:

  • Players with the zenith.ban.bypass permission cannot be banned
  • All bans are recorded in the history database (zn_history)
  • Each ban receives a unique case ID
  • Templates support escalation (duration increases with repeat offenses)

Example usage: 


 ZenithAPI api = ZenithAPI.getInstance();
 if (api != null) {
     BanAPI banAPI = api.getBanAPI();
     
     UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
     UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
     
     // Regular ban with duration
     banAPI.ban(playerUuid, staffUuid, "Cheating", "7d").thenAccept(caseId -> {
         if (caseId > 0) {
             getLogger().info("Player banned successfully. Case ID: " + caseId);
         }
     });
     
     // IP ban
     banAPI.ipBan(playerUuid, staffUuid, "Cheating", "30d").thenAccept(caseId -> {
         if (caseId > 0) {
             getLogger().info("Player IP banned successfully. Case ID: " + caseId);
         }
     });
     
     // Ban using template (with escalation)
     banAPI.banWithTemplate(playerUuid, staffUuid, "cheating", "Using hacks").thenAccept(caseId -> {
         if (caseId > 0) {
             getLogger().info("Player banned with template. Case ID: " + caseId);
         }
     });
     
     // Unban
     banAPI.unban(playerUuid, staffUuid, "Appeal accepted").thenAccept(success -> {
         if (success) {
             getLogger().info("Player unbanned successfully");
         }
     });
 }
Seit:
1.2.3
Autor:
Zenith-Studios

  • Konstruktordetails

    • BanAPI

      public BanAPI(@NotNull @NotNull me.kzlyth.ZenithMod plugin, @NotNull @NotNull ZenithAPI api)
      Constructs a new BanAPI instance.
      Parameter:
      plugin - The plugin instance
      api - The main API instance

  • Methodendetails

    • ban

      @NotNull public @NotNull CompletableFuture<Integer> ban(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      Bans a player with a specified duration.

      This method bans an online player. If the player is offline, use banOffline(UUID, UUID, String, String). The ban is recorded in the history database with a case ID.

      Duration formats:

      • "permanent" or "perm" or "forever" - Permanent ban
      • "1d" - 1 day
      • "2h" - 2 hours
      • "30m" - 30 minutes
      • "45s" - 45 seconds
      • "1w" - 1 week
      • "1M" - 1 month

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.ban(playerUuid, staffUuid, "Cheating detected", "7d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player banned successfully. Case ID: " + caseId);
     } else {
         getLogger().warning("Failed to ban player (player may be offline or have bypass permission)");
     }
 });
      Parameter:
      playerUuid - The UUID of the player to ban
      staffUuid - The UUID of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • ban

      @NotNull public @NotNull CompletableFuture<Integer> ban(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      Bans a player with a specified duration.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.ban("PlayerName", "AdminName", "Cheating detected", "7d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerName - The name of the player to ban
      staffName - The name of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • banOffline

      @NotNull public @NotNull CompletableFuture<Integer> banOffline(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      Bans an offline player with a specified duration.

      This method bans a player that is currently offline. The player must exist in the database.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.banOffline(playerUuid, staffUuid, "Cheating detected", "7d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Offline player banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerUuid - The UUID of the player to ban
      staffUuid - The UUID of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • banOffline

      @NotNull public @NotNull CompletableFuture<Integer> banOffline(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      Bans an offline player with a specified duration.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.banOffline("PlayerName", "AdminName", "Cheating detected", "7d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Offline player banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerName - The name of the player to ban
      staffName - The name of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • ipBan

      @NotNull public @NotNull CompletableFuture<Integer> ipBan(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      IP bans a player with a specified duration.

      This method IP bans an online player. If the player is offline, use ipBanOffline(UUID, UUID, String, String). IP bans affect all accounts using the same IP address.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.ipBan(playerUuid, staffUuid, "Cheating detected", "30d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player IP banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerUuid - The UUID of the player to IP ban
      staffUuid - The UUID of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • ipBan

      @NotNull public @NotNull CompletableFuture<Integer> ipBan(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      IP bans a player with a specified duration.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.ipBan("PlayerName", "AdminName", "Cheating detected", "30d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player IP banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerName - The name of the player to IP ban
      staffName - The name of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • ipBanOffline

      @NotNull public @NotNull CompletableFuture<Integer> ipBanOffline(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      IP bans an offline player with a specified duration.

      This method IP bans a player that is currently offline. The player must exist in the database.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.ipBanOffline(playerUuid, staffUuid, "Cheating detected", "30d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Offline player IP banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerUuid - The UUID of the player to IP ban
      staffUuid - The UUID of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • ipBanOffline

      @NotNull public @NotNull CompletableFuture<Integer> ipBanOffline(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason, @NotNull @NotNull String duration)
      IP bans an offline player with a specified duration.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.ipBanOffline("PlayerName", "AdminName", "Cheating detected", "30d").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Offline player IP banned successfully. Case ID: " + caseId);
     }
 });
      Parameter:
      playerName - The name of the player to IP ban
      staffName - The name of the staff member performing the ban (can be null for console)
      reason - The reason for the ban
      duration - The duration string (e.g., "7d", "2h", "permanent")
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • banWithTemplate

      @NotNull public @NotNull CompletableFuture<Integer> banWithTemplate(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String templateKey, @Nullable @Nullable String customReason)
      Bans a player using a template (custom ban with escalation support).

      Templates support escalation, meaning the ban duration increases with repeat offenses. The escalation can be tracked by IP address or by player UUID, depending on the template configuration.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.banWithTemplate(playerUuid, staffUuid, "cheating", "Using hacks").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player banned with template. Case ID: " + caseId);
     }
 });
      Parameter:
      playerUuid - The UUID of the player to ban
      staffUuid - The UUID of the staff member performing the ban (can be null for console)
      templateKey - The template key (identifier, e.g., "cheating", "griefing")
      customReason - Optional custom reason (if null, uses template default reason)
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • banWithTemplate

      @NotNull public @NotNull CompletableFuture<Integer> banWithTemplate(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String templateKey, @Nullable @Nullable String customReason)
      Bans a player using a template (custom ban with escalation support).

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.banWithTemplate("PlayerName", "AdminName", "cheating", "Using hacks").thenAccept(caseId -> {
     if (caseId > 0) {
         getLogger().info("Player banned with template. Case ID: " + caseId);
     }
 });
      Parameter:
      playerName - The name of the player to ban
      staffName - The name of the staff member performing the ban (can be null for console)
      templateKey - The template key (identifier, e.g., "cheating", "griefing")
      customReason - Optional custom reason (if null, uses template default reason)
      Gibt zurück:
      A CompletableFuture that completes with the case ID (positive if successful, -1 if failed)

    • unban

      @NotNull public @NotNull CompletableFuture<Boolean> unban(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason)
      Unbans a player.

      This method removes both Bukkit and database bans, creates an UNBAN history entry, and deactivates any IP bans associated with the player's IP address.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 banAPI.unban(playerUuid, staffUuid, "Appeal accepted").thenAccept(success -> {
     if (success) {
         getLogger().info("Player unbanned successfully");
     } else {
         getLogger().warning("Failed to unban player (player may not be banned)");
     }
 });
      Parameter:
      playerUuid - The UUID of the player to unban
      staffUuid - The UUID of the staff member performing the unban (can be null for console)
      reason - The reason for the unban
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • unban

      @NotNull public @NotNull CompletableFuture<Boolean> unban(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason)
      Unbans a player.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 banAPI.unban("PlayerName", "AdminName", "Appeal accepted").thenAccept(success -> {
     if (success) {
         getLogger().info("Player unbanned successfully");
     }
 });
      Parameter:
      playerName - The name of the player to unban
      staffName - The name of the staff member performing the unban (can be null for console)
      reason - The reason for the unban
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • unban

      @NotNull public @NotNull CompletableFuture<Boolean> unban(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason, @Nullable @Nullable String additionalData)
      Unbans a player with additional data.

      This method allows you to provide additional data (JSON string) that will be stored with the unban history entry.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 String additionalData = "{\"source\":\"api\",\"custom_field\":\"value\"}";
 
 banAPI.unban(playerUuid, staffUuid, "Appeal accepted", additionalData).thenAccept(success -> {
     if (success) {
         getLogger().info("Player unbanned successfully");
     }
 });
      Parameter:
      playerUuid - The UUID of the player to unban
      staffUuid - The UUID of the staff member performing the unban (can be null for console)
      reason - The reason for the unban
      additionalData - Additional data to store with the unban (JSON string, can be null)
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • unban

      @NotNull public @NotNull CompletableFuture<Boolean> unban(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason, @Nullable @Nullable String additionalData)
      Unbans a player with additional data.

      This is an overloaded method that accepts player and staff names instead of UUIDs.

      Example: 

      
 String additionalData = "{\"source\":\"api\",\"custom_field\":\"value\"}";
 banAPI.unban("PlayerName", "AdminName", "Appeal accepted", additionalData).thenAccept(success -> {
     if (success) {
         getLogger().info("Player unbanned successfully");
     }
 });
      Parameter:
      playerName - The name of the player to unban
      staffName - The name of the staff member performing the unban (can be null for console)
      reason - The reason for the unban
      additionalData - Additional data to store with the unban (JSON string, can be null)
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • getActiveBanInfo

      @NotNull public @NotNull CompletableFuture<ActiveBanInfo> getActiveBanInfo(@NotNull @NotNull UUID playerUuid)
      Gets complete information about the active ban for a player.

      Returns detailed information about the player's active ban including case ID, reason, duration, expiration time, staff member, and whether it's an IP ban or permanent.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 banAPI.getActiveBanInfo(playerUuid).thenAccept(banInfo -> {
     if (banInfo != null) {
         getLogger().info("Player is banned:");
         getLogger().info("  Case ID: " + banInfo.getCaseId());
         getLogger().info("  Reason: " + banInfo.getReason());
         getLogger().info("  Staff: " + banInfo.getStaffName());
         getLogger().info("  IP Ban: " + banInfo.isIpBan());
         if (banInfo.isPermanent()) {
             getLogger().info("  Type: Permanent");
         } else {
             getLogger().info("  Expires at: " + new Date(banInfo.getExpiresAt()));
         }
     } else {
         getLogger().info("Player is not banned");
     }
 });
      Parameter:
      playerUuid - The UUID of the player
      Gibt zurück:
      A CompletableFuture that completes with the active ban information, or null if player is not banned

    • getActiveBanInfo

      @NotNull public @NotNull CompletableFuture<ActiveBanInfo> getActiveBanInfo(@NotNull @NotNull String playerName)
      Gets complete information about the active ban for a player.

      This is an overloaded method that accepts a player name instead of UUID.

      Example: 

      
 banAPI.getActiveBanInfo("PlayerName").thenAccept(banInfo -> {
     if (banInfo != null) {
         getLogger().info("Player is banned. Case ID: " + banInfo.getCaseId());
     }
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with the active ban information, or null if player is not banned or doesn't exist