CityRP Documentation Repository

cityrp.ui

Primary UI library for CityRP 2. Two halves. Resolution-aware scaling for every Derma panel and HUD element, consistent across screen resolutions and respecting the player's HUD scale preference (cl_llhud_scale ConVar). And the panel kit -- frame chrome, buttons, lists, cards -- that the patterns in docs/ui-style.md are built from, so a panel matches the ones around it without retyping them.

Functions

Clientcityrp.ui.AddTitleBarCloseButton(frame, titleBarHeight, onClose) → PanelSource ☍

Adds a text-only close button to a frame title bar, matching the cooking stove UI. The stock DFrame close control is hidden by the cityrp.ui chrome; this draws a plain centred X on the dark header rather than a coloured box.

Parameters

  • framePanelThe menu frame. Must already be sized for layout to settle.
  • titleBarHeightnumberTitle bar height from the styled frame.
  • onClosefunctionCalled when pressed.

Returns

  1. PanelThe close button.
Clientcityrp.ui.ButtonColours(variant) → UIButtonColoursSource ☍

A button variant's state fills and label colour, for a control that must match a button but cannot be one. Shared and cached: read-only.

variant:
    | "accent" -- The primary action, in COL_BRAND. One per view.
    | "neutral" -- The default, in COL_PANEL_BUTTON.
    | "positive" -- Confirm or save, in COL_SUCCESS.
    | "danger" -- Destructive, in COL_DANGER.

Parameters

  • variant("accent"|"danger"|"neutral"|"positive")?Defaults to "neutral", as does an unknown variant.

Returns

  1. UIButtonColours
Clientcityrp.ui.CreateScaledFont(name, baseFont, baseSize, weight) → stringSource ☍

Creates a resolution-aware font that scales with the UI scale factor. The font size is automatically calculated based on the current scale factor and rounded to the nearest integer for crisp rendering.

cityrp.ui.CreateScaledFont("MyFont", "Open Sans", 14) -- Creates 14px font that scales
cityrp.ui.CreateScaledFont("BoldTitle", "Open Sans", 24, 700) -- Creates bold 24px font

Parameters

  • namestringUnique identifier for the font (e.g., "MyScaledFont")
  • baseFontstringFont family name (e.g., "Open Sans", "Roboto", "Arial")
  • baseSizenumberBase font size in pixels at 1920x1080 reference resolution
  • weightnumber?Font weight (100-900, default: 500 for normal weight)

Returns

  1. stringThe name of the created font (same as input name parameter)
Clientcityrp.ui.GetScaleFactor() → numberSource ☍

Gets the current UI scale factor for resolution-aware rendering. Combines automatic resolution-based scaling with user-adjustable HUD scale. The scale factor is calculated as: (baseScale * autoScale), where:

  • baseScale = cl_llhud_scale ConVar value (0.5 to 2.0, default 1.0)
  • autoScale = max(0.75, screenWidth / 1920)
local scale = cityrp.ui.GetScaleFactor() -- Returns 2.67 on 5120x1440 with default settings

Returns

  1. numberThe total scale factor to apply to UI elements (typically 0.75 to 5.0+)
Clientcityrp.ui.OnScaleChanged(id, callback)Source ☍

Runs callback now, and again (debounced) whenever the UI scale changes. The first call is synchronous, so fonts registered here exist on the next line -- in exchange, the callback must be safe to run at registration time.

Parameters

  • idstringUnique identifier, used to name the callback, hook and timer.
  • callbackfunctionCalled now, and again once a later scale change has settled.

Example

cityrp.ui.OnScaleChanged("door", createDoorMenuFonts)
Clientcityrp.ui.PaintCard(panel, w, h, fill)Source ☍

Draws the card's 1px inset border and fill. Call from a Paint override that has its own drawing to do on top; StyleCard is the whole-panel form.

Parameters

  • panelPanelUnused, so that this reads as a Paint body.
  • wnumberPanel width.
  • hnumberPanel height.
  • fillColor?Inner fill. Defaults to COL_PANEL_CARD.
Clientcityrp.ui.Scale(value) → numberSource ☍

Scales a single value based on the current UI scale factor. This is the primary function for scaling individual dimensions, margins, positions, etc.

Rounded to a whole pixel. The raw product is almost always fractional, and fractional pixel geometry misbehaves: panels land on half pixels and render soft, adjacent elements sized from the same base can differ by one, and anything fed into a moving effect such as a screen bounce jitters as the fraction rounds differently frame to frame.

Use GetScaleFactor directly if you genuinely need the unrounded factor -- for a value that is not a pixel measurement, or where you intend to do the arithmetic first and round once at the end.

