Skip to content
Download

Text (function list)

Status: Implemented (API 1.24). Generated from client/clight/idl/clight_api.json by tools/docs/gen_api_reference.py; do not edit by hand. 16 functions, the newest from API 1.6.

Explanations and examples: Text and chat. Every function of the text module is listed here in table order. The details of each function follow the table, in the same order. Side: where the function works (server, client, both). Context: the thread it may be called on (Conventions). Since: the API version that added it.

C function Lua Side Context Since
cl_text_literal cl.text.literal both ANY 1.0
cl_text_translatable cl.text.translatable both ANY 1.0
cl_text_retain cl.text.retain both ANY 1.0
cl_text_release cl.text.release both ANY 1.0
cl_text_append cl.text.append both ANY 1.0
cl_text_color cl.text.color both ANY 1.0
cl_text_to_plain cl.text.to_plain both ANY 1.0
cl_text_set_style cl.text.set_style both ANY 1.4
cl_text_click cl.text.click both ANY 1.4
cl_text_hover cl.text.hover both ANY 1.4
cl_text_add_arg cl.text.add_arg both ANY 1.4
cl_client_show_message cl.text.client_show_message client TICK 1.4
cl_client_show_title cl.text.client_show_title client TICK 1.4
cl_text_parse cl.text.parse both ANY 1.6
cl_text_strip cl.text.strip both ANY 1.6
cl_text_to_json cl.text.to_json both ANY 1.6

cl_text_literal

cl_text cl_text_literal(cl_str s);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.literal
  • C++: clight::text::literal(std::string_view s) → Text
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_text_translatable

cl_text cl_text_translatable(cl_str key);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.translatable
  • C++: clight::text::translatable(std::string_view key) → Text
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_text_retain

void cl_text_retain(cl_text t);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.retain, text:retain(...)
  • C++: Text::retain() → void; clight::text::retain(cl_text t) → void

cl_text_release

void cl_text_release(cl_text t);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.release, text:release(...)
  • C++: Text::release() → void; clight::text::release(cl_text t) → void

cl_text_append

cl_result cl_text_append(cl_text parent, cl_text child);

Takes its own reference to child.

  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.append, text:append(...)
  • C++: Text::append(cl_text child) → Expected<void>; clight::text::append(cl_text parent, cl_text child) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_color

cl_result cl_text_color(cl_text t, cl_color rgb);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.color, text:color(...)
  • C++: Text::color(cl_color rgb) → Expected<void>; clight::text::color(cl_text t, cl_color rgb) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_to_plain

cl_result cl_text_to_plain(cl_text t, char* buf, size_t cap, size_t* out_len);
  • Side: both. Context: ANY (any thread). Since: API 1.0.
  • Lua: cl.text.to_plain, text:to_plain(...)
  • C++: Text::to_plain() → Expected<std::string>; clight::text::to_plain(cl_text t) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_set_style

cl_result cl_text_set_style(cl_text t, cl_text_style styles, bool on);

Turns styles on (on = true) or explicitly off (on = false, e.g. not italic inside an item name).

  • Side: both. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.text.set_style, text:set_style(...)
  • C++: Text::set_style(cl_text_style styles, bool on) → Expected<void>; clight::text::set_style(cl_text t, cl_text_style styles, bool on) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_click

cl_result cl_text_click(cl_text t, cl_click_action action, cl_str value);

What clicking the text does. run_command / suggest_command values start with ‘/’; open_url needs http(s).

  • Side: both. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.text.click, text:click(...)
  • C++: Text::click(cl_click_action action, std::string_view value) → Expected<void>; clight::text::click(cl_text t, cl_click_action action, std::string_view value) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_hover

cl_result cl_text_hover(cl_text t, cl_text hover);

The text shown while the mouse is over this text. Takes its own reference to hover.

  • Side: both. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.text.hover, text:hover(...)
  • C++: Text::hover(cl_text hover) → Expected<void>; clight::text::hover(cl_text t, cl_text hover) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_add_arg

cl_result cl_text_add_arg(cl_text t, cl_text arg);

Adds a translation argument (%s / %1$s in the language file) to a translatable text. Takes its own reference.

  • Side: both. Context: ANY (any thread). Since: API 1.4.
  • Lua: cl.text.add_arg, text:add_arg(...)
  • C++: Text::add_arg(cl_text arg) → Expected<void>; clight::text::add_arg(cl_text t, cl_text arg) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_client_show_message

cl_result cl_client_show_message(cl_text message, bool overlay);

A chat line only this client sees (nothing is sent to the server). overlay: above the hotbar instead of the chat.

  • Side: client. Context: TICK (tick thread). Since: API 1.4.
  • Lua: cl.text.client_show_message, text:client_show_message(...)
  • C++: Text::client_show_message(bool overlay) → Expected<void>; clight::text::client_show_message(cl_text message, bool overlay) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_client_show_title

cl_result cl_client_show_title(cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out);

A title only this client sees (subtitle may be null; fade timing in ticks, -1 = keep).

  • Side: client. Context: TICK (tick thread). Since: API 1.4.
  • Lua: cl.text.client_show_title, text:client_show_title(...)
  • C++: Text::client_show_title(cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out) → Expected<void>; clight::text::client_show_title(cl_text title, cl_text subtitle, int32_t fade_in, int32_t stay, int32_t fade_out) → Expected<void>
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_parse

cl_text cl_text_parse(cl_str s);

Formatted text from a string, auto-detected and mixable: legacy codes (&a, §l, &r), hex (&#RRGGBB, <#RRGGBB>, {#RRGGBB}, &x&R&R&G&G&B&B), tags (<red>, <bold>, <!italic>, gradient:#f00:#00f, <rainbow>, <reset>, <newline>, click:run_command:/spawn, hover:show_text:‘...’, </red>, </>) or a JSON component (a string starting with { or [). Escapes: && & < . Every API that takes a string as text uses this parser; cl_text_literal keeps text untouched.

  • Side: both. Context: ANY (any thread). Since: API 1.6.
  • Lua: cl.text.parse
  • C++: clight::text::parse(std::string_view s) → Text
  • The returned handle is owned: release it ©, or let the RAII class do it (C++). Lua releases it when it is collected (or at once with local s <close> = ...).

cl_text_strip

cl_result cl_text_strip(cl_str s, char* buf, size_t cap, size_t* out_len);

The visible text of a formatted string (codes, tags and JSON syntax removed).

  • Side: both. Context: ANY (any thread). Since: API 1.6.
  • Lua: cl.text.strip
  • C++: clight::text::strip(std::string_view s) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_text_to_json

cl_result cl_text_to_json(cl_text t, char* buf, size_t cap, size_t* out_len);

The vanilla JSON component of a text, e.g. for commands (/bossbar, /scoreboard, /team, /tellraw, /data on signs).

  • Side: both. Context: ANY (any thread). Since: API 1.6.
  • Lua: cl.text.to_json, text:to_json(...)
  • C++: Text::to_json() → Expected<std::string>; clight::text::to_json(cl_text t) → Expected<std::string>
  • Writes a string: buf / cap / out_len (a too small buffer returns CL_E_BUFFER_TOO_SMALL with the needed length in *out_len). Lua and C++ return the string.
  • Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.