From 08fb6e5d919469d672de71f5bc67f95498eaaf8e Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Wed, 15 Oct 2025 14:05:29 +0100 Subject: [PATCH 1/4] feature(adventure): Adventure 5.0 --- astro.config.ts | 3 +- .../docs/adventure/migration/adventure-4.x.md | 104 ++++++++++++++++++ src/content/docs/adventure/migration/index.md | 12 +- src/content/docs/adventure/text.md | 2 + src/utils/versions.ts | 2 +- 5 files changed, 117 insertions(+), 6 deletions(-) create mode 100644 src/content/docs/adventure/migration/adventure-4.x.md diff --git a/astro.config.ts b/astro.config.ts index e9743423f..0fd8b26d2 100644 --- a/astro.config.ts +++ b/astro.config.ts @@ -444,10 +444,11 @@ export default defineConfig({ ], }, { - label: "Migrating to Adventure from other APIs", + label: "Migration", items: [ "adventure/migration", "adventure/migration/bungeecord-chat-api", + "adventure/migration/adventure-4.x", "adventure/migration/text-3.x", ], }, diff --git a/src/content/docs/adventure/migration/adventure-4.x.md b/src/content/docs/adventure/migration/adventure-4.x.md new file mode 100644 index 000000000..608066b30 --- /dev/null +++ b/src/content/docs/adventure/migration/adventure-4.x.md @@ -0,0 +1,104 @@ +--- +title: Migrating from Adventure 4.x to 5.x +slug: adventure/migration/adventure-4.x +description: Move 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. + +## A modern codebase +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.Internal` 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. + +Adventure has also migrated to using JSpecify for nullness annotations. +These are applied at a module level, so unless otherwise specified, everything should be treated as non-null. + +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. + +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. +The Examination library has been entirely removed from Adventure and is no longer a transitive dependency. + +Finally, Adventure now contains proper `module-info.java` files for those of you using the Java 9+ module system. + +## Breaking changes + +### Click event changes + +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. + +### Component construction changes + +All component construction methods now only accept `StyleBuilderApplicable` as additional parameters for styling. +This allows for more flexibility in how you construct components and also reduces the number of methods used to create components. +This change will only require a recompile, as all existing methods of constructing components will translate to the new methods seamlessly. + +Regarding forward-compatibility (e.g., running code compiled against Adventure 4.x on Adventure 5.x), the old methods will continue to work. +During the 5.x series, we will maintain the old methods as invisible synthetic methods. +This means that old code compiled against Adventure 4.x will work, but the methods will not be visible in your IDE. + +This period of migration will end in Adventure 6.0 with the removal of the invisible synthetic methods. + +## Removal of deprecated methods and classes +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 progress has been removed.**\ + This includes the max/min progress constants and methods to change/get the progress. + You should instead be using the percent 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. diff --git a/src/content/docs/adventure/migration/index.md b/src/content/docs/adventure/migration/index.md index f8504a2b2..2f4805104 100644 --- a/src/content/docs/adventure/migration/index.md +++ b/src/content/docs/adventure/migration/index.md @@ -1,15 +1,19 @@ --- -title: Migrating to Adventure from other APIs +title: Migration slug: adventure/migration -description: Moving from other chat APIs to Adventure. +description: Moving to the latest Adventure version. tableOfContents: false sidebar: label: Overview --- -Moving to Adventure from other APIs is fairly straightforward. These guides -provide advice and replacements for tasks in other APIs. +These guides provide advice and replacements useful when migrating to the latest version of Adventure. +This includes migrating from older versions of Adventure, as well as migrating from other libraries. +* [Migrating from Adventure 4.x to 5.x](/adventure/migration/adventure-4.x) + * [A modern codebase](/adventure/migration/adventure-4.x#a-modern-codebase) + * [Breaking changes](/adventure/migration/adventure-4.x#breaking-changes) + * [Removal of deprecated methods and classes](/adventure/migration/adventure-4.x#removal-of-deprecated-methods-and-classes) * [Migrating from the BungeeCord Chat API](/adventure/migration/bungeecord-chat-api) * [Audiences](/adventure/migration/bungeecord-chat-api#audiences) * [Decoration and styling](/adventure/migration/bungeecord-chat-api#decoration-and-styling) diff --git a/src/content/docs/adventure/text.md b/src/content/docs/adventure/text.md index 83bb528ea..045c7aea2 100644 --- a/src/content/docs/adventure/text.md +++ b/src/content/docs/adventure/text.md @@ -69,6 +69,8 @@ When a user clicks on the text component, a click event is fired which can perfo * Suggest a command * Change a book's page * Copy a string to clipboard +* Open a dialog +* Send a custom payload back to the server ## Serializing and deserializing components diff --git a/src/utils/versions.ts b/src/utils/versions.ts index 09c18c8a9..0453d5b11 100644 --- a/src/utils/versions.ts +++ b/src/utils/versions.ts @@ -86,7 +86,7 @@ export const LATEST_USERDEV_RELEASE = userdevVersions[0]; export const LATEST_ADVENTURE_SUPPORTED_MC = "1.21.9"; export const LATEST_ADVENTURE_SUPPORTED_MC_RANGE = LATEST_ADVENTURE_SUPPORTED_MC; -export const LATEST_ADVENTURE_API_RELEASE = "4.25.0"; +export const LATEST_ADVENTURE_API_RELEASE = "5.0.0"; export const LATEST_ADVENTURE_PLATFORM_RELEASE = "4.4.1"; export const LATEST_ADVENTURE_PLATFORM_MOD_RELEASE = "6.5.1"; export const LATEST_ANSI_RELEASE = "1.1.1"; From b8ace184f5df7474bbfc953e0cf1c504cf1ad528 Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Wed, 15 Oct 2025 14:07:31 +0100 Subject: [PATCH 2/4] chore(adventure): Remove unmaintained community library links --- src/content/docs/adventure/community-libraries.mdx | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/content/docs/adventure/community-libraries.mdx b/src/content/docs/adventure/community-libraries.mdx index edf3f58dc..7831ec9b2 100644 --- a/src/content/docs/adventure/community-libraries.mdx +++ b/src/content/docs/adventure/community-libraries.mdx @@ -28,7 +28,6 @@ They typically have no dependencies on a specific platform, just Adventure and p {/* spellchecker:off */} Name | Description | Link ----------------------------|-----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------- -adventure-binary-serializer | Serializer for converting to packed bytes | [Moulberry/adventure-binary-serializer](https://github.com/Moulberry/adventure-binary-serializer) EnhancedLegacyText | Alternative input format that is legacy compatible with new features | [Vankka/EnhancedLegacyText](https://github.com/Vankka/EnhancedLegacyText) MCDiscordReserializer | Serializers for going between Minecraft & Discord | [Vankka/MCDiscordReserializer](https://github.com/Vankka/MCDiscordReserializer) Minedown | A markdown-style format for representing components | [Phoenix616/MineDown](https://github.com/Phoenix616/MineDown) @@ -45,7 +44,6 @@ These libraries will often depend on one or more specific platforms to support t Name | Description | Link --------------------|-----------------------------------------------------------------------|---------------------------------------------------- Cloud | A general-purpose Java command dispatcher & framework | [Incendo/cloud](https://github.com/Incendo/cloud) -Core | The Core allows you to register (mini)messages to a central database in multiple languages and access them via a very intuitive "key" and "locale" query. | [JuliGamesCore](https://github.com/JuliGames/JuliGamesCore) Creative | A resource-pack library for Minecraft: Java Edition | [Creative](https://github.com/unnamed/creative) Inventory Framework | An inventory framework for managing GUIs | [Inventory Framework](https://github.com/stefvanschie/IF) LiteCommands | A annotation based command framework for Velocity, Bukkit, BungeeCord | [LiteCommands](https://github.com/Rollczi/LiteCommands) From 4b4723727bec215cd26e553090f245c8c51489a2 Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Thu, 16 Oct 2025 12:33:11 +0100 Subject: [PATCH 3/4] feature(adventure): Add new dependencies section and note about typo removals --- .../docs/adventure/migration/adventure-4.x.md | 15 +++++++++++---- src/content/docs/adventure/migration/index.md | 1 + 2 files changed, 12 insertions(+), 4 deletions(-) diff --git a/src/content/docs/adventure/migration/adventure-4.x.md b/src/content/docs/adventure/migration/adventure-4.x.md index 608066b30..680482043 100644 --- a/src/content/docs/adventure/migration/adventure-4.x.md +++ b/src/content/docs/adventure/migration/adventure-4.x.md @@ -17,9 +17,6 @@ This means that you can no longer extend these classes, although you shouldn't h 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. -Adventure has also migrated to using JSpecify for nullness annotations. -These are applied at a module level, so unless otherwise specified, everything should be treated as non-null. - 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. @@ -27,10 +24,17 @@ This will allow for more flexibility working around the more frequent Kotlin upd 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. + +## Updated dependencies + +Adventure has migrated to using JSpecify for nullness annotations. +These are applied at a module 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 have 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. -Finally, Adventure now contains proper `module-info.java` files for those of you using the Java 9+ module system. +The `adventure-text-logger-slf4j` module has been updated to use SLF4J 2.0. ## Breaking changes @@ -102,3 +106,6 @@ This section documents the removals that have been made and how you can migrate 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. +* **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. diff --git a/src/content/docs/adventure/migration/index.md b/src/content/docs/adventure/migration/index.md index 2f4805104..902071a6b 100644 --- a/src/content/docs/adventure/migration/index.md +++ b/src/content/docs/adventure/migration/index.md @@ -12,6 +12,7 @@ This includes migrating from older versions of Adventure, as well as migrating f * [Migrating from Adventure 4.x to 5.x](/adventure/migration/adventure-4.x) * [A modern codebase](/adventure/migration/adventure-4.x#a-modern-codebase) + * [Updated dependencies](/adventure/migration/adventure-4.x#updated-dependencies) * [Breaking changes](/adventure/migration/adventure-4.x#breaking-changes) * [Removal of deprecated methods and classes](/adventure/migration/adventure-4.x#removal-of-deprecated-methods-and-classes) * [Migrating from the BungeeCord Chat API](/adventure/migration/bungeecord-chat-api) From df70adf98668d0bd10a484221440d56e1405c63a Mon Sep 17 00:00:00 2001 From: Kieran Wallbanks Date: Fri, 17 Oct 2025 13:34:29 +0100 Subject: [PATCH 4/4] chore(adventure): Address review comments --- src/content/docs/adventure/migration/adventure-4.x.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/src/content/docs/adventure/migration/adventure-4.x.md b/src/content/docs/adventure/migration/adventure-4.x.md index 680482043..044e5a2f5 100644 --- a/src/content/docs/adventure/migration/adventure-4.x.md +++ b/src/content/docs/adventure/migration/adventure-4.x.md @@ -12,7 +12,7 @@ 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.Internal` has now been made sealed. +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. @@ -73,9 +73,9 @@ This section documents the removals that have been made and how you can migrate 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 progress has been removed.**\ - This includes the max/min progress constants and methods to change/get the progress. - You should instead be using the percent constants/methods. +* **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.**\