Package net.kyori.adventure.audience

Interface Audience

All Superinterfaces:
Pointered
All Known Subinterfaces:
ForwardingAudience, ForwardingAudience.Single
public interface Audience
extends Pointered
A receiver of Minecraft media.

Audience is designed to be a universal interface for any player, command sender, console, or otherwise who can receive text, titles, boss bars, and other Minecraft media. It is also designed for a group of receivers such as a team, server, world, or permission.

In the past, Minecraft platforms have typically reserved methods such as showTitle for a Player interface. While this is good textbook object-oriented design, it presents two key drawbacks: 1) there is no abstraction for groups of players, such as a Server or a Team and 2) it add boilerplate for handling special cases like console or command senders.

Consider the use-case of sending a message and title to every player on a server, and also sending a message to console. Without an Audience, the code might look like this:

   Server server;
   for (Player player : server.getPlayers()) {
     player.sendMessage(...);
     player.showTitle(...);
   }
   server.getConsole().sendMessage(...);

Now, if Server implemented Audience, its unified interface would allow users to easily send media without if-guarding console or iterating through the list of players:

   Server server;
   server.sendMessage(...); // Sends a message to players and console
   server.showTitle(...); // Shows a title to players, silently ignored by console

When an Audience is unable to perform an operation, such as sending a boss bar to console, it will silently fail, without logging. This requirement allows users to easily send media to a group of Audiences without checking each for compatibility.

While the scope of Audience may be expanded in the future to support new Minecraft media such as the player list, its interface will remain stateless and any new methods will be stubbed by default.

Since:
4.0.0
See Also:
ForwardingAudience

  • Method Details

    • empty

      @NotNull static @NotNull Audience empty()
      Gets an audience that does nothing.
      Returns:
      a do-nothing audience
      Since:
      4.0.0

    • audience

      @NotNull static @NotNull Audience audience​(@NotNull @NotNull Audience @NotNull ... audiences)
      Creates an audience that forwards to many other audiences.
      Parameters:
      audiences - an array of audiences, can be empty
      Returns:
      an audience
      Since:
      4.0.0
      See Also:
      ForwardingAudience

    • audience

      @NotNull static @NotNull ForwardingAudience audience​(@NotNull @NotNull Iterable<? extends Audience> audiences)
      Creates an audience that forwards to many other audiences.

      The underlying Iterable is not copied, therefore any changes made will be reflected in Audience.

      Parameters:
      audiences - an iterable of audiences, can be empty
      Returns:
      an audience
      Since:
      4.0.0
      See Also:
      ForwardingAudience

    • toAudience

      @NotNull static @NotNull Collector<? super Audience,​?,​ForwardingAudience> toAudience()
      Provides a collector to create a forwarding audience from a stream of audiences.

      The audience produced is immutable and can be reused as desired.

      Returns:
      a collector to create a forwarding audience
      Since:
      4.0.0

    • sendMessage

      default void sendMessage​(@NotNull @NotNull ComponentLike message)
      Sends a chat message with a nil identity to this Audience.
      Parameters:
      message - a message
      Since:
      4.1.0
      See Also:
      Component, sendMessage(Identified, ComponentLike), sendMessage(Identity, ComponentLike)

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identified source, @NotNull @NotNull ComponentLike message)
      Sends a chat message from the given Identified to this Audience.
      Parameters:
      source - the source of the message
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identity source, @NotNull @NotNull ComponentLike message)
      Sends a chat message from the entity represented by the given Identity (or the game using Identity.nil()) to this Audience.
      Parameters:
      source - the identity of the source of the message
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Component message)
      Sends a chat message with a nil identity to this Audience.
      Parameters:
      message - a message
      Since:
      4.1.0
      See Also:
      Component, sendMessage(Identified, Component), sendMessage(Identity, Component)

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identified source, @NotNull @NotNull Component message)
      Sends a chat message from the given Identified to this Audience.
      Parameters:
      source - the source of the message
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identity source, @NotNull @NotNull Component message)
      Sends a chat message from the entity represented by the given Identity (or the game using Identity.nil()) to this Audience.
      Parameters:
      source - the identity of the source of the message
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull ComponentLike message, @NotNull @NotNull MessageType type)
      Sends a chat message with a nil identity to this Audience.
      Parameters:
      message - a message
      type - the type
      Since:
      4.1.0
      See Also:
      Component, sendMessage(Identified, ComponentLike, MessageType), sendMessage(Identity, ComponentLike, MessageType)

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identified source, @NotNull @NotNull ComponentLike message, @NotNull @NotNull MessageType type)
      Sends a chat message from the given Identified to this Audience.
      Parameters:
      source - the source of the message
      message - a message
      type - the type
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identity source, @NotNull @NotNull ComponentLike message, @NotNull @NotNull MessageType type)
      Sends a chat message from the entity represented by the given Identity (or the game using Identity.nil()) to this Audience.
      Parameters:
      source - the identity of the source of the message
      message - a message
      type - the type
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Component message, @NotNull @NotNull MessageType type)
      Sends a chat message with a nil identity to this Audience.
      Parameters:
      message - a message
      type - the type
      Since:
      4.1.0
      See Also:
      Component, sendMessage(Identified, Component, MessageType), sendMessage(Identity, Component, MessageType)

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identified source, @NotNull @NotNull Component message, @NotNull @NotNull MessageType type)
      Sends a chat message.
      Parameters:
      source - the source of the message
      message - a message
      type - the type
      Since:
      4.0.0
      See Also:
      Component

    • sendMessage

      default void sendMessage​(@NotNull @NotNull Identity source, @NotNull @NotNull Component message, @NotNull @NotNull MessageType type)
      Sends a chat message.
      Parameters:
      source - the identity of the source of the message
      message - a message
      type - the type
      Since:
      4.0.0
      See Also:
      Component

    • sendActionBar

      default void sendActionBar​(@NotNull @NotNull ComponentLike message)
      Sends a message on the action bar.
      Parameters:
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendActionBar

      default void sendActionBar​(@NotNull @NotNull Component message)
      Sends a message on the action bar.
      Parameters:
      message - a message
      Since:
      4.0.0
      See Also:
      Component

    • sendPlayerListHeader

      default void sendPlayerListHeader​(@NotNull @NotNull ComponentLike header)
      Sends the player list header.

      Depending on the implementation of this Audience, an existing footer may be displayed. If you wish to set both the header and the footer, please use sendPlayerListHeaderAndFooter(ComponentLike, ComponentLike).

      Parameters:
      header - the header
      Since:
      4.3.0

    • sendPlayerListHeader

      default void sendPlayerListHeader​(@NotNull @NotNull Component header)
      Sends the player list header.

      Depending on the implementation of this Audience, an existing footer may be displayed. If you wish to set both the header and the footer, please use sendPlayerListHeaderAndFooter(Component, Component).

      Parameters:
      header - the header
      Since:
      4.3.0

    • sendPlayerListFooter

      default void sendPlayerListFooter​(@NotNull @NotNull ComponentLike footer)
      Sends the player list footer.

      Depending on the implementation of this Audience, an existing footer may be displayed. If you wish to set both the header and the footer, please use sendPlayerListHeaderAndFooter(ComponentLike, ComponentLike).

      Parameters:
      footer - the footer
      Since:
      4.3.0

    • sendPlayerListFooter

      default void sendPlayerListFooter​(@NotNull @NotNull Component footer)
      Sends the player list footer.

      Depending on the implementation of this Audience, an existing footer may be displayed. If you wish to set both the header and the footer, please use sendPlayerListHeaderAndFooter(Component, Component).

      Parameters:
      footer - the footer
      Since:
      4.3.0

    • sendPlayerListHeaderAndFooter

      default void sendPlayerListHeaderAndFooter​(@NotNull @NotNull ComponentLike header, @NotNull @NotNull ComponentLike footer)
      Sends the player list header and footer.
      Parameters:
      header - the header
      footer - the footer
      Since:
      4.3.0

    • sendPlayerListHeaderAndFooter

      default void sendPlayerListHeaderAndFooter​(@NotNull @NotNull Component header, @NotNull @NotNull Component footer)
      Sends the player list header and footer.
      Parameters:
      header - the header
      footer - the footer
      Since:
      4.3.0

    • showTitle

      default void showTitle​(@NotNull @NotNull Title title)
      Shows a title.
      Parameters:
      title - a title
      Since:
      4.0.0
      See Also:
      Title

    • clearTitle

      default void clearTitle()
      Clears the title, if one is being displayed.
      Since:
      4.0.0
      See Also:
      Title

    • resetTitle

      default void resetTitle()
      Resets the title and timings back to their default.
      Since:
      4.0.0
      See Also:
      Title

    • showBossBar

      default void showBossBar​(@NotNull @NotNull BossBar bar)
      Shows a boss bar.
      Parameters:
      bar - a boss bar
      Since:
      4.0.0
      See Also:
      BossBar

    • hideBossBar

      default void hideBossBar​(@NotNull @NotNull BossBar bar)
      Hides a boss bar.
      Parameters:
      bar - a boss bar
      Since:
      4.0.0
      See Also:
      BossBar

    • playSound

      default void playSound​(@NotNull @NotNull Sound sound)
      Plays a sound at the location of the recipient of the sound.

      To play a sound that follows the recipient, use playSound(Sound, Sound.Emitter) with Sound.Emitter.self().

      Parameters:
      sound - a sound
      Since:
      4.0.0
      See Also:
      Sound

    • playSound

      default void playSound​(@NotNull @NotNull Sound sound, double x, double y, double z)
      Plays a sound at a location.
      Parameters:
      sound - a sound
      x - x coordinate
      y - y coordinate
      z - z coordinate
      Since:
      4.0.0
      See Also:
      Sound

    • stopSound

      default void stopSound​(@NotNull @NotNull Sound sound)
      Stops a sound.
      Parameters:
      sound - the sound
      Since:
      4.8.0

    • playSound

      default void playSound​(@NotNull @NotNull Sound sound, @NotNull Sound.Emitter emitter)
      Plays a sound from an emitter, usually an entity.

      Sounds played using this method will follow the emitter unless the sound is a custom sound. In this case the sound will be played at the location of the emitter and will not follow them.

      To play a sound that follows the recipient, use Sound.Emitter.self().

      Note: Due to MC-138832, the volume and pitch may be ignored when using this method.

      Parameters:
      sound - a sound
      emitter - an emitter
      Since:
      4.8.0

    • stopSound

      default void stopSound​(@NotNull @NotNull SoundStop stop)
      Stops a sound, or many sounds.
      Parameters:
      stop - a sound stop
      Since:
      4.0.0
      See Also:
      SoundStop

    • openBook

      default void openBook​(@NotNull Book.Builder book)
      Opens a book.

      When possible, no item should persist after closing the book.

      Parameters:
      book - a book
      Since:
      4.0.0
      See Also:
      Book

    • openBook

      default void openBook​(@NotNull @NotNull Book book)
      Opens a book.

      When possible, no item should persist after closing the book.

      Parameters:
      book - a book
      Since:
      4.0.0
      See Also:
      Book