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

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:

cl.on("player.chat", function(e)
  -- the player's words stay exactly as typed; only our part is formatted
  local msg = cl.text.parse("&7[&6Shout&7] ")
  msg:append(cl.text.plain(e.message))
  cl.entity.server_broadcast(msg)
end)

cl.text.plain(s) (the same as cl.text.literal(s)) never looks at codes. cl.text.parse(s) turns a formatted string into a text you can keep changing with :bold(), :append(...), :hover(...) and the other methods from the last lesson.

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

player:give("minecraft:diamond_sword", 1, {
  name = "<gradient:#55FFFF:#5555FF>Frost Blade",
  lore = { "&7Cold to the touch", "&9+2 frost damage" },
})

local stack <close> = cl.stack("my_mod:ruby", 3)
stack:set_name("&cRuby"):add_lore("&7Shiny")
player:give(stack)

Kicking a player

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

JSON for commands

local json = cl.text.json("&6Boss &c<bold>Wither")   -- {"text":"","extra":[...]}
cl.cmd.run("bossbar add my_mod:boss " .. json)
print(cl.text.strip("&aHi <bold>there"))           -- Hi there

Try it

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