Package dev.itsharshxd.zentrix.api.scenario

Interface ScenarioService

public interface ScenarioService
Registration, configuration, selection and voting for scenarios.

Registration is in-memory. A scenario registered here is immediately visible everywhere a scenario can appear — /zx scenarioes, the management GUIs, voting pools, automatic selection, validation and every lookup on this service — but nothing about it is written to scenarios.yml until an administrator configures it through the GUI or through setEnabled(String, boolean) / setGlobalSetting(String, String, Object).

Zentrix unregisters every scenario a plugin owns when that plugin is disabled. Matches running such a scenario have its instance deactivated with ScenarioInstance.DeactivationReason.PROVIDER_DISABLED and everything it registered released; the match itself carries on without it.

Since:
1.6.0

  • Method Details

    • register

      @NotNull @NotNull ScenarioRegistration register(@NotNull @NotNull org.bukkit.plugin.Plugin owner, @NotNull @NotNull Scenario scenario)
      Adds a scenario to the runtime registry.
      Parameters:
      owner - the plugin providing the scenario; its shutdown removes the scenario again
      scenario - the scenario
      Returns:
      the registration handle
      Throws:
      IllegalArgumentException - if the ID is already taken by a different provider or the descriptor is invalid

    • unregister

      boolean unregister(@NotNull @NotNull String scenarioId)
      Removes a scenario from the registry.
      Returns:
      true when a scenario with this ID was removed

    • unregisterAll

      int unregisterAll(@NotNull @NotNull org.bukkit.plugin.Plugin owner)
      Removes every scenario a plugin registered.

    • isRegistered

      boolean isRegistered(@NotNull @NotNull String scenarioId)
      Whether a scenario with this ID is registered.

    • getRegistrations

      @NotNull @NotNull Collection<ScenarioRegistration> getRegistrations()
      Every registered scenario, ordered by descending priority then ID.

    • getRegistration

      @NotNull @NotNull Optional<ScenarioRegistration> getRegistration(@NotNull @NotNull String scenarioId)
      One registration by ID.

    • getDescriptor

      @NotNull @NotNull Optional<ScenarioDescriptor> getDescriptor(@NotNull @NotNull String scenarioId)
      One scenario's metadata by ID.

    • getRegistrations

      @NotNull @NotNull Collection<ScenarioRegistration> getRegistrations(@NotNull @NotNull org.bukkit.plugin.Plugin owner)
      Every scenario a given plugin registered.

    • getByTag

      @NotNull @NotNull Collection<ScenarioRegistration> getByTag(@NotNull @NotNull String tag)
      Every scenario carrying a tag.

    • getAnnouncement

      @NotNull @NotNull List<String> getAnnouncement(@NotNull @NotNull String scenarioId)
      The start announcement a scenario would be introduced with.

      Resolved exactly as Zentrix resolves it when a match starts: the locale entry written for this scenario, then the lines the scenario declared itself, then the locale's shared fallback layout. Lines still carry & colour codes and <center> tags, so an addon showing them elsewhere gets the same wording players hear.

      Returns:
      the raw lines, empty when the scenario is unknown or announces nothing

    • getAnnouncementDelaySeconds

      int getAnnouncementDelaySeconds()
      How long Zentrix waits between two scenario announcements, in seconds.

    • getByCapability

      @NotNull @NotNull Collection<ScenarioRegistration> getByCapability(@NotNull @NotNull ScenarioCapability capability)
      Every registered scenario that declares it takes charge of a capability.

      Useful for an addon that wants to know what else on this server touches the same gameplay area before deciding how to behave.

    • getConflicts

      @NotNull Set<String> getConflicts(@NotNull @NotNull String scenarioId)
      Every registered scenario that cannot run alongside this one right now.

      Combines the conflicts both sides declared by ID with the ones derived from ScenarioCapability, so the answer reflects what validate(Collection) would actually reject. It changes as scenarios are registered and unregistered.

      Returns:
      the conflicting scenario IDs, empty when the scenario is unknown or conflicts with nothing

    • isEnabled

      boolean isEnabled(@NotNull @NotNull String scenarioId)
      Whether a scenario is switched on and its required plugins are present.

    • setEnabled

      @NotNull @NotNull CompletableFuture<Boolean> setEnabled(@NotNull @NotNull String scenarioId, boolean enabled)
      Switches a scenario on or off and persists the choice.

      This is an explicit administrator action, so it does write the scenario's section to scenarios.yml even for a dynamically registered scenario.

      Returns:
      a future completing with true once the change is stored

    • getGlobalSetting

      @NotNull @NotNull Optional<Object> getGlobalSetting(@NotNull @NotNull String scenarioId, @NotNull @NotNull String key)
      The globally configured value of one setting, before any arena or lobby override.

    • setGlobalSetting

      @NotNull @NotNull CompletableFuture<Boolean> setGlobalSetting(@NotNull @NotNull String scenarioId, @NotNull @NotNull String key, @NotNull @NotNull Object value)
      Stores a global setting value and persists it.
      Returns:
      a future completing with true once the value validated and was stored

    • clearGlobalSetting

      @NotNull @NotNull CompletableFuture<Boolean> clearGlobalSetting(@NotNull @NotNull String scenarioId, @NotNull @NotNull String key)
      Removes a stored global value so the scenario's own default applies again.

    • setArenaSetting

      @NotNull @NotNull CompletableFuture<Boolean> setArenaSetting(@NotNull @NotNull String sourceArenaName, @NotNull @NotNull String scenarioId, @NotNull @NotNull String key, @NotNull @NotNull Object value)
      Stores an arena-level override.
      Parameters:
      sourceArenaName - the template arena, not a game-* runtime ID

    • clearArenaSetting

      @NotNull @NotNull CompletableFuture<Boolean> clearArenaSetting(@NotNull @NotNull String sourceArenaName, @NotNull @NotNull String scenarioId, @NotNull @NotNull String key)
      Removes an arena-level override.

    • setLobbyOverride

      boolean setLobbyOverride(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull String scenarioId, @NotNull @NotNull String key, @NotNull @NotNull Object value)
      Applies a temporary override to one match, ahead of its arena and the global configuration.

      Overrides only take effect while the match is still in its lobby; once the selection is locked, the settings snapshot the match runs on no longer changes. Nothing is persisted.

      Returns:
      true when the override was applied

    • clearLobbyOverrides

      void clearLobbyOverrides(@NotNull @NotNull ZentrixGame game)
      Drops every temporary override a match collected.

    • getSelectionMode

      @NotNull @NotNull ScenarioSelectionMode getSelectionMode(@NotNull @NotNull ZentrixGame game)
      How a match decides its scenarios, resolved through the override chain.

    • getGlobalSelectionMode

      @NotNull @NotNull ScenarioSelectionMode getGlobalSelectionMode()
      The globally configured selection mode.

    • setGlobalSelectionMode

      @NotNull @NotNull CompletableFuture<Boolean> setGlobalSelectionMode(@NotNull @NotNull ScenarioSelectionMode mode)
      Sets and persists the global selection mode.

    • getGlobalProfile

      @NotNull @NotNull ScenarioProfile getGlobalProfile()
      Zentrix's own scenario configuration, in the shape of a ScenarioProfile.

      Every value is the resolved one, so a key nobody configured appears as the value that would actually apply rather than being absent. That makes this the answer to "what happens if I override nothing", which is what an addon offering overrides of its own needs in order to show what it is overriding.

      Covers the selection mode, the administrator set, the automatic and voting rules, and, for every registered scenario, whether it is switched on, which game types it is kept out of, and the settings that have a configured value. A scenario setting left at the scenario's own default is not listed: ScenarioDescriptor.settings() already carries that default.

      This is a read of the configuration as it stands, not a live view. Nothing about the returned profile is attached to anything.

      Since:
      1.6.0

    • getSelectablePool

      @NotNull @NotNull Collection<ScenarioDescriptor> getSelectablePool()
      The scenarios currently registered, enabled, and usable in a selection.

    • validate

      @NotNull @NotNull ScenarioValidation validate(@NotNull @NotNull Collection<String> scenarioIds)
      Checks a combination without applying it: resolves dependencies, rejects conflicts and drops scenarios whose plugins are missing.

    • getSelection

      @NotNull @NotNull Optional<ScenarioSelection> getSelection(@NotNull @NotNull ZentrixGame game)
      A match's selection, empty until it has one.

    • getActiveScenarios

      @NotNull @NotNull List<ScenarioDescriptor> getActiveScenarios(@NotNull @NotNull ZentrixGame game)
      The scenarios active in a match right now, in activation order.

    • isActive

      boolean isActive(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull String scenarioId)
      Whether one scenario is active in a match.

    • getSettings

      @NotNull @NotNull Optional<ScenarioSettings> getSettings(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull String scenarioId)
      A scenario's resolved settings for a match, empty when it is not active there.

    • setSelection

      @NotNull @NotNull ScenarioValidation setSelection(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull Collection<String> scenarioIds)
      Replaces a match's selection before it starts.

      Rejected once the match locked its scenarios in, so a running match's rules cannot be swapped underneath its players, and for a match whose selection mode is ScenarioSelectionMode.DISABLED, which runs no scenario at all.

      Returns:
      the validation of the requested set; check ScenarioValidation.valid()

    • deactivate

      boolean deactivate(@NotNull @NotNull ZentrixGame game, @NotNull @NotNull String scenarioId)
      Deactivates one scenario in a running match, releasing everything it owns there.

      The rest of the match is untouched. This is the same path Zentrix uses to isolate a scenario that keeps failing.

    • getVote

      @NotNull @NotNull Optional<ScenarioVoteSnapshot> getVote(@NotNull @NotNull ZentrixGame game)
      A match's vote as it stands, empty when the match never voted.

    • isVotingOpen

      boolean isVotingOpen(@NotNull @NotNull ZentrixGame game)
      Whether a match is currently accepting votes.

    • vote

      @NotNull @NotNull ScenarioVoteResult vote(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String scenarioId)
      Casts or, when allow-changes is on and the vote already exists, withdraws a vote.

    • withdrawVote

      @NotNull @NotNull ScenarioVoteResult withdrawVote(@NotNull @NotNull org.bukkit.entity.Player player, @NotNull @NotNull String scenarioId)
      Takes back one of a player's votes.

    • forceResolveVote

      @NotNull @NotNull Optional<ScenarioSelection> forceResolveVote(@NotNull @NotNull ZentrixGame game)
      Closes a running vote immediately and locks its winners in.

      This is the administrator's escape hatch from a lobby that would otherwise wait for the timer. The configured tie and no-vote rules still apply, so the result is always a valid set.

      Returns:
      the resulting selection, empty when the match was not voting

    • openVoteMenu

      boolean openVoteMenu(@NotNull @NotNull org.bukkit.entity.Player player)
      Opens the scenario voting menu for a player, if their match is voting.

    • getFailureCounts

      @NotNull @NotNull Map<String,Integer> getFailureCounts(@NotNull @NotNull ZentrixGame game)
      How often each scenario failed in a match, keyed by scenario ID.

      Useful for spotting a misbehaving addon scenario; Zentrix isolates one on its own once it exceeds the configured failure limit.