adventure: a server-side user interface library for Minecraft Java Edition

One library, but not one dependency

The description is a single line, a serverside user interface library for Minecraft: Java Edition, and the repository layout shows how much of the design that hides. The top level is not a single source directory but a set of separate Gradle modules, and the names describe the whole architecture of the library. There is an api module, a bom, a key module, an nbt module, a javadoc module, an annotation-processors directory and a build-logic directory. Then there is the text half, split by format rather than by function: text-minimessage, text-serializer-ansi, text-serializer-plain, text-serializer-commons, text-serializer-gson, text-serializer-json, text-serializer-json-legacy-impl and text-serializer-legacy, plus a text-logger-slf4j module and a serializer-configurate4 module. The consequence for a consumer is that depending on the whole project is not the intended usage. You take the api and the one serializer that matches the format you actually send, and the rest stays out of your dependency tree.

The serializer modules are the real decision

The serializer list is where a server-side interface actually lives, and the names map onto concrete formats. There is a plain text serializer, an ANSI serializer, a GSON serializer for JSON, a JSON serializer, a legacy JSON implementation and a legacy serializer module, plus a commons module that the others build on. Choosing between them is choosing how your text reaches the client, and the two legacy modules exist because older clients and older protocol versions need a different representation. The serializer-configurate4 module points at a configuration library being supported directly, which tells you that the JSON path is meant to be configured rather than hand-built. The text-minimessage module sits alongside them, which is the format that lets you express styled text in a compact markup rather than a sequence of chat component objects. Whether a project picks the plain serializer, the ANSI one or the JSON ones depends on what its clients understand, and the documentation is where that decision is documented.

NBT and the key module cover the newer protocol surface

Two modules exist for parts of the protocol that are not text at all. The nbt module is the named binary tag support, which is how modern Minecraft clients receive structured data rather than chat text, and the repository topics list minecraft-nbt alongside the JSON one, so the two are the two data encodings in play. The key module sits alongside them and is the piece for the key-based mechanisms in the protocol. Both are relevant to the same audience: a server sending structured items or components to clients has to deal with NBT and with keys, and a library that isolates them in their own modules means a plugin that only sends chat text does not carry them. The api module is what everything else is written against, and it is the module that carries the component and audience model that the rest of the library renders or serialises.

A 5.x line built on Gradle with JDK 21 as the floor

The build requirements are stated plainly. All the Adventure projects are built with Gradle, require at least JDK 21, and use a common checkstyle configuration. The repository root shows the Gradle machinery in full, with a gradlew and gradlew.bat, a gradle directory, a build.gradle.kts, a settings.gradle.kts, a gradle.properties and a build-logic directory, which is the convention for sharing convention plugins across a multi-module build. There is also a .spotless directory and an .editorconfig, so formatting is enforced by tooling rather than by review comments, and a .checkstyle directory holding the shared configuration that every project in the family uses. The default branch is main/5, which tells you the current development line is the 5.x one and that the branch naming is not the usual main.

Published to Maven Central under net.kyori

The distribution story matters for a library that plugins depend on. The Maven Central badge points at a search for the net.kyori group and the adventure artefact pattern, and the stable version label is attached to the adventure-api artefact, so the api module is the one with the version most consumers track. A second badge points at the Maven metadata for the adventure-api artefact in the Sonatype snapshots repository, labelled as dev, so there is a snapshot feed alongside the stable releases. The Javadoc badge points at jd.papermc.io, a PaperMC-hosted Javadoc browser covering the project rather than the default Maven Central one, which is a nicer thing to link to from a plugin's documentation. The release history is steady, with 5.2.0 in June 2026, 5.1.1 in May and 5.1.0 a day earlier. The bom module lists the adventure modules and their versions together, which is how a project pins a consistent set of them in a larger dependency tree.

Contributing means talking first, then passing three checks

The contributing guidance is short and the order matters. Contributions of any type are welcome, but for any new feature or even a typo fix or style change you are asked to open an issue or come to a specific channel on the PaperMC Discord first, so the maintainers can make sure you are going in the right direction for the project. The channel is named for adventure contributions, and there is a general PaperMC Discord invite alongside it. Once the change is made, the checklist is that all the tests pass, the license headers are updated, and checkstyle passes, to help the review. The license header point is the one that catches people out, because the repository carries both a license.txt and a separate license_header.txt, so a new file needs the right header text rather than a general mention. The project is released under the MIT License, and renovate.json at the root means dependency updates are proposed automatically rather than by hand.

What this library is not

It is worth being clear about the scope, because the word interface in a Minecraft context can mean several things. This is a server-side library, so it is for the plugin or proxy that runs on the server and sends things to players. It is not a client-side rendering library, and it is not a mod, so it does not change the game itself. The repository topics are a useful sanity check on that, listing java, json, minecraft, minecraft-java-edition, minecraft-nbt, papermc and user-interface, with no mod loader anywhere in the list. A related consequence is the version coupling: the library tracks the protocol and the client versions it supports, so a project that targets an unusual mix of client versions needs to check the compatibility notes in the documentation rather than assume the latest release is right for everyone. That is also why the module split exists, since different pieces of the library can move at different rates as the protocol evolves.

Editorial conclusion

adventure suits a plugin or proxy developer who sends formatted text, JSON, or NBT to Minecraft clients and wants one API for the modern protocol instead of ad-hoc packet work. It does not suit a Minecraft mod, since the library is server side, and it does not suit a team that wants one artefact to depend on, because the module split means choosing components deliberately. Before you adopt it, read the documentation for the dependency information, decide which text serializer and which protocol versions you need, and check the branch you are on, since the repository's default branch is main/5 rather than main.

Frequently asked questions

Official sources

1. License: MIT
2. PaperMC/adventure on GitHub
3. Project website
4. README
5. Releases