Chat

Minecraft supports two-way chat communication via the Player 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).

Heads up! Currently out of date. 1.20.3+ encodes the JSON Chat into NBT in most cases when sent over the network (indicated via the Chat and Json Chat data types). How its converted in both directions needs to be documented.

Current system (JSON Chat)

Chat data is sent in a JSON structure called a text component. For most situations, the JSON is strictly parsed, but lenient JSON parsing is used for the Disconnect packet and for written book text.

In any situation where a text component is expected, it may be either a string, an array, or an object (the most common choice).

A component specified as a string is interpreted equivalently to {"text":"string"}.

A component specified as an array is interpreted as the first element of the array, with the rest of the elements then appended to the component's extra field. This can produce unusual behavior with style inheritance, but it is still useful shorthand.

A component specified as an object must contain the field(s) corresponding to its content type, and may additionally contain any number of the common fields listed below.

Content types

The content type of a component specifies what kind of direct content it includes. The full content of a component is the concatenation of its direct content, and the full contents of all its child components (elements of the extra field), in that order.

If the component includes a type field, it specifies the component's content type. Otherwise, each of the content types is tried in the listed order until one for which the component is valid is found.

The following content types are defined:

Type	Resolved By
text	Client
translatable	Client
keybind	Client
score	Server
selector	Server
nbt	Server

Content types marked as Resolved By Server are resolved server-side, e.g. in response to commands, and need not be implemented by clients.

Fields common to all content types

type

Optional String. The content type of this component.

extra

Optional Array of Text Component. The child components of this component. If present, cannot be empty. Somewhat confusingly, these may also be thought of as siblings to the direct content of their parent component. Each child component inherits properties from the style of its parent, using those styles if they are not defined in the child's own style.

color

Optional String. The text color, which may be a color name or a #-prefixed hexadecimal RGB specification. See #Colors below.

bold, italic, underlined, strikethrough, obfuscated

Optional Boolean. Enables or disables the given style. See #Styles below.

font

Optional String. See #Fonts below. This option is only valid on 1.16+; otherwise the property is ignored.

insertion

Optional String. Text to be inserted into chat at the cursor when shift-clicked. Only used for messages in chat; has no effect in other locations at this time.

clickEvent

Optional Object. Defines an event that occurs when this component is clicked. Contains the fields action and value, both strings. action may be one of the following:

open_url

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 http or https, for security reasons.

open_file

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.

run_command

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.

twitch_user_info

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.

suggest_command

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 /).

change_page

Only usable within written books. Changes the page of the book to the given page, starting at 1. For instance, "value":"1" 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.

copy_to_clipboard

Copies the given text to the client's clipboard when clicked.

hoverEvent

Optional Object. Defines an event that occurs when this component hovered over. Contains the fields action (a string) and contents (dependent on action). action may be one of the following:

show_text

Displays a tooltip with arbitrary text. contents can either be a string directly ("contents":"la") or a full component ("contents":{"text":"la","color":"red"}).

show_item

Displays a tooltip describing an item. contents contains the following fields:

id

String. The textual identifier of the item's type. If unrecognized, defaults to minecraft:air.

count

Integer. The number of items in the item stack. If omitted, defaults to 1.

tag

Optional String. The item's NBT information as sNBT (as would be used in /give).

show_entity

Displays a tooltip describing an entity. Shown only if Advanced tooltips (F3+H) is enabled. contents contains the following fields:

type

String. The textual identifier of the entity's type. If unrecognized, defaults to minecraft:pig.

id

String. The entity's UUID (with dashes). Does not need to correspond to an existing entity; only for display.

name

Optional String. The entity's custom name.

show_achievement

No longer supported. Since 1.12, this no longer exists; advancements instead simply use show_text. The ID of an achievement or statistic to display. Example: "value":"achievement.openInventory".

The content field was introduced in Minecraft 1.16, replacing the old value field, which is still supported by new versions for compatibility. value functioned similarly to content, but was always interpreted as a chat component, with show_item and show_entity data represented as sNBT (e.g. "value":"{id:35,Damage:5,Count:2,tag:{display:{Name:Testing}}}").

Text content

text

String. Set as the content directly, with no additional processing.

Translatable content

translate

String. A translation key, looked up in the current language file to obtain a translation text, which becomes the component's content after processing (see below).

with

Optional Array of Text Component. Replacements for placeholders in the translation text.

The translation text may contain any number of the placeholder tokens %s, %n$s (where n is a one-based index) and %%.

Each %s is replaced by the element of with corresponding to the placeholder's index among all %s's (excluding %n$s) in the string.

Each %n$s is replaced by the nth element of with.

Each %% is replaced by a literal % symbol.

Any out-of-bounds or otherwise invalid placeholders are simply left intact in the output.

If the translation key is unrecognized, it itself becomes the translation text, which then has placeholder replacement performed on it as usual.

	The following information needs to be added to this page:
	Is the replacement behavior with an unrecognized key intended or buggy?

Prior to 1.19.1 the narrator was hardcoded to replace the translation key chat.type.text with chat.type.text.narrate. This mechanism has been superseded by chat types, and is no longer present in new versions.

Keybind content

keybind

String. The name of a keybinding. The client's current setting for the specified keybinding becomes the component's content.

The value is named after the keys in options.txt (for instance, for key_key.forward in options.txt, key.forward 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 key.invalid would remain as key.invalid).

Score content

score

Object. Contains the following fields:

name

String. A player username, player or entity UUID, entity selector (that selects one entity), or * to match the sending player.

objective

String. The name of the objective.

Resolved by the server into text content containing the value of objective for name, or the empty string if none exists.

This content type must be resolved by the server, and will be displayed as empty text if sent directly to a client.

Selector content

selector

String. An entity selector.

separator

Optional Text Component. Separator to place between results. If omitted, defaults to {"color":"gray","text":", "}.

Resolved by the server into a delimited list of entities matching the selector, each with an appropriate hover event (and click event if it happens to be a player).

This content type must be resolved by the server, and will be displayed as the selection pattern if sent directly to a client.

NBT content

nbt

String. NBT path to be queried.

interpret

Optional Boolean. If true, the server will attempt to parse and resolve each result as (an NBT string containing) a text component for display. If omitted, defaults to false.

separator

Optional Text Component. Separator to place between results. If omitted, defaults to {"text":", "}.

Additionally, exactly one of the following fields specifying the data source must be present:

block

String. Location of a block entity to be queried, in the usual space-separated coordinate syntax with support for ~ and ^.

entity

String. Selector specifying the set of entities to be queried.

storage

String. Identifier specifying the storage to be queried.

Resolved by the server into a delimited list of all NBT values, for all objects specified by the data source, matching the specified path.

This content type must be resolved by the server, and will be displayed as empty text if sent directly to a client.

Examples

Inheritance

In this component:

{
    "text": "foo",
    "bold": true,
    "extra": [
        {
            "text": "bar"
        },
        {
            "text": "baz",
            "bold": false
        },
        {
            "text": "qux",
            "bold": true
        }
    ]
}

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

Standard chat message

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

Since 1.19.1 the Notchian client uses the chat type mechanism, meaning chat messages are no longer sent directly like shown in this example.

{"translate":"chat.type.text","with":[{"text":"Herobrine","clickEvent":{"action":"suggest_command","value":"/msg Herobrine "},"hoverEvent":{"action":"show_entity","value":"{id:f84c6a79-0a4e-45e0-879b-cd49ebd4c4e2,name:Herobrine}"},"insertion":"Herobrine"},{"text":"I don't exist"}]}

