Adventure 5.0

astro.config.ts

@@ -446,10 +446,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",
                   ],
                 },

src/content/docs/adventure/migration/adventure-4.x.md

@@ -0,0 +1,138 @@
+---
+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.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.
+
+## Updated dependencies
+
+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.
+
+## 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.
+
+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.
+
+### Component renderer changes
+
+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.
+
+### Sealing of `TextFormat` interface
+
+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.
+
+### Chat type changes
+
+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`.
+
+## 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 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.

src/content/docs/adventure/migration/index.md

@@ -1,15 +1,20 @@
 ---
-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)
+  * [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)
   * [Audiences](/adventure/migration/bungeecord-chat-api#audiences)
   * [Decoration and styling](/adventure/migration/bungeecord-chat-api#decoration-and-styling)

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
 

src/utils/versions.ts

@@ -86,7 +86,7 @@ export const LATEST_USERDEV_RELEASE = userdevVersions[0];
 
 export const LATEST_ADVENTURE_SUPPORTED_MC = "1.21.11";
 export const LATEST_ADVENTURE_SUPPORTED_MC_RANGE = LATEST_ADVENTURE_SUPPORTED_MC;
-export const LATEST_ADVENTURE_API_RELEASE = "4.26.1";
+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.8.0";
 export const LATEST_ANSI_RELEASE = "1.1.1";