Text components and chat

Status: Implemented for literal and translatable text, colour, the five styles (on or explicitly off), click and hover events, translation arguments, appended parts, titles with fade times, client-only text, and the chat events (plain text, mutable, cancellable). Keybind, score, selector and NBT components, parsing JSON or legacy & codes, fonts, item and entity hovers, chat formatting events, dialogs and a markup helper are Planned.

Function table: text. Chat sending to players: Players.

cl_text is an owned rich text value with the structure of vanilla’s text components.

Functions

cl_text   cl_text_literal(cl_str s);
cl_text   cl_text_translatable(cl_str key);
cl_result cl_text_add_arg(cl_text t, cl_text arg);       // a translation argument (%s, %1$s); takes its own reference
cl_result cl_text_append(cl_text parent, cl_text child); // takes its own reference to child
cl_result cl_text_color(cl_text t, cl_color rgb);        // 0xRRGGBB
cl_result cl_text_set_style(cl_text t, cl_text_style styles, bool on);   // CL_STYLE_BOLD | ITALIC | UNDERLINED | STRIKETHROUGH | OBFUSCATED
cl_result cl_text_click(cl_text t, cl_click_action a, cl_str value);    // CL_TEXT_CLICK_OPEN_URL (http/https), _RUN_COMMAND, _SUGGEST_COMMAND, _COPY_TO_CLIPBOARD
cl_result cl_text_hover(cl_text t, cl_text hover);                      // text shown on mouse-over; own reference
cl_result cl_text_to_plain(cl_text t, char* buf, size_t cap, size_t* out_len);
void      cl_text_retain(cl_text t);
void      cl_text_release(cl_text t);

cl_result cl_player_send_title(cl_entity p, cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out);  // null text / -1 keep
cl_result cl_player_clear_title(cl_entity p, bool reset_times);
cl_result cl_client_show_message(cl_text message, bool overlay);       // client only, nothing is sent
cl_result cl_client_show_title(cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out);

set_style(t, CL_STYLE_ITALIC, false) turns a style off explicitly (for example not italic inside an item name). run_command and suggest_command values start with /. The server sends the component as data (26.3 field names click_event / hover_event), so vanilla clients show every style and event.

Bindings

C	C++ (`clight::Text`)	Lua
`cl_text_literal(CL_STR("Hi"))`	`clight::literal("Hi")`	`cl.text.literal("Hi")` (plain strings work wherever text is expected)
`cl_text_translatable(key)` + `cl_text_add_arg`	`clight::text::translatable(key)`, `t.add_arg(arg)`	`cl.text.translatable(key, arg1, arg2)`
`cl_text_color(t, 0xFFAA00)`	`t.color(0xFFAA00)`	`t:color(0xFFAA00)` (chainable)
`cl_text_set_style(t, CL_STYLE_BOLD, true)`	`t.set_style(CL_STYLE_BOLD, true)`	`t:bold()`, `t:italic(false)`, `t:underlined()`, `t:strikethrough()`, `t:obfuscated()`
`cl_text_click(t, CL_TEXT_CLICK_RUN_COMMAND, CL_STR("/spawn"))`	`t.click(CL_TEXT_CLICK_RUN_COMMAND, "/spawn")`	`t:click("run_command", "/spawn")`
`cl_text_hover(t, h)`	`t.hover(h)`	`t:hover("Click me")`
`cl_text_append(t, child)`	`t.append(child)`	`t:append(" more")`

local msg = cl.text.literal("[Spawn]"):color(0x55FF55):bold()
  :click("run_command", "/spawn"):hover("Teleport to spawn")
player:send_message(cl.text.literal("Click "):append(msg))

Chat events

Event	Context	Use
`player.chat`	server TICK	Cancel or change a chat message before it is broadcast (`message` mutable)
`player.command`	server TICK	Cancel or change a command a player runs (`command` mutable)
`client.chat_received`	RENDER	Cancel or change an incoming line (`message` mutable, plain text; `overlay` = action bar)
`client.chat_send`	client TICK	Cancel or change outgoing chat before it is sent (`message` mutable)

cl.on("player.chat", function(event)
  if event.message:find("badword", 1, true) then
    event:cancel()
    event.player:send_message("Please keep it friendly.")
  end
end)

Planned

Keybind, score, selector and NBT components; parsing JSON, SNBT and legacy & codes; fonts, shadow colours and insertions; item and entity hovers; JSON output; chat formatting events and adding local chat lines with history; server-driven dialogs; a markup helper for coloured text.