Package dev.itsharshxd.zentrix.api.arena

Interface ArenaSourceLease

public interface ArenaSourceLease
A source arena a provider has set aside for Zentrix.

A lease is a promise in both directions. The provider keeps the source registered and does not hand it to anything else — including its own matchmaking — until the lease ends, and Zentrix ends every lease it takes out exactly once: release() when the source turned out not to be needed, consume(String) when a match actually started from it. After consume the provider owns the source again and may clean it up under its ordinary rules, because the runtime world is a copy that no longer depends on it.

A lease survives a restart only as the source arena name Zentrix stored. A provider that keeps its own reservation state across restarts should ask ArenaSourceService.isSourceBusy(String) before reclaiming a source it believes is idle: Zentrix reports a source held by a published custom game as busy.

  • Method Summary

    Modifier and Type
    Method
    Description
    void
    consume(@NotNull String runtimeId)
    Reports that a match started from this source.
    void
    release()
    Gives the source back unused.
    default Optional<ScenarioProfile>
    scenarioProfile()
    The scenario overrides matches created from this source should run under.
    @NotNull String
    sourceArenaName()
    The registered source arena this lease covers.

  • Method Details

    • sourceArenaName

      @NotNull @NotNull String sourceArenaName()
      The registered source arena this lease covers.

    • scenarioProfile

      @NotNull default Optional<ScenarioProfile> scenarioProfile()
      The scenario overrides matches created from this source should run under.

      Read once, when Zentrix takes the lease, and kept for as long as the match created from this source lasts. That is what makes the answer a promise about one match rather than a setting: a provider that changes its mind afterwards changes the next match, and never the one already playing.

      The profile is read ahead of the arena's stored overrides and the global configuration, and nothing in it is written to scenarios.yml. An empty profile — the default — means matches on this source read the server's own scenario configuration, exactly as they would from any other arena.

      Because nothing is written down, a profile lives only as long as the server runs. A source whose lease was taken out before a restart — a published custom game holds one for as long as its schedule lasts — is adopted afterwards without one, and the match it eventually creates reads the ordinary configuration. A provider that needs its overrides to survive that has to store them itself and offer them again on the next lease.

      Since:
      1.6.0

    • release

      void release()
      Gives the source back unused. Calling this more than once has no further effect.

    • consume

      void consume(@NotNull @NotNull String runtimeId)
      Reports that a match started from this source.
      Parameters:
      runtimeId - the runtime game created from it, for the provider's own bookkeeping