Colours and formatting

Every string you send as text can have colours, styles, gradients, click actions and hover text. Write them right into the string.

player.send_message("&aWelcome back, &l" + player.name() + "&r!");
player.send_message("<gradient:#FF5555:#FFAA00>Fire sale</gradient> <gray>today only");
player.send_action_bar("<red><bold>Low health!");
player.send_message("<click:run_command:/spawn><hover:show_text:'Click to go home'><aqua>[Spawn]</click>");

Every overload that takes a std::string_view as text reads the formats below. clight::formatted(s) gives you the text as a clight::Text; clight::plain(s) and clight::literal(s) never look at codes.

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:

clight::Text msg = clight::formatted("&7[&6Shout&7] ");
clight::Text words = clight::plain(typed);   // exactly as the player typed it
msg.append(words);
clight::broadcast("&eSomeone shouted!");

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.

Items with names and lore

clight::ItemStack sword = clight::item("minecraft:diamond_sword");
sword.set_name("<gradient:#55FFFF:#5555FF>Frost Blade");
sword.add_lore("&7Cold to the touch");
sword.add_lore("&9+2 frost damage");
player.give(sword);

Kicking a player

player.kick("&cYou were kicked: &fspam");

JSON for commands

std::string json = clight::formatted("&6Boss &c<bold>Wither").to_json().value_or("{}");
clight::cmd::run("bossbar add my_mod:boss " + json);

Try it

Make /hello reply with your name in a rainbow, and give a stick named “&dMagic Wand” with two lore lines.