Java API Documentation

Beta Notice

This API is currently in Beta. The API and event system are still under active development and may undergo changes. While we strive for stability and accuracy, please be aware that:

• In very rare cases, events may not fire or fire incorrectly
• In very rare cases, event data may contain incorrect or incomplete information
• In very rare cases, API methods may behave unexpectedly or change between versions
• We do not provide any warranty or guarantee regarding the API’s functionality
• Use of this API is at your own risk

Note: Data loss is generally not possible with this API, as it primarily handles notifications and event firing. However, we are not responsible for any issues or problems that may in very rare cases arise from using this Beta API. For complete API reference documentation, see javadoc.zenith-studios.org.

Zenith-Mod provides a comprehensive Java API for developers to integrate with other plugins and extend functionality.

Javadoc

For complete API reference documentation, see javadoc.zenith-studios.org.

📋 Getting Started

Setup in plugin.yml

To use the Zenith-Mod API in your plugin, add Zenith-Mod as a dependency in your plugin.yml:

plugin.yml

name: YourPlugin
version: 1.0.0
main: com.yourcompany.yourplugin.YourPlugin
api-version: 1.21

depend: [Zenith-Mod]
# OR use soft-depend if your plugin can work without Zenith-Mod:
# softdepend: [Zenith-Mod]

Basic Usage Example

Here’s a simple example of how to get started with the Zenith-Mod API:

In onEnable

YourPlugin.java

import me.kzlyth.api.ZenithAPI;

public class YourPlugin extends JavaPlugin {

  @Override
  public void onEnable() {
      // Get the Zenith-Mod API instance
      // This returns null if Zenith-Mod is not loaded or not yet initialized
      ZenithAPI api = ZenithAPI.getInstance();

      // Always check if the API instance is null before using it
      if (api == null) {
          getLogger().severe("Zenith-Mod is not loaded! Please install Zenith-Mod.");
          getServer().getPluginManager().disablePlugin(this);
          return; // Exit early if API is not available
      }

      // API is now available for use
      // You can access various API modules through this instance
      getLogger().info("Zenith-Mod API loaded successfully!");
  }
}

Check Availability

// Get the API instance (may be null if Zenith-Mod is not loaded)
ZenithAPI api = ZenithAPI.getInstance();

// Check both null and availability status
// isAvailable() ensures the API is fully initialized and ready
if (api != null && api.isAvailable()) {
  // API is ready to use - safe to call methods
  String version = api.getVersion();
  getLogger().info("Zenith-Mod version: " + version);

  // Now you can use any of the API modules:
  // api.getBanAPI(), api.getMuteAPI(), etc.
} else {
  // API is not available - handle gracefully
  getLogger().warning("Zenith-Mod API is not available!");
}

Important

Always check if the API is available before using it. The API instance can be null if Zenith-Mod is not loaded or not yet initialized.

📚 Available APIs

Zenith-Mod provides various APIs for different functionalities:

Ban API

Ban and unban players programmatically. See Javadoc for details.

Mute API

Mute and unmute players programmatically. See Javadoc for details.

Warn API

Warn players with templates or custom reasons. See Javadoc for details.

Kick API

Kick players with custom reasons. See Javadoc for details.

History API

Access player punishment history. See Javadoc for details.

Notes API

Manage player notes programmatically. See Javadoc for details.

Full API Reference

For complete documentation of all available APIs, methods, and parameters, visit javadoc.zenith-studios.org.

🎯 Events System

The Zenith-Mod Events system allows you to listen to moderation actions and react to them in real-time. Events are fired after the action has been completed and logged to the database, making them perfect for integrations with external systems, notifications, and analytics.

Getting Started with Events

First, get the ZenithEventBus instance. The event bus is a singleton, so you can safely call getInstance() from anywhere:

import me.kzlyth.api.events.ZenithEventBus;

// Get the singleton event bus instance
// This instance is shared across all plugins using the event system
ZenithEventBus eventBus = ZenithEventBus.getInstance();

