Migrating from Adventure 4.x to 5.x

With the release of Adventure 5.0, some breaking changes have been introduced from the Adventure 4.x series. This page documents the changes made and how you as a developer can migrate your code.

One of the main goals for Adventure 5.0 was to migrate to a more modern codebase. The minimum version of Java required to use Adventure is now Java 21.

By updating to Java 21, Adventure has taken advantage of sealed classes and interfaces. Almost every interface/class that was annotated with @ApiStatus.NonExtendable has now been made sealed. This means that you can no longer extend these classes, although you shouldn’t have been doing that in the first place! One relatively common incorrect usage was to create custom Component implementations. This is now no longer possible, and you should instead be using the VirtualComponent API.

Another side effect of wanting a modern codebase is that the adventure-extra-kotlin module has been removed. This module will be re-introduced in a separate repo under a new module in the future. This will allow for more flexibility working around the more frequent Kotlin updates.

The adventure-text-serializer-gson-legacy-impl module has also been removed. This module has been replaced with the implementation-agnostic adventure-text-serializer-json-legacy-impl module.

Finally, Adventure now contains proper module-info.java files for those of you using the Java 9+ module system.

Many non-breaking updates to dependencies have been made. There are a few notable breaking/major changes that are documented below.

Adventure has migrated to using JSpecify for nullness annotations. These are applied at a package/class level, so unless otherwise specified, everything should be treated as non-null.

As most of the internal implementation of Adventure is now using records, we no longer need to use the Examination library for toString generation. The Examination library has been entirely removed from Adventure and is no longer a transitive dependency.

The adventure-text-logger-slf4j module has been updated to use SLF4J 2.0.

The GSON library has been updated to 2.13.2. Although this version is higher than most Minecraft versions that are supported by Adventure, it is not our intention to drop support for these older versions. We will endeavor to not use newer GSON features that would break support for older versions of GSON used in legacy Minecraft versions.

The ClickEvent class is now a typed interface. The type argument for this click event is the payload type. This does not change how you construct click events but does make serialization and deserialization easier.

This change also extends to ClickEvent$Action, which is now no longer an enum and instead is a typed interface.

Additionally, the nbt field for custom click event payloads is now nullable. This is to allow for the possibility of custom click events without NBT and to be more in line with Vanilla Minecraft behavior.

With the addition of the new object component, the AbstractComponentRenderer interface has been updated to include a new method to render object components. This is a breaking change, as implementations of this method will be required. Going forward, we will be adding new methods to this class whenever Mojang adds new component types. This breaking change is documented in the AbstractComponentRenderer javadocs.

Although it was never recommended to extend TextFormat, it was possible to do so in the past. This ability has been removed from the API, and the interface is now sealed. If you were extending this interface, you should instead consider extending the StyleBuilderApplicable interface for a more powerful and widely-used alternative.

Due to changes in the chat system, specifically around the creation of dynamic chat types, it is possible for chat types to not be keyed. Due to this internal change, ChatType#key is now nullable. Additionally, the class no longer implemented Keyed.

A number of methods and classes have been deprecated in across the Adventure 4.x series. This section documents the removals that have been made and how you can migrate your code, if applicable.

• BuildableComponent has been removed.
  You can now obtain a ComponentBuilder directly from a Component using Component#toBuilder. A breaking side effect of this change is that NBTComponent now only accepts one type argument, rather than two.
• Legacy chat signing/identifying methods have been removed.
  Although legacy versions still use these features, they did not have enough usage to warrant their continued existence in Adventure. Generally speaking, you should migrate to using signed messages if you intend to send identified/chat messages.
  • The MessageType enum has been removed entirely.
    Chat messages are now identified when sending a signed message. All other messages are system messages.
  • All Audience#sendMessage methods that accept an Identity or Identified have been removed.
    Prefer sending signed messages instead.
• Boss bar percent has been removed.
  This includes the max/min percent constants and methods to change/get the percent. You should instead be using the progress constants/methods.
• of style static methods have been removed.
  These methods have been deprecated for some time, and each has named replacements.
• Custom click payload data has been removed.
  As custom click payloads contain NBT, you should instead be using the nbt method. This includes the custom click event constructor methods that accept strings instead of NBT.
• ClickEvent#create(Action, String) has been removed.
  As click events can now hold data other than strings, this method has been removed. If you were using this method, you should migrate to the create method that accepts a payload or use the direct construct methods (e.g. ClickEvent#openUrl(String)).
• ClickEvent#value has been removed.
  As noted above, click events can now hold data other than strings. Therefore, this method has been removed in favor of the payload method.
• AbstractComponent has been removed.
  As this class was primarily an implementation detail, it has been removed with no replacement.
• Non-builder component joining has been removed.
  This includes the Component#join family of methods that do not accept a JoinConfiguration. You should instead be using Component#textOfChildren or join methods that accept a JoinConfiguration.
• Component#detectCycle(Component) has been removed.
  As components are immutable, this method is not required and has therefore been removed with no replacement.
• Non-builder component text replacement has been removed.
  This includes the Component#replace[First]Text family of methods that do not accept a TextReplacementConfig. You should instead be using the replaceText methods that accept a TextReplacementConfig.
• TranslationRegistry has been removed.
  Registries have been replaced with the more powerful TranslationStore. See static methods on TranslationStore for a compatible replacement.
• JSONComponentConstants has been removed.
  This has been replaced with ComponentTreeConstants from the adventure-text-serializer-commons module.
• PlainComponentSerializer has been removed.
  This has been replaced with the equivalent PlainTextComponentSerializer class.
• ClickEvent$Action#payloadType has been removed.
  As click event actions are now typed, this field is no longer required.
• UTF8ResourceBundleControl has been removed.
  From Java 9 onwards, resource bundles are loaded using UTF-8 by default. Therefore, this class is no longer required. Instead of using this class, you can load properties files without any resource bundle control.
• Removal of methods from GSONComponentSerializer.
  Since the addition of the options system to customize JSON serializers, the downsampleColors and emitLegacyHoverEvent options in the GSONComponentSerializer has been removed. You should instead use EMIT_RGB and EMIT_HOVER_EVENT_TYPE fields in JSONOptions respectively. Additionally, the legacyHoverEventSerializer that accepts a LegacyHoverEventSerializer from the GSON module has been removed in favor of the generic alternative in the JSON module.
• Typos have been removed.
  Some incorrectly spelt/named methods, such as Argument#numeric and ComponentSerializer#deseializeOrNull, have been removed. These methods have been deprecated, and correctly spelt/named methods have been available for a while.