Convenções de nomenclatura para recursos de UI em minigames: imagens transparentes, botões, ícones e personagens

Na pasta do seu projeto, existem arquivos como btn_ok.png, button_confirm.png e botao_confirmar.png misturados? Três estilos de nome, três formas de interpretar, três começos diferentes para um desastre de colaboração.

Eu já caí nessa armadilha. No fim do meu primeiro projeto de minigame, a pasta de arte tinha mais de 200 recursos. Metade usava abreviações em inglês, metade usava traduções soltas, e alguns arquivos se chamavam simplesmente nova_pasta_2.png. Procurar um arquivo parecia caçar agulha no palheiro. Toda vez que eu precisava mudar a UI, gastava um bom tempo só confirmando qual imagem correspondia a qual estado.

Este artigo resolve um problema: como usar uma fórmula de nomenclatura para deixar seus recursos de UI visíveis de cara. Prefixo, categoria, função e estado. Quatro partes bem combinadas bastam.

Capítulo 1: O custo real da nomenclatura bagunçada — por que o padrão importa tanto

Comecemos por uma história real.

No ano passado, eu e dois amigos fizemos um minigame casual. A divisão era simples: eu cuidava do código, João fazia a arte e Maria escrevia o design do jogo. No segundo mês do projeto, João enviou uma leva de botões: 12 arquivos chamados de botao1.png até botao12.png. Perguntei qual era o botão de confirmar e qual era o de cancelar. Ele respondeu: “é só olhar a imagem”.

Naquele momento, fiquei encarando 12 imagens na tela. Todas eram retângulos arredondados quase do mesmo tamanho, com pequenas variações de cor. Levei 15 minutos para entender a correspondência. Depois que o projeto foi ao ar, João mudou o esquema de cores dos botões e mandou mais 12 imagens. Desta vez, os arquivos eram novo_botao1.png até novo_botao12.png. As imagens antigas não tinham sido removidas, as novas ficaram misturadas, e minha pasta passou a ter 24 “botões”.

Equipes de jogos do WeChat, da Tencent, já mediram que uma nomenclatura razoável pode economizar 80% do tempo de busca por arquivos. Não é pouca coisa. Imagine que você procure recursos 10 vezes por dia, 3 minutos por busca. São 30 minutos diários. Com padronização, isso cai para 6 minutos. Em um mês, você recupera 12 horas, tempo suficiente para criar o protótipo de uma nova funcionalidade.

O problema fica ainda maior em scripts de automação. Eu já escrevi uma ferramenta simples para substituir recursos de botões em lote. A lógica era direta: encontrar todos os PNGs que começavam com btn_ e trocar pela nova versão. O script rodou e não encontrou nada, porque os nomes usados pela arte não tinham btn_; eram todos localizados de outro jeito. O script perdeu valor, e a substituição manual tomou duas horas.

Quando o nome do recurso aparece no código, a diferença fica ainda mais clara:

// Nomenclatura padronizada
this.confirmButton.spriteFrame = assets.get('btn_ok_pressed');

// Nomenclatura sem padrão
this.confirmButton.spriteFrame = assets.get('button2');

Na primeira linha, você entende de imediato: é o estado pressionado do botão de confirmação. E na segunda? O que é button2? Você precisa abrir a pasta de arte, encontrar button2.png, olhar a imagem e só então descobrir. Repetir isso a cada ajuste de UI derruba a legibilidade do código.

Capítulo 2: Fórmula geral de nomenclatura — uma regra para quase todos os cenários

Não se assuste com a palavra “padrão”. A fórmula principal é bem simples:

prefixo_funcao_estado.png

Ou, em uma versão mais completa:

[email protected]

São quatro elementos, do mais geral para o mais específico. Veja [email protected]: módulo de e-mail, categoria de ícone, função de busca, estado pressionado e imagem em 2x. Cada trecho tem um significado claro.

Tabela rápida de prefixos comuns

Separei 15 abreviações frequentes, combinando recomendações de tutoriais básicos de Cocos Creator da Tencent Cloud e práticas de design de UI usadas em equipes de produto:

Abreviação	Nome completo	Onde usar
bg	background	Fundo de tela, fundo de modal
nav	navbar	Elementos de barra de navegação
tab	tabbar	Ícones de barra de abas
btn	button	Todos os tipos de botão
icon	icon	Ícones funcionais e de estado
img	image	Imagens genéricas
txt	text	Imagens de texto, como títulos
pop	popup	Elementos relacionados a modais
bar	bar	Barra de progresso ou de estado
mask	mask	Máscaras
sep	separator	Linhas divisórias
del	delete	Botão ou ícone de exclusão
add	add	Botão ou ícone de adição
msg	message	Mensagens, dicas e balões
logo	logo	Imagens de logotipo

Essas abreviações têm algo em comum: são curtas, fáceis de lembrar e comunicam o tipo do recurso de cara. Use btn em vez de button, bg em vez de background. Quanto maior o nome, maior a chance de erro de digitação e mais difícil fica escanear a pasta.

Recurso específico de módulo vs recurso global

Antes de nomear, faça uma pergunta: este recurso só aparece em um módulo ou pode ser usado no projeto inteiro?

Recurso global: não leva prefixo de módulo, começa direto pela categoria. Um fundo da tela inicial pode se chamar bg_home.png, não home_bg.png. Como fundos podem ser reutilizados em outros módulos, agrupar por categoria costuma facilitar a busca.

Recurso específico de módulo: leva prefixo de módulo, o que facilita processamento em lote. O ícone de busca do módulo de e-mail pode ser mail_icon_search.png. Quando você trocar a UI do e-mail, basta buscar o prefixo mail_ para encontrar todos os recursos relacionados.

Nomes com diferença de tamanho

Às vezes, o mesmo botão tem duas versões de tamanho. Minha prática é adicionar a descrição de tamanho depois da função:

btn_ok_big_n.png      # Botão de confirmação grande, estado normal
btn_ok_small_n.png    # Botão de confirmação pequeno, estado normal

Ou usar o tamanho exato:

btn_ok_128_n.png      # Botão de confirmação com 128px de largura
btn_ok_64_n.png       # Botão de confirmação com 64px de largura

Qualquer uma das duas opções funciona. O ponto essencial é manter consistência no projeto. Não use big/small em alguns arquivos, números em outros e l/s em outro canto. A raiz da bagunça raramente é a regra em si; é a falta de uma regra única.

Capítulo 3: Nomes de botões e ícones — estados claros de cara

Botões são o tipo de recurso de UI mais numeroso e com mais estados. Um botão geralmente tem quatro estados: normal, pressionado, selecionado e desativado. Convenções de UI como as usadas pelo Douban recomendam padronizar nomes em inglês ou abreviações:

Estado	Nome completo	Abreviação	Exemplo
Normal	normal	n / def	btn_ok_n.png
Hover	hover	h	btn_ok_h.png
Pressionado	pressed	p / pre	btn_ok_p.png
Selecionado	selected	s / sel	btn_ok_s.png
Desativado	disabled	d / dis	btn_ok_d.png

Eu costumo usar abreviações de uma letra por um motivo simples: elas são curtas. btn_ok_n.png tem 5 caracteres a menos que btn_ok_normal.png, é rápido de digitar e fica mais limpo visualmente. Claro: se sua equipe prefere nomes completos, use nomes completos. Só não misture btn_ok_normal em alguns botões com btn_ok_n em outros, porque isso complica qualquer busca.

Exemplo prático de nome para botão

Imagine que seu projeto precise de um botão “confirmar”, azul, com cantos arredondados e quatro estados. Uma opção de nomenclatura:

btn_ok_n.png          # Estado normal
btn_ok_p.png          # Estado pressionado
btn_ok_s.png          # Estado selecionado
btn_ok_d.png          # Estado desativado

Se também houver versões vermelha e verde:

