🧱 UI Components

KAPLAY‑UI provides a small set of lightweight, game‑ready UI components.

All components behave like native KAPLAY objects, integrating naturally with scenes, layers, positions, and events.

🔤 TextButton

A clickable button with centered text.

const btn = k.addTextButton("Play");

Signature

The addTextButton method takes a required string and an optional object.

k.addTextButton(txt: string, opts?: {});

Options

All fields are optional. Defaults are shown below.

Default Styling

These are the built‑in visual defaults applied automatically.

The button object is created with:

• k.anchor("topleft")
• k.area()

The button text is created with:

• k.anchor("center")

Text Button Instance Methods

The returned ButtonComponent exposes the following mutator methods, allowing the button to be updated after creation:

Layout & Geometry

• setSize(w: number, h: number): void
  Update the button width and height.

• setPosition(x: number, y: number): void
  Move the button to a new position.

• setAnchor(a: Anchor): void
  Change the anchor used for positioning.

• setRadius(r: number): void
  Update the corner radius.

• setOutline(t: number): void
  Set the outline thickness.

Text

• setButtonText(txt: string): void
  Replace the button label.

• setButtonTextSize(size: number): void
  Change the font size of the button text.

• setButtonTextColor(color: KaplayColor): void
  Update the text color.

Colors

• setButtonColor(color: KaplayColor): void
  Change the button fill color.

• setButtonOutlineColor(color: KaplayRGB): void
  Change the outline stroke color.

Examples

// Basic usage
const btn1 = addTextButton("Play");
btn1.onClick(() => k.go("game"));

// Runtime mutation
const btn2 = addTextButton("Start");
btn2.setSize(300, 120);
btn2.setButtonColor([255, 100, 100]);
btn2.setButtonText("Go!");

// Visual-only updates
const btn3 = addTextButton("Options", {
  radius: 2,
});
btn3.setButtonOutlineColor([0, 0, 0]);
btn3.setButtonTextSize(24);

🏷️ Label

A small, fast text element ideal for HUDs, overlays, and lightweight UI.

const score = k.addLabel("Score: 0");

Signature

The addLabel method takes a required string and an optional object.

k.addLabel(txt: string, opts?: {});

Options

All fields are optional. Defaults are shown below.

Default Styling

Label Instance Methods

The returned LabelComponent exposes helper methods that allow the label to be updated dynamically at runtime.

Layout & Geometry

• setSize(w: number, h: number): void
  Update the label width and height.

• setPosition(x: number, y: number): void
  Move the label to a new position.

• setRadius(r: number): void
  Update the background corner radius.

• setLabelAnchor(anchor: Anchor): void
  Change the anchor used for positioning the label.

Appearance

• setOpacity(o: number): void
  Set label background opacity (0–1).

• setLabelColor(c: KaplayColor): void
  Change the background color of the label.

Text

• setLabelText(txt: string): void
  Replace the label text.

• setLabelTextSize(size: number): void
  Change the font size of the label text.

• setLabelTextColor(c: KaplayColor): void
  Update the label text color.

Example

// Basic usage
const lbl = addLabel("Score: 0");
lbl.setPosition(20, 20);

// Dynamic text updates (e.g. score counter)
let score = 0;
const scoreLbl = addLabel(`Score: ${score}`);

k.wait(2, () => {
  score++;
  scoreLbl.setLabelText(`Score: ${score}`);
});

// Runtime appearance updates
const title = addLabel("Game Over", {
  txtSize: 36,
});
title.setLabelColor([40, 40, 40]);
title.setLabelTextColor([255, 80, 80]);
title.setOpacity(0.9);

// Layout adjustment after creation
const hudLabel = addLabel("Paused");
hudLabel.setSize(200, 60);
hudLabel.setLabelAnchor("center");

📦 More Components Coming Soon

Planned UI components include:

• Sliders
• Toggles
• Panels / Containers
• Layout helpers (stacks, grids)

These will be added here as the library grows.