Package me.kzlyth.api.warn

Klasse WarnAPI

java.lang.Object
me.kzlyth.api.warn.WarnAPI
public class WarnAPI extends Object
API for warning players in Zenith-Mod.

This API provides methods to warn players manually or using templates (custom warns). All warnings are automatically recorded in the history database with a case ID.

Features:

  • Manual warnings with custom reasons
  • Template-based warnings
  • Online and offline player warning
  • Automatic escalation support (can trigger bans, mutes, or kicks)

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:

  • All warnings are recorded in the history database (zn_history)
  • Each warning receives a unique case ID
  • Templates may support escalation (automatically triggers bans/mutes/kicks after X warnings)
  • Warnings are permanent entries (no unwarn functionality)

Example usage: 


 ZenithAPI api = ZenithAPI.getInstance();
 if (api != null) {
     WarnAPI warnAPI = api.getWarnAPI();
     
     UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
     UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
     
     // Manual warn
     warnAPI.warn(playerUuid, staffUuid, "Toxic behavior").thenAccept(success -> {
         if (success) {
             getLogger().info("Player warned successfully");
         }
     });
     
     // Warn using template
     warnAPI.warnWithTemplate(playerUuid, staffUuid, "toxicity").thenAccept(success -> {
         if (success) {
             getLogger().info("Player warned with template successfully");
         }
     });
 }
Seit:
1.2.3
Autor:
Zenith-Studios

  • Konstruktordetails

    • WarnAPI

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

  • Methodendetails

    • warn

      @NotNull public @NotNull CompletableFuture<Boolean> warn(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String reason)
      Warns a player with a specified reason.

      This method warns a player (online or offline) with a custom reason. The warning is recorded in the history database with a case ID.

      Example: 

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

    • warn

      @NotNull public @NotNull CompletableFuture<Boolean> warn(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String reason)
      Warns a player with a specified reason.

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

      Example: 

      
 warnAPI.warn("PlayerName", "AdminName", "Toxic behavior in chat").thenAccept(success -> {
     if (success) {
         getLogger().info("Player warned successfully");
     }
 });
      Parameter:
      playerName - The name of the player to warn
      staffName - The name of the staff member performing the warn (can be null for console)
      reason - The reason for the warning
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • warnWithTemplate

      @NotNull public @NotNull CompletableFuture<Boolean> warnWithTemplate(@NotNull @NotNull UUID playerUuid, @Nullable @Nullable UUID staffUuid, @NotNull @NotNull String templateKey)
      Warns a player using a template (custom warn).

      Templates provide pre-configured warning reasons. Templates may support escalation, which can automatically trigger bans, mutes, or kicks when a player accumulates a certain number of warnings using the same template.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 UUID staffUuid = UUID.fromString("00000000-0000-0000-0000-000000000001");
 
 warnAPI.warnWithTemplate(playerUuid, staffUuid, "toxicity").thenAccept(success -> {
     if (success) {
         getLogger().info("Player warned with template successfully");
     }
 });
      Parameter:
      playerUuid - The UUID of the player to warn
      staffUuid - The UUID of the staff member performing the warn (can be null for console)
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • warnWithTemplate

      @NotNull public @NotNull CompletableFuture<Boolean> warnWithTemplate(@NotNull @NotNull String playerName, @Nullable @Nullable String staffName, @NotNull @NotNull String templateKey)
      Warns a player using a template (custom warn).

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

      Example: 

      
 warnAPI.warnWithTemplate("PlayerName", "AdminName", "toxicity").thenAccept(success -> {
     if (success) {
         getLogger().info("Player warned with template successfully");
     }
 });
      Parameter:
      playerName - The name of the player to warn
      staffName - The name of the staff member performing the warn (can be null for console)
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with true if successful, false otherwise

    • getWarningCount

      @NotNull public @NotNull CompletableFuture<Integer> getWarningCount(@NotNull @NotNull UUID playerUuid)
      Gets the total count of warnings for a player.

      Returns the total number of warnings (both manual and template-based) for the specified player.

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 warnAPI.getWarningCount(playerUuid).thenAccept(count -> {
     getLogger().info("Player has " + count + " total warnings");
 });
      Parameter:
      playerUuid - The UUID of the player
      Gibt zurück:
      A CompletableFuture that completes with the warning count

    • getWarningCount

      @NotNull public @NotNull CompletableFuture<Integer> getWarningCount(@NotNull @NotNull String playerName)
      Gets the total count of warnings for a player.

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

      Example: 

      
 warnAPI.getWarningCount("PlayerName").thenAccept(count -> {
     getLogger().info("Player has " + count + " warnings");
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with the warning count, or 0 if player doesn't exist

    • getWarningCountByTemplate

      @NotNull public @NotNull CompletableFuture<Integer> getWarningCountByTemplate(@NotNull @NotNull UUID playerUuid, @NotNull @NotNull String templateKey)
      Gets the count of warnings for a player using a specific template.

      Returns the number of warnings the player has received using the specified template. This is useful for checking escalation levels (e.g., "How many 'spam' warnings does this player have?").

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 warnAPI.getWarningCountByTemplate(playerUuid, "toxicity").thenAccept(count -> {
     getLogger().info("Player has " + count + " 'toxicity' warnings");
     if (count >= 3) {
         getLogger().info("Escalation threshold reached!");
     }
 });
      Parameter:
      playerUuid - The UUID of the player
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with the warning count for the template

    • getWarningCountByTemplate

      @NotNull public @NotNull CompletableFuture<Integer> getWarningCountByTemplate(@NotNull @NotNull String playerName, @NotNull @NotNull String templateKey)
      Gets the count of warnings for a player using a specific template.

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

      Example: 

      
 warnAPI.getWarningCountByTemplate("PlayerName", "toxicity").thenAccept(count -> {
     getLogger().info("Player has " + count + " 'toxicity' warnings");
 });
      Parameter:
      playerName - The name of the player
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with the warning count for the template, or 0 if player doesn't exist

    • getWarningsByTemplate

      @NotNull public @NotNull CompletableFuture<List<Warn>> getWarningsByTemplate(@NotNull @NotNull UUID playerUuid, @NotNull @NotNull String templateKey)
      Gets all warnings for a player using a specific template.

      Returns all warning entries where the player was warned using the specified template. Warnings are ordered by timestamp (most recent first).

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 warnAPI.getWarningsByTemplate(playerUuid, "toxicity").thenAccept(warnings -> {
     getLogger().info("Player has " + warnings.size() + " 'toxicity' warnings:");
     for (Warn warn : warnings) {
         getLogger().info("  Case #" + warn.getCaseId() + ": " + warn.getReason());
         getLogger().info("  Date: " + new Date(warn.getTimestamp()));
         getLogger().info("  Staff: " + warn.getStaffName());
     }
 });
      Parameter:
      playerUuid - The UUID of the player
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with a list of warnings for the template

    • getWarningsByTemplate

      @NotNull public @NotNull CompletableFuture<List<Warn>> getWarningsByTemplate(@NotNull @NotNull String playerName, @NotNull @NotNull String templateKey)
      Gets all warnings for a player using a specific template.

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

      Example: 

      
 warnAPI.getWarningsByTemplate("PlayerName", "toxicity").thenAccept(warnings -> {
     getLogger().info("Player has " + warnings.size() + " 'toxicity' warnings");
 });
      Parameter:
      playerName - The name of the player
      templateKey - The template key (identifier, e.g., "toxicity", "spam")
      Gibt zurück:
      A CompletableFuture that completes with a list of warnings for the template, or empty list if player doesn't exist

    • getWarnings

      @NotNull public @NotNull CompletableFuture<List<Warn>> getWarnings(@NotNull @NotNull UUID playerUuid)
      Gets all warnings for a player.

      Returns all warning entries (both manual and template-based) for the specified player. Warnings are ordered by timestamp (most recent first).

      Example: 

      
 UUID playerUuid = UUID.fromString("123e4567-e89b-12d3-a456-426614174000");
 warnAPI.getWarnings(playerUuid).thenAccept(warnings -> {
     getLogger().info("Player has " + warnings.size() + " total warnings:");
     for (Warn warn : warnings) {
         getLogger().info("  Case #" + warn.getCaseId() + ": " + warn.getReason());
         getLogger().info("  Staff: " + warn.getStaffName());
         getLogger().info("  Date: " + new Date(warn.getTimestamp()));
         if (warn.getTemplateName() != null) {
             getLogger().info("  Template: " + warn.getTemplateName());
         }
     }
 });
      Parameter:
      playerUuid - The UUID of the player
      Gibt zurück:
      A CompletableFuture that completes with a list of warnings

    • getWarnings

      @NotNull public @NotNull CompletableFuture<List<Warn>> getWarnings(@NotNull @NotNull String playerName)
      Gets all warnings for a player.

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

      Example: 

      
 warnAPI.getWarnings("PlayerName").thenAccept(warnings -> {
     getLogger().info("Player has " + warnings.size() + " warnings");
 });
      Parameter:
      playerName - The name of the player
      Gibt zurück:
      A CompletableFuture that completes with a list of warnings, or empty list if player doesn't exist