btn_blue_ok_n.png     # Botão azul de confirmação, normal
btn_red_ok_n.png      # Botão vermelho de confirmação, normal
btn_green_ok_n.png    # Botão verde de confirmação, normal

A ordem é: categoria (btn) + cor (blue) + função (ok) + estado (n). A vantagem é que, ao ordenar alfabeticamente, botões da mesma cor ficam próximos, o que ajuda em substituições em lote.

Nomes de ícones: função em primeiro lugar

A diferença entre ícones e botões está na quantidade de estados. A maioria dos ícones tem apenas dois estados: normal e desativado. O padrão fica assim:

icon_search_n.png     # Ícone de busca, normal
icon_search_d.png     # Ícone de busca, desativado

O ponto mais importante nos ícones é descrever a função com precisão. Não use icon1.png; use icon_search.png ou icon_delete.png. O nome do arquivo deve explicar a finalidade sem exigir que você abra a imagem.

Um erro comum

Eu já vi nomes como button_confirmar_normal.png em projetos que também usavam btn_ok_n.png. Parece intuitivo, mas cria três problemas:

1. Ordenação bagunçada: palavras localizadas e abreviações em inglês não ficam agrupadas de forma útil
2. Baixa compatibilidade com scripts: automações costumam usar regex, e padrões misturados complicam a lógica
3. Dificuldade de colaboração: se o projeto precisar de internacionalização depois, todos os nomes localizados entram na lista de débito técnico

A opção mais estável é usar inglês do começo ao fim, com letras minúsculas e underscores. btn_ok_n.png é curto, ordenável, fácil de buscar por regex e pronto para internacionalização.

Capítulo 4: Nomes de recursos de personagem — sequências de frames sem bagunça

Recursos de personagem são bem mais complexos que botões de UI. Um protagonista pode ter sete ou oito ações: idle, walk, run, attack, hurt, death, jump. Cada ação pode ter direções diferentes, como cima, baixo, esquerda e direita, ou até oito direções. Cada direção ainda tem uma sequência de frames de animação.

A maior armadilha em que caí foi a numeração de frames. Na primeira animação de personagem que fiz, usei números de um dígito:

hero_run_left_1.png
hero_run_left_2.png
hero_run_left_3.png
...
hero_run_left_10.png

Parece normal. O problema aparece na ordenação. Ao abrir a pasta, hero_run_left_10.png fica entre hero_run_left_1.png e hero_run_left_2.png. O sistema de arquivos ordena por caracteres; o primeiro caractere de 10 é 1, então ele vem antes de 2.

É um desastre completo.

Depois disso, passei a exigir numeração com dois dígitos:

hero_run_left_00.png
hero_run_left_01.png
hero_run_left_02.png
...
hero_run_left_09.png
hero_run_left_10.png

Agora 00 até 09 ficam antes de 10, e a ordenação funciona. Se a animação tiver mais de 100 frames, use três dígitos, de 000 a 999.

Fórmula para personagens

A fórmula completa para sprites de personagem é:

nomeDoPersonagem_acao_direcao_frame.png

Alguns exemplos:

• hero_idle_down_00.png — protagonista_idle_baixo_frame0
• player_run_left_01.png — jogador_corrida_esquerda_frame1
• enemy_attack_right_02.png — inimigo_ataque_direita_frame2

Tabela rápida de ações

Ação	Inglês	Abreviação opcional
Parado	idle	—
Andando	walk	—
Correndo	run	—
Atacando	attack	atk
Ferido	hurt	—
Morte	death	die
Pulando	jump	—
Conjurando	cast	—

Usar ou não abreviações depende da equipe. atk é mais curto que attack, mas um membro novo talvez não reconheça de imediato. O nome completo é mais universal; a abreviação é mais compacta. Minha sugestão: use nomes completos enquanto cada animação tiver menos de 20 frames. Acima disso, considere abreviações, porque nomes longos podem ser truncados em algumas visualizações de caminho.

Identificadores de direção

O caso mais simples tem quatro direções: up, down, left, right.

Para oito direções, você pode usar números de 0 a 7, combinando que 0 é para cima, 1 é para cima e direita, e assim por diante. O problema desse esquema é que ninguém memoriza fácil. Toda hora alguém precisa consultar uma tabela. Eu prefiro nomes diretos:

hero_attack_up.png
hero_attack_upright.png
hero_attack_right.png
hero_attack_downright.png
hero_attack_down.png
hero_attack_downleft.png
hero_attack_left.png
hero_attack_upleft.png

Os nomes de oito direções ficam um pouco longos, mas não exigem adivinhação. Se o projeto usa direções simples, como quatro direções ou apenas esquerda e direita, nomes de direção são a opção mais segura. Se as direções forem muitas, a numeração pode ser mais compacta.

Capítulo 5: Estrutura de diretórios no Cocos Creator — organize por categoria para ganhar velocidade

A convenção de nomes resolve a pergunta “como o arquivo se chama”. A estrutura de diretórios resolve “onde o arquivo fica”. As duas precisam funcionar juntas para que encontrar recursos realmente fique rápido.

Uma estrutura recomendada em tutoriais básicos de Cocos Creator da Tencent Cloud é:

assets/
├── textures/           # Recursos de textura
│   ├── ui/             # Elementos de UI, como botões e barras
│   ├── icons/          # Ícones funcionais
│   ├── backgrounds/    # Fundos
│   └── characters/     # Sprites de personagens
├── audio/              # Arquivos de áudio
│   ├── effects/        # Efeitos sonoros
│   └── music/          # Música de fundo
├── animations/         # Clipes de animação
├── prefabs/            # Prefabs
└── scripts/            # Scripts TypeScript

Global vs específico de módulo: guarde separado

Uma armadilha que já enfrentei foi jogar todos os recursos em textures/ui/. O resultado: 300 arquivos na mesma pasta. Abrir demorava, rolar demorava, encontrar qualquer coisa demorava.

Uma abordagem melhor é separar recursos globais de recursos específicos de módulos.

Recursos globais ficam em subdiretórios de primeiro nível dentro de textures/. Por exemplo, textures/icons/ guarda ícones que podem ser usados por qualquer módulo.

Recursos específicos de módulo ficam em diretórios próprios:

assets/
├── modules/
│   ├── login/          # Módulo de login
│   │   ├── textures/   # Recursos exclusivos da tela de login
│   │   ├── prefabs/    # Prefabs da tela de login
│   │   └── scripts/    # Scripts da lógica de login
│   ├── battle/         # Módulo de batalha
│   │   ├── textures/   # Recursos da interface de batalha
│   │   ├── prefabs/    # Prefabs de batalha
│   │   └── scripts/    # Scripts de batalha

A vantagem é que, ao mexer em um módulo, você não precisa vasculhar o diretório assets inteiro. Vai alterar a tela de batalha? Olhe modules/battle. Vai alterar login? Olhe modules/login.

Não fragmente demais

Classificar demais também atrapalha. Já vi alguém criar textures/ui/buttons/blue/rounded/, cinco níveis de pasta, com dois ou três arquivos em cada diretório. Para encontrar um recurso, era preciso clicar camada por camada na árvore de arquivos; mais lento do que ler um nome bem feito.

Minha sugestão: uma camada de categoria costuma bastar, exceto quando uma categoria realmente fica grande, como mais de 50 sprites de personagem. Coloque botões, barras de progresso e divisores em textures/ui/; ícones em textures/icons/; fundos em textures/backgrounds/. Até três níveis, a estrutura continua fácil de entender.

Coloque prefabs e scripts perto do que eles usam

Prefabs e scripts devem ficar próximos dos recursos correspondentes. O prefab de um botão da tela de login pode ficar em modules/login/prefabs/, enquanto suas imagens ficam em modules/login/textures/. Os dois diretórios ficam lado a lado, os caminhos são curtos e você não precisa pular entre pastas distantes ao editar.

