Interface PlayersApi

public interface PlayersApi
Looks up Plex players and manages their saved custom tags.

  • Method Details

    • player

      CompletableFuture<Optional<PlexPlayerView>> player(UUID uuid)
      Looks up a player by UUID.
      Parameters:
      uuid - player UUID
      Returns:
      future containing the player view, if known

    • byName

      CompletableFuture<Optional<PlexPlayerView>> byName(String name)
      Looks up a player by exact, case-insensitive name.
      Parameters:
      name - player name
      Returns:
      future containing the player view, if known

    • resolveCommandPlayer

      CompletableFuture<Optional<PlexPlayerView>> resolveCommandPlayer(String name)
      Resolves an exact name first, then a unique online name prefix, ignoring case. Callers that accept UUID input must resolve it with player(UUID) first. The future fails with AmbiguousPlayerException when multiple online names match. Callbacks can run on a database thread.
      Parameters:
      name - command player name
      Returns:
      future containing the player view, if known

    • setTag

      CompletableFuture<Void> setTag(UUID uuid, net.kyori.adventure.text.Component tag)
      Saves a player's custom tag for chat and the tab list.

      Works for known online and offline players. Applies Plex's visual formatting rules and configured chat.max-tag-length. This does not set a rank prefix or an additive PlayerPrefixEvent prefix. The caller must enforce its own permissions.

      Supports text, sprites, and player heads. Removes click and hover actions, insertion text, obfuscated formatting, and right-to-left text. Rejects dynamic component types such as translations, scores, and selectors.

      The future completes after persistence and the local cached tag update. It fails for an unknown UUID, an invalid tag, or a storage failure. An overlong tag fails with TagTooLongException. No player record is created. Callbacks may run on a database thread; do not block a player or region thread waiting for completion.

      Parameters:
      uuid - player UUID
      tag - custom tag component
      Returns:
      completion of the saved tag change

    • clearTag

      CompletableFuture<Void> clearTag(UUID uuid)
      Removes a known player's saved custom tag from chat and the tab list.

      Uses the same persistence and completion contract as setTag(UUID, Component). Rank fallback and additive PlayerPrefixEvent prefixes remain unchanged.

      Parameters:
      uuid - player UUID
      Returns:
      completion of the saved tag removal

    • onlineNames

      List<String> onlineNames()
      Returns the names of online players.
      Returns:
      names of online players

    • moduleData

      PlayerModuleData moduleData(PlexModule module, UUID playerUuid)
      Returns module-scoped data storage for a player.
      Parameters:
      module - module requesting player data
      playerUuid - player UUID
      Returns:
      module-scoped player data storage