🖼️ UI System
UI retained-mode sobre ECS para HUDs e menus de jogo: os widgets são entidades, o layout resolve retângulos de âncoras em cada frame e bindings de valor podem conduzir progress bars e sliders a partir do estado do jogo.
Visão Geral#
A UI de jogo é retained mode: widgets são entidades ECS com um componente
UIWidget mais um componente específico (UIButton, UILabel, …). Em cada frame o
UISystem:
- Corre os bindings de valor e escreve
UIProgressBar::currentValue/UISlider::currentValue. - Resolve os offsets das âncoras em
UIWidget::computedRect(até 8 passagens). - Faz hit-test do rato, dispara callbacks de hover/click e atualiza o estado dos botões.
Esta é a UI de jogo em runtime. O editor Doppio usa componentes Rust/Iced, não este sistema; o host ImGui legado está documentado em ImGui host.
Componentes#
UIColor#
Cor RGBA com canais f32 em [0, 1]. Presets estáticos: white(), black(),
transparent(), red(), green(), blue().
UIRect#
Retângulo de ecrã com position e size (Vec2). Métodos: contains(Vec2),
isValid() (verdadeiro quando ambas as componentes de size são positivas).
RectTransform#
Layout relativo ao parent. anchorMin / anchorMax são frações do tamanho do parent;
offsetMin / offsetMax são deltas em píxeis a partir desses cantos.
stateDiagram-v2
anchorMin=anchorMax={0,0}, offsetMin={px,py}, offsetMax={px+w,py+h} --> widget fixo em (px,py) tamanho (w,h)
UIStyle#
Aparência visual: backgroundColor, textColor, borderColor, borderWidth,
borderRadius, fontSize, textAlignment (um Vec2 em [0, 1]).
UIWidget#
Componente base presente em todas as entidades de UI:
| Campo | Tipo | Descrição |
|---|---|---|
type |
UIWidgetType |
Canvas, Panel, Button, Label, ProgressBar, Checkbox, Slider |
parentId |
u32 |
Id do parent; kUIInvalidParent para um canvas raiz |
visible |
bool |
Se falso, não é disposto nem devolvido por hitTest |
interactable |
bool |
Se falso, hitTest ignora-o |
siblingOrder |
i32 |
Valor maior vence quando dois widgets se sobrepõem |
style |
UIStyle |
Cores, bordo e tamanho de fonte |
transform |
RectTransform |
Âncoras e offsets usados pelo layout |
computedRect |
UIRect |
Preenchido em cada frame por layoutWidgets() |
onClick |
std::function<void(Entity)> |
Disparado ao clicar |
onHoverEnter |
std::function<void(Entity)> |
Disparado quando o rato entra |
onHoverExit |
std::function<void(Entity)> |
Disparado quando o rato sai |
onValueChanged |
std::function<void(Entity, f32)> |
Disparado por bindValue |
Componentes específicos#
| Struct | Campos relevantes |
|---|---|
UIButton |
labelText (FixedString<64>), idleColor, hoverColor, pressedColor, isHovered, isPressed |
UILabel |
text (FixedString<256>), wordWrap |
UIProgressBar |
minValue, maxValue, currentValue, showText, fillColor |
UISlider |
minValue, maxValue, currentValue, snapToInt |
UICheckbox |
checked, checkedColor |
API — UISystem#
namespace Caffeine::UI {
class UISystem : public ECS::ISystem {
public:
explicit UISystem(Events::EventBus* eventBus = nullptr);
void onUpdate(ECS::World& world, f32 dt) override;
void layout(ECS::World& world); // resolve rects without consuming input
ECS::Entity createCanvas(ECS::World& world, Vec2 size = {1280.0f, 720.0f});
ECS::Entity createPanel(ECS::World& world, u32 parentId, UIRect rect);
ECS::Entity createButton(ECS::World& world, u32 parentId, const char* text,
Vec2 pos, Vec2 size = {120.0f, 40.0f});
ECS::Entity createLabel(ECS::World& world, u32 parentId, const char* text, Vec2 pos);
ECS::Entity createProgressBar(ECS::World& world, u32 parentId,
Vec2 pos, Vec2 size = {200.0f, 20.0f});
ECS::Entity createSlider(ECS::World& world, u32 parentId,
Vec2 pos, Vec2 size = {200.0f, 20.0f});
ECS::Entity createCheckbox(ECS::World& world, u32 parentId, Vec2 pos);
void bindValue(ECS::Entity widget, std::function<f32(ECS::World&)> getter);
ECS::Entity hitTest(ECS::World& world, Vec2 screenPos);
void injectMousePosition(Vec2 pos);
void injectMouseClick(bool pressed);
};
} // namespace Caffeine::UI
bindValue atualiza um UIProgressBar ou um UISlider; os outros tipos de widget são
ignorados. A lista de bindings vive na instância do UISystem, não no componente, pelo
que não é serializada.
Hierarquia de Widgets#
Canvas (raiz)Panel (HUD)ProgressBar (health) ← bindValue → devolve Health.currentLabel (score)Label (fps counter)
Panel (inventory)[slots criados dinamicamente]
Panel (pause menu — visible=false por omissão)Button "Resume"Button "Options"Button "Quit"
Um painel também pode ser parent de um widget através de Scene::Parent quando
parentId é kUIInvalidParent; nesse caso layoutWidgets recorre à hierarquia da
cena.
Exemplo de Uso#
UISystem uiSys;
Entity canvas = uiSys.createCanvas(world, {1280.0f, 720.0f});
Entity hudPanel = uiSys.createPanel(world, canvas.id(), {{0, 0}, {1280, 720}});
Entity healthBar = uiSys.createProgressBar(world, hudPanel.id(), {20.0f, 700.0f}, {200.0f, 20.0f});
world.get<UIProgressBar>(healthBar)->fillColor = {0.9f, 0.2f, 0.2f, 1.0f};
uiSys.bindValue(healthBar, [&](ECS::World& w) {
return static_cast<f32>(w.get<Health>(playerEntity)->current);
});
Entity scoreLabel = uiSys.createLabel(world, hudPanel.id(), "Score: 0", {1100.0f, 700.0f});
Entity playBtn = uiSys.createButton(world, canvas.id(), "Play Game", {640.0f, 360.0f}, {200.0f, 50.0f});
world.get<UIWidget>(playBtn)->onClick = [&](ECS::Entity) {
sceneManager.switchScene("assets/scenes/level1.caf");
};
// Once per frame: bindings, layout, input.
uiSys.injectMousePosition(mousePos);
uiSys.injectMouseClick(isMouseDown);
uiSys.onUpdate(world, dt);
Health::current é u32; o getter devolve f32, por isso faz o cast.
Decisões de Design#
| Decisão | Justificativa |
|---|---|
| Retained mode | A UI persiste entre frames sem reconstrução |
| Widgets como entidades ECS | A UI pode ser consultada e afetada por sistemas |
bindValue com getter f32 |
Evita reflexão em C++; suficiente para progress bars e sliders |
UIColor com f32 |
O Scene::Color da engine usa u8; a UI quer precisão float |
| Até 8 passagens de layout | forEach não garante ordem topológica, por isso hierarquias profundas assentam ao longo de passagens |
kUIInvalidParent = 0xFFFFFFFFu |
Sentinela compatível com ids u32 |
Sem serialização no UISystem |
Bindings são código, não dados de cena; os componentes dos widgets são serializados pelo serializador de cenas |
Critério de Aceitação#
tests/test_ui.cpp cobre:
- [x] Presets e igualdade de
UIColor - [x]
UIRect::containsdentro, fora e na borda;isValid - [x] Defaults de
UIWidget,UIButton,UILabel,UIProgressBar,UISlidereUICheckbox - [x]
createCanvas,createPanel,createButton,createLabel,createProgressBarecreateSliderdevolvem entidades válidas com os componentes esperados - [x]
onUpdatenum world vazio e com vários canvases não faz crash - [x]
hitTestdevolve o widget sob o ponto;INVALIDsem widgets ou fora de todos os retângulos - [x] Widgets com
visible = falsenão são devolvidos porhitTest - [x]
onClickdispara dentro do widget e não fora - [x]
onHoverEnterdispara quando o rato entra - [x]
bindValueatualizaUIProgressBar::currentValue
Dependências#
- Upstream: ECS Core, Event Bus
- Downstream: HUDs e menus de jogo; o editor Doppio usa Iced, não este sistema
🔗 Tópicos Relacionados#
| Tópico | Descrição |
|---|---|
| ImGui host | O host immediate-mode legado usado pelo runtime e por plugins antigos |
| Workspace and theme | A UI do editor em Rust/Iced |
| ECS Core | Componentes e queries |
Referências#
src/caffeine/ui/UIComponents.hpp— componentes dos widgetssrc/caffeine/ui/UISystem.hpp— layout, input e bindingstests/test_ui.cpp— suite de comportamento