Event Packages

Events are organized into sub-packages for better code organization:

• me.kzlyth.api.events.ban.* - Ban and unban events
• me.kzlyth.api.events.mute.* - Mute and unmute events
• me.kzlyth.api.events.warn.* - Warn events
• me.kzlyth.api.events.kick.* - Kick events

Ban Events

Listen to when players are banned or unbanned. These events are fired after the ban/unban has been successfully processed and saved to the database:

PlayerBanEvent

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.ban.PlayerBanEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerBanEvent - fired when a player is banned
  // The lambda receives the event with all relevant information
  bus.subscribe(PlayerBanEvent.class, event -> {
      // Extract event data - all fields are populated by Zenith-Mod
      String playerName = event.getPlayerName(); // Name of the banned player
      String staffName = event.getStaffName();   // Staff member who performed the ban
      String reason = event.getReason();          // Reason for the ban
      boolean isIpBan = event.isIpBan();         // Whether this is an IP ban
      long duration = event.getDurationSeconds(); // Duration in seconds (-1 for permanent)

      // Log the ban action
      getLogger().info(playerName + " was " +
          (isIpBan ? "IP-" : "") + "banned by " + staffName);
      getLogger().info("Reason: " + reason);

      // Handle permanent vs temporary bans
      if (duration < 0) {
          getLogger().info("Duration: Permanent");
      } else {
          getLogger().info("Duration: " + duration + " seconds");
      }

      // You can perform additional actions here:
      // - Send to Discord webhook
      // - Update external database
      // - Notify other plugins
      // - Log to analytics system
  });
}

PlayerUnbanEvent

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.ban.PlayerUnbanEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerUnbanEvent - fired when a player is unbanned
  bus.subscribe(PlayerUnbanEvent.class, event -> {
      // Extract event data
      String playerName = event.getPlayerName(); // Name of the unbanned player
      String staffName = event.getStaffName();   // Staff member who unbanned the player
      String reason = event.getReason();          // Reason for the unban (if provided)

      // Log the unban action
      getLogger().info(playerName + " was unbanned by " + staffName);
      getLogger().info("Reason: " + reason);

      // Example: Notify external systems about the unban
      // This could sync with Discord, external databases, etc.
      notifyExternalSystem(playerName, "unbanned");

      // You can also access the player UUID if needed:
      // UUID playerUuid = event.getPlayerUuid();
      // int caseId = event.getCaseId(); // Case ID of the original ban
  });
}

Mute Events

Listen to when players are muted or unmuted. Similar to ban events, these are fired after the action completes:

PlayerMuteEvent

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.mute.PlayerMuteEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerMuteEvent - fired when a player is muted
  bus.subscribe(PlayerMuteEvent.class, event -> {
      // Extract event data
      String playerName = event.getPlayerName();   // Name of the muted player
      String reason = event.getReason();           // Reason for the mute
      boolean isIpMute = event.isIpMute();         // Whether this is an IP mute
      boolean isPermanent = event.isPermanent();   // Whether the mute is permanent

      // Log the mute action
      getLogger().info(playerName + " was " +
          (isIpMute ? "IP-" : "") + "muted");
      getLogger().info("Permanent: " + isPermanent);

      // Example: Send to Discord webhook
      // You could format this message however you need for your Discord integration
      sendToDiscord(playerName + " has been muted: " + reason);

      // Additional event data available:
      // UUID playerUuid = event.getPlayerUuid();
      // String staffName = event.getStaffName();
      // int caseId = event.getCaseId();
  });
}