A documentação oficial do Cocos Creator também menciona esse princípio: arquivos relacionados devem ficar próximos para reduzir referências entre diretórios distantes. Quanto mais curto o caminho, mais claro o projeto; migrações e refatorações também ficam menos dolorosas.

Capítulo 6: 7 regras de ouro de nomenclatura — experiência de equipes de jogos da Tencent

Equipes de jogos do WeChat, da Tencent, já resumiram um conjunto de regras de ouro para nomenclatura. Abaixo, eu explico cada uma com base na minha prática.

1. Seja breve: inclua detalhes suficientes, sem exagerar

O nome do arquivo deve comunicar as informações importantes, mas não pode ficar longo demais.

Bom exemplo: btn_ok_n.png — dá para ver de cara que é um botão, de confirmação, no estado normal.

Mau exemplo: button_confirm_normal_state_blue_rounded_large.png — informação demais, leitura cansativa e digitação ainda pior.

Minha prática: manter o nome entre 3 e 5 partes. Passou de 5, considere remover detalhes secundários, como rounded, e documentá-los em comentário ou no guia da equipe.

2. Avance por camadas: do geral ao específico

A ordem do nome deve seguir a lógica de leitura: primeiro a categoria maior, depois a função, por fim o detalhe.

environment_forest_tree_01.png

Leitura: recurso de ambiente → cenário de floresta → árvore → primeira variação.

Essa ordem faz arquivos da mesma categoria ficarem juntos automaticamente. Ao buscar environment_forest, todos os recursos de floresta aparecem.

3. Ordene bem: facilite a busca alfabética

A escolha do prefixo afeta a ordenação. Coloque a categoria mais importante no começo.

Em recursos de personagem, por exemplo, começar com hero_ costuma ser melhor que character_hero_, porque todos os recursos do protagonista ficam concentrados na área do h, sem exigir busca dentro de um grupo genérico de character.

4. Mantenha o formato: snake_case ou camelCase

Escolha um formato no projeto e use do começo ao fim.

Eu prefiro snake_case, com minúsculas e underscores, por três motivos:

• Compatibilidade melhor com sistemas de arquivos, evitando problemas de sensibilidade a maiúsculas
• Legibilidade alta, porque o limite entre palavras fica claro
• Regex mais simples, já que _ separa cada parte

Se sua equipe prefere camelCase, tudo bem. Só mantenha o mesmo padrão. Misturar formatos quebra scripts e dificulta busca.

5. Padronize numeração: 01/02 ou 001/002, nunca um dígito solto

Esta regra apareceu no Capítulo 4. Números de um dígito bagunçam a ordenação; use preenchimento com zero.

Duas regras simples:

• Até 99 frames, use dois dígitos, de 00 a 99
• Acima de 99 frames, use três dígitos, de 000 a 999

6. Use a mesma gramática: uma forma verbal por ação

Algumas ações podem aparecer em duas formas: spin e spinning, attack e attacking.

Escolha uma e mantenha.

Exemplo errado:

cha_sonic_spin_01.png
cha_sonic_spinning_02.png

Os dois arquivos representam a mesma ação, mas os nomes não batem. Um script de busca pode deixar um deles passar.

Exemplo correto:

cha_sonic_spin_01.png
cha_sonic_spin_02.png

7. Use a mesma ortografia: um padrão de escrita

Algumas palavras variam entre inglês britânico e americano: ambience contra ambiance, colour contra color.

Escolha um padrão, normalmente o americano por ser mais comum em ferramentas e documentação, e aplique no projeto inteiro. Não use bg_ambience.png em um lugar e bg_ambiance.png em outro, porque scripts e buscas vão falhar.

Capítulo 7: Dicas para imagens transparentes e recursos especiais

Alguns recursos de UI têm características específicas e merecem cuidado extra no nome.

Nomes de PNGs transparentes

PNGs com fundo transparente são comuns em UI de jogos: botões, ícones e efeitos sobrepostos. No nome, você pode usar o sufixo _trans ou _overlay:

btn_trans_round.png        # Botão arredondado transparente, sem borda
icon_overlay_star.png      # Ícone de estrela sobreposto, usado em badge

