Wiki

Regras de validação

Verificações de validação de assets executadas no check-in a partir do editor Unreal : as 9 regras integradas, as severidades error / warning / info, a configuração JSON, exportar / importar / reset, e o limite a conhecer.

Introdução

As regras de validação são verificações de assets do Unreal executadas no momento do check-in a partir do editor Unreal : nomenclatura, tamanho de textura, dependências ausentes, etc. Elas servem para fazer cumprir as convenções do estúdio automaticamente, antes que o conteúdo entre no repositório (o projeto versionado no servidor). Elas são configuradas por repositório.

Onde as regras realmente se aplicam

A validação é feita pelo editor Unreal, não pelo servidor As regras configuradas aqui são baixadas e executadas pelo plugin uVersion para Unreal Engine, no momento em que você envia a partir do editor. O servidor, por sua vez, nunca consulta as regras quando registra um commit. Consequência a conhecer antes de contar com elas : um envio feito a partir do cliente desktop, da linha de comando (uversion checkin) ou do plugin Rider contorna integralmente a política de validação, sem erro e sem deixar rastro.

Isso não é um erro de configuração da sua parte : é o funcionamento atual. As regras se aplicam a assets do Unreal (.uasset, .umap) e sua inspeção exige o editor aberto, com o projeto carregado. Trate-as, portanto, como uma proteção para os artistas que trabalham no editor, e não como uma barreira que ninguém pode transpor.

Duas consequências práticas :

Se uma convenção deve ser garantida e não apenas incentivada, preveja um controle a mais (revisão, verificação do lado do build) : as regras sozinhas não a asseguram.
Se uma regra “nunca dispara” com alguém, verifique primeiro de onde ele envia. Um artista que envia a partir do cliente desktop não verá nenhuma validação, seja qual for a configuração.

Acesso e funções

A aba Regras está disponível para o super admin e para o project_admin nos repositórios que ele administra.

Semeadura automática, mas todas desativadas As 9 regras padrão são criadas automaticamente na criação de um repositório (e, na falta disso, na primeira vez que se abre a aba Rules de um repositório que não tem nenhuma). Elas são semeadas desativadas : em um repositório novo, nenhuma validação roda enquanto um administrador não tiver ativado as regras que deseja. Você parte de um conjunto completo, para ativar e ajustar.

Severidades

A severidade decide o que acontece no editor Unreal quando uma regra ativada falha.

Severidade	Efeito no check-in a partir do editor Unreal
`error`	Bloqueia o check-in : a janela de validação se abre, o botão Proceed fica esmaecido e apenas OK permanece clicável. É preciso corrigir o asset.
`warning`	Não impede o envio, mas não passa em silêncio : a janela de validação se abre mesmo assim, lista os avisos, e o usuário deve clicar em Proceed para continuar.
`info`	Puramente informativo : não abre a janela sozinho e não interrompe nada.

A janela Pre-Checkin Validation no editor Unreal, com a lista de constatações e o botão Proceed.

As 9 regras integradas

Regra	Padrão	O que ela verifica
`blueprint_compilation`	error	Os Blueprints compilam sem erros antes do check-in.
`naming_convention`	warning	Prefixos de nomenclatura (estilo Allar UE5) : `T_` texturas, `M_` materiais, `BP_` blueprints, `SM_` static meshes, `WBP_` widgets, etc.
`max_texture_size`	warning	Tamanho máximo das texturas : por padrão 4096 × 4096, potência de 2 obrigatória.
`material_complexity`	warning	Complexidade dos materiais : por padrão máx. 256 instruções, 16 amostras de textura.
`import_settings`	warning	Ajustes de importação em conformidade (texturas, meshes).
`missing_dependency`	error	Nenhuma dependência ausente (ignora por padrão o conteúdo do motor).
`circular_dependency`	error	Sem dependência circular (profundidade de busca 20 por padrão).
`unreferenced_asset`	info	Sinaliza os assets não referenciados (exclui mapas e widgets por padrão).
`duplicate_asset`	warning	Detecta os assets duplicados (ignora os `.umap` por padrão).

Ativar e configurar

1. Abrir a aba Rules

No painel de administração, escolha primeiro o repositório no seletor da linha PROJECT, depois abra a aba Rules dessa mesma linha : as regras se aplicam a um único repositório por vez. As 9 regras são exibidas, uma por linha, com um chevron para expandir, um interruptor, o nome da regra, sua severidade e sua descrição.

A lista das 9 regras de validação : em cada linha o chevron, o interruptor de ativação, o nome da regra, sua severidade e o menu suspenso Error / Warning / Info à direita.

2. Ativar a regra

Clique no interruptor à esquerda do nome. O salvamento é imediato : não há botão de salvar para essa ação. É a etapa que se esquece : em um repositório novo, todos os interruptores estão desligados, e uma regra desligada não diz nada a ninguém, seja qual for sua severidade.

3. Escolher a severidade

O menu suspenso à direita da linha oferece Error, Warning e Info, com salvamento imediato aqui também. Apenas error bloqueia realmente o check-in : ver Severidades.

4. Ajustar os parâmetros (JSON)

Clique no chevron no início da linha para expandir a regra. O campo Configuration (JSON) contém seus parâmetros ; modifique-os, depois clique em Save Config. Um JSON inválido bloqueia o salvamento e exibe o detalhe do erro abaixo do campo (Invalid JSON: ...), a regra permanece então no seu estado anterior.

Uma regra expandida no seu editor Configuration (JSON) : o texto dos parâmetros na área de entrada e o botão Save Config no canto inferior direito.

Exemplo : baixar max_texture_size para 2048 em um projeto mobile, ou passar naming_convention para error para impô-la estritamente.

Exportar, importar, reset

Três botões ocupam a barra de ferramentas, no canto superior direito da aba Rules :

Export : baixa um arquivo rules.json contendo o estado de todas as regras (ativação, severidade, config).
Import : recarrega um rules.json e aplica cada entrada às regras correspondentes (as chaves desconhecidas são ignoradas).
Reset to Defaults : redefine todas as regras para seus valores padrão. As configurações personalizadas são perdidas (confirmação solicitada).

Exportar / importar serve para replicar uma política de validação de um repositório para outro, ou para versioná-la offline.

rules.json no repositório

Um rules.json commitado não é aplicado por qualquer um Um arquivo .uversion/rules.json commitado só é aplicado à política do repositório se o autor do commit possuir a permissão chamada manage_rules (uma “capacidade”, ou seja, uma permissão vinculada a um papel e válida em todo o servidor). Caso contrário, o arquivo é armazenado mas as regras não mudam. É uma salvaguarda : um colaborador com direito de escrita nesse caminho não pode desativar a validação commitando um arquivo.

Armadilhas comuns

Um check-in está bloqueado no editor Unreal

Uma regra em error falhou : a janela de validação lista as constatações e o botão Proceed permanece esmaecido. Corrija o asset, ou (se a regra for estrita demais para o seu contexto) baixe sua severidade para warning, ou desative-a.

Reset apaga minhas configurações

Reset to Defaults é destrutivo para suas configurações personalizadas. Faça um Export antes se quiser poder voltar atrás.

Uma regra parece não fazer nada

Três verificações, nesta ordem :

De onde a pessoa envia? A partir do cliente desktop, da linha de comando ou do plugin Rider, nenhuma regra é avaliada (ver Onde as regras realmente se aplicam).
A regra está ativada? Em um repositório novo, todas estão desativadas no início.
Sua severidade está correta? Apenas error bloqueia o check-in ; info não interrompe nada.