|
| 1 | +--- |
| 2 | +title: Migrating from Adventure 4.x to 5.x |
| 3 | +slug: adventure/migration/adventure-4.x |
| 4 | +description: Move from Adventure 4.x to 5.x. |
| 5 | +--- |
| 6 | + |
| 7 | +With the release of Adventure 5.0, some breaking changes have been introduced from the Adventure 4.x series. |
| 8 | +This page documents the changes made and how you as a developer can migrate your code. |
| 9 | + |
| 10 | +## A modern codebase |
| 11 | +One of the main goals for Adventure 5.0 was to migrate to a more modern codebase. |
| 12 | +The minimum version of Java required to use Adventure is now Java 21. |
| 13 | + |
| 14 | +By updating to Java 21, Adventure has taken advantage of sealed classes and interfaces. |
| 15 | +Almost every interface/class that was annotated with `@ApiStatus.Internal` has now been made sealed. |
| 16 | +This means that you can no longer extend these classes, although you shouldn't have been doing that in the first place! |
| 17 | +One relatively common incorrect usage was to create custom `Component` implementations. |
| 18 | +This is now no longer possible, and you should instead be using the `VirtualComponent` API. |
| 19 | + |
| 20 | +Adventure has also migrated to using JSpecify for nullness annotations. |
| 21 | +These are applied at a module level, so unless otherwise specified, everything should be treated as non-null. |
| 22 | + |
| 23 | +Another side effect of wanting a modern codebase is that the `adventure-extra-kotlin` module has been removed. |
| 24 | +This module will be re-introduced in a separate repo under a new module in the future. |
| 25 | +This will allow for more flexibility working around the more frequent Kotlin updates. |
| 26 | + |
| 27 | +The `adventure-text-serializer-gson-legacy-impl` module has also been removed. |
| 28 | +This module has been replaced with the implementation-agnostic `adventure-text-serializer-json-legacy-impl` module. |
| 29 | + |
| 30 | +As most of the internal implementation of Adventure is now using records, we no longer have need to use the Examination library for `toString` generation. |
| 31 | +The Examination library has been entirely removed from Adventure and is no longer a transitive dependency. |
| 32 | + |
| 33 | +Finally, Adventure now contains proper `module-info.java` files for those of you using the Java 9+ module system. |
| 34 | + |
| 35 | +## Breaking changes |
| 36 | + |
| 37 | +### Click event changes |
| 38 | + |
| 39 | +The `ClickEvent` class is now a typed interface. |
| 40 | +The type argument for this click event is the payload type. |
| 41 | +This does not change how you construct click events but does make serialization and deserialization easier. |
| 42 | + |
| 43 | +This change also extends to `ClickEvent$Action`, which is now no longer an enum and instead is a typed interface. |
| 44 | + |
| 45 | +### Component construction changes |
| 46 | + |
| 47 | +All component construction methods now only accept `StyleBuilderApplicable` as additional parameters for styling. |
| 48 | +This allows for more flexibility in how you construct components and also reduces the number of methods used to create components. |
| 49 | +This change will only require a recompile, as all existing methods of constructing components will translate to the new methods seamlessly. |
| 50 | + |
| 51 | +Regarding forward-compatibility (e.g., running code compiled against Adventure 4.x on Adventure 5.x), the old methods will continue to work. |
| 52 | +During the 5.x series, we will maintain the old methods as invisible synthetic methods. |
| 53 | +This means that old code compiled against Adventure 4.x will work, but the methods will not be visible in your IDE. |
| 54 | + |
| 55 | +This period of migration will end in Adventure 6.0 with the removal of the invisible synthetic methods. |
| 56 | + |
| 57 | +## Removal of deprecated methods and classes |
| 58 | +A number of methods and classes have been deprecated in across the Adventure 4.x series. |
| 59 | +This section documents the removals that have been made and how you can migrate your code, if applicable. |
| 60 | + |
| 61 | +* **`BuildableComponent` has been removed.**\ |
| 62 | + You can now obtain a `ComponentBuilder` directly from a `Component` using `Component#toBuilder`. |
| 63 | + A breaking side effect of this change is that `NBTComponent` now only accepts one type argument, rather than two. |
| 64 | +* **Legacy chat signing/identifying methods have been removed.**\ |
| 65 | + Although legacy versions still use these features, they did not have enough usage to warrant their continued existence in Adventure. |
| 66 | + Generally speaking, you should migrate to using signed messages if you intend to send identified/chat messages. |
| 67 | + * **The `MessageType` enum has been removed entirely.**\ |
| 68 | + Chat messages are now identified when sending a signed message. |
| 69 | + All other messages are system messages. |
| 70 | + * **All `Audience#sendMessage` methods that accept an `Identity` or `Identified` have been removed.**\ |
| 71 | + Prefer sending signed messages instead. |
| 72 | +* **Boss bar progress has been removed.**\ |
| 73 | + This includes the max/min progress constants and methods to change/get the progress. |
| 74 | + You should instead be using the percent constants/methods. |
| 75 | +* **`of` style static methods have been removed.**\ |
| 76 | + These methods have been deprecated for some time, and each has named replacements. |
| 77 | +* **Custom click payload data has been removed.**\ |
| 78 | + As custom click payloads contain NBT, you should instead be using the `nbt` method. |
| 79 | + This includes the custom click event constructor methods that accept strings instead of NBT. |
| 80 | +* **`ClickEvent#create(Action, String)` has been removed.**\ |
| 81 | + As click events can now hold data other than strings, this method has been removed. |
| 82 | + 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)`). |
| 83 | +* **`ClickEvent#value` has been removed.**\ |
| 84 | + As noted above, click events can now hold data other than strings. |
| 85 | + Therefore, this method has been removed in favor of the `payload` method. |
| 86 | +* **`AbstractComponent` has been removed.**\ |
| 87 | + As this class was primarily an implementation detail, it has been removed with no replacement. |
| 88 | +* **Non-builder component joining has been removed.**\ |
| 89 | + This includes the `Component#join` family of methods that do not accept a `JoinConfiguration`. |
| 90 | + You should instead be using `Component#textOfChildren` or `join` methods that accept a `JoinConfiguration`. |
| 91 | +* **`Component#detectCycle(Component)` has been removed.**\ |
| 92 | + As components are immutable, this method is not required and has therefore been removed with no replacement. |
| 93 | +* **Non-builder component text replacement has been removed.**\ |
| 94 | + This includes the `Component#replace[First]Text` family of methods that do not accept a `TextReplacementConfig`. |
| 95 | + You should instead be using the `replaceText` methods that accept a `TextReplacementConfig`. |
| 96 | +* **`TranslationRegistry` has been removed.**\ |
| 97 | + Registries have been replaced with the more powerful `TranslationStore`. |
| 98 | + See static methods on `TranslationStore` for a compatible replacement. |
| 99 | +* **`JSONComponentConstants` has been removed.**\ |
| 100 | + This has been replaced with `ComponentTreeConstants` from the `adventure-text-serializer-commons` module. |
| 101 | +* **`PlainComponentSerializer` has been removed.**\ |
| 102 | + This has been replaced with the equivalent `PlainTextComponentSerializer` class. |
| 103 | +* **`ClickEvent$Action#payloadType` has been removed.**\ |
| 104 | + As click event actions are now typed, this field is no longer required. |
0 commit comments