A paint thread

Esta é, provavelmente, a regra mais importante do framework para não corromper seu app.

O CrossFly é single-thread na paint thread

Toda operação de UI e de renderização acontece em uma única thread — a paint thread. O Main chama create(), render() e resize() sempre nela; todo onShow, onPaint, onLayout, callback de toque e mudança de componente roda nela.

Por quê essa decisão? Simplicidade e correção. Com um único fio de execução tocando a UI, não há locks, nem estado compartilhado disputado no caminho de pintura. O preço é uma regra que você precisa respeitar: nunca toque na UI de outra thread.

O padrão canônico: trabalho pesado fora, UI de volta com onUI

Rede, banco, arquivo, cálculo longo → thread de fundo. Para tocar na UI com o resultado, volte para a paint thread com Component.onUI(...):

new Thread(() -> {
   List<Cliente> dados = repositorio.buscarTudo();   // trabalho pesado, thread de fundo
   Component.onUI(() -> {                             // volta para a paint thread
      lista.setItems(dados);                          // agora é seguro mexer na UI
      Component.repaint();                             // pede um novo frame
   });
}).start();

Existe também Main.runOnPaintThread(Runnable) (e a variante runOnPaintThreadAndWait(...)) para o mesmo fim fora do contexto de um Component.

Sintoma clássico de violar a regra: o app trava ou se comporta de forma errática ao “atualizar a tela” de dentro de um callback de rede/timer. A correção é sempre envelopar o toque na UI com onUI(...).

Render sob demanda

A paint thread não fica redesenhando continuamente. Um novo frame só é gerado quando alguém chama repaint() (internamente Gdx.graphics.requestRendering()). Isso economiza bateria — uma tela parada não gasta GPU.

A maioria dos setters de componente já chama repaint() por você. As consequências a lembrar:

• Mudou algo que o framework não conhece? Chame repaint() você mesmo.
• Animação? Ela precisa manter o pedido de render vivo a cada frame (é o que os animadores fazem no onUpdate; ver Animações de valor).

Veja também

• Relacionado: O pipeline de renderização · Estado e fluxo de dados
• Próximo: Layout e o modelo Relative