The chat.type.text translation key becomes <%s> %s, 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 type is missing), and an insertion (for the player's name).

Old system

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.

e.g.: This is white, but §4this is dark red. §lThis is still red, but also bold, while §rthis is neither.

In Minecraft Classic, the Notchian 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 server must sanitize outbound messages by removing any control characters at the end.

Styling

Colors

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

Hex digit to color mapping

1. REDIRECT Text formatting/ColorSample

Sample	Common Name	Legacy Code	JSON Name	Foreground Color				Background Color
				R	G	B	Hex	R	G	B	Hex
Black	0	black	0	0	0	#000000	0	0	0	#000000
	Dark blue	1	dark_blue	0	0	170	#0000aa	0	0	42	#00002a
	Dark green	2	dark_green	0	170	0	#00aa00	0	42	0	#002a00
	Dark cyan	3	dark_aqua	0	170	170	#00aaaa	0	42	42	#002a2a
	Dark red	4	dark_red	170	0	0	#aa0000	42	0	0	#2a0000
	Purple	5	dark_purple	170	0	170	#aa00aa	42	0	42	#2a002a
	Gold	6	gold	255	170	0	#ffaa00	42	42	0	#2a2a00
	Gray	7	gray	170	170	170	#aaaaaa	42	42	42	#2a2a2a
	Dark gray	8	dark_gray	85	85	85	#555555	21	21	21	#151515
	Blue	9	blue	85	85	255	#5555ff	21	21	63	#15153f
	Bright green	a	green	85	255	85	#55ff55	21	63	21	#153f15
	Cyan	b	aqua	85	255	255	#55ffff	21	63	63	#153f3f
	Red	c	red	255	85	85	#ff5555	63	21	21	#3f1515
	Pink	d	light_purple	255	85	255	#ff55ff	63	21	63	#3f153f
	Yellow	e	yellow	255	255	85	#ffff55	63	63	21	#3f3f15
	White	f	white	255	255	255	#ffffff	63	63	63	#3f3f3f

Starting with Minecraft 1.16 the JSON color field may also be specified as an arbitrary RGB color in the usual hexadecimal format #RRGGBB. The part after # may also be shorter than 6 digits, but is then interpreted simply as the rightmost digits of the full 6-digit value, with the rest taken to be zero—there is no compacted 3-digit variant or support for transparency.

Styles

The "Random" style is used for the "§kFUNKY LOL" message in /title/splashes.txt inside minecraft.jar.

Sample	Style	Legacy Code	JSON Name
	Random	k	obfuscated
	Bold	l	bold
	Strikethrough	m	strikethrough
	Underlined	n	underline
	Italic	o	italic
	Plain White	r	reset

Fonts

Since Minecraft 1.16 it has been possible to add custom fonts via resource packs, and use them in text components through the font field.

By default, the following fonts are available:

Identifier	Default Look	Notes
minecraft:default	Standard Minecraft font (with Unifont fallback)	Default font. Hardcoded to alias minecraft:uniform when Force Unicode Font is enabled.
minecraft:uniform	GNU Unifont	Default font when Force Unicode Font is enabled.
minecraft:alt	Standard Galactic Alphabet	Enchanting table font.
minecraft:illageralt	Illageralt from Minecraft Dungeons	Unused.

Processing chat

Client chat mode

The client may use the Chat Mode field of the Client Information packet to indicate that it only wants to receive some types of chat messages.

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 a clients based on their chat settings:

Clientbound packet	Client setting			Usage
	Full	Commands only	Hidden
Player Chat Message	✔	✘	✘	Player-initiated chat messages, including the commands /say, /me, /msg, /tell, /w and /teammsg.
Disguised Chat Message	✔	✘	✘	Messages sent by non-players using the commands /say, /me, /msg, /tell, /w and /teammsg.
System Chat Message	✔	✔	✘	Feedback from running a command, such as "Your game mode has been updated to creative."
System Chat Message (overlay)	✔	✔	✔	Game state information that is displayed above the hot bar, such as "You may not rest now, the bed is too far away".

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

Serverbound packet	Client setting
	Full	Commands only	Hidden
Chat Message	✔	✘	✘
Chat Command	✔	✔	✘

If the client attempts to send a chat message and the server rejects it, the Notchian server will send that client a System Chat Message (non-overlay) with a red chat.disabled.options translation component (which becomes "Chat disabled in client options.").

Social Interactions (blocking)

1.16 added a social interactions screen that lets players block chat from other players. Blocking takes place clientside by detecting whether a message is from a blocked player.

Player Chat Message packets are blocked based on the included sender UUID.

Disguised Chat Message packets are never blocked.

System Chat Message packets (regardless of the Overlay field!) are blocked based on the first occurrence of <playername> anywhere in the message, including split across multiple chat components, where playername may be any text, including the empty string or whitespace. If playername is the name of a blocked player (matched case-sensitively), the message is blocked. This only occurs if Hide Matched Names is enabled in Chat Settings (the default).