Chat

Minecraft supports two-way chat communication via the Chat Message packet, which support a variety of formatting options. Note that this system isn't exclusive to the Chat Message packet - it's used in several other places (including written books, death messages, window titles, and the like).

Current system (JSON Chat)
Chat data is sent in JSON. For most situations, the JSON is strictly parsed, but lenient JSON parsing is used for the Disconnect packet and for written book text.

Inheritance
Each component can have multiple siblings. Each sibling component inherits properties from the style of its parent, using those styles if they are not defined in the sibling's own style.

For example, in this component:

The text "foo", "bar", and "qux" are all rendered as bold while "baz" is not.

Schema
Each situation where a component can appear may be either a JSON object (the most common choice), an array, or a JSON primitive (which is converted to a String).

JSON primitives can be used for components, in which case they are implicitly converted into a String component. Note that it is invalid to have a JSON primitive as the root object, so it is not valid to merely send the text in quotes. This shorthand is useful for sibling lists, though.

It is also legal to put a JSON array where a component would go, so long as the array is not empty. The first component in the array is the parent of all of the following components. This can produce unusual behavior with style inheritance, but it is still useful shorthand.

The most common type of component is a JSON object; the format is as follows:

Shared between all components
All component types have certain fields that represent the style. All of these fields may be skipped, in which case the parent's style will be inherited.


 * Boolean - if, the component is emboldened.
 * Boolean - if, the component is emboldened.


 * Boolean - if, the component is italicized.
 * Boolean - if, the component is italicized.


 * Boolean - if, the component is underlined.
 * Boolean - if, the component is underlined.


 * Boolean - if, the component is struck out.
 * Boolean - if, the component is struck out.


 * Boolean - if, the component randomly switches between characters of the same width.
 * Boolean - if, the component randomly switches between characters of the same width.


 * String - contains the color for the component. Should be one of the normal colors, but can also be a format code (however, the fields relating to styles should be used instead for that purpose).  If not present (or set to  ), then the default color for the text will be used, which varies by the situation (in some cases, it is white; in others, it is black; in still others, it is a shade of gray that isn't normally used on text).
 * String - contains the color for the component. Should be one of the normal colors, but can also be a format code (however, the fields relating to styles should be used instead for that purpose).  If not present (or set to  ), then the default color for the text will be used, which varies by the situation (in some cases, it is white; in others, it is black; in still others, it is a shade of gray that isn't normally used on text).


 * String - contains text to insert. Only used for messages in chat.  When shift is held, clicking the component inserts the given text into the chat box at the cursor (potentially replacing selected text).  Has no effect on other locations at this time.
 * String - contains text to insert. Only used for messages in chat.  When shift is held, clicking the component inserts the given text into the chat box at the cursor (potentially replacing selected text).  Has no effect on other locations at this time.


 * JSON object - Defines an event that occurs when this component is clicked. Contains an   key and a   key.    is internally handled as a String, although it can be any type of JSON primitive.
 * Opens the given URL in the default web browser. Ignored if the player has opted to disable links in chat; may open a GUI prompting the user if the setting for that is enabled.  The link's protocol must be set and must be   or , for security reasons.
 * Cannot be used within JSON chat . Opens a link to any protocol, but cannot be used in JSON chat for security reasons.  Only exists to internally implement links for screenshots.
 * Runs the given command. Not required to be a command - clicking this only causes the client to send the given content as a chat message, so if not prefixed with , they will say the given text instead.  If used in a book GUI, the GUI is closed after clicking.
 * No longer supported; cannot be used within JSON chat . Only usable in 1.8 and below; twitch support was removed in 1.9.  Additionally, this is only used internally by the client.  On click, opens a twitch user info GUI screen.  Value should be the twitch user name.
 * Only usable for messages in chat. Replaces the content of the chat box with the given text - usually a command, but it is not required to be a command (commands should be prefixed with  ).
 * Only usable within written books. Changes the page of the book to the given page, starting at 1.  For instance,   switches the book to the first page.  If the page is less than one or beyond the number of pages in the book, the event is ignored.
 * Runs the given command. Not required to be a command - clicking this only causes the client to send the given content as a chat message, so if not prefixed with , they will say the given text instead.  If used in a book GUI, the GUI is closed after clicking.
 * No longer supported; cannot be used within JSON chat . Only usable in 1.8 and below; twitch support was removed in 1.9.  Additionally, this is only used internally by the client.  On click, opens a twitch user info GUI screen.  Value should be the twitch user name.
 * Only usable for messages in chat. Replaces the content of the chat box with the given text - usually a command, but it is not required to be a command (commands should be prefixed with  ).
 * Only usable within written books. Changes the page of the book to the given page, starting at 1.  For instance,   switches the book to the first page.  If the page is less than one or beyond the number of pages in the book, the event is ignored.
 * Only usable for messages in chat. Replaces the content of the chat box with the given text - usually a command, but it is not required to be a command (commands should be prefixed with  ).
 * Only usable within written books. Changes the page of the book to the given page, starting at 1.  For instance,   switches the book to the first page.  If the page is less than one or beyond the number of pages in the book, the event is ignored.
 * Only usable within written books. Changes the page of the book to the given page, starting at 1.  For instance,   switches the book to the first page.  If the page is less than one or beyond the number of pages in the book, the event is ignored.


 * JSON object - Defines an event that occurs when this component hovered over. Contains an   key and a   key; action is a String and value is a text component.  However, since text components can be serialized as primitives as well as arrays and objects, this can directly be a String.  A list of actions:
 * The text to display. Can either be a string directly  or a full component.
 * The NBT of the item to display, in the JSON-NBT format (as would be used in ).  Note that this is a String and not a JSON object - it should either be set in a String directly  or as text of a component .  If the item is invalid, "Invalid Item!" will be drawn in red instead.
 * A JSON-NBT String describing the entity. Contains 3 values: , the entity's UUID (with dashes);   (optional), which contains the resource location for the entity's type (eg  ); and  , which contains the entity's custom name (if present).  Note that this is a String and not a JSON object.  It should be set in a String directly  or as the content of a component.  If the entity is invalid, "Invalid Entity!" will be displayed.  Note that the client does not need to have the given entity loaded.
 * No longer supported . Since 1.12, this no longer exists; advancements instead simply use  .  The ID of an achievement or statistic to display.  Example:.
 * The NBT of the item to display, in the JSON-NBT format (as would be used in ).  Note that this is a String and not a JSON object - it should either be set in a String directly  or as text of a component .  If the item is invalid, "Invalid Item!" will be drawn in red instead.
 * A JSON-NBT String describing the entity. Contains 3 values: , the entity's UUID (with dashes);   (optional), which contains the resource location for the entity's type (eg  ); and  , which contains the entity's custom name (if present).  Note that this is a String and not a JSON object.  It should be set in a String directly  or as the content of a component.  If the entity is invalid, "Invalid Entity!" will be displayed.  Note that the client does not need to have the given entity loaded.
 * No longer supported . Since 1.12, this no longer exists; advancements instead simply use  .  The ID of an achievement or statistic to display.  Example:.
 * No longer supported . Since 1.12, this no longer exists; advancements instead simply use  .  The ID of an achievement or statistic to display.  Example:.
 * No longer supported . Since 1.12, this no longer exists; advancements instead simply use  .  The ID of an achievement or statistic to display.  Example:.


 * An array of sibling components. If present, cannot be empty.
 * An array of sibling components. If present, cannot be empty.

Beyond that, there are additional properties. Attempt to parse as each of the following in the order they are described:

String component
A String component contains only text. If the JSON contains a  key, then the component is a String component. The only content of this component is its text, with no additional processing.

Translation component
Translates text into the current language. If the JSON contains a  key, then the component is a translation component.

Translation supports  and   format tokens. is just an escaped percent symbol. marks text to replace using content from the optional  tag. is an array of components.

As a special case, if the translation key is, it will be changed to   when passed to narrator (although it will remain as   in chat).

Keybind component
Displays the client's current keybind for the specified key. If the component contains a  key, then it is a keybind component. The value is named after the keys in (for instance, for   in options.txt,   would be used in the component and W would be displayed). For keys that are not known, the value provided should be displayed instead (for instance  would remain as  ).

Score component
Displays a score. If the JSON contains a  key, then the component is a score component.

The  JSON object contains data about the objective.

When being sent to the client, it must contain,  , and   keys. is a player username or entity UUID (if it is a player, it is a username);  is the name of the objective;   is the resolved value of that objective.

When being sent to the server,  is not used. can be an entity selector (that selects one entity), or alternatively  which matches the sending player.

Selector component
Displays the results of an entity selector. Should not be sent to clients; only intended for commands and client-to-server actions. If the component contains a  key, then it is a selector component.

The server resolves the list selector into a list of entities, each with an appropriate hover event, joined with commas between each entry, without an "and".

Examples
Here are some examples from the Notchain server for how chat formatting can be used.

TODO - additional examples

Standard chat message
The normal chat message uses a translation component along with some styling.

The  translation key becomes , which is then filled in with the player's name and the actual message. Note that the player's name has a click event (which inserts text to message the player), a hover event (which shows the entity ID; also note that  is missing), and an insertion (for the player's name).

Control Sequences
The client treats certain two-character sequences specially. The first character must be:


 * § (U+00A7) for minecraft
 * & for minecraft classic

The following character indicates a certain color or formatting to apply to the proceeding text.

The Notchian classic client expects that an escape code in a chat message will be followed by at least one character, and will otherwise crash with a StringIndexOutOfBoundsException. The workaround for servers is to never end a message with a color control character. This is not an issue for the modern Notchian client.

Colors
These correspond very roughly to the colors available in ANSI terminals.

e.g.:



Styles
Like the color codes above, style escape codes are created by combining § (U+00A7) with one of the following characters. Style codes can be combined (except for "r") to enable multiple effects at once. Using any color codes will reset the current style back to plain (unknown if this is a bug or intended behavior). The "r" plain style code will also reset the current chat color back to white (may also be a bug). The "k" random style code is used for the "§kFUNKY LOL" message in /title/splashes.txt inside minecraft.jar.

Processing chat
Actually handling chat between the client and server is slightly more complicated than simply forwarding chat messages to other players. There's a somewhat complicated interaction regarding the chat settings of each player and whether it is a command or not, which is used to handle the various options in chat settings (specifically, Chat: Shown/Commands Only/Hidden, and the equivalent for narrator).

This is made more complicated by the two different enums, one which represents client settings and the other which represents chat positions.

The client setting (as used in the Client Settings packet) is what the player chose to have displayed, and affects what types of chat messages the server should send:

The message type (as used in the Chat Message packet) indicates the type of chat message:

Note that it is the server's responsibility to not send packets if the client has the given type disabled. However, it is the client's responsibility to not send incorrect chat packets.

Here's a matrix comparing what packets the server should send to the client by settings:

Here's a matrix comparing what the client may send based off of its chat setting:

If the client attempts to send a chat message and the server rejects it, the Notchian server will send that client a red  translation component (which becomes "Cannot send chat message"). Else, if it starts with a, then the message is processed as a command. Otherwise, it will broadcast a translate component with  (which becomes  ), with the player's name (and the appropriate hover events) as the first format parameter and the message as the second parameter.

Font
Minecraft has two fonts types that can be encountered normally: Ascii and Unicode. The ascii font will fall back upon unicode characters if they are not provided (see below). However, use of the Unicode font can be forced for all characters in the language menu.

There is no glyph for the space character. However, the space character has a width of 4.

Additionally, Minecraft has a Standard Galactic Alphabet font. This cannot be used in chat, but works much the same as the normal Ascii font in terms of width. The SGA font only supports lowercase and uppercase letters (the rest of the glyphs are blank), and has the same indexing as the normal ascii font.

The Minecraft client calculates the widths of the default font when the texture is loaded, whilst the sizes of the unicode type are provided in. Each byte in  contains the start and end position of each character, the top nibble (0xF0) is the start position and the bottom nibble (0x0F) is the end position (relative to the character's position in the font sheet). Example: https://gist.github.com/TkTech/dff9bbe54c9a074612e1

The Ascii font supports these characters, with the given indexes in :