Package dev.itsharshxd.zentrix.api.scenario

Interface Scenario

public interface Scenario
A gameplay modifier that a match can run.

A scenario is registered once and produces one ScenarioInstance per match it takes part in, which is what keeps its runtime state isolated to a single game and arena.

Third-party scenarios are registered through ScenarioService.register(org.bukkit.plugin.Plugin, Scenario) and are treated exactly like the ones Zentrix ships: they appear in the scenario commands, the management and voting GUIs, the automatic-selection pool, validation and every API lookup, and they get the same metadata, settings, dependencies, conflicts, priorities, per-game state, lifecycle hooks, scheduling and automatic cleanup.

Registration is in-memory only. Nothing about a dynamically registered scenario is written to scenarios.yml until an administrator explicitly configures it, so an addon that is removed again leaves no trace behind.

Example


 public final class NoFallScenario implements Scenario {

     private static final ScenarioDescriptor DESCRIPTOR = ScenarioDescriptor.builder("no-fall")
             .displayName("No Fall")
             .description("Fall damage is disabled.")
             .icon(Material.FEATHER)
             .setting(ScenarioSetting.bool("also-in-deathmatch", true))
             .build();

     @Override public ScenarioDescriptor descriptor() { return DESCRIPTOR; }

     @Override public ScenarioInstance createInstance() {
         return new ScenarioInstance() {
             @Override public void onActivate(ScenarioContext context) {
                 context.override(GameplayHooks.PLAYER_DAMAGE, request ->
                         request.cause().equals("FALL") && context.isParticipant(request.victim())
                                 ? HookOutcome.cancel()
                                 : HookOutcome.pass());
             }
         };
     }
 }

 ZentrixAPI.get().getScenarioService().register(this, new NoFallScenario());
Since:
1.6.0

  • Method Summary

    Modifier and Type
    Method
    Description
    @NotNull ScenarioInstance
    createInstance()
    Creates the runtime instance for one match.
    @NotNull ScenarioDescriptor
    descriptor()
    The scenario's immutable metadata.
    default void
    onRegister()
    The scenario has been added to the registry.
    default void
    onUnregister()
    The scenario has been removed from the registry, whether explicitly or because its plugin was disabled.

  • Method Details

    • descriptor

      @NotNull @NotNull ScenarioDescriptor descriptor()
      The scenario's immutable metadata. Must return the same descriptor every time.

    • createInstance

      @NotNull @NotNull ScenarioInstance createInstance()
      Creates the runtime instance for one match.

      Called once per match the scenario takes part in, just before activation. Return a fresh object every time: sharing one instance between matches would leak state between them.

    • onRegister

      default void onRegister()
      The scenario has been added to the registry.

      Runs on the thread that registered it and is a good place for one-off setup that does not belong to any match. Throwing here aborts the registration.

    • onUnregister

      default void onUnregister()
      The scenario has been removed from the registry, whether explicitly or because its plugin was disabled.

      Matches that were already running the scenario have had their instances deactivated before this is called.