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 Detail

      • 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 java.lang.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 java.util.stream.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

        @NotNull
default @NotNull Audience filterAudience​(@NotNull
                                         @NotNull java.util.function.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​(@NotNull
                             @NotNull java.util.function.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

        @Deprecated
default void sendMessage​(@NotNull
                         @NotNull Identity source,
                         @NotNull
                         @NotNull ComponentLike message)
        Deprecated.
        since 4.12.0, the client errors on and can reject identified messages without SignedMessage data, this may be unsupported in the future, use sendMessage(SignedMessage, ChatType.Bound) instead
        Sends an unsigned player chat message from the entity represented by the given Identity to this Audience with the system chat type.
        Parameters:
        source - the identity of the source of the message
        message - a message
        Since:
        4.0.0
        See Also:
        Component

      • sendMessage

        @Deprecated
default void sendMessage​(@NotNull
                         @NotNull Identified source,
                         @NotNull
                         @NotNull Component message)
        Deprecated.
        since 4.12.0, the client errors on receiving and can reject identified messages without SignedMessage data, this may be unsupported in the future, use sendMessage(SignedMessage, ChatType.Bound) instead
        Sends an unsigned player chat message from the given Identified to this Audience with the system chat type.
        Parameters:
        source - the source of the message
        message - a message
        Since:
        4.0.0
        See Also:
        Component

      • sendMessage

        @Deprecated
default void sendMessage​(@NotNull
                         @NotNull Identity source,
                         @NotNull
                         @NotNull Component message)
        Deprecated.
        since 4.12.0, the client errors on receiving and can reject identified messages without SignedMessage data, this may be unsupported in the future, use sendMessage(SignedMessage, ChatType.Bound) instead
        Sends an unsigned player chat message from the entity represented by the given Identity to this Audience with the system chat type.
        Parameters:
        source - the identity of the source of the message
        message - a message
        Since:
        4.0.0
        See Also:
        Component

      • sendMessage

        @ScheduledForRemoval(inVersion="5.0.0")
@Deprecated
default void sendMessage​(@NotNull
                         @NotNull Identity source,
                         @NotNull
                         @NotNull ComponentLike message,
                         @NotNull
                         @NotNull MessageType type)
        Deprecated.
        for removal since 4.12.0, MessageType is deprecated for removal and the client errors on receiving and can reject identified messages without SignedMessage data, use sendMessage(SignedMessage, ChatType.Bound) instead
        Sends an unsigned player chat message from the entity represented by the given Identity 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

        @ScheduledForRemoval(inVersion="5.0.0")
@Deprecated
default void sendMessage​(@NotNull
                         @NotNull Identity source,
                         @NotNull
                         @NotNull Component message,
                         @NotNull
                         @NotNull MessageType type)
        Deprecated.
        for removal since 4.12.0, MessageType is deprecated for removal and the client errors on receiving and can reject identified messages without SignedMessage data, use sendMessage(SignedMessage, ChatType.Bound) instead
        Sends a player chat message from the entity represented by the given Identity to this Audience with the ChatType corresponding to the provided MessageType.
        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 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​(@NotNull
                         @NotNull ComponentLike message,
                         @NotNull 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​(@NotNull
                         @NotNull SignedMessage signedMessage,
                         @NotNull 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​(@NotNull
                           @NotNull 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:
        SignedMessage.canDelete()
        Since Minecraft:
        1.19

      • deleteMessage

        default void deleteMessage​(@NotNull 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​(@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

      • sendTitlePart

        default <T> void sendTitlePart​(@NotNull
                               @NotNull TitlePart<T> part,
                               @NotNull
                               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
        Throws:
        java.lang.IllegalArgumentException - if a title part that is not in TitlePart is used
        Since:
        4.9.0

      • 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,
                       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

      • 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 Sound sound)
        Stops a sound.
        Parameters:
        sound - the sound
        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