> ## Documentation Index
> Fetch the complete documentation index at: https://lua.nlcrack.cc/llms.txt
> Use this file to discover all available pages before exploring further.

# UI

> Script menu elements. Appear in the cheat menu under a tab named after the script.

## Sidebar, tabs and groups

```lua theme={null} theme={null}
ui.sidebar('My Script', 'globe')
local tab = ui.tab('My Tab', 'user')
local group = tab:group('Settings')
local cb = group.checkbox('Enable', true)
```

All element constructors are available on `ui`, on tab objects, and on group objects. Both `tab:group(...)` and `tab.group(...)` work.

| Function | Description |
| - | - |
| `ui.sidebar([name, icon])` | Sets the script's sidebar entry name and icon. `icon` is an icon name (`'globe'`, `'user'`, `'users'`, `'crosshairs'`, `'mouse'`, `'image'`, `'code'`, `'brackets-curly'`, ...), SVG markup or a texture. Without an icon the entry shows `brackets-curly` (the curly braces) |
| `ui.tab(name [, icon])` | Creates (or reuses) a tab of the script. At most 64 tabs per script |
| `ui.group(name)` | Creates a group in the current context |

## Menu state

| Function | Returns | Description |
| - | - | - |
| `ui.alpha()` | `number` | The menu's fade (0 closed … 1 open; it animates for 0.2 s when the menu opens or closes) |
| `ui.scale([name, value])` | `number` | `value` (default 1) multiplied by a scale setting: `'menu'` (default), `'esp'` or `'windows'` (ESP Scale and Windows Scale of the user popup). Any other name raises `"invalid option '<name>'"` |
| `ui.position()` | `vector` / `nil` | Top-left corner of the menu window (`z` is 0), `nil` before the menu window exists |
| `ui.size()` | `vector` / `nil` | Size of the menu window (`z` is 0), `nil` before the menu window exists |
| `ui.cursor()` | `vector` | Mouse position on the screen (`z` is 0) |
| `ui.style([name])` | `table` / `color` | Without a name: every menu palette colour by name. With a name: that colour, or nothing for an unknown name. Names: `Text`, `Disabled Text`, `Active Text`, `Small Text`, `Grey Text`, `Logo`, `Sidebar Background`, `Popup Background`, `Main Window Background`, `Preview Background`, `Border`, `Frame Background`, `Frame Active Background`, `Text Preview`, `Window Title`, `Active Window Title`, `Scrollbar Background`, `Scrollbar Grab`, `Scrollbar Grab Active`, `Switch`, `Switch Active`, `Switch Background`, `Switch Active Background`, `Slider Background`, `Slider Active Background`, `Slider Grab`, `Slider Grab Active`, `Button`, `Button Active`, `Link`, `Link Active` (the accent), `Selection`, `Separator`, `Tab`, `Text Selection`, `Shadows`, `Spinner`, `Block Background`, `Sidebar Selection`, `Logo Back`, `Button Text`, `Button Active Text`, `Transparent Background` (case-sensitive) |
| `ui.units([distance])` | `string` / `number, string, string` | Without an argument: `'metric'` or `'imperial'` (the Units setting; Automatic follows the Windows measurement system). With a distance in game units: the converted value (metres, or feet = units / 12), the suffix (`'m'` / `'ft'`) and the unit name |
| `ui.binds([all])` | `table` | The active hotkeys: an array of `{name, mode, value, reference, is_active}`. Without `all` only hotkeys with *Display in Hotkey List* on are listed (the Hotkeys window's list); with `all = true` every active hotkey. `mode`: 0 Toggle, 1 Hold (2 = nlcrack' Always). `value`: the value the hotkey sets (typed like `ref:get()`). `reference`: the control (`ui.find` reference) or `nil` |
| `ui.localize(language, text, translation)` | | Shows `translation` instead of `text` in this script's element labels, tooltips and sidebar name while `language` (a language's short name, e.g. `'en'`, `'ru'`) is selected. An unknown language raises `"invalid language"` |

```lua theme={null} theme={null}
ui.localize('ru', 'Enable', 'Включить')
local accent = ui.style('Link Active')
local meters, suffix = ui.units(512)
```

## Constructors

| Function | Returns | Description |
| - | - | - |
| `ui.checkbox(label [, default])` | `element` | Boolean toggle |
| `ui.slider_int(label, min, max [, default, format])` | `element` | Integer slider. `format`: `"%d rpm"` |
| `ui.slider_float(label, min, max [, default, format])` | `element` | Float slider |
| `ui.combo(label, items [, default])` | `element` | Dropdown (0-indexed) |
| `ui.multi_combo(label, items [, defaults])` | `element` | Multi-select. `defaults`: `{false, true, ...}` |
| `ui.color(label [, default, alpha])` | `element` | Color picker. `alpha` enables alpha channel (default `true`) |
| `ui.button(label [, fn])` | `element` | Button with click callback |
| `ui.text(label [, default])` | `element` | Text input |
| `ui.label(text)` | `element` | Static text |
| `ui.keybind(label [, vk])` | `element` | Key bind selector |
| `ui.listbox(label, items [, rows, default])` | `element` | Scrollable list with its label above the box. `rows` (default 5, at most 11) is how many rows are visible; when there are more items, a quarter of the next row shows and the list scrolls |
| `ui.divider([label])` | `element` | Separator line |
| `ui.image(label, texture [, height])` | `element` | Image display |
| `ui.custom(label, height, fn)` | `element` | Custom draw row. `fn(x, y, w, h, input)` |
| `ui.widget(name, width, height, fn)` | `element` | Floating panel. `fn(x, y, w, h, input)` |

## Element methods

| Method | Returns | Description |
| - | - | - |
| `elem:get([index])` | value | Get current value. `index` for multi\_combo items |
| `elem:set(value [, index, bool])` | | Set value |
| `elem:visible([show])` | `bool` / | Get or set visibility |
| `elem:depends(other [, value])` | `self` | Show only when `other` equals `value` |
| `elem:callback(fn)` | `self` | On-change callback |
| `elem:items(list)` | | Replace combo/listbox items |
| `elem:active()` | `bool` | Whether keybind is held |
| `elem:name()` | `string` | Element label |
| `elem:tooltip([text])` | `string` / `self` | Get or set tooltip |
| `elem:inactive([flag, reason])` | `bool` / `self` | Grey out with reason text |
| `elem:image(texture)` | `self` | Change displayed image |
| `elem:position()` | `x, y` | Widget screen position |
| `elem:set_position(x, y)` | `self` | Set widget position |

## Built-in menu controls: `ui.find`

Scripts can read and drive the cheat's own menu controls. The path is the control's location in the menu, in English, from the root: section, tab, sub-tab (if any), group, popup title / titled popup section (if the control lives in a popup), control name. Matching is case-insensitive.

```lua theme={null} theme={null}
local enabled = ui.find('Aimbot', 'Rage', 'Main', 'Enabled')
local selftrack = ui.find('Aimbot', 'Rage', 'Main', 'Limiters', 'Selftrack')
```

**Copy Path.** Turn on *Developer Mode* in the user popup (click your name at the bottom of the sidebar), then right-click any control: the hotkey popup gets a **Copy Path** row that copies the exact `ui.find(...)` call for that control to the clipboard, e.g. `ui.find("Aimbot", "Rage", "Main", "Enabled")`. Right-clicking the row copies it with single quotes.

| Call | Returns |
| - | - |
| `ui.find(part, part, ..., control)` | a control reference, or `nil` if the path is unknown. The same path always returns the same reference (`==` works) |
| `ui.find(part, ..., group)` | a group object: add your own elements into that built-in group |
| `ui.find(page, group)` | old two-argument form, same as above |

`ui.find` works whether the menu is open or closed.

### Control reference methods

Value types: toggle → `boolean`; slider → `number` (integer for integer sliders); combo → item name (an index is also accepted when setting); multi-combo → table of item names.

