Retained GUI controls

game.gui is BornEngine’s retained, object-oriented 2D GUI. Create controls as objects, attach them to a parent, and keep their state between frames. The engine lays out and submits the tree after Game.render(); native responses are applied before the next Game.loop().

Choose game.gui or game.ui

Use game.ui when a small immediate-mode HUD is easiest to describe again during each render() call. Use game.gui when you want reusable controls, parent-child organization, subclass hooks, profiles, or persistent widget state. Both APIs render through the same egui context and surface. Their IDs and response stores stay separate, and the developer inspector remains on top when enabled.

Platform status

watchOS: GUI controls do not work on watchOS in the current release: controls do not render and GUI input/events are unavailable. This limitation is temporary. A future SwiftUI adapter is planned, with no delivery date promised. Check game.gui.isAvailable() before building platform-specific behavior.

Import and attach controls

Import from the package root or from the gui subpath:

import { GUI, GuiButton, GuiPanel, GuiScroll, GuiText, Vector2D } from '@bornengine/engine';
// Or: import { GUI, GuiButton, GuiPanel, GuiScroll, GuiText } from '@bornengine/engine/gui';

Construct controls independently, then attach one or more roots to the Game-owned manager. A child can only belong to one parent at a time.

const panel = new GuiPanel({ position: new Vector2D(24, 24), width: 320, height: 180 });
const title = new GuiText({ position: new Vector2D(12, 10), width: 280, height: 28 });
title.setText('Inventory');
panel.addControl(title);
game.gui.addControl(panel);

Geometry and parent helpers

x and y are logical-pixel offsets from the parent content origin, after the parent profile’s padding. A GuiWindow also reserves its title bar above the child content. A root control uses the game viewport as its parent bounds. center() centers on both axes of the current parent content area; centerHorizontal() and centerVertical() anchor one axis. Anchors update after parent or viewport resize. Geometry setters return the control for chaining.

const scroll = new GuiScroll({ position: Vector2D.zero(), width: 420, height: 300 });
scroll.center();
scroll.moveBy(Vector2D.right().scale(24)).centerVertical();
scroll.setSize(460, 320);

const child = new GUI({ position: new Vector2D(12, 16), width: 120, height: 32 });
scroll.addControl(child);
const parent = child.getParent();
const screenPoint = child.localToGlobal(Vector2D.zero());
const localPoint = child.globalToLocal(screenPoint);
const position = child.getPosition();
child.setPosition(position.add(new Vector2D(4, 0)));

Positions accept Vector2D or any { x, y } value through position and setPosition(). getPosition(), localToGlobal(), and globalToLocal() return independent Vector2D snapshots. moveBy(offset) translates the control and clears both center anchors. Existing x/y, setX()/setY(), and setPosition(x, y) calls remain supported; explicit x or y options override only the matching component of position. Width and height remain separate dimensions.

Common geometry and tree methods:

GUIManager also exposes getControls(), isAvailable(), wantsPointerInput(), and wantsKeyboardInput(). Check input-capture methods when deciding whether gameplay should react to the same pointer or keyboard input; the GUI does not automatically consume game input.

Profiles

GuiProfile holds normal, hover, disabled, text, and selection colors; font and alignment; spacing, border, opacity, background texture, shadow, focus and modality settings, cursor, and optional button sounds. Profiles are shared by reference until cloned. setOwnProfile() gives one control an independent copy.

import { GUIProfiles } from '@bornengine/engine/gui';

const button = new GuiButton({ width: 160, height: 36 });
const profile = button.setOwnProfile(GUIProfiles.get('button'));
profile.normalColor = { r: 0.08, g: 0.24, b: 0.5, a: 1 };
button.setText('Continue');

Built-in names include default, text, button, window, scroll, checkbox, radio, popup, slider, progress, tree, list, and blue. Use GUIProfiles.register(name, profile) for an application-wide profile; duplicate names and unknown lookups throw. Use GUIProfiles.clone(name) or control.setOwnProfile() before changing a profile for one control.

Built-in controls

Every concrete control extends GUI; add it to a parent with addControl() or to the root with game.gui.addControl(). Controls accept optional GUIControlOptions for geometry, visibility, clipping, and activity.

Base and layout

Buttons and values

Text and editing

Selection and navigation

Images, progress, and custom drawing

Textures are accepted only when they are loaded and owned by the current Game. Foreign or unloaded images are omitted. Background and control textures are registered through the same egui texture path as game.ui.image().

Events, focus, and response timing

Override only the hooks a control needs: onAction, onChange, onFocus, onBlur, onPointerEnter, onPointerLeave, onPointerMove, onPointerDown, onPointerUp, onPointerDrag, onWheel, onKeyDown, and onKeyUp. Lifecycle hooks include onAdd, onRemove, onShow, onHide, onWake, onSleep, onMove, and onResize.

class ApplyButton extends GuiButton {
  protected override onAction(event: GUIEvent): void {
    console.log(event.target === this, event.currentTarget === this);
  }
}

GUI events carry target, currentTarget, localPosition and globalPosition as Vector2D snapshots, plus the compatible scalar localX/localY and globalX/globalY fields, key/button/wheel data, and modifiers when present. They bubble from the target to its parents; call event.stopPropagation() to stop bubbling. Use focus(), blur(), isFocused(), makeFirstResponder(), and isFirstResponder() for keyboard focus. Hidden, inactive, detached, or destroyed controls do not receive stale input responses.

The native backend evaluates both UI APIs after game rendering. game.gui applies the completed response snapshot during the next frame’s service update, before Game.loop(). Value setters made in TypeScript take precedence over an older pending native value. Use game.gui.isAvailable() before relying on GUI rendering or input; unavailable targets return false and dispatch no GUI events.

Related pages

• Immediate game.ui API
• GUI controls guide
• Debug UI
• Apple platform notes