Como estilizar a interface no Godot 4 com Theme e StyleBox

Seu menu funciona, o HUD mostra a vida certa, mas tudo ainda tem aquela cara cinza de projeto recem-criado. A boa noticia e que trocar esse visual nao exige refazer nada: com um recurso Theme godot e alguns StyleBox voce muda a aparencia do jogo inteiro a partir de um unico ponto. Neste tutorial da CursoGame.Dev voce vai entender o que e um Theme na Godot 4, como aplica-lo num Control raiz e deixar a herança fazer o trabalho pesado, como desenhar botoes e paineis com o StyleBoxFlat, e como criar dois estilos de botao sem duplicar recurso.

O foco aqui e o visual. Se a estrutura do seu menu ainda nao existe, vale montar primeiro o menu principal na Godot e depois voltar para estiliza-lo. O mesmo Theme que voce construir aqui vale para o menu, para a tela de pausa e para o HUD, entao pense nele como a identidade visual reaproveitavel do jogo.

O que e um recurso Theme na Godot 4

Todo no que herda de Control (Button, Label, Panel, LineEdit e por ai vai) desenha a si mesmo lendo valores de um Theme. Quando voce nao define nenhum, a Godot usa o Theme padrao interno, aquele cinza que voce ja conhece. Um Theme e simplesmente um recurso (.tres) que guarda esses valores organizados por tipo de no.

Dentro de um Theme, cada propriedade cai em uma de cinco categorias:

• Color: cores, como a cor do texto de um Label.
• Constant: numeros inteiros, como o espacamento interno de um container.
• Font e Font Size: a fonte e o tamanho usados no texto.
• Icon: texturas, como o desenho do check num CheckBox.
• StyleBox: o desenho do fundo do no (preenchimento, borda, cantos).

A sacada e que essas propriedades sao agrupadas por tipo. O Theme tem uma secao "Button", outra "Panel", outra "Label", e cada uma expoe so as propriedades que aquele tipo entende. Um Button tem styleboxes chamados normal, hover, pressed, disabled e focus; um Label nem tem stylebox de estado, mas tem a cor font_color. Entender esse mapa de tipo mais propriedade e metade do caminho.

Criando e aplicando o Theme num Control raiz

Vamos pela via do editor primeiro, que e como voce vai trabalhar no dia a dia.

1. Selecione o no Control que esta na raiz da sua cena de interface (o pai de tudo).
2. No Inspector, procure a propriedade Theme, clique na seta e escolha New Theme.
3. Clique no recurso Theme que apareceu para abrir o editor de Theme no painel de baixo do editor.

A partir desse momento, todo no Control abaixo desse raiz herda o Theme. Isso e a herança de Theme: voce estiliza um Button na secao "Button" do recurso e todos os botoes daquela arvore mudam juntos, sem voce selecionar cada um. Se um filho tiver o proprio Theme definido, ele ganha do herdado, mas o normal e deixar so a raiz com Theme.

No editor de Theme, o botao + no canto superior direito adiciona tipos para editar. Clique nele, escolha Button, e a Godot mostra abas para Color, Constant, Font, Icon e StyleBox daquele tipo. Uma previa ao vivo aparece do lado, entao voce ve o resultado enquanto mexe.

Aplicando o mesmo Theme em varias cenas

