Package dev.itsharshxd.zentrix.api.scenario

Interface ScenarioContext

public interface ScenarioContext
Everything one scenario may do inside one match.

A context belongs to exactly one scenario in exactly one game. Every scheduled task, event listener, gameplay override, tracked block, entity and dropped item registered through it is owned by that pair and released automatically when the scenario is deactivated, the match ends, the match is cancelled, or the server shuts down. That is what keeps two simultaneous matches — even two running the same scenario — completely independent, and what guarantees the world is handed back the way Zentrix expects it.

The context is not a place to hold long-lived state: use store() for anything the scenario needs to remember for the length of the match. Everything in the store is discarded during cleanup.

All methods are safe to call from the server main thread. Scheduling helpers may be called from any thread.

Since:
1.6.0

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    cancelTask(int taskId)
    Cancels one task started through this context.
    @NotNull ScenarioDescriptor
    descriptor()
    The scenario this context belongs to.
    <R, V> HookOutcome<V>
    dispatch(@NotNull GameplayHook<R,V> hook, R request)
    Asks every scenario active in this match about a decision point, in priority order.
    @NotNull org.bukkit.entity.Entity
    dropItem(@NotNull org.bukkit.Location location, @NotNull org.bukkit.inventory.ItemStack item)
    Drops an item that belongs to this scenario and removes it during cleanup if it is still lying around.
    @NotNull ZentrixGame
    game()
    The match this context belongs to.
    boolean
    isActive()
    Whether the scenario is still active in this match.
    boolean
    isInScope(@Nullable org.bukkit.Location location)
    Whether a location lies in one of the match's worlds.
    boolean
    isInScope(@Nullable org.bukkit.World world)
    Whether a world belongs to this match.
    boolean
    isInScope(@Nullable org.bukkit.entity.Entity entity)
    Whether an entity belongs to one of the match's worlds.
    boolean
    isParticipant(@Nullable org.bukkit.entity.Player player)
    Whether a player is a living participant of this match.
    <R, V> @NotNull HookHandle
    override(@NotNull GameplayHook<R,V> hook, @NotNull GameplayHookHandler<R,V> handler)
    Takes part in one of Zentrix's gameplay decisions for the length of this match.
    org.bukkit.plugin.Plugin
    owner()
    The plugin that registered this scenario.
    default @NotNull Optional<UUID>
    participantId(@Nullable org.bukkit.entity.Player player)
    A player's UUID as this match knows it, for convenience in listeners.
    @NotNull Collection<org.bukkit.entity.Player>
    participants()
    The living participants of this match.
    void
    registerListener(@NotNull org.bukkit.event.Listener listener)
    Registers a Bukkit listener for the length of this match.
    void
    reportFailure(@NotNull String message, @Nullable Throwable cause)
    Reports a recoverable problem against this scenario.
    void
    runTask(@NotNull Runnable task)
    Runs a task on the main thread, skipped if the match ended first.
    int
    runTaskAsync(@NotNull Runnable task)
    Runs a task off the main thread, cancelled if the match ends first.
    int
    runTaskLater(@NotNull Runnable task, long delayTicks)
    Runs a task on the main thread after a delay, cancelled if the match ends first.
    int
    runTaskTimer(@NotNull Runnable task, long delayTicks, long periodTicks)
    Runs a repeating main-thread task, cancelled when the match ends.
    @NotNull String
    runtimeId()
    The runtime game-* identifier of the match.
    @NotNull ScenarioSettings
    settings()
    The settings of this scenario as they apply to this match.
    @NotNull Optional<String>
    sourceArenaName()
    The source arena the match was copied from, when known.
    @NotNull ScenarioStore
    store()
    A scratch space private to this scenario and this match.
    void
    trackBlock(@NotNull org.bukkit.block.Block block)
    Records a block this scenario is about to change so its original state is restored during cleanup.
    void
    trackEntity(@NotNull org.bukkit.entity.Entity entity)
    Records an entity this scenario spawned so it is removed during cleanup.
    void
    unregisterListener(@NotNull org.bukkit.event.Listener listener)
    Unregisters a listener registered through registerListener(Listener).
    @NotNull Optional<org.bukkit.World>
    world(@NotNull GameWorldType type)
    One of the match's worlds, empty when it does not exist for this match.
    @NotNull Collection<org.bukkit.World>
    worlds()
    Every world that belongs to this match: arena, waiting lobby, Nether, End, deathmatch.
    @NotNull Optional<GameWorldType>
    worldType(@Nullable org.bukkit.World world)
    The role a world plays in this match, empty when it belongs to another match or to none.

  • Method Details

    • descriptor

      @NotNull @NotNull ScenarioDescriptor descriptor()
      The scenario this context belongs to.

    • game

      @NotNull @NotNull ZentrixGame game()
      The match this context belongs to.

    • runtimeId

      @NotNull @NotNull String runtimeId()
      The runtime game-* identifier of the match.

    • sourceArenaName

      @NotNull @NotNull Optional<String> sourceArenaName()
      The source arena the match was copied from, when known.

    • owner

      @NotNull org.bukkit.plugin.Plugin owner()
      The plugin that registered this scenario.

    • settings

      @NotNull @NotNull ScenarioSettings settings()
      The settings of this scenario as they apply to this match.

    • isActive

      boolean isActive()
      Whether the scenario is still active in this match.

    • worlds

      @NotNull @NotNull Collection<org.bukkit.World> worlds()
      Every world that belongs to this match: arena, waiting lobby, Nether, End, deathmatch.

    • world

      @NotNull @NotNull Optional<org.bukkit.World> world(@NotNull @NotNull GameWorldType type)
      One of the match's worlds, empty when it does not exist for this match.

    • isInScope

      boolean isInScope(@Nullable @Nullable org.bukkit.World world)
      Whether a world belongs to this match.

    • worldType

      @NotNull @NotNull Optional<GameWorldType> worldType(@Nullable @Nullable org.bukkit.World world)
      The role a world plays in this match, empty when it belongs to another match or to none.

      The inverse of world(GameWorldType), and what a listener uses to tell an arena apart from that match's Nether copy or deathmatch arena without hard-coding world names.

    • isInScope

      boolean isInScope(@Nullable @Nullable org.bukkit.Location location)
      Whether a location lies in one of the match's worlds.

    • isParticipant

      boolean isParticipant(@Nullable @Nullable org.bukkit.entity.Player player)
      Whether a player is a living participant of this match.

      Spectators are excluded, which is the check a listener needs before touching anything a player did.

    • isInScope

      boolean isInScope(@Nullable @Nullable org.bukkit.entity.Entity entity)
      Whether an entity belongs to one of the match's worlds.

    • participants

      @NotNull @NotNull Collection<org.bukkit.entity.Player> participants()
      The living participants of this match.

    • override

      @NotNull <R, V> @NotNull HookHandle override(@NotNull @NotNull GameplayHook<R,V> hook, @NotNull @NotNull GameplayHookHandler<R,V> handler)
      Takes part in one of Zentrix's gameplay decisions for the length of this match.

      Handlers are consulted in descending scenario priority. The returned handle is released automatically during cleanup; releasing it earlier restores Zentrix's own behaviour immediately.

      Parameters:
      hook - the decision point, from GameplayHooks or the scenario's own
      handler - what this scenario decides
      Returns:
      a handle for dropping the override early

    • dispatch

      @NotNull <R, V> HookOutcome<V> dispatch(@NotNull @NotNull GameplayHook<R,V> hook, @NotNull R request)
      Asks every scenario active in this match about a decision point, in priority order.

      This is how a scenario dispatches a hook it defined itself, so mechanics Zentrix never anticipated stay composable between scenarios.

      Parameters:
      hook - the decision point
      request - the request handed to the handlers
      Returns:
      the first non-passing outcome, or pass when nobody took the decision

    • registerListener

      void registerListener(@NotNull @NotNull org.bukkit.event.Listener listener)
      Registers a Bukkit listener for the length of this match.

      The listener is unregistered during cleanup. It still receives server-wide events, so use isParticipant(Player) or isInScope(World) to ignore anything happening outside this match.

    • unregisterListener

      void unregisterListener(@NotNull @NotNull org.bukkit.event.Listener listener)
      Unregisters a listener registered through registerListener(Listener).

    • runTask

      void runTask(@NotNull @NotNull Runnable task)
      Runs a task on the main thread, skipped if the match ended first.

    • runTaskLater

      int runTaskLater(@NotNull @NotNull Runnable task, long delayTicks)
      Runs a task on the main thread after a delay, cancelled if the match ends first.

    • runTaskTimer

      int runTaskTimer(@NotNull @NotNull Runnable task, long delayTicks, long periodTicks)
      Runs a repeating main-thread task, cancelled when the match ends.

    • runTaskAsync

      int runTaskAsync(@NotNull @NotNull Runnable task)
      Runs a task off the main thread, cancelled if the match ends first.

    • cancelTask

      void cancelTask(int taskId)
      Cancels one task started through this context.

    • trackBlock

      void trackBlock(@NotNull @NotNull org.bukkit.block.Block block)
      Records a block this scenario is about to change so its original state is restored during cleanup.

      Call this before changing the block. Tracking the same block twice keeps the first snapshot, so the block always returns to what the arena template had.

    • trackEntity

      void trackEntity(@NotNull @NotNull org.bukkit.entity.Entity entity)
      Records an entity this scenario spawned so it is removed during cleanup.

    • dropItem

      @NotNull @NotNull org.bukkit.entity.Entity dropItem(@NotNull @NotNull org.bukkit.Location location, @NotNull @NotNull org.bukkit.inventory.ItemStack item)
      Drops an item that belongs to this scenario and removes it during cleanup if it is still lying around.

    • store

      @NotNull @NotNull ScenarioStore store()
      A scratch space private to this scenario and this match.

    • reportFailure

      void reportFailure(@NotNull @NotNull String message, @Nullable @Nullable Throwable cause)
      Reports a recoverable problem against this scenario.

      The message is logged with the scenario's ID. Repeated failures may lead Zentrix to deactivate the scenario for this match so the rest of the game keeps running.

    • participantId

      @NotNull default @NotNull Optional<UUID> participantId(@Nullable @Nullable org.bukkit.entity.Player player)
      A player's UUID as this match knows it, for convenience in listeners.