Colours and formatting

Status: Implemented (API 1.6). One shared parser reads colour codes, hex colours, tags and JSON in every string that becomes text, in Lua, C and C++.

Every API that takes a string as text formats it: player:send_message("&aHi"), cl_easy_send_message(p, "<red>Hi"), player.send_message("&#FF8800Hi"). Text handles made with cl_text_literal / cl.text.plain / clight::plain are sent untouched.

The formats

All of these work in the same string, and you can mix them:

You write	You get
`&a` … `&f`, `&0` … `&9` (or `§a`)	The 16 vanilla colours (`&a` green, `&c` red, `&6` gold, `&7` gray, …).
`&l` `&o` `&n` `&m` `&k`	Bold, italic, underlined, strikethrough, obfuscated.
`&r`	Back to normal (all colours, styles and tags end).
`&#FF8800`, `{#FF8800}`, `<#FF8800>`	Any colour as hex.
`&x&F&F&8&8&0&0` (or with `§`)	Hex the way Bukkit plugins write it.
`<red>`, `<gold>`, `<color:#FF8800>`, `<c:aqua>`	A colour until its closing tag (`</red>`, `</color>`) or `</>`.
`<bold>` `<b>` `<italic>` `<i>` `<underlined>` `<u>` `<strikethrough>` `<st>` `<obfuscated>` `<obf>`	Styles until the closing tag. `<!italic>` turns a style off.
`<gradient:#FF0000:#0000FF>text</gradient>`	A colour fade over the text (two or more colours).
`<rainbow>text</rainbow>`	Rainbow colours (`<rainbow:!>` goes the other way).
`<click:run_command:/spawn>`	Clicking runs a command. Also `suggest_command`, `open_url` (http/https only) and `copy_to_clipboard`.
`<hover:show_text:'<red>Hi'>`	Text shown while the mouse is over it (it can be formatted too).
`<lang:item.minecraft.diamond>`	A translated text, in each player’s language.
`<newline>` or `<br>`	A line break. `<reset>` is the same as `&r`.
`{"text":"Hi","color":"red"}` or `[...]`	A vanilla JSON text component, used as it is.

A colour code (&a, &#...) ends the styles of earlier codes, like in vanilla: &lBold&aGreen makes only “Bold” bold.

Anything that is not a valid code stays as normal text: a < b, Tom & Jerry, 50% and <notatag> are shown exactly like that.

Escapes

Write	To show
`&&`	`&`
`\&a`	`&a` (not green)
`\<red>`	`<red>` (not a tag)
`\{`, `\§`, `\\`	`{`, `§`, `\`

Text from players: use plain text

A player can type &c or <click:run_command:/op me> into chat or a sign. If your mod repeats what a player typed, wrap it in plain text, which is sent exactly as it is:

Lua: cl.text.plain(s)
C: cl_text_literal(CL_STR_C(s))
C++: clight::plain(s)

Where formatting works

Every place that takes a string as text: chat messages, the action bar, titles and subtitles, broadcasts, client-only chat, command replies and failures, kick reasons, item names and lore, menu and screen titles, GUI labels, buttons, check boxes, sliders, text field hints, tooltips, HUD text drawn with gui_text, keybind labels, config comments, and your mod’s log lines.

Item names and lore are upright: vanilla draws custom names in italics, but a name from your mod stays upright unless the text itself turns italic on (&o, <italic>).
Log lines show the colours in a terminal; the log file gets the text without them.
Players on vanilla clients see the same colours: the server always sends real text components, never raw codes.
For commands that take JSON (/bossbar, /scoreboard, /team, /tellraw, /data on signs and books), turn formatted text into JSON first (see below).
Strings without any &, §, <, {, [ or \ skip the parser, so plain text costs nothing extra.

API

Lua	C	C++	What it does
`cl.text.parse(s)`	`cl_text_parse`	`clight::formatted(s)`	Formatted string to a text.
`cl.text.plain(s)`	`cl_text_literal`	`clight::plain(s)`	A string as it is.
`cl.text.strip(s)`	`cl_text_strip`	`clight::text::strip(s)`	The visible text.
`cl.text.json(t)`	`cl_text_to_json`	`Text::to_json()`	The vanilla JSON of a text.
`stack:set_name(t)`	`cl_stack_set_name`	`ItemStack::set_name`	The custom name.
`stack:add_lore(t)`	`cl_stack_add_lore`	`ItemStack::add_lore`	One more lore line (256 at most).
`stack:clear_text()`	`cl_stack_clear_text`	`ItemStack::clear_text`	Removes name and lore.
`player:kick(t)`	`cl_player_kick`	`Entity::kick`	Disconnects the player with a reason.

Not yet in the API: dedicated boss bar, scoreboard, team, sign and book functions. Use cl_cmd_run with the JSON from cl_text_to_json until they arrive.