Se voce salvar o Theme como um arquivo separado (clique com o botao direito no recurso e escolha Save As, algo como res://ui/tema_principal.tres), da para apontar a propriedade Theme de qualquer outra cena para esse mesmo arquivo. Menu, pausa e HUD passam a compartilhar exatamente o mesmo visual, e uma mudanca no arquivo se propaga para todos.

StyleBoxFlat: bordas, cantos e cor no Button e no Panel

O StyleBoxFlat e o cavalo de batalha da estilizacao. Ele desenha um retangulo com cor de fundo, bordas configuraveis por lado, cantos arredondados e ate sombra, tudo sem imagem nenhuma. E o que transforma um botao chapado num botao com cara de jogo.

Na aba StyleBox do tipo Button, clique no campo normal, escolha New StyleBoxFlat e clique para expandir. As propriedades que mais importam:

• BG Color: a cor de fundo do botao.
• Border Width (left, top, right, bottom): a espessura da borda em cada lado.
• Border Color: a cor da borda.
• Corner Radius (os quatro cantos): o raio do arredondamento. Deixe todos iguais para um botao uniforme.
• Content Margin: o respiro interno entre a borda e o texto. Sem isso o texto cola na borda.
• Anti Aliasing: mantenha ligado para o canto nao serrilhar.

Para um Panel (a base de qualquer janela ou caixa de HUD), o processo e identico: adicione o tipo Panel no Theme, defina o stylebox panel como um novo StyleBoxFlat e escolha uma cor de fundo mais escura, uma borda sutil e cantos arredondados. Pronto, suas caixas param de ser retangulos cinza duros.

Estados do botao: normal, hover, pressed e disabled

Um botao profissional reage ao mouse. Na Godot voce controla isso definindo um StyleBoxFlat diferente para cada estado, todos dentro da secao Button do Theme:

• normal: o estado parado.
• hover: quando o cursor esta por cima. Costuma ser uma cor um pouco mais clara.
• pressed: no clique. Escurecer ou inverter a borda passa a sensacao de afundar.
• disabled: botao desligado. Cor apagada e texto acinzentado avisam que nao da para clicar.
• focus: contorno para navegacao por teclado ou controle. Nao esqueca dele se o jogo usa gamepad.

Um truque que economiza tempo: crie o stylebox normal, clique com o botao direito nele e escolha Copy, depois cole em hover e pressed e mude so a cor. Assim os quatro estados compartilham a mesma forma e mudam apenas o tom, o que deixa a transicao coerente.

As cores de texto de cada estado ficam na aba Color do tipo Button: font_color, font_hover_color, font_pressed_color e font_disabled_color. Combine a cor do texto com o stylebox de cada estado para o botao ler bem em qualquer situacao.

Customizando fontes e cores por tipo de no

O Theme padrao usa uma fonte de sistema pequena. Para dar personalidade, importe uma fonte .ttf ou .otf para o projeto (basta arrastar o arquivo para a pasta de assets) e aplique no Theme.

Voce pode definir uma fonte global para o Theme inteiro na aba de configuracoes do editor de Theme, ou por tipo. Por tipo funciona assim: na secao Label, aba Font, arraste sua fonte para o campo font, e na aba Font Size ajuste o font_size. Na aba Color, o font_color controla a cor do texto do Label. Repita para Button, LineEdit e o que mais o seu jogo usar.

O ganho de fazer por tipo e o controle: titulos podem usar uma fonte display grande enquanto o corpo de texto usa algo legivel e menor, tudo no mesmo Theme. Uma tela pesada de texto, como um menu de opcoes e configuracoes, fica muito mais clara quando os tamanhos de fonte seguem uma hierarquia definida no Theme em vez de valores soltos em cada Label.

Theme Type Variation: dois estilos de botao no mesmo Theme

Cedo ou tarde voce vai querer um botao diferente: um botao de "Excluir save" vermelho de alerta, ou um botao primario destacado contra os secundarios. Duplicar o Theme inteiro so por causa disso e desperdicio. A solucao e o Theme Type Variation.

No editor de Theme, clique no + para adicionar um tipo, mas em vez de escolher um tipo pronto, digite um nome novo, por exemplo BotaoPerigo. Depois, no canto superior do editor de tipos, existe um campo Base Type: aponte para Button. Agora BotaoPerigo herda tudo de Button e voce sobrescreve so o que quer, como o normal com fundo vermelho.

Para usar, selecione o botao especifico na cena e no Inspector procure a propriedade Theme Type Variation; escolha BotaoPerigo. Esse botao passa a usar a variacao, enquanto todos os outros continuam com o estilo padrao de Button. Um Theme, dois (ou dez) estilos de botao.

Criando o Theme inteiro por codigo com tipagem

Fazer pelo editor e o normal, mas as vezes voce quer gerar o Theme por codigo: para trocar de paleta em tempo de execucao, para um sistema de temas claro e escuro, ou so para versionar o visual como script. Tudo que o editor faz tem equivalente em GDScript tipado.

Primeiro, uma funcao auxiliar que monta um StyleBoxFlat, para nao repetir codigo:

func _criar_stylebox(cor: Color, cor_borda: Color) -> StyleBoxFlat:
    var estilo: StyleBoxFlat = StyleBoxFlat.new()
    estilo.bg_color = cor
    estilo.border_color = cor_borda
    estilo.set_border_width_all(2)
    estilo.set_corner_radius_all(8)
    estilo.content_margin_left = 16.0
    estilo.content_margin_right = 16.0
    estilo.content_margin_top = 8.0
    estilo.content_margin_bottom = 8.0
    return estilo

Agora o Theme em si. Note que cada propriedade do Theme e definida com o tipo do no ("Button", "Panel") como parametro, exatamente o mesmo agrupamento que voce viu no editor:

func _construir_tema() -> Theme:
    var tema: Theme = Theme.new()

    # Fonte e tamanho globais para botoes
    var fonte: FontFile = load("res://ui/fonte_jogo.ttf") as FontFile
    tema.set_font("font", "Button", fonte)
    tema.set_font_size("font_size", "Button", 20)

    # Cores de texto por estado do botao
    tema.set_color("font_color", "Button", Color("f5f5f5"))
    tema.set_color("font_pressed_color", "Button", Color("cfcfcf"))
    tema.set_color("font_disabled_color", "Button", Color("777777"))

    # StyleBox por estado
    tema.set_stylebox("normal", "Button", _criar_stylebox(Color("2e3440"), Color("4c566a")))
    tema.set_stylebox("hover", "Button", _criar_stylebox(Color("3b4252"), Color("81a1c1")))
    tema.set_stylebox("pressed", "Button", _criar_stylebox(Color("242933"), Color("5e81ac")))
    tema.set_stylebox("disabled", "Button", _criar_stylebox(Color("2e3440"), Color("3b4252")))

    # Painel
    tema.set_stylebox("panel", "Panel", _criar_stylebox(Color("232831"), Color("3b4252")))

    return tema

Para a variacao de tipo por codigo, voce registra o tipo com uma base. A Theme guarda essa relacao com set_type_variation, e o resto e definir os styleboxes do tipo novo:

func _adicionar_variacao_perigo(tema: Theme) -> void:
    tema.set_type_variation("BotaoPerigo", "Button")
    tema.set_stylebox("normal", "BotaoPerigo", _criar_stylebox(Color("6b2020"), Color("bf616a")))
    tema.set_stylebox("hover", "BotaoPerigo", _criar_stylebox(Color("803030"), Color("d08770")))
    tema.set_stylebox("pressed", "BotaoPerigo", _criar_stylebox(Color("501818"), Color("bf616a")))

Por fim, aplique o Theme no Control raiz e use a variacao num botao especifico. Tudo tipado, sem depender do Inspector:

extends Control

func _ready() -> void:
    var tema: Theme = _construir_tema()
    _adicionar_variacao_perigo(tema)

    # Aplicar no raiz: todos os filhos herdam
    theme = tema

    # Um botao especifico usa a variacao
    var botao_excluir: Button = $VBoxContainer/BotaoExcluir
    botao_excluir.theme_type_variation = "BotaoPerigo"

Se voce quiser mexer em um unico no sem tocar no Theme global, existe o caminho dos overrides. Por exemplo, botao_excluir.add_theme_stylebox_override("normal", meu_stylebox) troca so o stylebox normal daquele botao. Use com moderacao: override e otimo para um caso pontual, mas o visual do jogo inteiro deve morar no recurso Theme, senao vira caca-fantasma quando algo destoa.

Juntando tudo

O caminho que funciona na pratica e sempre o mesmo: crie um Theme, salve como arquivo, aplique no Control raiz de cada tela e deixe a herança propagar. Desenhe os botoes e paineis com StyleBoxFlat controlando cor, borda e cantos, defina os quatro estados para o botao reagir, ajuste fontes e cores por tipo de no, e reserve o Theme Type Variation para os poucos botoes que precisam fugir do padrao. Quando quiser controle total ou troca de tema em tempo real, o mesmo desenho vira GDScript tipado com Theme.new() e StyleBoxFlat.new().

O resultado e uma interface que parece intencional, nao um projeto vazio. E como tudo vive num unico recurso, redesenhar o jogo inteiro no futuro e questao de editar um arquivo. Se voce quer aprender esse tipo de fluxo de forma estruturada, do menu ao HUD polido, vale conhecer o melhor curso de Godot para acelerar a parte visual sem tropecar nos detalhes.