Interface NexoriMinigameApi

public interface NexoriMinigameApi
Public Nexori minigame integration surface intended for other mods.

Third-party minigames compile against this API and call it at runtime through the installed Nexori plugin. The API exposes lifecycle callbacks, public match snapshots, player state operations, local AFK detection controls, result requirements, final result submission, and return-to-lobby commands.

  • Method Details

    • registerMatchLifecycleListener

      @Nonnull NexoriListenerRegistration registerMatchLifecycleListener(@Nonnull String rulesEngineId, @Nonnull NexoriMatchLifecycleListener listener)
      Registers a listener for Nexori match lifecycle callbacks for one rules engine id.

      The listener receives only callbacks for matches owned by the supplied rules engine id. Close the returned registration during mod shutdown or adapter cleanup.

      Parameters:
      rulesEngineId - rules engine id owned by the caller.
      listener - callback object.
      Returns:
      registration handle used to unregister the listener.

    • registerAfkActivityListener

      @Nonnull default NexoriListenerRegistration registerAfkActivityListener(@Nonnull String rulesEngineId, @Nonnull NexoriAfkActivityListener listener)
      Registers a listener for Nexori AFK activity callbacks for one rules engine id.
      Parameters:
      rulesEngineId - rules engine id owned by the caller.
      listener - callback object for local AFK transitions.
      Returns:
      registration handle used to unregister the listener.

    • setMatchAfkDetectionPolicy

      @Nonnull default NexoriSetAfkDetectionPolicyResult setMatchAfkDetectionPolicy(@Nonnull NexoriSetMatchAfkDetectionPolicyRequest request)
      Overrides the AFK detection policy for one active match runtime without changing persistent arena config.
      Parameters:
      request - match policy override request.
      Returns:
      result describing whether the override was stored.

    • clearMatchAfkDetectionPolicy

      @Nonnull default NexoriSetAfkDetectionPolicyResult clearMatchAfkDetectionPolicy(@Nonnull String matchId)
      Clears the AFK detection policy override for one active match runtime.
      Parameters:
      matchId - Nexori local match id.
      Returns:
      result describing whether the override was cleared.

    • setPlayerAfkDetectionPolicy

      @Nonnull default NexoriSetAfkDetectionPolicyResult setPlayerAfkDetectionPolicy(@Nonnull NexoriSetPlayerAfkDetectionPolicyRequest request)
      Overrides the AFK detection policy for one player inside one active match runtime.
      Parameters:
      request - player policy override request.
      Returns:
      result describing whether the override was stored.

    • clearPlayerAfkDetectionPolicy

      @Nonnull default NexoriSetAfkDetectionPolicyResult clearPlayerAfkDetectionPolicy(@Nonnull String matchId, @Nonnull UUID playerUuid)
      Clears the AFK detection policy override for one player inside one active match runtime.
      Parameters:
      matchId - Nexori local match id.
      playerUuid - player whose override should be cleared.
      Returns:
      result describing whether the override was cleared.

    • setPlayerAfk

      @Nonnull default NexoriSetPlayerAfkResult setPlayerAfk(@Nonnull NexoriSetPlayerAfkRequest request)
      Sets or clears the AFK state of one player inside one active match.

      Nexori maintains a single public AFK state per player. Calling with afk=true marks the player as AFK; calling with afk=false marks the player as active and resets the idle timer so the built-in automatic detector does not re-trigger immediately.

      If Nexori's built-in AFK detection policy is still enabled for the match, player input and inventory activity can change this same AFK state normally. Minigames that want to own AFK detection completely should first disable the built-in policy via setMatchAfkDetectionPolicy(NexoriSetMatchAfkDetectionPolicyRequest) or setPlayerAfkDetectionPolicy(NexoriSetPlayerAfkDetectionPolicyRequest), then use this method to report AFK state from their own game logic.

      Returns NexoriSetPlayerAfkStatus.UNCHANGED and dispatches no callback if the player was already in the requested state.

    • findActiveMatchId

      @Nonnull Optional<String> findActiveMatchId(@Nonnull UUID playerUuid)
      Finds the currently active Nexori match id for one player UUID.
      Parameters:
      playerUuid - player to look up.
      Returns:
      active match id, or empty when the player is not in a Nexori active match.

    • findActivePlayerUuid

      @Nonnull Optional<UUID> findActivePlayerUuid(@Nonnull String matchId, @Nonnull String playerToken)
      Finds an active player in one match by UUID string or by current username.
      Parameters:
      matchId - Nexori local match id.
      playerToken - player UUID string or current username.
      Returns:
      matching active player UUID, or empty when no active player matches.

    • findActiveMatchInfo

      @Nonnull Optional<NexoriActiveMatchInfo> findActiveMatchInfo(@Nonnull String matchId)
      Returns the public runtime snapshot for one active match.
      Parameters:
      matchId - Nexori local match id.
      Returns:
      public active match snapshot, or empty when the match is missing.

    • findRulesEngineId

      @Nonnull Optional<String> findRulesEngineId(@Nonnull String matchId)
      Returns the rules engine id that should control one active manual/custom match.
      Parameters:
      matchId - Nexori local match id.
      Returns:
      controlling rules engine id, or empty when unavailable.

    • setPlayerOutcome

      @Nonnull NexoriSetPlayerOutcomeResult setPlayerOutcome(@Nonnull String matchId, @Nonnull UUID playerUuid, @Nonnull NexoriMatchResultPlayerOutcome outcome, @Nonnull String reason)
      Stores or replaces one player's accumulated outcome inside the active match runtime.

      Call this before submitting the final result. All players from findMatchResultRequirements(String) requiredPlayerUuids must have outcomes before local match completion can be accepted.

      Parameters:
      matchId - Nexori local match id.
      playerUuid - player receiving the outcome.
      outcome - final outcome to store for the player.
      reason - short public reason for diagnostics.
      Returns:
      result describing whether the outcome was stored.

    • setPlayerSpectator

      @Nonnull NexoriSetPlayerSpectatorResult setPlayerSpectator(@Nonnull String matchId, @Nonnull UUID playerUuid, boolean spectator, @Nonnull String reason)
      Stores logical spectator state for one player inside the active match runtime.
      Parameters:
      matchId - Nexori local match id.
      playerUuid - player whose spectator state should change.
      spectator - whether the player should be treated as a spectator.
      reason - short public reason for diagnostics.
      Returns:
      result describing whether the spectator state was stored.

    • setPlayerSpectator

      @Nonnull default NexoriSetPlayerSpectatorResult setPlayerSpectator(@Nonnull String matchId, @Nonnull UUID playerUuid, boolean spectator, @Nonnull String reason, String spectatorModelId)
      Stores logical spectator state and optionally applies a temporary spectator model while the player is online. Blank or unknown model ids do not change the logical spectator outcome.
      Parameters:
      matchId - Nexori local match id.
      playerUuid - player whose spectator state should change.
      spectator - whether the player should be treated as a spectator.
      reason - short public reason for diagnostics.
      spectatorModelId - optional runtime model id to apply while the player is online.
      Returns:
      result describing whether the spectator state was stored.

    • returnPlayerToLobby

      @Nonnull NexoriReturnPlayerResult returnPlayerToLobby(@Nonnull String matchId, @Nonnull UUID playerUuid, int delaySeconds, @Nonnull String reason)
      Schedules one player for Nexori's return-to-lobby flow without changing their outcome.
      Parameters:
      matchId - Nexori local match id.
      playerUuid - player to return.
      delaySeconds - delay before return; implementations validate the supported range.
      reason - short public reason for diagnostics.
      Returns:
      result describing whether the return was scheduled.

    • findMatchResultRequirements

      @Nonnull Optional<NexoriMatchResultRequirements> findMatchResultRequirements(@Nonnull String matchId)
      Returns the complete player set a rules mod must include when submitting a match result.

      NexoriMatchResultRequirements.requiredPlayerUuids() is the official result requirement set for the match. Use it as the source of truth for final outcomes.

      Parameters:
      matchId - Nexori local match id.
      Returns:
      result requirements, or empty when the match is missing.

    • submitFinalMatchResult

      @Nonnull NexoriSubmitFinalMatchResultResult submitFinalMatchResult(@Nonnull NexoriSubmitFinalMatchResultRequest request)
      Completes one match using accumulated player outcomes and optionally queues a backend result report when configured.

      matchStatus in the returned result describes local acceptance by Nexori. backendReportStatus describes only backend result transport.

      Parameters:
      request - final result request.
      Returns:
      local completion and backend reporting status.

    • closeMatchAdmission

      @Nonnull NexoriCloseMatchAdmissionResult closeMatchAdmission(@Nonnull NexoriCloseMatchAdmissionRequest request)
      Explicitly closes backend admission reporting for one active backend-driven match.
      Parameters:
      request - close admission request.
      Returns:
      result describing whether admission changed locally.

    • findMatchPlacementState

      @Nonnull Optional<NexoriMatchPlacementState> findMatchPlacementState(@Nonnull String matchId)
      Returns the state of Nexori's initial player placement phase for one active match.
      Parameters:
      matchId - Nexori local match id.
      Returns:
      placement/start gate state, or empty when the match is missing.

    • findMatchResolutionTriggerId

      @Nonnull @Deprecated(forRemoval=true) Optional<String> findMatchResolutionTriggerId(@Nonnull String matchId)
      Deprecated, for removal: This API element is subject to removal in a future version.
      Legacy field kept only for compatibility.

      Nexori no longer supports built-in match resolution triggers. Active matches return the legacy value "none" only for older mods that treated it as manual/external resolution. Use rulesEngineId from match info/lifecycle events to identify the external minigame/rules engine. External minigames should resolve matches through the public API. This member will be removed in a future API cleanup.

      Parameters:
      matchId - Nexori local match id.
      Returns:
      legacy resolution trigger id, normally "none", or empty when unavailable.