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 aPlayer
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 aServer
or aTeam
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
implementedAudience
, 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 ofAudience
s 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 Summary
All Methods Static Methods Instance Methods Default Methods Modifier and Type Method Description static @NonNull ForwardingAudience
audience(@NonNull Iterable<? extends Audience> audiences)
Creates an audience that forwards to many other audiences.static @NonNull Audience
audience(@NonNull Audience @NonNull ... audiences)
Creates an audience that forwards to many other audiences.default void
clearTitle()
Clears the title, if one is being displayed.static @NonNull Audience
empty()
Gets an audience that does nothing.default void
hideBossBar(@NonNull BossBar bar)
Hides a boss bar.default void
openBook(@NonNull Book book)
Opens a book.default void
openBook(@NonNull Book.Builder book)
Opens a book.default void
playSound(@NonNull Sound sound)
Plays a sound.default void
playSound(@NonNull Sound sound, double x, double y, double z)
Plays a sound at a location.default void
resetTitle()
Resets the title and timings back to their default.default void
sendActionBar(@NonNull Component message)
Sends a message on the action bar.default void
sendActionBar(@NonNull ComponentLike message)
Sends a message on the action bar.default void
sendMessage(@NonNull Identified source, @NonNull Component message)
Sends a chat message from the givenIdentified
to thisAudience
.default void
sendMessage(@NonNull Identified source, @NonNull ComponentLike message)
Sends a chat message from the givenIdentified
to thisAudience
.default void
sendMessage(@NonNull Identified source, @NonNull ComponentLike message, @NonNull MessageType type)
Sends a chat message from the givenIdentified
to thisAudience
.default void
sendMessage(@NonNull Identified source, @NonNull Component message, @NonNull MessageType type)
Sends a chat message.default void
sendMessage(@NonNull Identity source, @NonNull Component message)
Sends a chat message from the entity represented by the givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.default void
sendMessage(@NonNull Identity source, @NonNull ComponentLike message)
Sends a chat message from the entity represented by the givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.default void
sendMessage(@NonNull Identity source, @NonNull ComponentLike message, @NonNull MessageType type)
Sends a chat message from the entity represented by the givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.default void
sendMessage(@NonNull Identity source, @NonNull Component message, @NonNull MessageType type)
Sends a chat message.default void
sendMessage(@NonNull Component message)
default void
sendMessage(@NonNull ComponentLike message)
default void
sendMessage(@NonNull ComponentLike message, @NonNull MessageType type)
default void
sendMessage(@NonNull Component message, @NonNull MessageType type)
default void
sendPlayerListFooter(@NonNull Component footer)
Sends the player list footer.default void
sendPlayerListFooter(@NonNull ComponentLike footer)
Sends the player list footer.default void
sendPlayerListHeader(@NonNull Component header)
Sends the player list header.default void
sendPlayerListHeader(@NonNull ComponentLike header)
Sends the player list header.default void
sendPlayerListHeaderAndFooter(@NonNull ComponentLike header, @NonNull ComponentLike footer)
Sends the player list header and footer.default void
sendPlayerListHeaderAndFooter(@NonNull Component header, @NonNull Component footer)
Sends the player list header and footer.default void
showBossBar(@NonNull BossBar bar)
Shows a boss bar.default void
showTitle(@NonNull Title title)
Shows a title.default void
stopSound(@NonNull SoundStop stop)
Stops a sound, or many sounds.static @NonNull Collector<? super Audience,?,ForwardingAudience>
toAudience()
Provides a collector to create a forwarding audience from a stream of audiences.
-
-
-
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 inAudience
.- 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 ComponentLike message)
- Parameters:
message
- a message- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, ComponentLike)
,sendMessage(Identity, ComponentLike)
-
sendMessage
default void sendMessage(@NonNull Identified source, @NonNull ComponentLike message)
Sends a chat message from the givenIdentified
to thisAudience
.- Parameters:
source
- the source of the messagemessage
- 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 givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.- Parameters:
source
- the identity of the source of the messagemessage
- a message- Since:
- 4.0.0
- See Also:
Component
-
sendMessage
default void sendMessage(@NonNull Component message)
- Parameters:
message
- a message- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, Component)
,sendMessage(Identity, Component)
-
sendMessage
default void sendMessage(@NonNull Identified source, @NonNull Component message)
Sends a chat message from the givenIdentified
to thisAudience
.- Parameters:
source
- the source of the messagemessage
- 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 givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.- Parameters:
source
- the identity of the source of the messagemessage
- a message- Since:
- 4.0.0
- See Also:
Component
-
sendMessage
default void sendMessage(@NonNull ComponentLike message, @NonNull MessageType type)
- Parameters:
message
- a messagetype
- the type- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, ComponentLike, MessageType)
,sendMessage(Identity, ComponentLike, MessageType)
-
sendMessage
default void sendMessage(@NonNull Identified source, @NonNull ComponentLike message, @NonNull MessageType type)
Sends a chat message from the givenIdentified
to thisAudience
.- Parameters:
source
- the source of the messagemessage
- a messagetype
- 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 givenIdentity
(or the game usingIdentity.nil()
) to thisAudience
.- Parameters:
source
- the identity of the source of the messagemessage
- a messagetype
- the type- Since:
- 4.0.0
- See Also:
Component
-
sendMessage
default void sendMessage(@NonNull Component message, @NonNull MessageType type)
- Parameters:
message
- a messagetype
- the type- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, Component, MessageType)
,sendMessage(Identity, Component, MessageType)
-
sendMessage
default void sendMessage(@NonNull Identified source, @NonNull Component message, @NonNull MessageType type)
Sends a chat message.- Parameters:
source
- the source of the messagemessage
- a messagetype
- 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 messagemessage
- a messagetype
- 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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 headerfooter
- 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 headerfooter
- 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 soundx
- x coordinatey
- y coordinatez
- 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
-
-