> For the complete documentation index, see [llms.txt](https://devix.gitbook.io/devix/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://devix.gitbook.io/devix/devix-core/user-interface.md). # User Interface Lightweight in-game overlay in **devix-core** for toasts, keybind hints, and a proximity-style prompt. ## Features | Feature | Position | Lua API | | ---------------- | ------------- | --------------------------------------------------- | | Toasts | Top-right | `DEVIX.UINotify` / `exports['devix-core']:UINotify` | | Keybind hints | Bottom-right | `DEVIX.UISetKeybinds`, `UIClearKeybinds` | | Proximity prompt | Bottom-center | `DEVIX.UIShowPrompt`, `UIHidePrompt` | ## Prerequisites * Resource: **`ensure devix-core`** before scripts that use the UI. * **Client-side only** — use from `client/*.lua`, not server. * Three equivalent ways to call the APIs: ```lua -- 1) DEVIX (available after devix-core client loads) DEVIX.UINotify("Hello", "success") -- 2) Export (any client script) exports['devix-core']:UINotify("Hello", "success") -- 3) Net event TriggerEvent('devix-core:client:UINotify', "Hello", "success") -- Table args: TriggerEvent('devix-core:client:UIShowPrompt', { key = "E", label = "Use" }) ``` ## Usage examples — `UINotify` (toast) **Minimal** ```lua DEVIX.UINotify("Item picked up") -- type defaults to "primary"; duration uses Config.DevixUI.NotifyDuration ``` **Types + duration (ms)** ```lua DEVIX.UINotify("Saved", "success", 3500) DEVIX.UINotify("Payment failed", "error", 6000) DEVIX.UINotify("Check engine", "warning", 5000) DEVIX.UINotify("Tip text", "info", 4000) DEVIX.UINotify("Neutral", "primary", 4500) ``` **From another resource** ```lua exports['devix-core']:UINotify("Garage stored", "success", 3000) ``` **After an async result** ```lua RegisterNetEvent('myresource:client:result', function(ok, message) DEVIX.UINotify(message or (ok and "OK" or "Failed"), ok and "success" or "error") end) ``` ## Usage examples — `UISetKeybinds` / `UIClearKeybinds` **Static hints** (stay until you clear or replace) ```lua DEVIX.UISetKeybinds({ { key = "E", label = "Open door" }, }) DEVIX.UIClearKeybinds() ``` **Multiple rows** ```lua DEVIX.UISetKeybinds({ { key = "Q", label = "Previous" }, { key = "E", label = "Next" }, { key = "Enter", label = "Confirm" }, }) ``` **Loop + `keepAlive`** (refresh each tick so the overlay does not expire while the loop runs) ```lua CreateThread(function() while inCustomizer do Wait(0) DEVIX.UISetKeybinds({ { key = "←", label = "Part -" }, { key = "→", label = "Part +" }, }, { keepAlive = true, keepAliveMs = 800, -- > your Wait(); can override Config.DevixUI.KeepAliveMs }) end DEVIX.UIClearKeybinds() end) ``` **Custom window only for keybinds** ```lua DEVIX.UISetKeybinds({ { key = "G", label = "Drop" } }, { keepAlive = true, keepAliveMs = 2500, }) ``` ## Usage examples — `UIShowPrompt` / `UIHidePrompt` ### A) Proximity loop (default keepAlive) Call while the player is in range. Same `key` + `label` → Lua does not spam NUI. ```lua CreateThread(function() while true do local sleep = 500 if IsPlayerNearShop() then -- your check sleep = 0 DEVIX.UIShowPrompt({ key = "E", label = "Browse shop" }) end Wait(sleep) end end) ``` Set `Config.DevixUI.KeepAliveMs` **above** your `Wait()` when the prompt should stay visible (e.g. `Wait(500)` → use at least `800–1000` ms or call every frame with `Wait(0)`). ### B) Manual prompt (`UIHidePrompt` required) ```lua DEVIX.UIShowPrompt({ key = "E", label = "Hold to search", keepAlive = false, -- or: persistent = true }) -- ... DEVIX.UIHidePrompt() ``` ### C) `Key` / `Label` (capital aliases) ```lua DEVIX.UIShowPrompt({ Key = "G", Label = "Throw" }) ``` ### D) Per-call keepAlive timeout ```lua DEVIX.UIShowPrompt({ key = "E", label = "Enter", keepAliveMs = 3000, }) ``` ### E) Exports ```lua exports['devix-core']:UIShowPrompt({ key = "E", label = "Lockpick" }) exports['devix-core']:UIHidePrompt() ``` ## Usage example — prompt + notify together ```lua CreateThread(function() while true do Wait(0) if CanRepairHere() then DEVIX.UIShowPrompt({ key = "E", label = "Repair ($500)" }) if IsControlJustReleased(0, 38) then -- E local ok = lib.callback.await('mechanic:tryRepair', false) DEVIX.UINotify(ok and "Repaired" or "Not enough money", ok and "success" or "error") end end end end) ``` ## Server → client (notify from server) `UINotify` is **client-only**. From **server** Lua, trigger the registered client event: ```lua -- Server — show toast to one player (src = player id) TriggerClientEvent('devix-core:client:UINotify', src, 'Quest turned in', 'success', 4500) -- Args: message, type (optional), durationMs (optional) ``` ```lua -- Server — all players TriggerClientEvent('devix-core:client:UINotify', -1, 'Server restarting in 60s', 'warning', 8000) ``` Prompt and keybinds are normally driven from **client** (proximity loops). If you need server-driven prompt, add your own `RegisterNetEvent` in your resource’s client that calls `UIShowPrompt`. ## Configuration (`Config.DevixUI`) | Key | Purpose | | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `NotifyDuration` | Default toast lifetime (ms). | | `NotifyMax` | Max concurrent toasts; oldest removed first. | | `GlassBlur` | Blur strength for `data-hlsl` glass (`data-blur-strength`). | | `KeepAliveMs` | For **keepAlive** prompt/keybinds: if no refresh within this window, the UI auto-hides. **Should be greater than your loop `Wait()`** or you get hide/show flicker. | `client/cl_ui.lua` pushes these to NUI on `devix-ui:ready` as `devix-ui:init`. ## Prompt (`UIShowPrompt`) ### Default behaviour (proximity / loop) * Omit `persistent` and do **not** set `keepAlive = false` → **keepAlive is on**. * Call `UIShowPrompt({ key = "E", label = "Interact" })` every tick inside your loop. * Each call **refreshes the deadline** (`GetGameTimer() + KeepAliveMs`). * If the **same** `key` + `label` is already shown, Lua **does not** resend NUI (signature dedupe) → less spam. * When the deadline passes without another call, client sends `devix-ui:prompt:hide`. ### Fixed / manual prompt * `persistent = true` **or** `keepAlive = false` → no auto-hide from keepAlive; you must call `UIHidePrompt()`. ### Options ```lua DEVIX.UIShowPrompt({ key = "E", -- or Key label = "Use", -- or Label keepAlive = true, -- optional; default true unless persistent / false keepAliveMs = 2500, -- optional; overrides Config.DevixUI.KeepAliveMs persistent = false, -- if true → manual hide only }) ``` ### NUI behaviour (no open animation) * **Show**: `devix-hidden` is removed; the prompt appears **immediately** (no enter keyframes). This avoids flicker with WebGL blur and keepAlive hide/show cycles. * **Hide**: inner `.devix-prompt-panel` plays a short **exit** animation, then the root is hidden. * **Dedupe (JS)**: If the prompt is already visible and `key + label` is unchanged, `showPrompt` returns early (no DOM churn). ## Keybind hints (`UISetKeybinds`) ```lua DEVIX.UISetKeybinds({ { key = "F", label = "Flashlight" }, }, { keepAlive = true, -- refresh deadline each call; auto-clear when idle keepAliveMs = 2000, }) ``` Empty table + `UIClearKeybinds` sends `{ items = {} }` and hides the stack. ## Toasts (`UINotify`) ```lua DEVIX.UINotify("Saved", "success", 4000) -- types: success | error | warning | primary | info ``` NUI stacks toasts, applies enter/leave animations, progress bar, and `data-hlsl` per toast. ## NUI message contract | `action` | `data` | | ---------------------- | ------------------------------------------ | | `devix-ui:init` | `{ notifyDuration, notifyMax, glassBlur }` | | `devix-ui:notify` | `{ message, type, duration }` | | `devix-ui:keybinds` | `{ items = { { key, label }, ... } }` | | `devix-ui:prompt` | `{ visible = true, key, label }` | | `devix-ui:prompt:hide` | `{}` | ## Events & exports **Net events** * `devix-core:client:UINotify` * `devix-core:client:UISetKeybinds` * `devix-core:client:UIClearKeybinds` * `devix-core:client:UIShowPrompt` * `devix-core:client:UIHidePrompt` **Exports** (same names as `DEVIX.`\* functions). ## Troubleshooting | Symptom | Likely cause | | -------------------------------- | ------------------------------------------------------------------------------------------------- | | Prompt flickers on/off in a loop | `KeepAliveMs` shorter than time between `UIShowPrompt` calls; increase config or call more often. | | Prompt never hides | `persistent` or `keepAlive = false` without `UIHidePrompt`. | --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://devix.gitbook.io/devix/devix-core/user-interface.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.