| Method | Description |
| - | - |
| `ref:get()` | Effective value (after hotkeys and overrides). A toggle disabled with `set_disabled` reads as `false` |
| `ref:get_value()` | The control's own value (or its active bind value), ignoring overrides |
| `ref:set_value(v)` | Writes the control's own value and clears this script's override |
| `ref:get_raw_value()` | Current override, or `nil` |
| `ref:set_raw_value(v)` | **Override**: forces the value above hotkeys. Not saved to the config, removed when the script unloads. `ref:set_raw_value(nil)` clears it |
| `ref:get_values()` / `ref:set_values(t)` | Multi-combo: own selection (table of item names) |
| `ref:get_raw_values()` / `ref:set_raw_values(t)` | Multi-combo: override (`nil` clears) |
| `ref:get_effective_values()` | Multi-combo: effective selection |
| `ref:get_default()` / `ref:set_default(v)` | Default value |
| `ref:get_visible()` / `ref:set_visible(bool)` | Hide or show the row in the menu (nlcrack extension, reverted when the script unloads) |
| `ref:get_disabled()` / `ref:set_disabled(bool)` | Draw the row as inactive (nlcrack extension, reverted when the script unloads) |
| `ref:get_name()` | English name |
| `ref:get_tooltip()` | The row's tooltip text, or `nil` |
| `ref:get_icon()` | Icon (empty string for built-in controls) |
| `ref:get_id()` | Numeric id |
| `ref:get_type()` | `'toggle'`, `'slider'`, `'combo'` or `'multicombo'` |
| `ref:get_is_down()` | Always `false` for built-in controls |
| `ref:get_parent()` | Parent control or group |
| `ref:get_items()` | Combo / multi-combo item names |
| `ref:get_min()` / `ref:get_max()` | Slider range |
| `ref:set_min(n)` / `ref:set_max(n)` | Change a slider's range (the menu slider follows); the value is clamped. Errors: `"option is not a slider"`, `"max value should be greater than the min value"` |
| `ref:export()` | The control's value as a JSON string |
| `ref:group()` | A group inside the control's "..." popup (created if the control has none); you can add your own elements to it. Inside a popup: error `"cannot create a group on an element that is already inside a group"` |
| `ref:add_callback(fn)` / `ref:remove_callback(fn)` | `fn(ref)` is called when the value changes |
| `tostring(ref)`, `==` | The control's Copy Path text; references to the same control compare equal |

These raise an error on built-in controls (as in the original API, they only work on elements your script owns): `set_name`, `set_icon`, `set_items`, `import` (`"script does not own this element"`), `set_tooltip` (`"cannot change the tooltip of the default menu item"`), `color_picker` / `color_set` / `color_modes`, `chip` (`"chips can only be added to entity elements"`), `get_category` / `set_category` / `get_categories` (`"option is not a color picker"`).

### Extra roots

| Path | Controls |
| - | - |
| `ui.find('settings', name)` | The user popup: `Menu Scale`, `ESP Scale`, `Windows Scale`, `Units`, `Safe Mode`, `Synchronization`, `Developer Mode`. Scale combos read item names and accept the numeric value when set (e.g. `150`) |
| `ui.find('esp options', 'Universal DPI Scaling')` | The ESP Items toggle |

```lua theme={null} theme={null}
local dt = ui.find('Aimbot', 'Rage', 'Other', 'Double Tap')
local hc = ui.find('Aimbot', 'Rage', 'Selection', 'Hit Chance')

events.on('createmove', function()
    if dt:get() then
        hc:set_raw_value(50)
    else
        hc:set_raw_value(nil)
    end
end)
```

## Input table (custom/widget)

The `input` argument passed to custom draw callbacks:

| Field | Type | Description |
| - | - | - |
| `hover` | `bool` | Mouse is over the area |
| `click` | `bool` | Mouse was clicked |
| `rclick` | `bool` | Right-clicked |
| `mx, my` | `number` | Mouse position |

## Example

```lua theme={null} theme={null}
local tab = ui.tab('Visuals')
local group = tab:group('Crosshair')

local enable = group.checkbox('Enable', true)
local col = group.color('Color', color(0, 255, 100))
local size = group.slider_int('Size', 1, 20, 6)
local gap = group.slider_int('Gap', 0, 10, 2)

size:depends(enable)
gap:depends(enable)
col:depends(enable)

events.on('paint', function()
    if not enable:get() then return end
    local w, h = render.screen_size()
    local cx, cy = w / 2, h / 2
    local s, g = size:get(), gap:get()
    local c = col:get()
    render.line(cx - s - g, cy, cx - g, cy, c)
    render.line(cx + g, cy, cx + s + g, cy, c)
    render.line(cx, cy - s - g, cx, cy - g, c)
    render.line(cx, cy + g, cx, cy + s + g, c)
end)
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.