This documentation page applies to both the Paper and Velocity projects
Since Minecraft 1.7, the game has utilized components to represent text to be displayed by clients. Components offer a number of benefits over plain text strings which are enumerated below. Paper and Velocity natively implements the Adventure API to add component support wherever possible.
Why you should use Components
Previously, text was a linear structure with the only formatting options being
confusing symbols like
§k to control basic colors and styles of text.
Components are a tree-like structure which inherit style and colors from their parents.
Components have several types which do different things than just display raw text, like translating text to the client's language based on a key, or showing a client-specific keybind to a player.
All these component types support more style options like any RGB color, interaction events (click and hover). The other component types and these style options have poor or missing representations in the legacy string format.
Representing text as Components is now the supported way of representing text for Paper and Velocity. They are used
for almost all aspects of text being displayed to clients. Text like item names, lore, boss bars, team prefixes and
suffixes, custom names, and much more all support Components in respective APIs.
Mojang has stated
that client support for the legacy format with
§ will be removed in the future.
In the Paper API, there are lots of deprecated methods and types that deal with this legacy format. This is to signal that a better alternative in Components is available and should be migrated to going forward.
Components can be interacted with as objects. There are different interfaces for each type along with builders for all the types. These objects are immutable so when constructing more complex components, it's recommended to use builders to avoid creating new Component instances with every change.
// This is a sub-optimimal construction of the
// component as each change creates a new component
final Component component = Component.text("Hello")
.append(Component.text(" world!", NamedTextColor.GREEN));
/* This is an optimal use of the builder to create
the same component. Also note that Adventure
Components are designed for use with static method imports
to make code less verbose */
final Component component = text()
.append(text(" world!", GREEN))
For complete documentation on the Adventure Component API Paper and Velocity use, please look at the Adventure documentation.
Paper and Velocity include the MiniMessage library which is a string representation of components. If you prefer working with strings rather than objects, MiniMessage is vastly superior to the legacy string format. It can utilize the tree structure for style inheritance and can represent the more complex component types while legacy cannot.
final Component component = MiniMessage.miniMessage().deserialize(
"<#438df2><b>This is the parent component; its style is " +
"applied to all children.\n<u><!b>This is the first child, " +
"which is rendered after the parent</!b></u><key:key.inventory></b></#438df2>"
We recommend using this format for user-facing input such as commands or configuration values.
MiniMessage is a part of Adventure, and you can find its documentation on Adventure's documentation.
MiniMessage has a WebViewer which is useful for constructing more complicated components and seeing the results in real time
Components can be serialized and deserialized from a standard JSON format. This format is used
in vanilla in various commands which accept component arguments like
/tellraw. Below is a simple example
of this format.
"text": "This is the parent component; its style is applied to all children.\n",
"text": "This is this first child, which is rendered after the parent",
// This overrides the parent's "bold" value just for this component
// This is a keybind component which will display the client's keybind for that action
The JSON format is fully documented on the Minecraft Wiki.
There are online tools to make generating this format much easier like JSON Text Generator.
Paper and Velocity come bundled with different serializers for converting between Components and other forms of serialized text.
Component and JSON-formatted strings with convenience methods to directly deal with gson
This conversion is lossless and is the preferred form of serialization
for components that do not have to be edited by users regularly.
Component and a MiniMessage-formatted string. This conversion is lossless and is the preferred form of
serialization for components that have to be edited by users. There is also extensive customization you can add to the
serializer which is documented here.
Component into a plain text string. This is very lossy as all style information as well as most other
types of components will lose information. There may be special handling for
TranslatableComponents to be serialized
into a default language but generally this shouldn't be used except in certain circumstances like logging to a text file.
This is not recommended for use as the legacy format may be removed in the future.
Component and the legacy string format. This conversion is very lossy as component types and events
do not have a legacy string representation.
A more useful use case is converting legacy text to MiniMessage format in a migration process.
final String legacyString = ChatColor.RED + "This is a legacy " + ChatColor.GOLD + "string";
// this just runs the legacy string through two serializers to
final String miniMessageString = MiniMessage.miniMessage().serialize(
There are 2 built in legacy serializers, one dealing with
§ symbols and the other for
& symbols. They have their own instances available with