Communitygithub.com

Pré-visualização de UI

Em um projeto de jogo, crie uma prévia HTML ajustável de um elemento de HUD, menu, prompt, transição ou efeito de tela antes de implementá-lo na engine, convertendo os valores ajustados na especificação de construção. Ideal para quem trabalha em um jogo e precisa projetar, prototipar, reformular ou ajustar a aparência ou movimento da UI ou de um efeito visual.

O que é Pré-visualização de UI?

Este skill orienta a criação de pré-visualizações HTML interativas e ajustáveis para elementos de interface de usuário (UI) em jogos, como HUDs, menus, transições e efeitos de tela. A principal vantagem é permitir que designers e desenvolvedores ajustem visualmente cada detalhe (cores, tamanhos, animações, variantes) antes de qualquer implementação na engine, evitando alterações cegas. O fluxo de trabalho é rigoroso: primeiro, captura-se uma screenshot real do jogo na resolução alvo. Em seguida, constrói-se uma página HTML que sobrepõe o elemento de UI sobre a screenshot, com um painel de ajustes (sliders, seletores de cor, variantes). Cada alteração é salva em um arquivo `values.json`, que serve como especificação única para a implementação. Existe também uma folha de revisão que gera imagens de cada estado e variante para comparação. O skill suporta as principais engines: Godot, Unity e Unreal, fornecendo scripts específicos para aplicar os valores ajustados diretamente nos temas, classes e propriedades exportadas de cada engine. As pré-visualizações são mantidas no repositório do projeto para documentar as decisões de design, e qualquer alteração posterior exige um novo ciclo completo de ajuste e salvamento, garantindo que nenhum valor "mágico" ou não documentado entre no código final.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/thomas-ratz/game-ui-proof/tree/HEAD/skills/ui-preview

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

O que Pré-visualização de UI faz?

Nada que mude a aparência da UI do jogo é construído até que a pessoa tenha ajustado uma pré-visualização HTML e pressionado Salvar. O values.json salvo é a especificação: cada número nele se torna uma propriedade exposta no editor ou uma entrada de tema, nunca um número mágico no código. Uma mudança que ninguém pode ver não precisa de pré-visualização.

Ordem do trabalho: o que pré-visualizar → uma screenshot do local → a página de pré-visualização → a folha de revisão → a pessoa ajusta e pressiona Salvar → construir a partir do values.json → folha de construção vs pré-visualização.

1. Configuração (uma vez por projeto)

  • Copie assets/kit/ para docs/mockups/kit/ (outra pasta funciona: passe --mockups para os scripts). Arquivos específicos de engine podem ser omitidos quando não usados: godot_theme.js + apply_godot.py (Godot), unity_theme.js + apply_uss.py (Unity), unreal_theme.js + apply_unreal.py (Unreal). Para Godot: copie também assets/godot/project.js para kit/ e preencha-o (fontes, glifos de teclas); as páginas Godot o carregam de lá.
  • project.css é o único arquivo do kit a editar: as fontes do jogo (@font-face) e a paleta do painel, incluindo --display. O kit.js carrega todas as fontes declaradas antes de desenhar.
  • Mantenha as pré-visualizações fora da importação da engine (Godot: um .gdignore vazio em docs/mockups/) e adicione docs/mockups/*/values.draft.json e docs/mockups/*/shots/ ao .gitignore.
  • Sirva a raiz do projeto: python docs/mockups/kit/serve.py (apenas stdlib), depois abra http://127.0.0.1:8765/docs/mockups/<feature>/. As páginas carregam a arte do jogo por caminho relativo e salvam seus ajustes em disco (§5).
  • Leitura dos estilos próprios do projeto para o painel: Godot GodotTheme (tema .tres), Unity UnityTheme (.uss, ScriptableObject .asset), Unreal UnrealTheme (padrões de classe C++ do cabeçalho e Default*.ini, DataTable exportado para JSON/CSV). Veja references/engines.md; cada um tem uma página de exemplo funcional em assets/<engine>/.

2. Pergunte, depois obtenha o fundo real

  • Pergunte qual tela, elemento ou efeito, e em que situação, a menos que isso já esteja claro.
  • Capture uma screenshot desse local no tamanho da viewport do jogo (a configuração de resolução do projeto; também o stage do manifesto) com a UI oculta, e outra com a UI atual mostrada como linha de base. Use um pequeno script que a engine executa (template Godot: assets/godot/game_shots.gd; outros: references/engines.md) e mantenha-o junto à pré-visualização para a verificação de construção.
  • Peça uma screenshot à pessoa apenas quando o local não puder ser alcançado por script. Para algo novo sem nada para capturar ainda, ou quando a engine não puder ser executada aqui, use um fundo simples ou simulado e diga isso na legenda do estado.

3. Escreva a página

