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/paradocs/mockups/kit/(outra pasta funciona: passe--mockupspara 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émassets/godot/project.jsparakit/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
.gdignorevazio emdocs/mockups/) e adicionedocs/mockups/*/values.draft.jsonedocs/mockups/*/shots/ao.gitignore. - Sirva a raiz do projeto:
python docs/mockups/kit/serve.py(apenas stdlib), depois abrahttp://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), UnityUnityTheme(.uss, ScriptableObject.asset), UnrealUnrealTheme(padrões de classe C++ do cabeçalho eDefault*.ini, DataTable exportado para JSON/CSV). Vejareferences/engines.md; cada um tem uma página de exemplo funcional emassets/<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
stagedo 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 eshotTime),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 emsections 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 des.t(animações em loop comt % 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
ao 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) escreveshots/<variant>_<state>.pnge montasheet.png. Ele usa ovalues.jsonsalvo para sua variante (--defaultspara 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 comovalues.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.trese nos padrões[Export]/@exportdo 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.--writeaplica. - Unity:
python docs/mockups/kit/apply_uss.py <feature>faz o mesmo para propriedades personalizadas USS (gruposuss:). 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: sobrescritasConfig/Default<Config>.inipara uma classe Config (--target headerreescreve o padrão da declaração), chaves sem UPROPERTY ainda (com uma declaração para colar), e padrões a serem definidos manualmente.--writeaplica. 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.pngevalues.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.