O problema de recursos transparentes é que nem sempre o nome deixa a transparência evidente. O sufixo funciona como lembrete. Ao usar o arquivo, você sabe de cara que o fundo é transparente, sem precisar abrir a imagem para confirmar.

Nomes de máscaras

Máscaras (mask) são usadas para recortar imagens e criar efeitos de canto arredondado. Um padrão simples:

mask_rounded.png           # Máscara arredondada
mask_circle.png            # Máscara circular
mask_gradient.png          # Máscara em gradiente

Normalmente não há tantas máscaras. Elas podem ficar em textures/ui/masks/ ou diretamente em textures/ui/, dependendo do tamanho do projeto.

Nomes de recursos multilíngues

Projetos internacionalizados precisam de várias versões de imagens com texto. Um formato simples:

title_pt.png               # Título em português
title_en.png               # Título em inglês
title_ja.png               # Título em japonês

Ou usando códigos ISO:

btn_start_pt-BR.png        # Português do Brasil
btn_start_en-US.png        # Inglês americano
btn_start_ja-JP.png        # Japonês

Códigos ISO completos são mais precisos, mas deixam o nome mais longo. Se o projeto tiver até 5 idiomas, abreviações como pt/en/ja costumam bastar.

Nomes para múltiplas densidades

Jogos mobile precisam se adaptar a diferentes densidades de tela: normal, alta e muito alta. O Cocos Creator recomenda sufixos como @1x, @2x e @3x:

[email protected]            # Densidade normal, 1x
[email protected]            # Alta densidade, 2x
[email protected]            # Densidade muito alta, 3x

Esse padrão é compatível com iOS/Android e costuma ser reconhecido por ferramentas de asset pipeline, como TexturePacker.

Atenção: o sufixo de escala fica depois do estado, não no meio do nome. [email protected] é mais claro que btn_ok@2x_n.png: primeiro você identifica o recurso e o estado; depois, a escala.

Como lidar com caracteres especiais

Às vezes, nomes de arquivo incluem espaços, parênteses ou caracteres localizados. Minha recomendação é: evite todos.

Espaços: use underscore. btn ok.png → btn_ok.png.

Parênteses: remova ou troque por número. btn_ok(1).png → btn_ok_01.png.

Nomes localizados: converta para inglês. botao_confirmar.png → btn_ok.png.

Caracteres especiais podem dar problema entre plataformas. Windows aceita muitos nomes, mas alguns servidores Linux, ferramentas de FTP ou pipelines de CI/CD podem falhar com caminhos fora do padrão esperado. A solução mais estável é usar inglês, minúsculas e nenhum caractere especial.

Conclusão

A fórmula principal de nomenclatura é a combinação de quatro elementos: prefixo, função, estado e detalhe.

btn_ok_n.png — categoria, botão; função, confirmar; estado, normal. hero_run_left_00.png — personagem, ação, direção e número do frame. Ao dominar essa fórmula, você resolve 90% dos nomes de recursos de UI.

Os 10% restantes são detalhes: numeração com dois dígitos para evitar ordenação errada, inglês do começo ao fim para reduzir problemas multiplataforma e abreviações consistentes para não quebrar scripts. Esses detalhes não mudam a ideia central da nomenclatura, mas definem sua eficiência no trabalho real.

Você pode começar por três ações:

1. Verifique o projeto atual: abra a pasta de arte, procure arquivos fora do padrão e renomeie usando as fórmulas deste artigo
2. Crie um glossário de abreviações: combine com a equipe um padrão para bg/btn/icon/nav, registre e deixe visível
3. Organize a estrutura de diretórios: separe recursos globais de recursos específicos de módulo; não coloque tudo na mesma pasta

Convenção de nomes não é uma tarefa única, é um hábito contínuo. Quando você se acostuma com btn_ok_n.png, com numeração de dois dígitos e com inglês do começo ao fim, os arquivos do projeto ficam mais claros e encontrar recursos fica cada vez mais rápido.