---
title: "UI de jogo: onde fica e o que é possível"
version: snapshot-2026-10-06
engineGeneration: astra-current
language: C#
status: source-reviewed
runtimeVerified: false
platformEvidence: []
url: https://astraengine.com.br/pt-br/snapshot-2026-10-06/ui/comece-aqui/
---

# UI de jogo: onde fica e o que é possível

Encontre Canvas UI, Image e os elementos de interface pelo caminho real de autoria.

## Comece pelo que você quer criar

| Quero criar | Ferramenta de hoje | Tutorial |
|---|---|---|
| HUD de corações com dano e cura | Canvas UI + documento + Image + Behavior C# | [HUD funcional](/pt-br/snapshot-2026-10-06/ui/hud-coracoes/) |
| Ícone, retrato ou coração | Image, elemento do documento | [Image](/pt-br/snapshot-2026-10-06/ui/image/) |
| Barra contínua | Progress + escrita de Value | [Progress](/pt-br/snapshot-2026-10-06/ui/progress/) |
| Botão clicável ilustrado | Image + Clicável + Poll | [Interação e animação](/pt-br/snapshot-2026-10-06/ui/interacao-e-animacao/) |
| Menu de botões | Button, Text, VBox | [Catálogo de elementos](/pt-br/snapshot-2026-10-06/ui/elementos/) |
| Mover e olhar no touch | Joystick, ActionButton, LookArea + receptor | [Controles e receptores](/pt-br/snapshot-2026-10-06/ui/controles-e-receptores/) |

## O nome certo na Astra

**UiImage, UIImage, UIIMG e imagem de UI** são termos úteis de busca. Nesta geração da Astra, o nome exibido é **Image**. Ele é um nó de um documento **.aeui**, manipulado por [GuiElement](/pt-br/snapshot-2026-10-06/api/astra-guielement/). O componente do objeto é [Canvas UI](/pt-br/snapshot-2026-10-06/componentes/astra-ui-canvas/), com fachada **Astra.Components.UiCanvas**. Não há uma classe pública Astra.Components.UiImage neste snapshot.

## Criar e salvar o documento

1. Abra o projeto e, no menu do editor, entre em **Interface (UI + ImGui)**. Essa é a área de autoria de UI; não é o editor de scripts.
2. No campo do recurso, use **UI/hud.aeui**. O caminho deve ficar dentro do projeto e terminar em .aeui. Se já existe um rascunho aberto, salve-o antes de trocar de documento.
3. Crie os elementos pelo menu de criação. No Inspector integrado da cena, a ação equivalente é **+ Elemento**. **Image** aparece nessa lista, junto de Panel, Text e Button.
4. Dê nomes únicos e estáveis aos elementos usados por scripts. Nome resolve a busca; o handle de execução conserva o ID e a instância do Canvas.
5. Use **Salvar** na área Interface ou **Salvar UI** no Inspector integrado. Isso salva e registra o documento no projeto. Salvar apenas a cena não substitui Salvar UI.

## Exibir o documento na cena

1. Crie um objeto vazio chamado **HUD** na Hierarquia da cena.
2. Selecione HUD → **Adicionar componente** → procure **Canvas UI** na família **Renderização**.
3. No Inspector do componente, atribua **UI/hud.aeui** ao recurso **Documento UI**. O arquivo deve ter sido salvo/registrado, não é um GUID inventado.
4. Use **Apresentação = Tela** para HUD. O modo Mundo / objeto é para uma interface presa a um plano na cena.
5. Use **Editar documento UI** para abrir a fonte desse Canvas. Expandir o Canvas na Hierarquia mostra os elementos; selecionar Image abre suas propriedades no mesmo Inspector.
6. A trilha mostra o proprietário e quantos Canvas compartilham o recurso. Editar a fonte altera todos os Canvas autorais ligados a ela. Overrides individuais autorais ainda estão pendentes.

## Editar, Interagir e Play

| Modo | O que faz | O que conferir |
|---|---|---|
| Autoria | Edita o documento e seleciona elementos | Layout, recurso, nomes, Undo/Redo e salvar |
| Interagir | Usa uma cópia para testar hit, ações nativas, estados e animação | Pressionar, soltar, cancelar; não executa o Behavior C# do jogo |
| Play | Executa cena e scripts com uma instância de UI por Canvas | Poll, vida do jogador, controle e alterações por C# |

As escritas do script em Play não modificam o .aeui autoral. Ao parar/reabrir Play, resolva os handles de novo. Não guarde GuiElement entre execuções.

## Contrato e roadmap

Documentos externos, Canvas Tela/Mundo, seleção integrada e cópias de Play estão presentes no código. Esta atualização de docs não executa novamente o APK no aparelho. [Roadmap UI](/pt-br/snapshot-2026-10-06/ui/roadmap/) identifica as lacunas de layout, imagem, foco, bindings e autoria por instância.