PlayerUnmuteEvent

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.mute.PlayerUnmuteEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerUnmuteEvent - fired when a player is unmuted
  bus.subscribe(PlayerUnmuteEvent.class, event -> {
      // Extract event data
      String playerName = event.getPlayerName(); // Name of the unmuted player

      // Log the unmute action
      getLogger().info(playerName + " was unmuted");

      // Example: Restore permissions or notify player
      // This could be useful if your plugin manages permissions separately
      UUID playerUuid = event.getPlayerUuid();
      restorePlayerPermissions(playerUuid);

      // You can also check who unmuted the player:
      // String staffName = event.getStaffName();
      // String reason = event.getReason();
  });
}

Warn Events

Listen to when players are warned. Warn events are useful for tracking player behavior patterns:

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.warn.PlayerWarnEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerWarnEvent - fired when a player receives a warning
  bus.subscribe(PlayerWarnEvent.class, event -> {
      // Extract event data
      String playerName = event.getPlayerName();      // Name of the warned player
      String reason = event.getReason();             // Reason for the warning
      String templateKey = event.getTemplateKey();   // Template key if used (null for manual warns)
      boolean isTemplate = event.isTemplateWarning(); // Whether a template was used

      // Log the warning
      getLogger().info(playerName + " was warned");
      getLogger().info("Reason: " + reason);

      // Check if a template was used or if it was a manual warning
      if (isTemplate) {
          getLogger().info("Template used: " + templateKey);
      } else {
          getLogger().info("Manual warning");
      }

      // Example: Check if escalation actions should be triggered
      // If your plugin tracks warning counts or escalation rules,
      // you can react to specific template keys
      if (isTemplate && templateKey != null) {
          UUID playerUuid = event.getPlayerUuid();
          checkEscalationRules(playerUuid, templateKey);
      }

      // Additional event data available:
      // String staffName = event.getStaffName();
      // int caseId = event.getCaseId();
  });
}

Kick Events

Listen to when players are kicked. Kick events are fired after the player has been disconnected:

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.kick.PlayerKickEvent;

@Override
public void onEnable() {
  // Get the event bus instance
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to PlayerKickEvent - fired when a player is kicked
  bus.subscribe(PlayerKickEvent.class, event -> {
      // Extract event data
      String playerName = event.getPlayerName(); // Name of the kicked player
      String staffName = event.getStaffName();   // Staff member who kicked the player
      String reason = event.getReason();          // Reason for the kick
      int caseId = event.getCaseId();            // Case ID for tracking

      // Log the kick action
      getLogger().info(playerName + " was kicked by " + staffName);
      getLogger().info("Reason: " + reason);
      getLogger().info("Case ID: " + caseId);

      // Example: Log to external system
      // The caseId can be used to link this kick to other actions
      logKickToDatabase(event);

      // Note: The player is already disconnected when this event fires,
      // so event.getPlayer() will return null
  });
}

Multiple Event Types

You can subscribe to multiple event types in the same onEnable() method. Each subscription is independent:

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.ban.PlayerBanEvent;
import me.kzlyth.api.events.mute.PlayerMuteEvent;
import me.kzlyth.api.events.warn.PlayerWarnEvent;
import me.kzlyth.api.events.kick.PlayerKickEvent;

@Override
public void onEnable() {
  // Get the event bus instance (shared singleton)
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Subscribe to ban events
  // Each event type can have multiple handlers if needed
  bus.subscribe(PlayerBanEvent.class, event -> {
      getLogger().info("Ban: " + event.getPlayerName());
      // Your ban handling logic here
  });

  // Subscribe to mute events
  bus.subscribe(PlayerMuteEvent.class, event -> {
      getLogger().info("Mute: " + event.getPlayerName());
      // Your mute handling logic here
  });

  // Subscribe to warn events
  bus.subscribe(PlayerWarnEvent.class, event -> {
      getLogger().info("Warn: " + event.getPlayerName());
      // Your warn handling logic here
  });

  // Subscribe to kick events
  bus.subscribe(PlayerKickEvent.class, event -> {
      getLogger().info("Kick: " + event.getPlayerName());
      // Your kick handling logic here
  });

  // All subscriptions remain active until the plugin is disabled
  // or until you explicitly unsubscribe
}