local scaledWidth = cityrp.ui.Scale(128) -- Returns 341 on 5120x1440 with 1.0x user scale
local scaledMargin = cityrp.ui.Scale(8) -- Scales margin consistently with screen size

Parameters

  • valuenumberThe base value to scale (in pixels at 1920x1080 reference resolution)

Returns

  1. numberThe value multiplied by the current scale factor, to the nearest pixel
Clientcityrp.ui.ScaleCheckBox(checkbox, font)Source ☍

Applies a scaled font to a DCheckBoxLabel and grows its tick box to match. DCheckBoxLabel lays the box out at a fixed size, so setting a scaled font on one leaves a small box beside large text. This takes over the checkbox's layout so the two stay in proportion.

Guarded: if the panel's internals are not where we expect, the font is still applied and the stock layout is left alone rather than erroring.

cityrp.ui.ScaleCheckBox(self.lockdoors, "DoorMenuDefault")

Parameters

  • checkboxPanelThe DCheckBoxLabel to scale.
  • fontstringThe name of a scaled font, as made by CreateScaledFont.
Clientcityrp.ui.Shade(colour, amount) → ColorSource ☍

Lightens or darkens a colour, preserving its alpha. Returns a new colour rather than mutating the one passed in, which matters because the shared COL_* enumerations are the usual input.

Allocates. Cache the result -- work out a panel's hover and pressed shades once when you style it, not inside its Paint, or you are building a colour every frame the cursor rests on it.

local hover = cityrp.ui.Shade(COL_BRAND, 25) -- once, at style time

Parameters

  • colourColorThe base colour.
  • amountnumberPositive to lighten, negative to darken.

Returns

  1. ColorThe shifted colour.
Clientcityrp.ui.StyleButton(button, variant)Source ☍

Styles a DButton to one of the four variants, including its disabled state.

variant:
    | "accent" -- The primary action, in COL_BRAND. One per view.
    | "neutral" -- The default, in COL_PANEL_BUTTON.
    | "positive" -- Confirm or save, in COL_SUCCESS.
    | "danger" -- Destructive, in COL_DANGER.

Parameters

  • buttonPanelThe DButton to style.
  • variant("accent"|"danger"|"neutral"|"positive")?Defaults to "neutral".
Clientcityrp.ui.StyleCard(panel, fill)Source ☍

Gives a panel the card's inset border as its whole Paint.

Parameters

  • panelPanelThe panel to style.
  • fillColor?Inner fill. Defaults to COL_PANEL_CARD.
Clientcityrp.ui.StyleFrame(frame, heading, titleBarHeight) → numberSource ☍

Applies the standard frame chrome. The stock DFrame title and close button do not scale, so both are turned off and redrawn.

Parameters

  • framePanelThe DFrame to style.
  • headingstringTitle bar text. Pass "" for a bar with no heading.
  • titleBarHeightnumber?Scaled title bar height. Defaults to Scale(32), the multi-section frame height; a single-purpose popup passes cityrp.ui.Scale(26).

Returns

  1. numberThe height the title bar was drawn at.
Clientcityrp.ui.StyleList(list)Source ☍

Styles a DListView with scaled row heights and the panel palette. Wraps AddColumn and AddLine, so call it before either.

Parameters

  • listPanelThe DListView to style.

Classes

ClientUIButtonVariantSource ☍

Accepted values:

  • "accent" -- The primary action, in COL_BRAND. One per view.
  • "neutral" -- The default, in COL_PANEL_BUTTON.
  • "positive" -- Confirm or save, in COL_SUCCESS.
  • "danger" -- Destructive, in COL_DANGER.

Fields

Clientcityrp.ui.FONT_BODYSource ☍

The panel Body font: Roboto 14/400, the default for labels, rows, buttons and inputs.

Clientcityrp.ui.FONT_CAPTIONSource ☍

The panel Caption font: Roboto 12/500, for secondary lines, list headers and hints.

Clientcityrp.ui.FONT_TITLESource ☍

The panel Title font: Roboto 19/500, for a frame heading.

UIButtonColours

6 fields Source ☍
ClientUIButtonColours.baseSource ☍

Idle fill.

ClientUIButtonColours.disabledSource ☍

Disabled fill.

ClientUIButtonColours.downSource ☍

Pressed fill.

ClientUIButtonColours.hoverSource ☍

Hovered fill.

ClientUIButtonColours.labelSource ☍

Label colour, from COL_TEXT_ON.

ClientUIButtonColours.labelDisabledSource ☍

Label colour while disabled.