Theming

Every lation ui component is drawn from one set of theme tokens: colors, corner radius, font, UI scale, panel opacity, shadow and border width. Admins change them in game with the theme editor, players can keep their own on top if you allow it, and scripts can read or set them through exports.

How themes stackCopy Anchor Link

Three layers apply in this order, each one overriding the one before it key by key:

1. Built-in defaults. What you see on a fresh install.
2. Server theme. Set by admins with /uitheme, saved to data/theme.json and sent to every player.
3. Personal theme. Set by each player with /uisettings, only while the server allows it.

A personal theme stores only what the player set, so anything they leave alone follows the server theme.

Server themeCopy Anchor Link

add_ace group.admin lation_ui.admin allow

Reset to defaults, at the top of the Presets page, clears the server theme back to the built-in look for everyone. It asks first, then saves at once and closes the editor.

The server checks lation_ui.admin when the editor opens and again on every save and reset, so a player without it can't change the server theme. Each admin can save once a second, and a theme larger than 16 KB of JSON is refused (the console says Rejected theme save).

Personal themesCopy Anchor Link

setr lation_ui:allowUserThemes 1

Players already connected pick up a change to the convar when they next join, or the next time an admin saves or resets the server theme. If you turn it off, saved personal themes are ignored and everyone sees the server theme; turn it back on and they return.

The theme editorCopy Anchor Link

The editor is a panel with a rail of four pages down its left side: Presets, Colors, Shape & type and Components. Rest the pointer on the rail to see their names, or pin it open with the pin at its foot. Every change applies as you make it, and the editor's own panel wears the theme you're editing, so it is the preview. Nothing is kept until Save.

Along the top right:

A dot marks every value that differs from the preset your theme is built on (Lation, the built-in look, unless you picked another; in a personal theme, the server theme), and pointing at its row shows a button that puts that one value back. The line under each page counts them, such as "2 changed from default", with a button that resets the whole page at once.

The panel never goes below 85% opacity, so it stays readable over the game while you try a lower Panel opacity; the components take the value you set.

PresetsCopy Anchor Link

The editor opens on its presets: a card for each, with a notification and a menu drawn in that preset's colors and its palette beside its name. Click one and the whole editor takes that look. The one your theme is built on says In use, or Edited once you've changed anything since.

A preset replaces the colors, shape and type. Component overrides stay as they are. In a personal theme, the first card is the server theme itself, and every preset is shown over it, as it would look once saved.

ColorsCopy Anchor Link

Fifteen colors in four cards, each row saying what the color paints. Click a swatch for a picker, or type the hex beside it.

Each sets one of the color tokens.

Shape & typeCopy Anchor Link

A number typed outside its range is brought back to the nearest end when you leave the field.

ComponentsCopy Anchor Link

A card for each of the 13 components: Notifications, Menu, List Menu, Progress Bar, Text UI, Alert Dialog, Input Dialog, Radial Menu, Drawer, Skill Check, Pattern Lock, Signal Breach and Timeline. Each says what the component is and either "Inherits the general theme" or how many values it overrides.

A card opens that component's own page, with an arrow back. It takes 13 of the colors (all but Text (muted) and Headings), corner radius and panel opacity. Anything left unset follows the general theme, a reset puts a value back to it, and Clear overrides at the foot of the page removes them all.

FontsCopy Anchor Link

Inter (the default) and JetBrains Mono are bundled with the resource. The others load from Google Fonts the first time a theme uses them: Roboto, Rubik, Poppins, Nunito Sans, Barlow, Manrope, Sora, Outfit, Space Grotesk, IBM Plex Sans, Titillium Web, Saira, Exo 2, Chakra Petch, Oxanium, Orbitron, Fira Code and Space Mono. The Glass preset uses Outfit and Poster uses Space Grotesk, so they load them too. If a player can't reach Google Fonts, the text falls back to the next font in the stack. No other font can trigger a download. The picker lists them as Built in, Sans-serif, Display and Monospace, each name in its own face.

UI scaleCopy Anchor Link

lation ui scales with the screen's height, so it takes the same share of the screen at 1440p or 4K as at 1080p. It never gets smaller than its 1080p size and stops growing at twice that. UI scale multiplies on top.

Share codesCopy Anchor Link

The arrows at the top of the editor open Export or import:

• Export shows the theme you're editing as one code, with Copy. If the game blocks the clipboard, select the code and copy it yourself.
• Import takes a code you paste and says at once when it isn't a theme. Apply import (or Enter) loads it into the editor in place of everything there, component overrides included. Nothing is kept until you save.

