As an API,
Audienceis 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. This allows extending audiences to cover more than one individual receiver - possible “audiences” could include a team, server, world, or all players that satisfy some predicate (such as having a certain permission). The universal interface also allows reducing boilerplate by gracefully degrading functionality if it is not applicable.
Audience, or one of the subtypes, provides access to the full Adventure API.
Audiencedirectly. This means that if you have a reference to, for example, an
Instance, you can simply use the Adventure API on that instance. As an example, the following code would be used to send a message to all players in an instance:
Audiencesclass. The following code provides an example of how this class would be used in your project:
Audiencesclass also provides a
players(Predicate)function that allows you to collect an audience of players that match a specific predicate. For example, this could be used to check permissions before sending a broadcast. Additionally, if you would like access to each audience as an iterable, you can instead use the
IterableAudienceProvider, an instance of which can be obtained using
Audiencesclass also provides the ability to add custom audience members identified by a
Key. This could be used to add an audience for file logging or a
ForwardingAudiencerepresenting a custom collection of players. Audiences can be registered using the
AudienceRegistry, an instance of which can be obtained using
Audiences#registry(). For example, if you wanted to share a collection of staff members to send alerts to between plugins, this could be done using the following code:
Audience, use the Adventure method
Audience.audience(Iterable)or the Minestom
PacketGroupingAudience.of()method to create an audience backed on an iterable object. This means that you could register a custom audience backed by a collection that you continue to update and the changes will be reflected when anyone uses the custom methods.
of(Predicate)methods will collect every custom audience using streams, and combine this with the server audience. Such an operation is relatively costly, so should be avoided where possible.
PacketGroupingAudience. This is implemented by every audience in Minestom that has multiple players. Instead of the normal
ForwardingAudienceimplementation that iterates through the audience members, this implementation uses
PacketUtils#sendGroupedPacket(Collection, ServerPacket)to attempt to send a grouped packet to all of the players in this audience.
PacketGroupingAudience, you can use the static
of(Iterable)methods in the class which return an instance of
PacketGroupingAudiencewhen provided a group of players.
Viewableclass includes two methods to obtain the viewers of the viewable object as an audience. This means that you can use the full Adventure API on the viewers of a viewable object. For example, to send a message to everyone who can view a player in the old API you would do:
ViewableClass is that it implements
PacketGroupingAudiencewhich means the outgoing packets are grouped where possible, reducing networking overhead when compared to the looping method of sending messages.
ChatColorclass, a new
colorpackage has been created to replace all existing usage of the
ChatColorclass. These new classes are an accurate representation of how Minecraft stores colors for certain objects and allows for proper validation, preventing developers from applying styles to colorable objects at compile-time.
Colorclass is a general purpose class for representing RGB colors, similar to
java.awt.Color. As this class implements Adventure's
RGBLikeinterface, it can be used anywhere in the Adventure API that requires coloring (e.g. component text). A new addition to this class is the
mixWithmethod which mixes this color with a series of other
RGBLikecolors to create a new color using the same method that vanilla Minecraft uses to mix dyes and colors.
DyeColor. This enum represents the different colors of the dyes within Minecraft and provides values for each of the different vanilla dye types. This class includes a method to get the RGB color of the dye and the equivalent firework color. As with the
Colorclass, this class also implements
RGBLikeso it can also be used throughout the Adventure API.
SerializationManagerclass, a powerful and feature-rich way to control the flow of component translation. Adventure provides the concept of a
GlobalTranslator. By supplying sources, a collection of key-value pairs, you can perform server-side translations without any additional code or complicated localization libraries.
true. With this set, any components that are being sent to players will be translated using their locale automatically.
SerializationManagerprovides access to the serializer used to convert all components to JSON strings. By default, the serializer is a
Function<Component, String>that uses Adventure's
GsonComponentSerializerto serialize a component into a JSON string using the GSON library. However, you can mutate this serializer or change it completely.
net.minestom.server.bossbarpackage has been entirely deprecated. To create a boss bar you should instead use the static builder methods in the Adventure
BossBarclass. For example, with the old API you might do:
WrittenBookMetato a player using
Player#openBook(WrittenBookMeta). This has been replaced with
Bookcomponent can be constructed using the builder methods as described in the documentation.
Soundenum has been renamed to
SoundEvent. This is because the values for the enum do not represent specific sounds, rather representing events that are linked to one or more specific sounds. For more information about sound events, see the Minecraft Wiki page on sound events.
SoundCategoryhas been deprecated in favor of Adventure's
Sound.Sourceenum. To play a sound, you need to construct a
Soundobject. This can be done using the methods described in the documentation. In addition, instead of using an Adventure
Keyyou can instead pass a
SoundEventinto any places in the Adventure sound API that accept a supplier of
Sound.Type. Sound objects can also be stored and used multiple times.
SoundStopobject and passing that to a player using
StopSoundobject can be used to stop all sounds, using
SoundStop#all(), in addition to specific sounds, using
SoundStop#named(Key), or specific sounds in specific sources, using the previous methods with an additional
net.minestom.server.chatpackage has been entirely deprecated. To construct message you should instead use the
Componentclass and its builder methods as discussed in the Adventure documentation. However,
JsonMessagedoes implement the Adventure interface
ComponentLike. This means that you can use
JsonMessageand all its subtypes throughout the Adventure API within Minestom. You can also use
JsonMessage#fromComponent(Component)to convert an Adventure component to a
JsonMessage, allowing you to use new Adventure components with the old Minestom chat API.
ChatColor.RED + "some text". This is not possible with Adventure as it does not properly represent how text is stored in Minecraft. Instead, you can set the style of components using the methods found in the
Componentclass, such as
Component.text(String, TextColor), or by setting the style using the
ChatColorclass into classes for
TextDecorationcan also be negated, meaning you can remove styles from nested components whilst not impacting components that may follow this one. The old
ChatColorclass has been deprecated and replaced with new classes for
DyeColoracross the Minestom codebase. Both of these implement
RgbLikeand can be used to color Adventure components.
.clickEvent. Instead of using
ChatHoverEvent.showItem(ItemStack)you can instead put an
ItemStackdirectly into the argument of a hover event. For example, in the old chat API you would do: