Package com.ohacd.matchbox.api

Class MatchboxAPI

java.lang.Object
com.ohacd.matchbox.api.MatchboxAPI
public final class MatchboxAPI extends Object
Main API class for interacting with the Matchbox plugin.

This class provides static methods for managing game sessions, players, and event listeners. It serves as the primary entry point for external plugins to interact with Matchbox functionality.

All methods are thread-safe and handle null inputs gracefully.

Since:
0.9.5

  • Method Details

    • createSessionBuilder

      @NotNull public static @NotNull SessionBuilder createSessionBuilder(@NotNull @NotNull String name)
      Creates a new session builder for the specified session name.
      Parameters:
      name - the unique name for the session
      Returns:
      a new SessionBuilder instance
      Throws:
      IllegalArgumentException - if name is null or empty

    • getSession

      @NotNull public static @NotNull Optional<ApiGameSession> getSession(@Nullable @Nullable String name)
      Gets an existing game session by name.
      Parameters:
      name - the session name (case-insensitive)
      Returns:
      Optional containing the session if found, empty otherwise

    • getAllSessions

      @NotNull public static @NotNull Collection<ApiGameSession> getAllSessions()
      Gets all active game sessions.
      Returns:
      a collection of all active sessions

    • endSession

      public static boolean endSession(@Nullable @Nullable String name)
      Ends a game session gracefully.
      Parameters:
      name - the session name to end
      Returns:
      true if the session was found and ended, false otherwise

    • endAllSessions

      public static int endAllSessions()
      Ends all active game sessions gracefully.
      Returns:
      the number of sessions that were ended

    • getPlayerSession

      @NotNull public static @NotNull Optional<ApiGameSession> getPlayerSession(@Nullable @Nullable org.bukkit.entity.Player player)
      Gets the session a player is currently in.
      Parameters:
      player - the player to check
      Returns:
      Optional containing the session if the player is in one, empty otherwise

    • getPlayerRole

      @NotNull public static @NotNull Optional<com.ohacd.matchbox.game.utils.Role> getPlayerRole(@Nullable @Nullable org.bukkit.entity.Player player)
      Gets the current role of a player if they are in an active game.
      Parameters:
      player - the player to check
      Returns:
      Optional containing the player's role if in a game, empty otherwise

    • getCurrentPhase

      @NotNull public static @NotNull Optional<com.ohacd.matchbox.game.utils.GamePhase> getCurrentPhase(@Nullable @Nullable String sessionName)
      Gets the current game phase for a session.
      Parameters:
      sessionName - the session name
      Returns:
      Optional containing the current phase if session exists, empty otherwise

    • addEventListener

      public static void addEventListener(@NotNull @NotNull MatchboxEventListener listener)
      Adds an event listener to receive game events.
      Parameters:
      listener - the listener to add
      Throws:
      IllegalArgumentException - if listener is null

    • removeEventListener

      public static boolean removeEventListener(@Nullable @Nullable MatchboxEventListener listener)
      Removes an event listener.
      Parameters:
      listener - the listener to remove
      Returns:
      true if the listener was removed, false if it wasn't found

    • getListeners

      @NotNull public static @NotNull Set<MatchboxEventListener> getListeners()
      Gets all registered event listeners.
      Returns:
      an unmodifiable copy of all registered listeners

    • registerChatProcessor

      @Experimental public static boolean registerChatProcessor(@NotNull @NotNull String sessionName, @NotNull @NotNull ChatProcessor processor)
      Registers a custom chat processor for a specific session. The processor will be called for all chat messages in that session.
      Parameters:
      sessionName - the session name to register the processor for
      processor - the chat processor to register
      Returns:
      true if the processor was registered, false if session not found
      Throws:
      IllegalArgumentException - if sessionName or processor is null
      Since:
      0.9.5

    • unregisterChatProcessor

      @Experimental public static boolean unregisterChatProcessor(@NotNull @NotNull String sessionName, @NotNull @NotNull ChatProcessor processor)
      Unregisters a custom chat processor from a specific session.
      Parameters:
      sessionName - the session name to unregister the processor from
      processor - the chat processor to unregister
      Returns:
      true if the processor was unregistered, false if not found
      Throws:
      IllegalArgumentException - if sessionName or processor is null
      Since:
      0.9.5

    • clearChatProcessors

      @Experimental public static boolean clearChatProcessors(@NotNull @NotNull String sessionName)
      Unregisters all custom chat processors from a specific session.
      Parameters:
      sessionName - the session name to clear processors from
      Returns:
      true if processors were cleared, false if session not found
      Throws:
      IllegalArgumentException - if sessionName is null
      Since:
      0.9.5