Unsubscribing from Events

You can unsubscribe from events if needed. This is useful if you want to temporarily disable event handling or clean up resources:

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.ban.PlayerBanEvent;
import java.util.function.Consumer;

// Get the event bus instance
ZenithEventBus bus = ZenithEventBus.getInstance();

// Define handler as a variable so we can reference it later
// This allows us to unsubscribe using the same handler reference
Consumer<PlayerBanEvent> handler = event -> {
  getLogger().info("Player banned: " + event.getPlayerName());
  // Your event handling logic here
};

// Subscribe to the event
// The handler is now registered and will receive events
bus.subscribe(PlayerBanEvent.class, handler);

// Later, when you want to stop receiving events (e.g., on plugin disable):
// Unsubscribe using the same handler reference
// After this, the handler will no longer receive events
bus.unsubscribe(PlayerBanEvent.class, handler);

// Note: You must use the exact same handler reference to unsubscribe
// Lambda expressions cannot be unsubscribed unless stored in a variable

Event Properties

All events extend ZenithEvent and provide the following information:

Property	Type	Description
getPlayerUuid()	UUID	UUID of the target player
getPlayerName()	String	Name of the target player
getPlayer()	Player	Player object (null if offline)
getStaffUuid()	UUID	UUID of staff member (null for console)
getStaffName()	String	Name of staff member
getStaffPlayer()	Player	Staff player object (null if offline/console)
getReason()	String	Reason for the action
getCaseId()	int	Case ID of the action
isCancelled()	boolean	Whether the event has been cancelled (see below)
setCancelled(boolean)	void	Sets the cancellation state of the event

Event Cancellation

The isCancelled() method and setCancelled() method allow you to check or set the cancellation state of an event. Important: Event cancellation in Zenith-Mod events works differently than Bukkit events:

Event Cancellation Behavior

Zenith-Mod events are fired AFTER the action has been completed. This means:

• The ban/mute/warn/kick has already been applied and saved to the database
• Setting event.setCancelled(true) will NOT undo the action
• Cancellation is primarily for signaling to other listeners that you’ve handled the event
• Other plugins can check event.isCancelled() to determine if another plugin has processed the event

Understanding Event Cancellation

import me.kzlyth.api.events.ZenithEventBus;
import me.kzlyth.api.events.ban.PlayerBanEvent;

@Override
public void onEnable() {
  ZenithEventBus bus = ZenithEventBus.getInstance();

  // Example 1: Check if event was cancelled by another plugin
  bus.subscribe(PlayerBanEvent.class, event -> {
      // Check if another listener has already processed this event
      if (event.isCancelled()) {
          // Another plugin has marked this event as handled
          // You might want to skip additional processing
          return;
      }

      // Process the event
      processBanEvent(event);

      // Mark as cancelled to signal to other plugins
      // This is optional - it's just a convention for coordination
      event.setCancelled(true);
  });
}

void processBanEvent(PlayerBanEvent event) {
  // Your custom processing logic here
  // Note: The ban has already been applied at this point
  // This event is for notification/reaction purposes only
}

// Example 2: Coordinate between multiple plugins
// Plugin A processes the event and marks it as cancelled
bus.subscribe(PlayerBanEvent.class, event -> {
  if (event.isCancelled()) {
      // Plugin B sees Plugin A already handled it
      return; // Skip processing
  }
  // Process only if not cancelled
  doSomething(event);
  event.setCancelled(true); // Signal we handled it
});

Event Threading

Events are automatically handled on the main server thread, so you can safely access Bukkit API methods within event handlers. You don’t need to worry about thread safety when accessing Bukkit objects like Player, World, etc.

📖 Complete API Reference

For detailed documentation of all available APIs, methods, parameters, and return types, visit:

javadoc.zenith-studios.org

The Javadoc includes:

• Complete class and method documentation
• Parameter descriptions
• Return value types
• Usage examples
• Exception handling
• Best practices