Corvinal Personagens

Guia prático para quem trabalha com corvinal personagens

Muita gente entra nesse assunto achando que é só escolher os sprites e mandar exportar. Na prática, o pipeline de corvinal personagens costuma travar em problemas bem específicos que não aparecem na documentação. O formato de arquivo, a nomenclatura das pastas e a ordem de importação dos assets são os três pontos que mais geram dor de cabeça. Eu passei duas semanas travado num projeto porque os nomes dos arquivos de animação não estavam no padrão correto. O engine espera sufixos como _idle, _run, _attack no final do nome antes da extensão. Sem isso, o importador simplesmente ignora o arquivo sem emitir erro algum. Só percebi porque habilitei o modo de log detalhado nas configurações do editor.

Organização dos corvinal personagens

A estrutura de pastas recomendada funciona assim: Dentro da pasta do projeto, você cria um diretório chamado characters/. Dentro dele, cada personagem recebe sua própria subpasta. O nome da pasta deve seguir exatamente o identificador interno do personagem, sem espaços e em minúsculas. Exemplo: characters/kael_v2/. Dentro dessa pasta, você divide em subpastas obrigatórias: animations/, sprites/, audio/ e config/. A pasta config é onde fica o arquivo character.json, que contém todas as propriedades do personagem — hitbox, velocidade, frames de dano, tags de colisão e assim por diante.

O arquivo config é onde a maioria dos erros acontece. O campo hitbox precisa ser definido em pixels relativos ao ponto de origem do sprite, não em coordenadas absolutas. Se você definir a hitbox como x:0, y:0, width:64, height:64 e o sprite tiver um offset de 16 pixels na base, a colisão vai ficar desalinhada e o personagem vai parecer que leva dano de ataques que nunca chegaram nele. Eu descobri isso na hard mode de teste porque o timing dos frames de ataque não batia com a detecção de colisão real.

Processo de importação e exportação

O fluxo de trabalho que mais se encaixa para projetos grandes é o seguinte. Primeiro, você monta todos os sprites brutos em resolução 1x. O engine escala automaticamente para 2x e 3x durante a build, então não adianta gastar tempo separando resoluções. Segundo, você exporta cada animação como um sprite sheet individual, com frames alinhados em grid uniforme. O tamanho recomendado do grid é 64x64 pixels por frame, mesmo que o sprite final ocupe menos espaço. Aqui entra um problema que quase ninguém menciona. Quando você tem mais de 30 personagens num projeto, o tempo de compilação dos assets aumenta exponencialmente. A solução que eu encontrei foi agrupar os sprites de todos os personagens que compartilham o mesmo conjunto de animações base em um sprite sheet compartilhado. Isso reduziu meu tempo de build de 45 minutos para cerca de 8 minutos. O trade-off é que você perde flexibilidade para customizar animações individuais, mas para personagens genéricos ou NPCs, esse custo não vale a pena. Outro ponto prático: a configuração de priority layer. Personagens que ficam atrás de outros na tela precisam ter o layer value menor. Se dois personagens no mesmo layer se sobrepõem, o motor decide a ordem baseada no timestamp de criação, o que é imprevisível. Defina layer values de forma consistente — 0 para o plano de fundo, 10 para o primeiro plano de personagens, 20 para efeitos de HUD sobrepostos.

Arquivo character.json

Um exemplo funcional do arquivo de configuração: O campo origin define o ponto de ancoragem do sprite. O padrão é o centro inferior, que funciona para a maioria dos plataformas. Se seu personagem tem uma animação de inclinação para frente no ataque, mude o origin para o centro do corpo para que a rotação aconteça no ponto certo. O campo animations é um dicionário onde cada chave é o nome da animação e o valor aponta para o sprite sheet correspondente na pasta animations/. O engine faz match pelo sufixo no nome do arquivo. Se o sprite sheet se chama kael_run.png, a chave no JSON tem que ser run. Qualquer outro nome resulta em animação silenciosa — o personagem aparece parado mesmo quando a input está sendo processada.

O tags array é importante para sistemas de diálogo e quest. Cada tag é uma string que pode ser consultada pelo script de jogo. Use tags como npc, enemy, ally de forma consistente. Eu vi muitos projetos onde tags como friendly e ally eram usadas indistintamente, o que quebrava queries que buscavam por uma delas especificamente.

Erros comuns que você vai cometer

O primeiro erro é tentar refatorar a estrutura de pastas depois que já exportou assets. O engine armazena caminhos relativos nos arquivos de configuração, então mudar o nome de uma pasta invalida todos os links de animação de uma vez. Sempre organize antes de começar a importar. O segundo erro é ignorar o frame delay. Cada animação tem um atributo que define quantos milissegundos cada frame dura. Se você configurar tudo como 100ms mas as artes foram desenhadas para 16ms (60fps), o personagem vai se mover em câmera lenta aparente. O frame delay padrão recomendado é 100ms para idle e 66ms para ação, mas isso varia conforme a velocidade que você quer no movimento. O terceiro erro, que eu cometi pessoalmente, é não testar a exportação em diferentes resoluções de tela. Um personagem que funciona perfeitamente em 1920x1080 pode ter hitboxes desalinhadas em 1280x720 porque o sistema de referência de coordenadas muda entre resoluções. Sempre faça um teste de validação de colisão em pelo menos duas resoluções antes de considerar um personagem pronto.

Alternativas e quando sair do fluxo padrão

Se o seu projeto tem mais de 50 personagens, o processo manual de configuração do character.json não escala. Nesse caso, eu recomendo usar um gerador de assets em lote. Scripts Python que leem uma planilha CSV com todos os dados e geram os arquivos JSON automaticamente cortam o tempo de setup de horas para minutos. A desvantagem é que você perde o controle fino sobre cada personagem individual, mas para projetos grandes isso é um preço pequeno a pagar. Para projetos pequenos com até 10 personagens, o fluxo manual é rápido o suficiente e oferece mais flexibilidade. O importante é manter a consistência desde o início, porque corrigir depois é muito mais custoso do que fazer certo na primeira vez.