Package dev.itsharshxd.zentrix.api.scenario

Interface ScenarioInstance

public interface ScenarioInstance
One scenario running in one match.

Zentrix creates an instance per game, so a scenario's runtime state never leaks between simultaneous matches. Every callback runs on the server main thread.

All methods are optional. Implement only the moments the scenario cares about; the rest do nothing.

Anything a callback registers through its ScenarioContext is released automatically afterwards, so onDeactivate(ScenarioContext, DeactivationReason) only has to undo what the scenario did outside the context.

Exceptions thrown from any callback are caught, logged against the scenario and — for repeated failures — end with the scenario being deactivated for that one match. The match, the other scenarios and every other arena keep running.

Since:
1.6.0

  • Method Details

    • onActivate

      default void onActivate(@NotNull @NotNull ScenarioContext context)
      The scenario has been locked in for this match and may start setting up.

      Called once, before the match leaves the waiting lobby. This is where listeners, overrides and tasks belong.

    • onGameStart

      default void onGameStart(@NotNull @NotNull ScenarioContext context)
      The match has entered the playing state and the arena is live.

    • onWorldPrepared

      default void onWorldPrepared(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull GameWorldType type, @NotNull @NotNull org.bukkit.World world)
      One of the match's worlds has been prepared and had Zentrix's own setup applied to it.

      Raised for the arena as the match goes live and again for every world the match creates later — its Nether copy, its End copy, its deathmatch arena — always after Zentrix reset that world's weather, time and game rules. A scenario that pins a world-level property belongs here rather than in onGameStart(ScenarioContext), because otherwise the preparation of a world would overwrite what the scenario had already applied.

      The same world may be reported more than once; treat the callback as "apply your settings to this world now" rather than as a one-off.

    • onPlayerChangeWorld

      default void onPlayerChangeWorld(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull Optional<GameWorldType> from, @NotNull @NotNull GameWorldType to)
      A player of the match moved between two of the match's worlds.

      Raised for arena-to-Nether, arena-to-End, the returns from either, and the move into the deathmatch arena — every transfer where the destination belongs to this match. Transfers that take a player out of the match entirely are reported through onPlayerLeave(ScenarioContext, Player) instead.

      Parameters:
      from - the world role the player came from, empty when they arrived from outside the match
      to - the world role the player is now in

    • onPhaseChange

      default void onPhaseChange(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull Optional<GamePhase> previous, @NotNull @NotNull GamePhase current)
      The match moved into a new phase.

    • onPlayerJoin

      default void onPlayerJoin(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull org.bukkit.entity.Player player)
      A player joined the match, including a reconnecting one.

    • onPlayerLeave

      default void onPlayerLeave(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull org.bukkit.entity.Player player)
      A player left the match, whether by quitting, dying out or being removed.

    • onDeathmatchStart

      default void onDeathmatchStart(@NotNull @NotNull ScenarioContext context)
      The deathmatch started for this match.

    • onGameEnd

      default void onGameEnd(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull Optional<String> winningTeamId)
      The match ended. Called before onDeactivate(ScenarioContext, DeactivationReason) and only for matches that actually ran.
      Parameters:
      winningTeamId - the winning team, empty when the match ended without one

    • onDeactivate

      default void onDeactivate(@NotNull @NotNull ScenarioContext context, @NotNull @NotNull ScenarioInstance.DeactivationReason reason)
      The scenario is being torn down.

      Everything registered through the context is already being released, so implement this only to undo side effects the scenario created elsewhere. It is always called exactly once for an activated instance, including on cancellation and shutdown.