This guide builds a small inventory screen with the retained GUI. A panel holds a scrolling list of buttons. You create the controls once, react to clicks in event hooks, style the buttons with a profile, and play a sound when the player picks an item. The GUI API lists every control and method.
A retained GUI keeps its controls as objects. You build the tree once and change it only when something changes. That is different from the immediate-mode UI, where you describe every widget again on each frame.
Before you start
- Finish Quickstart and use a project that runs with
bornengine run main.ts. - For the sound, save a short WAV file as
assets/audio/ui-select.wavin the project. The example checksisLoaded, so it still runs without the file.
Create a scrollable panel
Replace main.ts with this file:
import { Colors, Game, GUIEvent, GUIProfiles, GuiButton, GuiPanel, GuiScroll, GuiText } from '@bornengine/engine';
class InventoryButton extends GuiButton {
constructor(label: string, y: number) {
super({ x: 8, y, width: 220, height: 34 });
this.setText(label);
const profile = this.setOwnProfile(GUIProfiles.get('button'));
profile.normalColor = { r: 0.12, g: 0.2, b: 0.32, a: 1 };
}
}
class InventoryScroll extends GuiScroll {
selection = '';
protected override onAction(event: GUIEvent): void {
if (!(event.target instanceof InventoryButton)) return;
this.selection = event.target.getText();
event.stopPropagation();
}
}
class InventoryGame extends Game {
private readonly selectSound = this.audio.loadSound('assets/audio/ui-select.wav');
private readonly status = new GuiText({ x: 10, y: 8, width: 270, height: 26 });
private readonly inventory = new InventoryScroll({ x: 10, y: 40, width: 270, height: 200 });
constructor() {
super({ window: { title: 'Inventory', width: 800, height: 480 }, targetFps: 60 });
}
protected override onStart(): void {
this.status.setText('Choose an item');
const items = ['Health potion', 'Torch', 'Map fragment', 'Rope', 'Key', 'Bread', 'Lantern', 'Compass'];
for (let index = 0; index < items.length; index++) {
this.inventory.addControl(new InventoryButton(items[index], 8 + index * 42));
}
const panel = new GuiPanel({ x: 24, y: 24, width: 300, height: 260 });
panel.addControl(this.status);
panel.addControl(this.inventory);
this.gui.addControl(panel);
}
protected override loop(_deltaTime: number): void {
if (this.inventory.selection.length === 0) return;
this.status.setText('Selected: ' + this.inventory.selection);
if (this.selectSound.isLoaded) this.selectSound.play();
this.inventory.selection = '';
}
protected override render(): void {
this.renderer.clear(Colors.DARKGRAY);
}
}
new InventoryGame().run();Run it with bornengine run main.ts. Click an item and the status line changes. Eight buttons do not fit in the 200 pixel high scroll area, so a scroll bar appears.
What each part does:
InventoryButtonis aGuiButtonwith its own profile.setOwnProfile(GUIProfiles.get('button'))copies the built-inbuttonprofile for this one button. ChangingnormalColoron the copy does not touch any other button.InventoryScrollis aGuiScrollwith anonActionhook. A click on a button raises an action event on that button. The event bubbles up to its parent, the scroll area, and the hook runs there.event.targetis the clicked button, andevent.currentTargetis the scroll area.event.stopPropagation()ends the bubbling, so the panel and any controls above it do not see the event.- The manager delivers events on the next frame, before
loop()runs.loop()readsselection, updates the status text, and plays the sound. this.guikeeps the controls attached to it until you remove them or theGameshuts down.
Geometry and composition
A control’s x and y are offsets from its parent’s content origin, which is the parent’s top-left corner moved in by the parent’s padding. A control without a parent is placed in the game window. Use getX() and getY() to read the offsets and setX(), setY(), and setPosition(x, y) to change them.
center(), centerHorizontal(), and centerVertical() anchor a control to the middle of its parent. The anchor is resolved when the control has a parent or is attached to game.gui, and again when the parent or the window changes size. Setting a position on an axis clears the anchor on that axis.
import { GuiPanel, GuiScroll } from '@bornengine/engine';
function buildSettingsScroll(): GuiScroll {
const scroll = new GuiScroll({ width: 420, height: 280 });
scroll.centerHorizontal();
scroll.setY(40);
scroll.setVerticalScrollBarMode('dynamic');
for (let index = 0; index < 4; index++) {
scroll.addControl(new GuiPanel({ x: 12, y: 12 + index * 112, width: 380, height: 100 }));
}
return scroll;
}
function removeFirstSection(scroll: GuiScroll): boolean {
const sections = scroll.getControls();
if (sections.length === 0) return false;
const first = sections[0];
return first.getParent() === scroll && scroll.removeControl(first);
}addControl(control)attaches a child. A control can have only one parent, and attaching a control that already has one throws.removeControl(control)detaches it and returnsfalseif it was not a child.getParent()returns the owner, ornullfor a root.localToGlobal(point)andglobalToLocal(point)convert between a control’s own space and window coordinates.setClipChildren(true)clips the children of a control to its bounds.GuiScrolldoes this on its own and keeps its scroll position for as long as the control exists.- Build large trees from parts. A small subclass for each part, such as
InventoryButton, keeps the setup in one place and gives you a class to hang hooks on.
Events, focus, and values
Override onAction for clicks and onChange for values that the player edits, such as check boxes, sliders, and text fields. Every event hook receives a GUIEvent with the target, the currentTarget, the pointer position in localX and localY, and key, button, wheel, and modifier data when they apply.
import { GUIEvent, GuiButton, GuiCheckBox, GuiPanel } from '@bornengine/engine';
class ConfirmButton extends GuiButton {
protected override onAction(event: GUIEvent): void {
this.hide();
event.stopPropagation();
}
}
class DialogPanel extends GuiPanel {
actions = 0;
protected override onAction(_event: GUIEvent): void {
this.actions += 1;
}
}
class MuteBox extends GuiCheckBox {
protected override onChange(_event: GUIEvent): void {
console.log('muted:', this.getValue());
}
}- The
ConfirmButtonhides itself and stops the event. ADialogPanelthat contains it counts the actions it receives, so it never counts a click on the confirm button. WithoutstopPropagation(), the event would reach the panel too. onChangeruns when the player changes the value. It does not run when your own code callssetValue(),setText(), orsetSelected().- A hidden, inactive, or removed control receives no events.
- Move keyboard focus with
focus()ormakeFirstResponder(), and release it withblur(). game.gui.wantsPointerInput()andwantsKeyboardInput()report whether the GUI is using the pointer or the keyboard. The GUI does not take input away from your game, so check them inloop()before gameplay reacts to the same input.- If your code sets a value while an older response from the renderer is still waiting, your value wins.
Textures, drawing, and sound
Images, bitmap button states, profile backgrounds, and GuiDrawingPanel images accept loaded textures that belong to the same Game. A texture that is not loaded, or that another Game owns, is skipped. Load textures with game.assets.loadTexture(path), and pass them to GuiBitmap.setTexture(texture), GuiBitmapButton.setTextures({ normal, hover, pressed }), or drawImage().
A GuiDrawingPanel draws shapes in the order you add them and clips them to its bounds. Coordinates start at the panel’s top-left corner.
import { Colors, GuiDrawingPanel } from '@bornengine/engine';
function buildChart(): GuiDrawingPanel {
const chart = new GuiDrawingPanel({ x: 16, y: 16, width: 240, height: 120 });
chart.drawRect({ x: 0, y: 0, width: 240, height: 120 }, Colors.DARKGRAY);
chart.drawLine({ x: 0, y: 100 }, { x: 240, y: 20 }, Colors.SKYBLUE, 2);
chart.drawText('Score', { x: 8, y: 6 }, 14, Colors.WHITE);
return chart;
}Profiles have a buttonSounds field, but the engine does not play it in this release. Play a sound from the event hook instead. A control has no direct access to the Game, so load the Sound in the game and pass it in:
import { Game, GUIEvent, GuiButton } from '@bornengine/engine';
import type { Sound } from '@bornengine/engine';
class ClickButton extends GuiButton {
private readonly click: Sound;
constructor(label: string, click: Sound) {
super({ width: 160, height: 34 });
this.setText(label);
this.click = click;
}
protected override onAction(_event: GUIEvent): void {
if (this.click.isLoaded) this.click.play();
}
}
class MenuGame extends Game {
protected override onStart(): void {
const click = this.audio.loadSound('assets/audio/ui-select.wav');
const play = new ClickButton('Play', click);
play.center();
this.gui.addControl(play);
}
}
new MenuGame().run();The sample plays the sound straight from the hook. Use this when the click needs no other state change. When a parent has to update first, as in the inventory example, play the sound from loop() instead. Audio explains buses, volume, and the sound manager.
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 you build platform-specific behavior.
Every other target that runs the shared engine supports the retained GUI. See the GUI API for the full reference.
Next steps
- GUI API lists every control, helper, and profile field.
- UI covers the immediate-mode widgets for quick menus and HUDs.
- Audio and UI combines sound effects with a heads-up display.
- Apple platforms explains the watchOS limitation.