← Back to Documentation Index

🖼️ UI System

Professional UI components: buttons, panels, text rendering, and layout helpers

📋 Overview

The UI System provides high-level components for building game interfaces. It includes interactive buttons with callbacks, decorative panels, advanced text rendering with shadows/outlines, progress bars, and layout utilities.

💡 Key Features
  • Button System - Interactive buttons with hover/press states and callbacks
  • Panel System - Decorative windows with borders, gradients, and titles
  • Text Rendering - Shadows, outlines, alignment, and font sizes
  • Progress Bars - Health bars, loading indicators, etc.
  • Layout Helpers - Centering, grid systems, responsive design

🔘 Button System

createButton(x, y, width, height, text, callback, options = {})

Creates an interactive button with hover effects and click callback.

x, y number - Button position
width, height number - Button size
text string - Button label
callback function - Called when button clicked
options object - Optional: normalColor, hoverColor, textColor, enabled, visible, etc.
Returns: object - Button object (store to modify later)
Example: Menu buttons
const startBtn = createButton(220, 150, 200, 40, "START GAME", () => {
  gameState = 'playing';
});

const quitBtn = createButton(220, 200, 200, 40, "QUIT", () => {
  // Quit game
}, {
  normalColor: rgba8(200, 50, 50),
  hoverColor: rgba8(255, 80, 80)
});
updateAllButtons()

Updates all button states (hover, click detection). Call in update() function.

Returns: boolean - true if any button was clicked
Example: Update loop
function update() {
  updateAllButtons(); // Check button interactions
}
drawAllButtons()

Renders all created buttons. Call in draw() function.

Example: Draw loop
function draw() {
  cls(rgba8(0, 0, 20));
  drawAllButtons(); // Render buttons
}
clearButtons()

Removes all buttons (useful for screen transitions).

removeButton(button)

Removes a specific button.

📦 Panel System

createPanel(x, y, width, height, options = {})

Creates a decorative panel/window with borders, gradients, and optional title bar.

x, y, width, height number - Panel position and size
options object - bgColor, borderColor, borderWidth, title, shadow, gradient, etc.
Returns: object - Panel object
Example: Info panel
const infoPanel = createPanel(50, 50, 300, 200, {
  title: "Game Info",
  bgColor: rgba8(0, 0, 50, 200),
  borderColor: uiColors.primary,
  borderWidth: 3,
  shadow: true,
  gradient: true
});
drawAllPanels()

Renders all panels. Call before drawing panel contents.

clearPanels()

Removes all panels.

✍️ Text Rendering

drawText(text, x, y, color = uiColors.white, scale = 1)

Draws text with current alignment and font settings.

text string - Text to display
x, y number - Position (affected by alignment)
color BigInt - Text color
scale number - Size multiplier
Example: Centered title
setTextAlign('center');
setTextBaseline('middle');
drawText("MY GAME", 320, 50, uiColors.primary, 3);
drawTextShadow(text, x, y, color, shadowColor, offset = 2, scale = 1)

Draws text with drop shadow effect.

Example: Title with shadow
drawTextShadow("LEVEL 1", 320, 100, 
  uiColors.white, uiColors.black, 3, 2);
drawTextOutline(text, x, y, color, outlineColor, scale = 1)

Draws text with outline (8-direction) for visibility on any background.

Example: Outlined score
drawTextOutline("SCORE: " + score, 10, 10, 
  uiColors.white, uiColors.black, 1);
setTextAlign(align)

Sets text horizontal alignment: "left", "center", or "right".

setTextBaseline(baseline)

Sets text vertical alignment: "top", "middle", or "bottom".

setFont(fontName)

Sets current font: "tiny", "small", "normal", "large", or "huge".

measureText(text, scale = 1)

Calculates text dimensions.

Returns: object - {width, height}

📊 Progress Bars

drawProgressBar(x, y, width, height, value, maxValue, options = {})

Draws a progress bar (health, loading, etc.).

value number - Current value
maxValue number - Maximum value
options object - fillColor, bgColor, borderColor, showText
Example: Health bar
drawProgressBar(10, 10, 200, 20, player.hp, player.maxHp, {
  fillColor: uiColors.success,
  bgColor: rgba8(50, 0, 0),
  showText: true
});

📐 Layout Helpers

centerX(width, screenWidth = 640)

Calculates X coordinate to center an element horizontally.

Returns: number - Centered X position
Example: Center button
const btnX = centerX(200); // Center 200px wide button
createButton(btnX, 150, 200, 40, "START", startGame);
centerY(height, screenHeight = 360)

Calculates Y coordinate to center an element vertically.

grid(cols, rows, cellWidth, cellHeight, paddingX = 0, paddingY = 0)

Creates a grid layout array for positioning elements.

Returns: array - Array of {x, y, width, height, col, row} objects
Example: Button grid
const cells = grid(3, 2, 100, 50, 10, 10);
cells.forEach((cell, i) => {
  createButton(cell.x + 50, cell.y + 100, 
    cell.width, cell.height, `BTN ${i}`, () => {});
});

🎨 Color Palette

The UI system provides a built-in color palette accessible via uiColors:

Color Name Value (RGB) Usage
uiColors.primaryrgba8(0, 120, 255)Primary buttons, borders
uiColors.secondaryrgba8(100, 100, 255)Secondary elements
uiColors.successrgba8(0, 255, 100)Health bars, positive
uiColors.warningrgba8(255, 200, 0)Warnings, caution
uiColors.dangerrgba8(255, 50, 50)Errors, critical
uiColors.whitergba8(255, 255, 255)Text, highlights
uiColors.blackrgba8(0, 0, 0)Shadows, backgrounds

💡 Complete Example

Full UI System Example
let gameState = 'menu';
let menuButtons = [];

function init() {
  // Create menu panel
  createPanel(170, 80, 300, 200, {
    title: "MAIN MENU",
    bgColor: rgba8(0, 0, 50, 220),
    borderColor: uiColors.primary,
    shadow: true,
    gradient: true
  });
  
  // Create buttons
  const btnX = centerX(200);
  createButton(btnX, 120, 200, 40, "START GAME", () => {
    gameState = 'playing';
    clearButtons();
    clearPanels();
  });
  
  createButton(btnX, 170, 200, 40, "OPTIONS", () => {
    gameState = 'options';
  });
  
  createButton(btnX, 220, 200, 40, "QUIT", () => {
    // Quit
  }, { normalColor: uiColors.danger });
}

function update() {
  if (gameState === 'menu') {
    updateAllButtons();
  }
}

function draw() {
  cls(rgba8(0, 0, 20));
  
  if (gameState === 'menu') {
    // Draw title
    setTextAlign('center');
    setFont('large');
    drawTextShadow("MY AWESOME GAME", 320, 40, 
      uiColors.primary, uiColors.black, 3, 2);
    
    // Draw UI
    drawAllPanels();
    drawAllButtons();
  }
}

📚 Related APIs