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:

  • Method Details

    • empty

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

    • audience

      static Audience audience(Audience... 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:

    • audience

      static ForwardingAudience audience(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:

    • toAudience

      static 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

    • filterAudience

      default Audience filterAudience(Predicate<? super Audience> filter)
      Filters this audience.

      The returned Audience may be the same, or a completely different one.

      Container audiences such as ForwardingAudience may or may not have their own identity. If they do, they may test themselves against the provided filter first, and if the test fails return an empty audience skipping any contained children. If they do not, they must not test themselves against the filter, only testing their children.

      Parameters:
      filter - a filter that determines if an audience should be included
      Returns:
      an audience providing a snapshot of all audiences that match the predicate when this method is invoked
      Since:
      4.9.0

    • forEachAudience

      default void forEachAudience(Consumer<? super Audience> action)
      Executes an action against all audiences.

      If you implement Audience and not ForwardingAudience in your own code, and your audience forwards to other audiences, then you must override this method and provide each audience to action.

      If an implementation of Audience has its own identity distinct from its contained children, it may test itself against the provided filter first, and if the test fails return an empty audience skipping any contained children. If it does not, it must not test itself against the filter, only testing its children.

      Parameters:
      action - the action
      Since:
      4.9.0

    • sendMessage

      default void sendMessage(ComponentLike message)
      Sends a system chat message to this Audience.
      Parameters:
      message - a message
      Since:
      4.1.0
      See Also:

    • sendMessage

      default void sendMessage(Component message)
      Sends a system chat message to this Audience.
      Parameters:
      message - a message
      Since:
      4.1.0
      See Also:

    • sendMessage

      default void sendMessage(Component message, ChatType.Bound boundChatType)
      Sends a message to this Audience with the provided bound chat type.
      Parameters:
      message - the component content
      boundChatType - the bound chat type
      Since:
      4.12.0
      Since Minecraft:
      1.19

    • sendMessage

      default void sendMessage(ComponentLike message, ChatType.Bound boundChatType)
      Sends a message to this Audience with the provided bound chat type.
      Parameters:
      message - the component content
      boundChatType - the bound chat type
      Since:
      4.12.0
      Since Minecraft:
      1.19

    • sendMessage

      default void sendMessage(SignedMessage signedMessage, ChatType.Bound boundChatType)
      Sends a signed player message to this Audience with the provided bound chat type.
      Parameters:
      signedMessage - the signed message data
      boundChatType - the bound chat type
      Since:
      4.12.0
      Since Minecraft:
      1.19

    • deleteMessage

      default void deleteMessage(SignedMessage signedMessage)
      Requests deletion of a message with the provided SignedMessage's signature.
      Parameters:
      signedMessage - the message to delete
      Since:
      4.12.0
      See Also:
      Since Minecraft:
      1.19

    • deleteMessage

      default void deleteMessage(SignedMessage.Signature signature)
      Requests deletion of a message with the provided SignedMessage.Signature.
      Parameters:
      signature - the signature
      Since:
      4.12.0
      Since Minecraft:
      1.19

    • sendActionBar

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

    • sendActionBar

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

    • sendPlayerListHeader

      default void sendPlayerListHeader(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(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(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(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(ComponentLike header, ComponentLike footer)
      Sends the player list header and footer.
      Parameters:
      header - the header
      footer - the footer
      Since:
      4.3.0

    • sendPlayerListHeaderAndFooter

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

    • showTitle

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

    • sendTitlePart

      default <T> void sendTitlePart(TitlePart<T> part, T value)
      Shows a part of a title.
      Type Parameters:
      T - the type of the value of the part
      Parameters:
      part - the part
      value - the value
      Since:
      4.9.0

    • clearTitle

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

    • resetTitle

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

    • showBossBar

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

    • hideBossBar

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

    • playSound

      default void playSound(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:

    • playSound

      default void playSound(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:

    • playSound

      default void playSound(Sound sound, 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().

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

    • stopSound

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

    • stopSound

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

    • openBook

      default void openBook(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:

    • openBook

      default void openBook(BookLike book)
      Opens a book.

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

      Parameters:
      book - a book
      Since:
      5.0.0
      See Also:

    • openBook

      default void openBook(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:

    • sendResourcePacks

      default void sendResourcePacks(ResourcePackInfoLike first, ResourcePackInfoLike... others)
      Sends a request to apply resource packs to this audience.

      Multiple resource packs are only supported since 1.20.3. On older versions, all requests behave as if ResourcePackRequest.replace() is set to true.

      Parameters:
      first - the resource pack info
      others - the other pack infos
      Since:
      4.15.0
      See Also:

    • sendResourcePacks

      default void sendResourcePacks(ResourcePackRequestLike request)
      Sends a request to apply resource packs to this audience.

      Multiple resource packs are only supported since 1.20.3. On older versions, all requests behave as if ResourcePackRequest.replace() is set to true.

      Parameters:
      request - the resource pack request
      Since:
      4.15.0
      See Also:

    • sendResourcePacks

      default void sendResourcePacks(ResourcePackRequest request)
      Sends a request to apply resource packs to this audience.

      Multiple resource packs are only supported since 1.20.3. On older versions, all requests behave as if ResourcePackRequest.replace() is set to true.

      Parameters:
      request - the resource pack request
      Since:
      4.15.0
      See Also:

    • removeResourcePacks

      default void removeResourcePacks(ResourcePackRequestLike request)
      Clear resource packs with the IDs used in the provided requests if they are present.
      Parameters:
      request - the request used to originally apply the packs
      Since:
      4.15.0
      Since Minecraft:
      1.20.3

    • removeResourcePacks

      default void removeResourcePacks(ResourcePackRequest request)
      Clear resource packs with the IDs used in the provided requests if they are present.
      Parameters:
      request - the request used to originally apply the packs
      Since:
      4.15.0
      Since Minecraft:
      1.20.3

    • removeResourcePacks

      default void removeResourcePacks(ResourcePackInfoLike request, ResourcePackInfoLike... others)
      Clear resource packs with the IDs used in the provided requests if they are present.
      Parameters:
      request - the first request used to originally apply the pack
      others - requests for other packs that should be removed
      Since:
      4.15.0
      Since Minecraft:
      1.20.3

    • removeResourcePacks

      default void removeResourcePacks(Iterable<UUID> ids)
      Clear resource packs with the provided ids if they are present.
      Parameters:
      ids - the ids of resource packs to remove
      Since:
      4.16.0
      Since Minecraft:
      1.20.3

    • removeResourcePacks

      default void removeResourcePacks(UUID id, UUID... others)
      Clear resource packs with the provided ids if they are present.
      Parameters:
      id - the id
      others - the ids of any additional resource packs
      Since:
      4.15.0
      Since Minecraft:
      1.20.3

    • clearResourcePacks

      default void clearResourcePacks()
      Clear all server-provided resource packs that have been sent to this user.
      Since:
      4.15.0

    • showDialog

      default void showDialog(DialogLike dialog)
      Shows a dialog to this audience.

      This method exists to allow initial native support for dialogs until Adventure has full API to support building and sending dialogs.

      Parameters:
      dialog - the dialog
      Since:
      4.22.0
      Since Minecraft:
      1.21.6

    • closeDialog

      default void closeDialog()
      Closes the dialog that is currently being shown to this audience, if any.

      This will return the user to the previous dialog if one was opened from the current dialog.

      Since:
      4.24.0
      Since Minecraft:
      1.21.6