Kura UI

Kura UI is the shared interface layer for the Kura ecosystem. It currently ships:

• one always-loaded NUI application
• a shared overlay registry so multiple resources can render at the same time
• a reusable controls overlay for hints like ESC Back
• client ownership tracking and cleanup on resource stop
• server relay helpers for target-player HUD overlays

Recommended style

For Kura-native resources, prefer the kura.ui global through @kura-core/init.lua.

local ui <const> = kura.ui

if not ui then
  return
end

ui.controls.show({
  id = 'garage:navigation',
  anchor = 'bottom-right',
  items = {
    { input = 'ESC', label = 'Back' },
    { input = 'ENTER', label = 'Select' },
  },
})

That is the recommended default for normal Kura UI usage:

• kura.ui for Kura-native resources
• stable ids for overlays you need to update later
• anchor plus offset for layout
• server relay only for player-targeted HUD overlays
• multiple resources rendered together instead of singleton UI ownership

Download Kura UI

1. Get the latest release from GitHub
2. Extract it into your server's resources directory
3. Ensure the folder is named kura-ui

Configure your server

For Kura-native servers, use this start order:

ensure kura-lib
ensure kuradb
ensure kura-ui
ensure kura-core

Then add ensure kura-ui to your server.cfg if it is not already in your base startup list.

Add to your resource

shared_scripts {
    '@kura-core/init.lua',
}

local ui = exports['kura-ui']:getInterface()

Editor setup

For LuaLS, add kura-ui to your workspace library paths once. Kura source checkouts can use:

{
  "Lua.runtime.version": "Lua 5.4",
  "Lua.diagnostics.globals": ["kura"],
  "Lua.workspace.checkThirdParty": false,
  "Lua.workspace.library": [
    "./kura-core",
    "./kura-lib",
    "./kura-ui",
    "./db/kuradb/lib"
  ]
}

Overlay model

kura-ui does not treat HUD elements as singletons.

Each resource can register its own overlay nodes, and Kura UI:

• tracks ownership per resource
• stacks overlays in the same anchor instead of replacing them
• clears a resource's overlays automatically when that resource stops
• keeps client-owned overlays and server-relayed overlays separate internally

That is what allows a future confirmation modal and a controls hint set to exist together without conflicting.

Your first controls overlay

local ui <const> = kura.ui

if not ui then
  return
end

local controlsId = ui.controls.show({
  id = 'inventory:controls',
  anchor = 'bottom-right',
  items = {
    { input = 'ESC', label = 'Close' },
    { input = 'TAB', label = 'Move focus' },
  },
})

ui.controls.update(controlsId, {
  items = {
    { input = 'ESC', label = 'Back' },
    { input = 'ENTER', label = 'Confirm' },
  },
})

Server relay example

Use the server surface when you want to show HUD controls for one or more target players:

local ui <const> = kura.ui

local id = ui.controls.showFor(source, {
  id = 'confirm:controls',
  anchor = 'bottom-right',
  items = {
    { input = 'ESC', label = 'Cancel' },
    { input = 'ENTER', label = 'Confirm' },
  },
})

ui.controls.hideFor(source, id)

Kura architecture note

Use kura-ui directly for reusable presentation primitives and shared framework UI.

For gameplay systems such as inventory, menus, shops, garages, or character creation, prefer higher-level Kura APIs when they exist. Those APIs can compose shared UI behavior, input routing, validation, and state flow on top of the base overlay layer.

What's next

• Controls — The full kura.ui.controls API, anchors, updates, and server relay usage