🧩 Canvas Engine UI Components

The UI system allows you to create buttons, text, images, progress bars and input fields directly on top of the game. UI elements are always drawn on a layer above the scene and can react to clicks, keys, or custom events. Even though UI elements are always visible above the scene, they are still managed inside the editor’s layer system.

📦 Main UI Types

• UIButton – Interactive button with click events.
• UILabel – Static or dynamic text.
• UIImage – Image or icon on screen.
• UIInputField – Editable text field.
• UIProgressBar – Visual progress bar.

🖱️ UIButton (Interactive Buttons)

UI buttons react to _onClickDown and _onClickUp events. You can use them to open menus, load scenes or execute any action.

Basic Example

function Start(obj) {
  const boton = getObjectByName("BtnIniciar");

  boton._onClickUp = () => {
    PlaySound("click.mp3");
    LoadSceneByName("MainScene");
  };
}

Modify appearance and state

boton.text = "Start Game";
boton.color = "#00bcd4";
boton.visible = true;
boton.active = true;

📝 UILabel (On-screen Text)

UILabel elements show static or dynamic text. You can update them in real time from Update().

Example: score display

function Update(obj, dt) {
  const label = getObjectByName("ScoreText");
  label.text = "Score: " + currentScore;
}

Useful Properties

• text: displayed content.
• color: text or background color depending on configuration.
• visible: show/hide the label.

🔤 UIInputField (Editable Text Field)

Allows the player to type text directly from the keyboard. When the user clicks the field, it gains focus (focused = true) and starts receiving input.

Usage Example

function Start(obj) {
  const campo = getObjectByName("InputNombre");
  campo.text = "Enter your name...";
  campo.color = "#ffffff";
  campo.focused = true;
}

Reading text in real time

function Update(obj, dt) {
  const campo = getObjectByName("InputNombre");
  if (campo.focused) {
    console.log("Typing:", campo.text);
  }
}

Input system events

• 🖊️ Typing: alphanumeric keys append characters.
• ⌫ Backspace: deletes last character.
• ↵ Enter: removes focus (focused = false).
• 🖱️ Click outside: also removes focus.

Combined example: field + button

function Start(obj) {
  const campo = getObjectByName("InputNombre");
  const boton = getObjectByName("BtnAceptar");

  boton._onClickUp = () => {
    PlaySound("confirm.mp3");
    console.log("👤 Entered name:", campo.text);
  };
}

🖼️ UIImage (Interface Images)

Displays an image inside the HUD, ideal for icons, logos or decorative UI elements.

function Start(obj) {
  const icono = getObjectByName("IconVida");
  icono.visible = true;
  icono.w = 64;
  icono.h = 64;
  icono.x = 20;
  icono.y = 20;
}

📊 UIProgressBar (Progress Bar)

The UIProgressBar visually shows a value between 0 and 1, useful for health, energy, loading or download progress. You can customize its color, background, border and percentage text.

Example: health bar

function Update(obj, dt) {
  const vida = getObjectByName("HealthBar");
  vida.value = player.hp / player.maxHp;
}

Properties

• value: current value (0 to 1).
• color: bar color.
• background: background color.
• borderColor: outer border color.
• showText: show percentage if true.
• font: percentage text font.
• textColor: percentage text color.

Example with dynamic color and text

function Update(obj, dt) {
  const bar = getObjectByName("LoadingBar");
  bar.value += dt * 0.1;
  if (bar.value > 1) bar.value = 1;

  if (bar.value < 0.5) bar.color = "#ff4444";
  else bar.color = "#00cc44";
}

🎨 Common UI Properties

• x, y: screen position.
• w, h: width and height.
• color: background or text color.
• text: text content (UILabel, UIButton, UIInputField).
• image: assigned image file (UIImage).
• visible: whether it is rendered.
• active: whether it can receive interaction.

⚡ Visibility and Activation Control

You can enable or disable UI elements the same way as any other object:

const menu = getObjectByName("MainMenu");
menu.visible = false;   // Hide
menu.active = false;    // Disable interaction

💡 Practical Tips

• UI elements are drawn above game objects.
• You can animate their position or color by changing values in Update().
• Combine buttons and labels to create full menus or HUDs.
• Use sounds with PlaySound() to improve feedback.
• UIProgressBar is ideal for loading bars, energy, or XP level.