Difference between revisions of "Chat"

From wiki.vg
Jump to navigation Jump to search
(Split off Text formatting.)
Line 1: Line 1:
Minecraft supports two-way '''chat''' communication via the [[Protocol#Player Chat Message|Player Chat Message]] packet, which support a variety of formatting options.
+
{{Hatnote|This page previously contained documentation on text formatting features, which can now be found at [[Text formatting]].}}
  
== Current system (text components) ==
+
This article details various features and considerations of Minecraft's chat system. The packets themselves are documented in [[Protocol]].
 
 
Formatted text appearing in many different contexts (including chat messages, written books, death messages, window titles, and the like) is encoded in a JSON structure called a text component. For most situations, the JSON is strictly parsed, but [https://www.javadoc.io/doc/com.google.code.gson/gson/latest/com.google.gson/com/google/gson/stream/JsonReader.html#setLenient(boolean) lenient JSON parsing] is used for the Disconnect packet and for written book text.
 
 
 
Versions 1.20.3 and later have the ability to encode text components into NBT as well, which is utilized in most cases when sending them over the network. This distinction is indicated via the [[Data types#Definitions:chat|Chat]] and [[Data types#Definitions:json_chat|Json Chat]] data types. Notchian Minecraft uses shared serialization logic for the two formats, so the conversions are mostly self-evident—objects correspond to compounds, etc. As in most contexts, any NBT integer type is accepted in place of an integer. Note, however, that NBT requires all elements of an array to have the same type, limiting flexibility.
 
 
 
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 <code>{"text":"''string''"}</code>.
 
 
 
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 <code>extra</code> 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 types|content type]], and may additionally contain any number of the [[#Fields common to all content types|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 <code>extra</code> field), in that order.
 
 
 
If the component includes a <code>type</code> 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:
 
 
 
{| class="wikitable"
 
! Type
 
! Resolved By
 
|-
 
| <code>[[#Text content|text]]</code>
 
| Client
 
|-
 
| <code>[[#Translatable content|translatable]]</code>
 
| Client
 
|-
 
| <code>[[#Keybind content|keybind]]</code>
 
| Client
 
|-
 
| <code>[[#Score content|score]]</code>
 
| Server
 
|-
 
| <code>[[#Selector content|selector]]</code>
 
| Server
 
|-
 
| <code>[[#NBT content|nbt]]</code>
 
| 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 ===
 
 
 
;<code>type</code>
 
:''Optional String''. The [[#Content types|content type]] of this component.
 
;<code>extra</code>
 
:''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 common fields other than <code>type</code> and <code>extra</code> from its parent, using their values for fields not defined on the child itself.
 
;<code>color</code>
 
:''Optional String''. The text color, which may be a color name or a #-prefixed hexadecimal RGB specification. See [[#Colors]] below.
 
;<code>bold</code>, <code>italic</code>, <code>underlined</code>, <code>strikethrough</code>, <code>obfuscated</code>
 
:''Optional Boolean''. Enables or disables the given style. See [[#Styles]] below.
 
;<code>font</code>
 
:''Optional String''. See [[#Fonts]] below. This option is only valid on 1.16+; otherwise the field is ignored.
 
;<code>insertion</code>
 
:''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.
 
;<code>clickEvent</code>
 
:''Optional Object''. Defines an event that occurs when this component is clicked.  Contains the fields <code>action</code> and <code>value</code>, both strings. <code>action</code> may be one of the following:
 
:;<code>open_url</code>
 
::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 <code>http</code> or <code>https</code>, for security reasons.
 
:;<s><code>open_file</code></s>
 
::<strong>Cannot be used within JSON chat</strong>.  Opens a link to any protocol, but cannot be used in JSON chat for security reasons.  Only exists to internally implement links for screenshots.
 
:;<code>run_command</code>
 
::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 <code>/</code>, they will say the given text instead.  If used in a book GUI, the GUI is closed after clicking.
 
:;<s><code>twitch_user_info</code></s>
 
::<strong>No longer supported; cannot be used within JSON chat</strong>.  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.
 
:;<code>suggest_command</code>
 
::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 <code>/</code>).
 
:;<code>change_page</code>
 
::Only usable within written books.  Changes the page of the book to the given page, starting at 1.  For instance, <code>"value":"1"</code> 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.
 
:;<code>copy_to_clipboard</code>
 
::Copies the given text to the client's clipboard when clicked.
 
;<code>hoverEvent</code>
 
:''Optional Object''. Defines an event that occurs when this component hovered over.  Contains the fields <code>action</code> (a string) and <code>contents</code> (dependent on <code>action</code>). <code>action</code> may be one of the following:
 
:;<code>show_text</code>
 
::Displays a tooltip with arbitrary text. <code>contents</code> can either be a string directly (<code>"contents":"la"</code>) or a full component (<code>"contents":{"text":"la","color":"red"}</code>).
 
:;<code>show_item</code>
 
::Displays a tooltip describing an item. <code>contents</code> contains the following fields:
 
::;<code>id</code>
 
:::''String''. The textual identifier of the item's type. If unrecognized, defaults to <code>minecraft:air</code>.
 
::;<code>count</code>
 
:::''Integer''. The number of items in the item stack. If omitted, defaults to 1.
 
::;<code>tag</code>
 
:::''Optional String''. The item's NBT information as sNBT (as would be used in <code>/give</code>)&mdash;even when the component is encoded as NBT!
 
:;<code>show_entity</code>
 
::Displays a tooltip describing an entity. Shown only if Advanced tooltips (F3+H) is enabled. <code>contents</code> contains the following fields:
 
::;<code>type</code>
 
:::''String''. The textual identifier of the entity's type. If unrecognized, defaults to <code>minecraft:pig</code>.
 
::;<code>id</code>
 
:::''String''. The entity's UUID (with dashes). Does not need to correspond to an existing entity; only for display.
 
::;<code>name</code>
 
:::''Optional String''. The entity's custom name.
 
:;<s><code>show_achievement</code></s>
 
::<strong>No longer supported</strong>.  Since 1.12, this no longer exists; advancements instead simply use <code>show_text</code>.  The ID of an achievement or statistic to display. Example: <code>"value":"achievement.openInventory"</code>.
 
<dd>{{Warning2|The <code>content</code> field was introduced in Minecraft 1.16, replacing the old <code>value</code> field, which is still supported by new versions for compatibility. <code>value</code> functioned similarly to <code>content</code>, but was always interpreted as a text component, with <code>show_item</code> and <code>show_entity</code> data represented as sNBT (e.g. <code><nowiki>"value":"{id:35,Damage:5,Count:2,tag:{display:{Name:Testing}}}"</nowiki></code>).}}</dd>
 
 
 
=== Text content ===
 
 
 
;<code>text</code>
 
:''String''. Set as the content directly, with no additional processing. (But see [[#Old system]], which still applies.)
 
 
 
=== Translatable content ===
 
 
 
;<code>translate</code>
 
:''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).
 
;<code>with</code>
 
:''Optional Array of Text Component''. Replacements for placeholders in the translation text.
 
 
 
The translation text may contain any number of the placeholder tokens <code>%s</code>, <code>%''n''$s</code> (where ''n'' is a one-based index) and <code>%%</code>.
 
 
 
Each <code>%s</code> is replaced by the element of <code>with</code> corresponding to the placeholder's index among all <code>%s</code>'s (excluding <code>%''n''$s</code>) in the string.
 
 
 
Each <code>%''n''$s</code> is replaced by the ''n''th element of <code>with</code>.
 
 
 
Each <code>%%</code> 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.
 
 
 
{{Need Info|Is the replacement behavior with an unrecognized key intended or buggy?}}
 
 
 
{{Warning2|Prior to 1.19.1 the narrator was hardcoded to replace the translation key <code>chat.type.text</code> with <code>chat.type.text.narrate</code>. This mechanism has been superseded by [[Registry Data#Chat Type|chat types]], and is no longer present in new versions.}}
 
 
 
=== Keybind content ===
 
 
 
;<code>keybind</code>
 
:''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 {{Minecraft Wiki|options.txt}} (for instance, for <code>key_key.forward</code> in options.txt, <code>key.forward</code> would be used in the component and <kbd>W</kbd> would be displayed).  For keys that are not known, the value provided should be displayed instead (for instance <code>key.invalid</code> would remain as <code>key.invalid</code>).
 
 
 
=== Score content ===
 
 
 
;<code>score</code>
 
:''Object''. Contains the following fields:
 
:;<code>name</code>
 
::''String''. A player username, player or entity UUID, entity selector (that selects one entity), or <code>*</code> to match the sending player.
 
:;<code>objective</code>
 
::''String''. The name of the objective.
 
 
 
Resolved by the server into text content containing the value of <code>objective</code> for <code>name</code>, or the empty string if none exists.
 
 
 
If sent directly to a client, will be displayed as empty text.
 
 
 
=== Selector content ===
 
 
 
;<code>selector</code>
 
:''String''. An entity selector.
 
;<code>separator</code>
 
:''Optional Text Component''. Separator to place between results. If omitted, defaults to <code>{"color":"gray","text":", "}</code>.
 
 
 
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).
 
 
 
If sent directly to a client, will be displayed as the selection pattern.
 
 
 
=== NBT content ===
 
 
 
;<code>nbt</code>
 
:''String''. NBT path to be queried.
 
;<code>interpret</code>
 
:''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.
 
;<code>separator</code>
 
:''Optional Text Component''. Separator to place between results. If omitted, defaults to <code>{"text":", "}</code>.
 
 
 
Additionally, exactly one of the following fields specifying the data source must be present:
 
 
 
;<code>block</code>
 
:''String''. Location of a block entity to be queried, in the usual space-separated coordinate syntax with support for <code>~</code> and <code>^</code>.
 
;<code>entity</code>
 
:''String''. Selector specifying the set of entities to be queried.
 
;<code>storage</code>
 
:''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.
 
 
 
If sent directly to a client, will be displayed as empty text.
 
 
 
=== Examples ===
 
 
 
==== Inheritance ====
 
 
 
In this component:
 
 
 
<syntaxhighlight lang="javascript">
 
{
 
    "text": "foo",
 
    "bold": true,
 
    "extra": [
 
        {
 
            "text": "bar"
 
        },
 
        {
 
            "text": "baz",
 
            "bold": false
 
        },
 
        {
 
            "text": "qux",
 
            "bold": true
 
        }
 
    ]
 
}
 
</syntaxhighlight>
 
 
 
"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.
 
 
 
{{Warning2|Since 1.19.1 the Notchian server uses the [[Registry Data#Chat Type|chat type]] mechanism, meaning chat messages are no longer sent directly like shown in this example.}}
 
 
 
<syntaxhighlight lang="javascript">
 
{"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"}]}
 
</syntaxhighlight>
 
 
 
The <code>chat.type.text</code> translation key becomes <code><nowiki><%s> %s</nowiki></code>, 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 <code>type</code> is missing), and an insertion (for the player's name).
 
 
 
== Old system ==
 
 
 
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 formatting change to apply to the proceeding text. It may be one of the [[#Colors|color]] or [[#Styles|style]] codes listed in their respective sections, or <code>r</code> to reset to default formatting.
 
 
 
e.g.: <code>This is white, but §4this is dark red. §lThis is still red, but also bold, while §rthis is neither.</code>
 
 
 
There is no way to escape the <code>§</code> or <code>&</code> symbol; the Notchian server and client simply disallow it in text originating from the player.
 
 
 
The Notchian client processes these formatting sequences in virtually all rendered text. Their effects are constrained to the specific run of text they're part of, and <code>§r</code> reverts back merely to the styling inherited from the surrounding context. In the context of text components, instances of <code>text</code> or <code>keybind</code> content are considered singular runs of text, whereas in <code>translatable</code> content each static (non-placeholder) segment is an individual run.
 
 
 
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.
 
 
 
[[File:Colors.png|thumb|Hex digit to color mapping]]
 
 
 
{| class="wikitable" style="text-align:center;" border="1" cellpadding="5"
 
|-
 
! colspan="1" rowspan="2" width="8px"| Sample
 
! colspan="1" rowspan="2" | Common Name
 
! colspan="1" rowspan="2" | Code
 
! colspan="1" rowspan="2" | Name
 
! colspan="4" | Foreground Color
 
! colspan="4" | Background Color
 
|-
 
! width="30px"|R
 
! width="30px"|G
 
! width="30px"|B
 
! Hex
 
! width="30px"|R
 
! width="30px"|G
 
! width="30px"|B
 
! Hex
 
|-
 
{{/ColorSample|000000|000000}}
 
| Black || 0 || <code>black</code> || 0 || 0 || 0 || #000000 || 0 || 0 || 0 || #000000
 
|-
 
{{/ColorSample|0000aa|00002a}}
 
| Dark blue || 1 || <code>dark_blue</code> || 0 || 0 || 170 || #0000aa || 0 || 0 || 42 || #00002a
 
|-
 
{{/ColorSample|00aa00|002a00}}
 
| Dark green || 2 || <code>dark_green</code> || 0 || 170 || 0 || #00aa00 || 0 || 42 || 0 || #002a00
 
|-
 
{{/ColorSample|00aaaa|002a2a}}
 
| Dark cyan || 3 || <code>dark_aqua</code> || 0  || 170 || 170 || #00aaaa || 0 || 42 || 42 || #002a2a
 
|-
 
{{/ColorSample|aa0000|2a0000}}
 
| Dark red || 4 || <code>dark_red</code> || 170 || 0 || 0 || #aa0000 || 42 || 0 || 0 || #2a0000
 
|-
 
{{/ColorSample|aa00aa|2a002a}}
 
| Purple || 5 || <code>dark_purple</code> || 170 || 0 || 170 || #aa00aa || 42 || 0 || 42 || #2a002a
 
|-
 
{{/ColorSample|ffaa00|2a2a00}}
 
| Gold || 6 || <code>gold</code> || 255 || 170 || 0 || #ffaa00 || 42 || 42 || 0 || #2a2a00
 
|-
 
{{/ColorSample|aaaaaa|2a2a2a}}
 
| Gray || 7 || <code>gray</code> || 170 || 170 || 170 || #aaaaaa || 42 || 42 || 42 || #2a2a2a
 
|-
 
{{/ColorSample|555555|151515}}
 
| Dark gray || 8 || <code>dark_gray</code> || 85 || 85 || 85 || #555555 || 21 || 21 || 21 || #151515
 
|-
 
{{/ColorSample|5555ff|15153f}}
 
| Blue || 9 || <code>blue</code> || 85 || 85 || 255 || #5555ff || 21 || 21 || 63 || #15153f
 
|-
 
{{/ColorSample|55ff55|153f15}}
 
| Bright green || a || <code>green</code> || 85 || 255 || 85 || #55ff55 || 21 || 63 || 21 || #153f15
 
|-
 
{{/ColorSample|55ffff|153f3f}}
 
| Cyan || b || <code>aqua</code> || 85 || 255 || 255 || #55ffff || 21 || 63 || 63 || #153f3f
 
|-
 
{{/ColorSample|ff5555|3f1515}}
 
| Red || c || <code>red</code> || 255 || 85 || 85 || #ff5555 || 63 || 21 || 21 || #3f1515
 
|-
 
{{/ColorSample|ff55ff|3f153f}}
 
| Pink || d || <code>light_purple</code> || 255 || 85 || 255 || #ff55ff || 63 || 21 || 63 || #3f153f
 
|-
 
{{/ColorSample|ffff55|3f3f15}}
 
| Yellow || e || <code>yellow</code> || 255 || 255 || 85 || #ffff55 || 63 || 63 || 21 || #3f3f15
 
|-
 
{{/ColorSample|ffffff|3f3f3f}}
 
| White || f || <code>white</code> || 255 || 255 || 255 || #ffffff || 63 || 63 || 63 || #3f3f3f
 
|}
 
 
 
Starting with Minecraft 1.16 the JSON <code>color</code> field may also be specified as an arbitrary RGB color in the usual hexadecimal format <code>#RRGGBB</code>. 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&mdash;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.
 
 
 
{| class="wikitable" style="text-align:center;" border="1" cellpadding="5"
 
|-
 
! colspan="1" | Sample
 
! colspan="1" | Style
 
! colspan="1" | Code
 
! colspan="1" | Name
 
|-
 
| [[File:random_chat.gif]] || Random || k || <code>obfuscated</code>
 
|-
 
| [[File:bold_chat.png]] || Bold || l || <code>bold</code>
 
|-
 
| [[File:strikethrough_chat.png]] || Strikethrough || m || <code>strikethrough</code>
 
|-
 
| [[File:underlined_chat.png]] || Underlined || n || <code>underline</code>
 
|-
 
| [[File:italic_chat.png]] || Italic || o || <code>italic</code>
 
|}
 
 
 
=== Fonts ===
 
 
 
Since Minecraft 1.16 it has been possible to {{Minecraft Wiki|Resource_pack#Fonts|add custom fonts via resource packs}}, and use them in text components through the <code>font</code> field.
 
 
 
By default, the following fonts are available:
 
 
 
{| class="wikitable"
 
|-
 
! Identifier
 
! Default Look
 
! Notes
 
|-
 
| <code>minecraft:default</code>
 
| Standard Minecraft font (with Unifont fallback)
 
| Default font. Hardcoded to alias <code>minecraft:uniform</code> when Force Unicode Font is enabled.
 
|-
 
| <code>minecraft:uniform</code>
 
| [[Wikipedia:GNU Unifont|GNU Unifont]]
 
| Default font when Force Unicode Font is enabled.
 
|-
 
| <code>minecraft:alt</code>
 
| [[Wikipedia:Standard Galactic Alphabet|Standard Galactic Alphabet]]
 
| Enchanting table font.
 
|-
 
| <code>minecraft:illageralt</code>
 
| {{Minecraft Wiki|Minecraft_Dungeons:Illageralt|Illageralt from Minecraft Dungeons}}
 
| Unused.
 
|}
 
 
 
== Processing chat ==
 
  
 
=== Client chat mode ===
 
=== Client chat mode ===

Revision as of 18:08, 10 January 2024

This page previously contained documentation on text formatting features, which can now be found at Text formatting.

This article details various features and considerations of Minecraft's chat system. The packets themselves are documented in Protocol.

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 [note 1]
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 text 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).

Notes

  1. This behavior varies. The Notchian server previously rejected chat messages, but now allows them to go through (sending them to all players, but they're invisible on the sender's side). CraftBukkit and derivatives continue to reject this. See MC-116824 for more information.