GUI drawing (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. 32 functions, the newest from API 1.21.

Explanations and examples: Screens and drawing. Every function of the gui 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_gui_width	cl.gui.width	client	RENDER	1.0
cl_gui_height	cl.gui.height	client	RENDER	1.0
cl_gui_scale_factor	cl.gui.scale_factor	client	RENDER	1.0
cl_gui_fill	cl.gui.fill	client	RENDER	1.0
cl_gui_fill_gradient	cl.gui.fill_gradient	client	RENDER	1.0
cl_gui_outline	cl.gui.outline	client	RENDER	1.0
cl_gui_text	cl.gui.text	client	RENDER	1.0
cl_gui_text_component	cl.gui.text_component	client	RENDER	1.0
cl_gui_text_centered	cl.gui.text_centered	client	RENDER	1.0
cl_gui_text_width	cl.gui.text_width	client	ANY	1.0
cl_gui_line_height	cl.gui.line_height	client	ANY	1.0
cl_gui_sprite	cl.gui.sprite	client	RENDER	1.0
cl_gui_blit	cl.gui.blit	client	RENDER	1.0
cl_gui_item	cl.gui.item	client	RENDER	1.0
cl_gui_item_by_name	cl.gui.item_by_name	client	RENDER	1.0
cl_gui_push_pose	cl.gui.push_pose	client	RENDER	1.0
cl_gui_pop_pose	cl.gui.pop_pose	client	RENDER	1.0
cl_gui_translate	cl.gui.translate	client	RENDER	1.0
cl_gui_scale	cl.gui.scale	client	RENDER	1.0
cl_gui_push_scissor	cl.gui.push_scissor	client	RENDER	1.0
cl_gui_pop_scissor	cl.gui.pop_scissor	client	RENDER	1.0
cl_gui_tooltip	cl.gui.tooltip	client	RENDER	1.0
cl_gui_set_title_background	cl.gui.set_title_background	client	MAIN	1.13
cl_gui_set_panorama	cl.gui.set_panorama	client	MAIN	1.13
cl_gui_set_sprite	cl.gui.set_sprite	client	MAIN	1.13
cl_gui_clear_sprites	cl.gui.clear_sprites	client	MAIN	1.13
cl_gui_panel	cl.gui.panel	client	RENDER	1.21
cl_gui_hud_panel	cl.gui.hud_panel	client	RENDER	1.21
cl_gui_round_rect	cl.gui.round_rect	client	RENDER	1.21
cl_gui_ui_text	cl.gui.ui_text	client	RENDER	1.21
cl_gui_icon	cl.gui.icon	client	RENDER	1.21
cl_gui_control	cl.gui.control	client	RENDER	1.21

cl_gui_width

int32_t cl_gui_width(cl_gui g);

Width/height of the GUI-scaled screen.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.width, gui:width(...)
• C++: Gui::width() → int32_t; clight::gui::width(Gui g) → int32_t

cl_gui_height

int32_t cl_gui_height(cl_gui g);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.height, gui:height(...)
• C++: Gui::height() → int32_t; clight::gui::height(Gui g) → int32_t

cl_gui_scale_factor

int32_t cl_gui_scale_factor(cl_gui g);

The current GUI scale factor (1…n).

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.scale_factor, gui:scale_factor(...)
• C++: Gui::scale_factor() → int32_t; clight::gui::scale_factor(Gui g) → int32_t

cl_gui_fill

void cl_gui_fill(cl_gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color argb);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.fill, gui:fill(...)
• C++: Gui::fill(int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color argb) → void; clight::gui::fill(Gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color argb) → void

cl_gui_fill_gradient

void cl_gui_fill_gradient(cl_gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color top, cl_color bottom);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.fill_gradient, gui:fill_gradient(...)
• C++: Gui::fill_gradient(int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color top, cl_color bottom) → void; clight::gui::fill_gradient(Gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1, cl_color top, cl_color bottom) → void

cl_gui_outline

void cl_gui_outline(cl_gui g, int32_t x, int32_t y, int32_t w, int32_t h, cl_color argb);

A 1-pixel rectangle outline.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.outline, gui:outline(...)
• C++: Gui::outline(int32_t x, int32_t y, int32_t w, int32_t h, cl_color argb) → void; clight::gui::outline(Gui g, int32_t x, int32_t y, int32_t w, int32_t h, cl_color argb) → void

cl_gui_text

int32_t cl_gui_text(cl_gui g, cl_str s, int32_t x, int32_t y, cl_color argb, bool shadow);

Draws UTF-8 text with the vanilla font (formatting codes are not parsed). Returns the end x.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.text, gui:text(...)
• C++: Gui::text(std::string_view s, int32_t x, int32_t y, cl_color argb, bool shadow) → int32_t; clight::gui::text(Gui g, std::string_view s, int32_t x, int32_t y, cl_color argb, bool shadow) → int32_t

cl_gui_text_component

int32_t cl_gui_text_component(cl_gui g, cl_text t, int32_t x, int32_t y, cl_color argb, bool shadow);

Draws a text component (styles, translations). Returns the end x.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.text_component, gui:text_component(...)
• C++: Gui::text_component(cl_text t, int32_t x, int32_t y, cl_color argb, bool shadow) → int32_t; clight::gui::text_component(Gui g, cl_text t, int32_t x, int32_t y, cl_color argb, bool shadow) → int32_t

cl_gui_text_centered

void cl_gui_text_centered(cl_gui g, cl_str s, int32_t cx, int32_t y, cl_color argb, bool shadow);

Centred on cx.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.text_centered, gui:text_centered(...)
• C++: Gui::text_centered(std::string_view s, int32_t cx, int32_t y, cl_color argb, bool shadow) → void; clight::gui::text_centered(Gui g, std::string_view s, int32_t cx, int32_t y, cl_color argb, bool shadow) → void

cl_gui_text_width

int32_t cl_gui_text_width(cl_str s);

Width of UTF-8 text in GUI pixels.

• Side: client. Context: ANY (any thread). Since: API 1.0.
• Lua: cl.gui.text_width
• C++: clight::gui::text_width(std::string_view s) → int32_t

cl_gui_line_height

int32_t cl_gui_line_height(void);

• Side: client. Context: ANY (any thread). Since: API 1.0.
• Lua: cl.gui.line_height
• C++: clight::gui::line_height() → int32_t

cl_gui_sprite

void cl_gui_sprite(cl_gui g, cl_str sprite, int32_t x, int32_t y, int32_t w, int32_t h);

A GUI atlas sprite (“minecraft:hud/heart/full”, or “<modid>:<path>” from assets/<modid>/textures/gui/sprites/<path>.png), stretched to w x h (nine-slice/tiling metadata in the .mcmeta is honoured as in vanilla).

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.sprite, gui:sprite(...)
• C++: Gui::sprite(std::string_view sprite, int32_t x, int32_t y, int32_t w, int32_t h) → void; clight::gui::sprite(Gui g, std::string_view sprite, int32_t x, int32_t y, int32_t w, int32_t h) → void

cl_gui_blit

void cl_gui_blit(cl_gui g, cl_str texture, int32_t x, int32_t y, int32_t w, int32_t h, float u0, float v0, float u1, float v1, cl_color argb);

Any texture (“<ns>:textures/gui/x.png”), with UVs in 0…1 and a tint.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.blit, gui:blit(...)
• C++: Gui::blit(std::string_view texture, int32_t x, int32_t y, int32_t w, int32_t h, float u0, float v0, float u1, float v1, cl_color argb) → void; clight::gui::blit(Gui g, std::string_view texture, int32_t x, int32_t y, int32_t w, int32_t h, float u0, float v0, float u1, float v1, cl_color argb) → void

cl_gui_item

void cl_gui_item(cl_gui g, cl_item_stack stack, int32_t x, int32_t y, bool decorations);

An item icon (16 x 16) and optionally its count / durability bar.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.item, gui:item(...)
• C++: Gui::item(cl_item_stack stack, int32_t x, int32_t y, bool decorations) → void; clight::gui::item(Gui g, cl_item_stack stack, int32_t x, int32_t y, bool decorations) → void

cl_gui_item_by_name

void cl_gui_item_by_name(cl_gui g, cl_str item, int32_t x, int32_t y);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.item_by_name, gui:item_by_name(...)
• C++: Gui::item_by_name(std::string_view item, int32_t x, int32_t y) → void; clight::gui::item_by_name(Gui g, std::string_view item, int32_t x, int32_t y) → void

cl_gui_push_pose

void cl_gui_push_pose(cl_gui g);

Pose stack: translate / scale everything drawn until the matching pop.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.push_pose, gui:push_pose(...)
• C++: Gui::push_pose() → void; clight::gui::push_pose(Gui g) → void

cl_gui_pop_pose

void cl_gui_pop_pose(cl_gui g);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.pop_pose, gui:pop_pose(...)
• C++: Gui::pop_pose() → void; clight::gui::pop_pose(Gui g) → void

cl_gui_translate

void cl_gui_translate(cl_gui g, float x, float y);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.translate, gui:translate(...)
• C++: Gui::translate(float x, float y) → void; clight::gui::translate(Gui g, float x, float y) → void

cl_gui_scale

void cl_gui_scale(cl_gui g, float x, float y);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.scale, gui:scale(...)
• C++: Gui::scale(float x, float y) → void; clight::gui::scale(Gui g, float x, float y) → void

cl_gui_push_scissor

void cl_gui_push_scissor(cl_gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1);

Clips drawing to a rectangle (nested scissors intersect).

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.push_scissor, gui:push_scissor(...)
• C++: Gui::push_scissor(int32_t x0, int32_t y0, int32_t x1, int32_t y1) → void; clight::gui::push_scissor(Gui g, int32_t x0, int32_t y0, int32_t x1, int32_t y1) → void

cl_gui_pop_scissor

void cl_gui_pop_scissor(cl_gui g);

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.pop_scissor, gui:pop_scissor(...)
• C++: Gui::pop_scissor() → void; clight::gui::pop_scissor(Gui g) → void

cl_gui_tooltip

void cl_gui_tooltip(cl_gui g, cl_str s, int32_t x, int32_t y);

A vanilla-style tooltip box with the text (multi-line with ‘\n’) at the mouse position.

• Side: client. Context: RENDER (render thread). Since: API 1.0.
• Lua: cl.gui.tooltip, gui:tooltip(...)
• C++: Gui::tooltip(std::string_view s, int32_t x, int32_t y) → void; clight::gui::tooltip(Gui g, std::string_view s, int32_t x, int32_t y) → void

cl_gui_set_title_background

cl_result cl_gui_set_title_background(cl_str path);

The title screen background: a mod texture drawn over the whole screen instead of the panorama (scaled to cover it, “my_mod:textures/gui/title.png”); “” = the vanilla panorama again. The last mod that sets one wins.

• Side: client. Context: MAIN (startup (main thread)). Since: API 1.13.
• Lua: cl.gui.set_title_background
• C++: clight::gui::set_title_background(std::string_view path) → Expected<void>
• Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_gui_set_panorama

cl_result cl_gui_set_panorama(cl_str prefix);

A panorama of the mod instead of the vanilla one: prefix “my_mod:textures/gui/title/background/panorama” loads panorama_0.png … panorama_5.png like vanilla. “” = vanilla.

• Side: client. Context: MAIN (startup (main thread)). Since: API 1.13.
• Lua: cl.gui.set_panorama
• C++: clight::gui::set_panorama(std::string_view prefix) → Expected<void>
• Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_gui_set_sprite

cl_result cl_gui_set_sprite(cl_str screen, cl_str sprite, cl_str texture);

Replaces a GUI sprite (“widget/button”, “widget/button_highlighted”, “widget/slider”, “container/slot”, …) with a mod texture, on one screen (“options”, “inventory”, “title”: the screen ids of client.screen_open) or on every screen (“”). The texture keeps the sprite’s scaling (nine-slice borders in the sprite’s pixel units, at any resolution). texture “”: the sprite is vanilla again. No resource pack needed; resource packs still change the vanilla sprites.

• Side: client. Context: MAIN (startup (main thread)). Since: API 1.13.
• Lua: cl.gui.set_sprite
• C++: clight::gui::set_sprite(std::string_view screen, std::string_view sprite, std::string_view texture) → Expected<void>
• Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_gui_clear_sprites

cl_result cl_gui_clear_sprites(void);

Removes every sprite override of the calling mod.

• Side: client. Context: MAIN (startup (main thread)). Since: API 1.13.
• Lua: cl.gui.clear_sprites
• C++: clight::gui::clear_sprites() → Expected<void>
• Returns CL_OK or an error code (Error codes). Lua raises a cl.Error on failure.

cl_gui_panel

void cl_gui_panel(cl_gui g, float x, float y, float w, float h);

A container in the current style: Fancy = the theme’s panel (rounded, hairline); Vanilla = the vanilla dark list background. Coordinates are GUI px (fractions allowed).

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.panel, gui:panel(...)
• C++: Gui::panel(float x, float y, float w, float h) → void; clight::gui::panel(Gui g, float x, float y, float w, float h) → void

cl_gui_hud_panel

void cl_gui_hud_panel(cl_gui g, float x, float y, float w, float h);

The HUD panel material (Fancy: the HUD’s rounded panel; Vanilla: vanilla’s translucent black box).

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.hud_panel, gui:hud_panel(...)
• C++: Gui::hud_panel(float x, float y, float w, float h) → void; clight::gui::hud_panel(Gui g, float x, float y, float w, float h) → void

cl_gui_round_rect

void cl_gui_round_rect(cl_gui g, float x, float y, float w, float h, float radius, cl_color argb, float stroke);

A rounded rectangle (anti-aliased, any style): radius in GUI px; stroke > 0 draws only an inside ring that wide.

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.round_rect, gui:round_rect(...)
• C++: Gui::round_rect(float x, float y, float w, float h, float radius, cl_color argb, float stroke) → void; clight::gui::round_rect(Gui g, float x, float y, float w, float h, float radius, cl_color argb, float stroke) → void

cl_gui_ui_text

float cl_gui_ui_text(cl_gui g, cl_str s, float x, float y, cl_ui_text style, cl_color argb);

Text in a kit style (Fancy: the UI font in that style; Vanilla: the game font with a shadow). argb 0 = the style’s own colour. (x, y) is the top of the line box. Returns the end x.

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.ui_text, gui:ui_text(...)
• C++: Gui::ui_text(std::string_view s, float x, float y, cl_ui_text style, cl_color argb) → float; clight::gui::ui_text(Gui g, std::string_view s, float x, float y, cl_ui_text style, cl_color argb) → float

cl_gui_icon

void cl_gui_icon(cl_gui g, cl_str name, float x, float y, float size, cl_color argb);

An icon of the icon set, size x size GUI px at (x, y); argb 0 = the theme’s icon colour.

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.icon, gui:icon(...)
• C++: Gui::icon(std::string_view name, float x, float y, float size, cl_color argb) → void; clight::gui::icon(Gui g, std::string_view name, float x, float y, float size, cl_color argb) → void

cl_gui_control

void cl_gui_control(cl_gui g, cl_ui_control kind, float x, float y, float w, float h, cl_str label, cl_ui_state state, float value);

Draws the look of a control (no input handling): for your own widgets. label: buttons; icon name: ICON_BUTTON.

• Side: client. Context: RENDER (render thread). Since: API 1.21.
• Lua: cl.gui.control, gui:control(...)
• C++: Gui::control(cl_ui_control kind, float x, float y, float w, float h, std::string_view label, cl_ui_state state, float value) → void; clight::gui::control(Gui g, cl_ui_control kind, float x, float y, float w, float h, std::string_view label, cl_ui_state state, float value) → void