Package com.ohacd.matchbox.api

Interface MatchboxEventListener

public interface MatchboxEventListener
Interface for listening to Matchbox game events.

Implement this interface and register it using MatchboxAPI.addEventListener(MatchboxEventListener) to receive notifications about game state changes, player actions, and other significant events.

All methods have default empty implementations, so you only need to override the events you're interested in. This follows the interface segregation principle.

Example usage:


 MatchboxAPI.addEventListener(new MatchboxEventListener() {
     @Override
     public void onGameStart(GameStartEvent event) {
         getLogger().info("Game started in session: " + event.getSessionName());
         // Handle game start - initialize UI, start timers, etc.
     }
     
     @Override
     public void onPlayerEliminate(PlayerEliminateEvent event) {
         // Handle player elimination - update scores, send messages, etc.
         Player eliminated = event.getPlayer();
         scoreboardManager.updatePlayerScore(eliminated, -10);
         getLogger().info("Player " + eliminated.getName() + " was eliminated");
     }
 });

Important Notes:

  • All event handlers are executed on the main server thread. Avoid long-running operations.
  • Exceptions in event handlers will be caught and logged, but won't stop other listeners.
  • Event objects contain contextual information - use them instead of querying global state.
Since:
0.9.5

  • Method Details

    • onGameStart

      default void onGameStart(@NotNull @NotNull GameStartEvent event)
      Called when a new game starts.
      Parameters:
      event - the game start event containing session information

    • onPhaseChange

      default void onPhaseChange(@NotNull @NotNull PhaseChangeEvent event)
      Called when a game phase changes.
      Parameters:
      event - the phase change event containing old and new phases

    • onPlayerEliminate

      default void onPlayerEliminate(@NotNull @NotNull PlayerEliminateEvent event)
      Called when a player is eliminated from the game.
      Parameters:
      event - the player elimination event containing player and elimination details

    • onPlayerVote

      default void onPlayerVote(@NotNull @NotNull PlayerVoteEvent event)
      Called when a player casts a vote during the voting phase.
      Parameters:
      event - the player vote event containing voter, target, and vote details

    • onAbilityUse

      default void onAbilityUse(@NotNull @NotNull AbilityUseEvent event)
      Called when a player uses a special ability.
      Parameters:
      event - the ability use event containing player, ability type, and usage details

    • onGameEnd

      default void onGameEnd(@NotNull @NotNull GameEndEvent event)
      Called when a game ends (either by win condition or manual termination).
      Parameters:
      event - the game end event containing session, winner, and end reason

    • onPlayerJoin

      default void onPlayerJoin(@NotNull @NotNull PlayerJoinEvent event)
      Called when a player joins a game session.
      Parameters:
      event - the player join event containing player and session information

    • onPlayerLeave

      default void onPlayerLeave(@NotNull @NotNull PlayerLeaveEvent event)
      Called when a player leaves a game session.
      Parameters:
      event - the player leave event containing player, session, and leave reason

    • onSwipe

      default void onSwipe(@NotNull @NotNull SwipeEvent event)
      Called when a swipe action is performed.
      Parameters:
      event - the swipe event containing attacker, target, and swipe details

    • onCure

      default void onCure(@NotNull @NotNull CureEvent event)
      Called when a cure action is performed.
      Parameters:
      event - the cure event containing medic, target, and cure details