Module ui
UI Helper & Utility Functions
Standardized helpers used across mplib scripts for rendering text, panels, buttons, and player-related visuals.
These functions unify visual style and behavior for common UI components.
Functions
| uiTextConstrained (text, font, fontSize, maxWidth[, maxLines]) | Measure how much of a text string fits within given constraints (client). |
| uiDrawTextConstrained (text, font, fontSize, maxWidth[, maxLines]) | Draw constrained text with error highlighting for overflow debugging (client). |
| uiDrawTextEllipsis (text, font, fontSize, maxWidth[, maxLines]) | Draw constrained text that always uses ellipsis when truncated (client). |
| uiGetPlayerImage (playerId) | Retrieve the preview image path for a player's character (client). |
| uiDrawPlayerImage (playerId, width, height, roundingRadius[, outlineColor[, outlineThickness]]) | Draw a player's preview image with optional rounded outline (client). |
| uiDrawPlayerRow (playerId[, height], maxWidth[, color[, dim]]) | Draw a full player row including avatar and player name (client). |
| uiDrawPrimaryButton (title, width[, disabled]) | Draw a styled primary action button (client). |
| uiDrawSecondaryButton (title, width[, disabled]) | Draw a styled secondary action button (client). |
| uiDrawButton (title, width, color, hoverColor, outline[, disabled]) | Draw a generic button with configurable background, hover colors and outline (client). |
| uiDrawPanel (width, height[, radius]) | Draw a translucent panel with optional rounded corners (client). |
| uiDrawTextPanel (message[, alpha]) | Draw a text panel with background and padding (client). |
| uiDrawTextAndImagePanel (message, imageItem[, alpha]) | Draw a panel containing text and an image icon (client). |
Functions
- uiTextConstrained (text, font, fontSize, maxWidth[, maxLines])
-
Measure how much of a text string fits within given constraints (client).
Performs width or multi-line height fitting based on
maxLines. If the text does not fit, the function finds the longest substring that fits using a binary search, and appends an ellipsis.Parameters:
- text string Text to measure
- font string Font asset path
- fontSize number Font size
- maxWidth number Maximum allowed width
- maxLines number Maximum number of lines; if omitted, single-line (optional)
Returns:
-
boolean
fits
trueif the entire text fits - string displayedText Either the original text or truncated version
- uiDrawTextConstrained (text, font, fontSize, maxWidth[, maxLines])
-
Draw constrained text with error highlighting for overflow debugging (client).
Uses uiTextConstrained internally. If text overflows, displays the text in red to help identify problematic UI layouts.
Parameters:
- uiDrawTextEllipsis (text, font, fontSize, maxWidth[, maxLines])
-
Draw constrained text that always uses ellipsis when truncated (client).
Similar to uiDrawTextConstrained, but does not color overflow text red.
Parameters:
- uiGetPlayerImage (playerId)
-
Retrieve the preview image path for a player's character (client).
Falls back to a default placeholder preview image if none exists.
Parameters:
- playerId number Player ID
Returns:
-
string
imagePath Filepath to preview image
- uiDrawPlayerImage (playerId, width, height, roundingRadius[, outlineColor[, outlineThickness]])
-
Draw a player's preview image with optional rounded outline (client).
Renders the player avatar using the character preview image. Optionally draws an outline using the player's team color or a provided color array.
Parameters:
- playerId number Player ID
- width number Image width
- height number Image height
- roundingRadius number Corner radius
- outlineColor table {r,g,b,a} color array (optional)
- outlineThickness number Outline thickness (optional)
- uiDrawPlayerRow (playerId[, height], maxWidth[, color[, dim]])
-
Draw a full player row including avatar and player name (client).
Displays an avatar, player name, and color-coded status. Used in scoreboards and player lists. Auto-scales height and applies dimming or local-player highlighting.
Parameters:
- playerId number Player ID
- height number Height of the row (default: 32) (optional)
- maxWidth number Maximum width for name text
- color table Override color {r,g,b} (optional)
- dim boolean Whether to dim the row (optional)
- uiDrawPrimaryButton (title, width[, disabled])
-
Draw a styled primary action button (client).
Parameters:
- title string Button text
- width number Button width in pixels
- disabled boolean Disable input (optional)
Returns:
-
boolean
pressed
trueif clicked - uiDrawSecondaryButton (title, width[, disabled])
-
Draw a styled secondary action button (client).
Parameters:
- title string Button label
- width number Button width
- disabled boolean Disable input (optional)
Returns:
-
boolean
pressed
trueif clicked - uiDrawButton (title, width, color, hoverColor, outline[, disabled])
-
Draw a generic button with configurable background, hover colors and outline (client).
Base implementation for all button types in the mplib UI.
Parameters:
- title string Text displayed in button
- width number Button width
- color table Background {r,g,b,a}
- hoverColor table Hover highlight {r,g,b,a}
- outline boolean Whether to draw outline
- disabled boolean Disable interaction (optional)
Returns:
-
boolean
pressed
trueon click - uiDrawPanel (width, height[, radius])
-
Draw a translucent panel with optional rounded corners (client).
Used for modal dialogs, popups, player lists, and other UI grouping elements.
Parameters:
- width number Panel width
- height number Panel height
- radius number Corner radius (optional)
- uiDrawTextPanel (message[, alpha])
-
Draw a text panel with background and padding (client).
Common for notifications or tooltips within mplib UI.
Parameters:
- message string Text to display
- alpha number Opacity multiplier (optional)
- uiDrawTextAndImagePanel (message, imageItem[, alpha])
-
Draw a panel containing text and an image icon (client).
Often used for objective info.
Parameters: