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 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 Deprecated Methods Modifier and Type Method Description static @NotNull ForwardingAudience
audience(@NotNull java.lang.Iterable<? extends Audience> audiences)
Creates an audience that forwards to many other audiences.static @NotNull Audience
audience(@NotNull Audience @NotNull ... audiences)
Creates an audience that forwards to many other audiences.default void
clearTitle()
Clears the title, if one is being displayed.default void
deleteMessage(@NotNull SignedMessage signedMessage)
Requests deletion of a message with the providedSignedMessage
's signature.default void
deleteMessage(@NotNull SignedMessage.Signature signature)
Requests deletion of a message with the providedSignedMessage.Signature
.static @NotNull Audience
empty()
Gets an audience that does nothing.default @NotNull Audience
filterAudience(@NotNull java.util.function.Predicate<? super Audience> filter)
Filters this audience.default void
forEachAudience(@NotNull java.util.function.Consumer<? super Audience> action)
Executes an action against all audiences.default void
hideBossBar(@NotNull BossBar bar)
Hides a boss bar.default void
openBook(@NotNull Book book)
Opens a book.default void
openBook(@NotNull Book.Builder book)
Opens a book.default void
playSound(@NotNull Sound sound)
Plays a sound at the location of the recipient of the sound.default void
playSound(@NotNull Sound sound, double x, double y, double z)
Plays a sound at a location.default void
playSound(@NotNull Sound sound, @NotNull Sound.Emitter emitter)
Plays a sound from an emitter, usually an entity.default void
resetTitle()
Resets the title and timings back to their default.default void
sendActionBar(@NotNull Component message)
Sends a message on the action bar.default void
sendActionBar(@NotNull ComponentLike message)
Sends a message on the action bar.default void
sendMessage(@NotNull SignedMessage signedMessage, @NotNull ChatType.Bound boundChatType)
Sends a signed player message to thisAudience
with the providedbound chat type
.default void
sendMessage(@NotNull Identified source, @NotNull Component message)
Deprecated.since 4.12.0, the client errors on receiving and can reject identified messages withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identified source, @NotNull ComponentLike message)
Deprecated.since 4.12.0, the client errors on and can reject identified messages withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identified source, @NotNull ComponentLike message, @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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identified source, @NotNull Component message, @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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identity source, @NotNull Component message)
Deprecated.since 4.12.0, the client errors on receiving and can reject identified messages withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identity source, @NotNull ComponentLike message)
Deprecated.since 4.12.0, the client errors on and can reject identified messages withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identity source, @NotNull ComponentLike message, @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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Identity source, @NotNull Component message, @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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteaddefault void
sendMessage(@NotNull Component message)
Sends a system chat message to thisAudience
.default void
sendMessage(@NotNull ComponentLike message)
Sends a system chat message to thisAudience
.default void
sendMessage(@NotNull ComponentLike message, @NotNull MessageType type)
Deprecated.for removal since 4.12.0,MessageType
is deprecated for removal, usesendMessage(ComponentLike)
default void
sendMessage(@NotNull ComponentLike message, @NotNull ChatType.Bound boundChatType)
Sends a message to thisAudience
with the providedbound chat type
.default void
sendMessage(@NotNull Component message, @NotNull MessageType type)
Deprecated.for removal since 4.12.0,MessageType
is deprecated for removal, usesendMessage(Component)
insteaddefault void
sendMessage(@NotNull Component message, @NotNull ChatType.Bound boundChatType)
Sends a message to thisAudience
with the providedbound chat type
.default void
sendPlayerListFooter(@NotNull Component footer)
Sends the player list footer.default void
sendPlayerListFooter(@NotNull ComponentLike footer)
Sends the player list footer.default void
sendPlayerListHeader(@NotNull Component header)
Sends the player list header.default void
sendPlayerListHeader(@NotNull ComponentLike header)
Sends the player list header.default void
sendPlayerListHeaderAndFooter(@NotNull ComponentLike header, @NotNull ComponentLike footer)
Sends the player list header and footer.default void
sendPlayerListHeaderAndFooter(@NotNull Component header, @NotNull Component footer)
Sends the player list header and footer.default <T> void
sendTitlePart(@NotNull TitlePart<T> part, T value)
Shows a part of a title.default void
showBossBar(@NotNull BossBar bar)
Shows a boss bar.default void
showTitle(@NotNull Title title)
Shows a title.default void
stopSound(@NotNull Sound sound)
Stops a sound.default void
stopSound(@NotNull SoundStop stop)
Stops a sound, or many sounds.static @NotNull java.util.stream.Collector<? super Audience,?,ForwardingAudience>
toAudience()
Provides a collector to create a forwarding audience from a stream of audiences.-
Methods inherited from interface net.kyori.adventure.pointer.Pointered
get, getOrDefault, getOrDefaultFrom, pointers
-
-
-
-
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 inAudience
.- 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 providedfilter
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 notForwardingAudience
in your own code, and your audience forwards to other audiences, then you must override this method and provide each audience toaction
.If an implementation of
Audience
has its own identity distinct from its contained children, it may test itself against the providedfilter
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(@NotNull @NotNull ComponentLike message)
Sends a system chat message to thisAudience
.- Parameters:
message
- a message- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, ComponentLike)
,sendMessage(Identity, ComponentLike)
-
sendMessage
default void sendMessage(@NotNull @NotNull Component message)
Sends a system chat message to thisAudience
.- Parameters:
message
- a message- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, Component)
,sendMessage(Identity, Component)
-
sendMessage
@ScheduledForRemoval(inVersion="5.0.0") @Deprecated default void sendMessage(@NotNull @NotNull ComponentLike message, @NotNull @NotNull MessageType type)
Deprecated.for removal since 4.12.0,MessageType
is deprecated for removal, usesendMessage(ComponentLike)
Sends a system chat message to thisAudience
ignoring the providedMessageType
.- Parameters:
message
- a messagetype
- the type- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, ComponentLike, MessageType)
,sendMessage(Identity, ComponentLike, MessageType)
-
sendMessage
@ScheduledForRemoval(inVersion="5.0.0") @Deprecated default void sendMessage(@NotNull @NotNull Component message, @NotNull @NotNull MessageType type)
Deprecated.for removal since 4.12.0,MessageType
is deprecated for removal, usesendMessage(Component)
insteadSends a system chat message to thisAudience
ignoring the providedMessageType
.- Parameters:
message
- a messagetype
- the type- Since:
- 4.1.0
- See Also:
Component
,sendMessage(Identified, Component, MessageType)
,sendMessage(Identity, Component, MessageType)
-
sendMessage
@Deprecated default void sendMessage(@NotNull @NotNull Identified source, @NotNull @NotNull ComponentLike message)
Deprecated.since 4.12.0, the client errors on and can reject identified messages withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the givenIdentified
to thisAudience
with thesystem
chat type.- Parameters:
source
- the source of the messagemessage
- a message- Since:
- 4.0.0
- See Also:
Component
-
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 withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the entity represented by the givenIdentity
to thisAudience
with thesystem
chat type.- Parameters:
source
- the identity of the source of the messagemessage
- 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 withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the givenIdentified
to thisAudience
with thesystem
chat type.- Parameters:
source
- the source of the messagemessage
- 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 withoutSignedMessage
data, this may be unsupported in the future, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the entity represented by the givenIdentity
to thisAudience
with thesystem
chat type.- Parameters:
source
- the identity of the source of the messagemessage
- a message- Since:
- 4.0.0
- See Also:
Component
-
sendMessage
@ScheduledForRemoval(inVersion="5.0.0") @Deprecated default void sendMessage(@NotNull @NotNull Identified 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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the givenIdentified
to thisAudience
with theChatType
corresponding to the providedMessageType
.- Parameters:
source
- the source of the messagemessage
- a messagetype
- 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 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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the entity represented by the givenIdentity
to thisAudience
.- Parameters:
source
- the identity of the source of the messagemessage
- a messagetype
- the type- Since:
- 4.0.0
- See Also:
Component
-
sendMessage
@ScheduledForRemoval(inVersion="5.0.0") @Deprecated default void sendMessage(@NotNull @NotNull Identified 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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends an unsigned player chat message from the givenIdentified
to thisAudience
with theChatType
corresponding to the providedMessageType
.- Parameters:
source
- the source of the messagemessage
- a messagetype
- 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 withoutSignedMessage
data, usesendMessage(SignedMessage, ChatType.Bound)
insteadSends a player chat message from the entity represented by the givenIdentity
to thisAudience
with theChatType
corresponding to the providedMessageType
.- 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(@NotNull @NotNull Component message, @NotNull ChatType.Bound boundChatType)
Sends a message to thisAudience
with the providedbound chat type
.- Parameters:
message
- the component contentboundChatType
- 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 thisAudience
with the providedbound chat type
.- Parameters:
message
- the component contentboundChatType
- 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 thisAudience
with the providedbound chat type
.- Parameters:
signedMessage
- the signed message databoundChatType
- 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 providedSignedMessage
'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 providedSignedMessage.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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 usesendPlayerListHeaderAndFooter(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 headerfooter
- 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 headerfooter
- 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 partvalue
- the value- Throws:
java.lang.IllegalArgumentException
- if a title part that is not inTitlePart
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)
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)
withSound.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 soundx
- x coordinatey
- y coordinatez
- 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 soundemitter
- 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
-
-