Package net.kyori.adventure.audience

Interface Audience

  • All Known Subinterfaces:
    ForwardingAudience, ForwardingAudience.Single
    public interface Audience
    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

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

      • audience

        static @NonNull Audience audience​(@NonNull Audience @NonNull ... 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

        static @NonNull ForwardingAudience audience​(@NonNull 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

        static @NonNull 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​(@NonNull Identified source,
                         @NonNull 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​(@NonNull Identity source,
                         @NonNull 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​(@NonNull Identified source,
                         @NonNull 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​(@NonNull Identity source,
                         @NonNull 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​(@NonNull Identified source,
                         @NonNull ComponentLike message,
                         @NonNull 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​(@NonNull Identity source,
                         @NonNull ComponentLike message,
                         @NonNull 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​(@NonNull Identified source,
                         @NonNull Component message,
                         @NonNull 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​(@NonNull Identity source,
                         @NonNull Component message,
                         @NonNull 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​(@NonNull ComponentLike message)
        Sends a message on the action bar.
        Parameters:
        message - a message
        Since:
        4.0.0
        See Also:
        Component

      • sendActionBar

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

      • sendPlayerListHeader

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

      • sendPlayerListHeaderAndFooter

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

      • showTitle

        default void showTitle​(@NonNull 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​(@NonNull BossBar bar)
        Shows a boss bar.
        Parameters:
        bar - a boss bar
        Since:
        4.0.0
        See Also:
        BossBar

      • hideBossBar

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

      • playSound

        default void playSound​(@NonNull Sound sound)
        Plays a sound.
        Parameters:
        sound - a sound
        Since:
        4.0.0
        See Also:
        Sound

      • playSound

        default void playSound​(@NonNull 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​(@NonNull SoundStop stop)
        Stops a sound, or many sounds.
        Parameters:
        stop - a sound stop
        Since:
        4.0.0
        See Also:
        SoundStop

      • openBook

        default void openBook​(@NonNull 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​(@NonNull 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