A share code is LATION1. followed by the theme as base64-encoded JSON. Paste it into Import on any server to get the same look. An imported code goes through the same checks as any other theme, so invalid values are dropped.

Theme formatCopy Anchor Link

A theme is one JSON object. global holds tokens for every component; components holds overrides per component. Every key is optional.

{
  "version": 1,
  "global": {
    "accent": "#8B5CF6",
    "surface": "#0E0E14",
    "radius": 14,
    "shadow": "strong"
  },
  "components": {
    "notify": { "accent": "#22C55E", "opacity": 0.9 },
    "progress": { "radius": 4 }
  }
}

The component keys are notify, menu, listmenu, progress, textui, alert, input, radial, drawer, skillcheck, patternlock, signalbreach and timeline.

lation ui checks every value when it applies a theme. Colors that aren't hex and unknown keys are dropped, and numbers are clamped to the ranges below.

Color tokensCopy Anchor Link

Colors are hex strings, #RGB or #RRGGBB.

accentSoft, successSoft, errorSoft, warningSoft, lineHover and contentIcon have no control in the editor; set them in the JSON or through setServerTheme. When a theme sets accent, success, error or warning without its soft variant, the soft variant is worked out for you: the base mixed 30% toward white, or 30% toward black on a light theme.

Text on a solid accent (a selected date, a checked box) is white, or black when white would read at less than 3:1 on that accent.

Light themesCopy Anchor Link

A theme whose surface is light, such as Paper or Poster, is drawn as ink on paper:

• Soft colors are worked out toward black instead of white, as above.
• Colors your scripts pass, such as an iconColor or a progress bar's color, are drawn 30% darker, since they were picked for a dark panel. A notification or text UI on its own bgColor keeps them as passed.
• Disabled list menu rows, disabled input fields and the descriptions of disabled menu options fade less.
• The alert, input and drawer buttons take their colors from the theme, and Signal Breach's cyan is deepened.

A component block that sets its own surface is judged on its own; the others follow the global one.

Other tokensCopy Anchor Link

Theme exportsCopy Anchor Link

Use these from your own scripts to read or set the theme.

getThemeCopy Anchor Link

local theme = exports.lation_ui:getTheme()

It returns the saved themes, so a theme applied with setTheme isn't part of it.

local theme = exports.lation_ui:getTheme()
local accent = theme and theme.global and theme.global.accent or '#3B82F6'

setThemeCopy Anchor Link

local ok = exports.lation_ui:setTheme(theme)

Applies a theme on this player's client without saving it, and fires lation_ui:themeChanged. It lasts until lation ui puts the saved theme back: when an admin saves or resets the server theme, when the player closes the theme editor, or when you call setTheme(nil).

-- A red interface while the player is wanted
exports.lation_ui:setTheme({ version = 1, global = { accent = '#EF4444' } })

-- And back to normal
exports.lation_ui:setTheme(nil)

getServerThemeCopy Anchor Link

local theme = exports.lation_ui:getServerTheme()

local theme = exports.lation_ui:getServerTheme()
print(theme and json.encode(theme) or 'built-in theme')

setServerThemeCopy Anchor Link

local ok = exports.lation_ui:setServerTheme(theme)

Saves the theme to data/theme.json and sends it to every player, as Save in the editor does. It needs no permission: any server script can call it.

exports.lation_ui:setServerTheme({
    version = 1,
    global = {
        accent = '#F59E0B',
        radius = 4,
        borderWidth = 2,
        shadow = 'none'
    }
})

lation_ui:themeChangedCopy Anchor Link

AddEventHandler('lation_ui:themeChanged', function(theme) end)

A local client event, fired whenever the theme the player sees changes: a server theme arriving, a personal theme saved or reset, or a setTheme call. The same theme twice in a row is sent once.

AddEventHandler('lation_ui:themeChanged', function(theme)
    local accent = theme and theme.global and theme.global.accent or '#3B82F6'
    SendNUIMessage({ action = 'setAccent', accent = accent })
end)

Scripts that follow the themeCopy Anchor Link

lation interact, lation banking, lation shops and lation jobs read getTheme when they start and again each time lation ui's server sends the theme (the lation_ui:themeSync client event), so a server theme saved with /uitheme reaches them at once. A player's personal theme reaches them when that player next joins. They follow the global tokens; component overrides style lation ui's own components only. Without lation ui they use the same built-in defaults.

For a script of your own, listen for lation_ui:themeChanged instead: it also fires when a player saves a personal theme.