UI System¶

SimVX provides a set of UI controls and layout containers for building game interfaces. All widgets are rendered via the engine’s Vulkan backend — no external GUI toolkit required.

Controls¶

All controls inherit from Control, which provides rect-based layout, mouse interaction, and focus management.

Label¶

from simvx.core import Label

label = Label(text="Score: 0", font_size=24)
label.position = Vec2(10, 10)
root.add_child(label)

Button¶

from simvx.core import Button

btn = Button(text="Start Game")
btn.pressed.connect(start_game)
root.add_child(btn)

TextEdit¶

from simvx.core import TextEdit

edit = TextEdit(placeholder="Enter name...")
edit.text_changed.connect(lambda text: print(text))
root.add_child(edit)

Slider¶

from simvx.core import Slider

slider = Slider(min_value=0, max_value=100, value=50)
slider.value_changed.connect(lambda v: print(f"Volume: {v}"))
root.add_child(slider)

ProgressBar¶

from simvx.core import ProgressBar

bar = ProgressBar(min_value=0, max_value=100, value=75)
root.add_child(bar)

Containers¶

Containers automatically arrange their children.

HBoxContainer / VBoxContainer¶

from simvx.core import HBoxContainer, VBoxContainer, Button

menu = VBoxContainer(separation=10)
menu.add_child(Button(text="New Game"))
menu.add_child(Button(text="Load Game"))
menu.add_child(Button(text="Settings"))
root.add_child(menu)

GridContainer¶

from simvx.core import GridContainer

grid = GridContainer(columns=3, h_separation=5, v_separation=5)
for i in range(9):
    grid.add_child(Button(text=str(i + 1)))

MarginContainer¶

from simvx.core import MarginContainer

margin = MarginContainer(
    margin_left=20, margin_right=20,
    margin_top=10, margin_bottom=10,
)
margin.add_child(Label(text="Padded content"))

Theming¶

Theme controls colours, fonts, and sizing for all widgets. Colours are (r, g, b, a) floats in 0.0–1.0 range.

from simvx.core.ui import get_theme

theme = get_theme()
theme.colours["accent"] = (0.3, 0.6, 1.0, 1.0)
theme.colours["bg"] = (0.15, 0.15, 0.15, 1.0)
theme.sizes["font_size"] = 18

Individual widgets can override theme colours via ThemeColour descriptors:

btn = Button(text="Delete")
btn.bg_colour = (0.8, 0.2, 0.2, 1.0)  # Override theme
btn.bg_colour = None                    # Revert to theme default

Default colour keys include: bg, bg_light, bg_dark, text, text_disabled, accent, accent_hover, accent_pressed, border, focus, btn_bg, btn_hover, btn_pressed, error, warning, success.

API Reference¶

See simvx.core.ui for the complete UI API.