Difference between revisions of "Text formatting"

From wiki.vg
Jump to navigation Jump to search
(s/Current system (text components)/Text components/g; s/Old system/Formatting codes/g; Labeling formatting codes as the "old system", while mostly true, might lead one to falsely assume that it no longer applies. And, of course, "Current system (text components)" is just painfully long.)
Line 22: Line 22:
  
 
;<code>type</code>
 
;<code>type</code>
:''Optional String''. The content type of this component, specifying what kind of direct content it includes.
+
:''Optional String''. The content type of this component, specifying what kind of direct content it includes. If omitted, each of the content types is tried in the listed order until one for which the component is valid is found.
 
;<code>extra</code>
 
;<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.
 
:''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.
  
 
Additionally, the component must contain the fields of its content type (refer to the table below).
 
Additionally, the component must contain the fields of its content type (refer to the table below).
 
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:
 
The following content types are defined:

Revision as of 15:48, 16 January 2024

Minecraft has two separate text formatting systems. The newer text component system is used in many specific contexts expecting formatted text, including chat messages, written books, death messages, window titles, and the like. In addition, the legacy formatting code system applies to more or less all displayed text, and is processed after text components.

Text components

A text component is a recursive structure, usually represented as JSON. For most situations, the JSON is strictly parsed, but 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 Chat and 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 {"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 consists of one or more content fields, and any number of styling fields.

Content fields

These fields specify the component's content.

The full content of the component is the concatenation of its direct content, to which the component's styling directly applies, and the full contents of all its child components, which inherit styling from their parent, in that order.

type
Optional String. The content type of this component, specifying what kind of direct content it includes. If omitted, each of the content types is tried in the listed order until one for which the component is valid is found.
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.

Additionally, the component must contain the fields of its content type (refer to the table below).

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.

Styling fields

These fields specify styling and actions to associate with the component's content. They also appear by themselves in some contexts, outside a text component.

Values for any unspecified fields are either inherited from the nearest parent that does specify them, if one exists, or otherwise assigned default values according to the surrounding context.

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 field 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)—even when the component is encoded as NBT!
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".

Warning.png 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 text 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. (But see #Formatting codes, which still apply.)

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.

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

Warning.png 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.

If sent directly to a client, will be displayed as empty text.

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

If sent directly to a client, will be displayed as the selection pattern.

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.

If sent directly to a client, will be displayed as empty text.

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.

Warning.png Since 1.19.1 the Notchian server 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).

Formatting codes

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 color or style codes listed in their respective sections, or r to reset to default formatting.

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

There is no way to escape the § or & 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 §r reverts back merely to the styling inherited from the surrounding context. In the context of text components, instances of text or keybind content are considered singular runs of text, whereas in translatable 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.

Hex digit to color mapping
Sample Common Name Code 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 Code Name
Random chat.gif Random k obfuscated
Bold chat.png Bold l bold
Strikethrough chat.png Strikethrough m strikethrough
Underlined chat.png Underlined n underline
Italic chat.png Italic o italic

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.