Copie assets/template/ (ou assets/<engine>/) para docs/mockups/<feature>/. O formato da página, especificações do painel, Kit.spec e parâmetros de URL estão em references/kit.md.

  • manifest.json: título, stage ([w, h]), states (um por situação que o jogador pode ver: vazio, cheio, focado, desabilitado, texto mais longo, meio de animação; cada um com uma legenda e shotTime), variants (2–4 quando há uma escolha real, cada um com um nome e uma nota), recommend (variante e porquê, em uma ou duas linhas).
  • index.html: Kit.start({ feature, images, groups, variants, draw }). Agrupe mais de cerca de seis valores em sections para que o painel os dobre. Cada grupo é o lugar onde os valores viverão na engine (uma classe de script, um tipo de tema, um shader), cada chave é o nome da propriedade que a construção usará, nas unidades da engine. draw(ctx, values, s) deve ser uma função pura de s.t (animações em loop com t % length).
  • A aparência real do jogo, não uma aproximação: suas fontes e tamanhos, cores do tema (uma nova cor é uma proposta: diga a qual paleta ela se junta), arte real por caminho relativo, texto e números reais, e prompts mostrando as teclas realmente vinculadas.
  • Pixel art: pixels inteiros, sem suavização (padrão do kit).
  • Movimento executa em sua duração e easing reais. Qualquer coisa que trema, derive, pisque ou oscile recebe alternâncias Reduzir Movimento / Reduzir Cintilação em um grupo preview: true, mostrando no que essas configurações o transformam.
  • Ao ajustar algo que já existe, a variante a o redesenha exatamente como é hoje. Verifique-a contra a screenshot de linha de base até que correspondam, ou toda outra variante será comparada contra uma linha de base errada.
  • Algo que várias pré-visualizações desenham vai em um arquivo compartilhado no kit, não copiado por página.

4. A folha de revisão

  • python docs/mockups/kit/shots.py <feature> (precisa de Chrome, Edge ou Chromium, e Pillow ≥ 10.1) escreve shots/<variant>_<state>.png e monta sheet.png. Ele usa o values.json salvo para sua variante (--defaults para os padrões da página) e sai com código não zero se uma página falhar, com o erro desenhado nessa captura.
  • Olhe a folha antes de mostrá-la; recorte o que está sendo decidido em 2×: texto cortado ou sobreposto, fonte errada, algo fora do palco, uma animação congelada em um momento tedioso (mova seu shotTime).
  • Envie a folha, a URL ao vivo e as decisões a tomar, com sua recomendação.

5. Leitura dos ajustes

  • Enquanto a pessoa ajusta, cada mudança é escrita em <feature>/values.draft.json. Leia sempre que a pessoa perguntar sua opinião; nunca construa a partir dele.
  • Salvar (ou Ctrl/Cmd+S) escreve <feature>/values.json, a especificação aprovada, e a página então abre nele: linhas que diferem são marcadas, ↺ coloca um valor de volta, Reset coloca todos de volta. Valores apenas de pré-visualização nunca são marcados ou salvos.
  • Sem o serve.py, os ajustes vivem apenas no navegador: Salvar copia o JSON (e o mantém como padrão daquele navegador), a pessoa o cola no chat, e você o salva como values.json.
  • Formato: {"feature", "variant", "values": {Group: {Key: value}}}; grupos apenas de pré-visualização são omitidos.

6. Construir a partir da especificação

  • Godot: python docs/mockups/kit/apply_godot.py <feature> lista o que a especificação muda no tema .tres e nos padrões [Export] / @export do script que cada grupo nomeia, nos padrões uniform de um grupo <name>.gdshader, chaves sem exportação ainda, e cenas que sobrescrevem essas propriedades. --write aplica.
  • Unity: python docs/mockups/kit/apply_uss.py <feature> faz o mesmo para propriedades personalizadas USS (grupos uss:). Valores de ScriptableObject são aplicados manualmente.
  • Unreal: python docs/mockups/kit/apply_unreal.py <feature> lista o que a especificação muda na classe C++ de cada grupo: sobrescritas Config/Default<Config>.ini para uma classe Config (--target header reescreve o padrão da declaração), chaves sem UPROPERTY ainda (com uma declaração para colar), e padrões a serem definidos manualmente. --write aplica. Valores de DataTable são aplicados reimportando a exportação editada.
  • Construa o que ainda não existe: cores, fontes e painéis no sistema de tema ou estilo da engine; tamanhos, deslocamentos, durações e forças como propriedades expostas no editor agrupadas como o JSON, com os valores aprovados como padrões.
  • Verifique no jogo em execução: capture uma screenshot de cada estado que a pré-visualização tem e crie <feature>/build_vs_preview.png, captura do jogo lado a lado com a captura da pré-visualização. Corrija o que diferir. Diga o que não foi verificado; a suavização de texto do navegador e da engine diferem, então julgue posição e tamanho, não pixels de borda.
  • Uma alteração posterior a uma aparência aprovada é um novo ciclo: pré-visualização, folha, Salvar, construir.

Regras

  • As pré-visualizações permanecem no repositório: elas registram por que a UI tem a aparência que tem. Commit sheet.png e values.json; shots/ e rascunhos são regenerados.
  • Nenhuma construção antes da existência do values.json; nunca construa a partir do rascunho.
  • Se o kit não tiver algo que uma pré-visualização precisa, adicione ao kit, não a uma página.

Habilidades Relacionadas