Skip to main content

traceless.ui

Visible-control constructors use string tab, group, and name arguments. LUA is the script-created tab. Creation must happen during a script invocation and raises an error when names, location, identity, or resources cannot be accepted. Controls are owned by the script instance and invalidated on unload. Saved/preloaded values take precedence over constructor defaults. See UI paths and configuration.

new_checkbox​

traceless.ui.new_checkbox(tab, group, name [, default = false])

Returns: UI reference.

Creates a boolean control; default uses Lua truthiness.

new_slider​

traceless.ui.new_slider(tab, group, name, min, max [, default = min])

Returns: UI reference.

Integer min, max, and default values. max below min raises an error. Values are clamped and rounded to the slider bounds; get returns an integer despite native float storage.

new_combobox​

traceless.ui.new_combobox(tab, group, name, items)

Returns: UI reference.

items is a nonempty array of strings; alternatively pass item strings as variadic arguments from slot 4. Starts at the first item unless a saved value exists. get returns the selected label; set accepts a label or zero-based index.

new_hotkey​

traceless.ui.new_hotkey(tab, group, name [, inline = nil [, default_key = -1]])

Returns: UI reference.

inline, when present, must be boolean but is currently ignored. Creates a checkbox with keybind support. Key -1 means unbound; 0–255 are accepted virtual keys. Initial stored boolean is false, unless restored. Invalid keys raise an error.

new_listbox​

traceless.ui.new_listbox(tab, group, name [, items = nil])

Returns: UI reference.

Optional array of strings, which may be empty. get/set use zero-based selected integer index; initial index is 0 and restored values are clamped to the item count.

new_multiselect​

traceless.ui.new_multiselect(tab, group, name, items)

Returns: UI reference.

Array of 1–31 strings, or variadic strings from slot 4. get returns selected labels as an array. set accepts a label array or variadic labels. Invalid element count or unknown selection labels raise an error.

new_color_picker​

traceless.ui.new_color_picker(tab, group, name [, r = 255 [, g = 255 [, b = 255 [, a = 255]]]])

Returns: UI reference.

Integer RGBA defaults are clamped to 0–255. name participates in config identity but is not displayed. Attaches to the preceding control, or uses an unnamed row if first in its group.

new_button​

traceless.ui.new_button(tab, group, name, callback)

Returns: UI reference.

callback must be a function. Clicking queues a script-owned zero-delay timer that calls it without arguments on a subsequent timer pump; unloading first removes the pending callback. The button has no readable configuration value.

new_label​

traceless.ui.new_label(tab, group, name)

Returns: UI reference.

Creates display text. ui.set(reference, string) replaces that text; its original identifier stays the same.

new_textbox​

traceless.ui.new_textbox(tab, group, name [, default])

Returns: UI reference.

Creates string-backed visible text input. A provided string-like default initializes a new value; other default types are ignored. Restored config values are retained.

new_string​

traceless.ui.new_string(name [, default = nil])

Returns: UI reference.

Creates configuration-backed string storage without a visible menu item. Requires a running script; name is a string, default is an optional string. Restored values take precedence.

reference​

traceless.ui.reference(tab, group, name, ...)

Returns: UI reference; or nil.

Finds a native control by path; additional strings descend nested items. Resolves weapon/map-specific variables when the reference is created. Not found or unavailable paths return nil. Native references support get/set/callbacks but cannot be hidden.

get​

traceless.ui.get(reference)

Returns: control value; four integers for color; or nil.

Reads effective keybind value. Boolean controls return boolean; sliders number/integer; comboboxes label; listboxes integer; multiselects label array; text/string controls string; color pickers r, g, b, a. Invalid or nonvalue references return nil.

get_raw​

traceless.ui.get_raw(reference)

Returns: control value; four integers for color; or nil.

Uses the same shape as get, but reads stored values before keybind overrides. Comboboxes still return labels and multiselects still return arrays, not native integer representations.

set​

traceless.ui.set(reference, value, ...)

Returns: none.

Requires a valid reference and a value matching its type. Colors accept r, g, b [, a = 255], clamped to 0–255; boolean requires an actual boolean; combobox accepts label or zero-based index; multiselect accepts array/variadic labels; sliders clamp and script sliders round; labels accept text. Invalid values or references raise an error.

set_callback​

traceless.ui.set_callback(reference, callback)

Returns: none.

Requires a valid reference and a function. Replaces that reference's previous change callback; callback receives the reference. Tracks changes in the effective value. Native references are supported. nil is not a supported removal argument.

set_visible​

traceless.ui.set_visible(reference, visible)

Returns: none.

Sets script-created visibility using truthiness. Invalid references raise an error. Native controls reject hiding or relocation.

update​

traceless.ui.update(reference, items)

Returns: none.

Replaces item labels of a script-created combobox using a nonempty array or variadic strings. Native controls and other control kinds raise errors. Invalid labels and allocation failure raise errors.

name​

traceless.ui.name(reference)

Returns: string; or nil.

Returns the control's display name, or nil if the reference/name is unavailable.

is_menu_open​

traceless.ui.is_menu_open()

Returns: boolean.

Returns the menu open state.

traceless.ui.menu_position()

Returns: x, y integers.

Menu origin in screen pixels.

traceless.ui.menu_size()

Returns: width, height integers.

Menu dimensions in pixels.

mouse_position​

traceless.ui.mouse_position()

Returns: x, y integers.

Current cursor position in screen pixels.

local traceless = require("traceless")
local mode = traceless.ui.new_combobox("LUA", "Example", "Mode", {"Off", "On"})
traceless.ui.set_callback(mode, function(reference)
    traceless.console.info(traceless.ui.get(reference))
end)
traceless.ui.set(mode, "On")

Reload candidates copy matching script-created control values and keybinds into independent variables. Cancelling or failing a staged reload leaves the active instance's current values intact. Copied variables join the configuration registry only when activation commits. References to native controls and arbitrary engine/global mutations retain the cleanup limits described in lifecycle.

References to another script's controls become unavailable when that source unloads, including references held by a pending reload candidate.