Documentação Técnica - Butterfly Hub

Bem-vindo(a) ao Projeto Butterfly! Este documento é o coração técnico do nosso projeto. Ele é seu guia para entender como tudo funciona, desde a configuração inicial até a implementação de novas ideias. Leia com atenção, pois ele é a base para colaborarmos de forma eficiente e criativa.

🤝1. Nosso Workflow: A Filosofia de Trabalho

O que é um Workflow?

Pense no "workflow" como a nossa receita de bolo. É o conjunto de passos e processos que concordamos em seguir para transformar uma ideia em uma parte funcional do jogo. Cada equipe tem o seu, e é a consistência desse processo que nos permitirá criar um game único e coeso. Respeitar nosso workflow é a chave para a colaboração dar certo.

Automatizar para Criar

Você notará que usamos vários scripts para automatizar tarefas (como o setup inicial). Fazemos isso para que possamos gastar nosso tempo e energia no que realmente importa: a criação. Menos tempo configurando, mais tempo criando.

Onde Estamos Agora?

Estamos na fase crucial de prototipagem e definição. Nosso foco atual é encontrar o "game feel" perfeito para a personagem e estabelecer como a arte será integrada ao jogo. Precisamos de modelos e referências dos artistas para testar diferentes pipelines: Qual o melhor formato de arquivo? Qual a resolução ideal? Como o cenário se conecta com as mecânicas? Suas contribuições agora definirão o futuro da produção.

🎨2. Nossas Ferramentas (Software Sugerido)

Somos grandes fãs de software open-source. As ferramentas abaixo são gratuitas, poderosas e formam a base do nosso pipeline de criação de assets.

🖌️

Krita

Nosso principal software para pintura digital e animação frame a frame. Usaremos para criar personagens, cenários e animações detalhadas.

Baixar Krita

✒️

Inkscape

O padrão ouro para arte vetorial. Perfeito para criar ícones de UI, logos ou assets com um estilo "clean" que podem ser redimensionados sem perder qualidade.

Baixar Inkscape

🧊

Blender

Um software 3D completo. Útil para criar modelos de referência, animar personagens para gerar spritesheets, ou até mesmo para criar efeitos visuais complexos.

Baixar Blender

🖼️

GIMP

Uma ferramenta poderosa para edição de imagem e manipulação. Ótimo para tarefas rápidas como cortar sprites, ajustar cores ou remover fundos.

Baixar GIMP

🚀3. Configuração do Ambiente (Primeiros Passos)

Para começar a trabalhar, a primeira coisa a fazer é configurar seu ambiente. Criamos um script que faz 99% do trabalho pesado para você.

Entendendo os Lançadores

Na pasta raiz do projeto, você encontrará alguns arquivos .bat. Eles são nossos atalhos automatizados:

setup_workspace.bat: Execute este primeiro e apenas uma vez. Ele verifica se você tem as ferramentas necessárias, baixa a versão exata da Godot que usamos e cria os outros atalhos. É a "chave de ignição" do projeto.
_ATUALIZAR_E_ABRIR.bat: Use este no dia a dia. Ele primeiro sincroniza seu projeto com as últimas mudanças do GitHub (git pull) e depois te dá a opção de abrir a Godot ou jogar.
_LANCADOR_AVANCADO.bat: Um atalho rápido para testar o jogo em diferentes modos (janela, tela cheia) ou simplesmente abrir o editor sem verificar por atualizações.

💾4. Como Usar o Git (Nosso Sistema de Salvamento)

O Git é como um "sistema de salvamento" superpoderoso para o nosso projeto. Ele rastreia cada mudança que fazemos. O GitHub é o "servidor na nuvem" onde guardamos a cópia principal do projeto.

Criando sua Conta no GitHub

Vá para github.com e clique em "Sign up".
Siga os passos para criar sua conta.

Ação Necessária: Compartilhe seu Usuário

Assim que sua conta for criada, nos envie seu nome de usuário (username). Nosso repositório é privado, então precisamos adicioná-lo manualmente como um colaborador para que você tenha acesso.

Nosso Workflow (Simples e Direto)

Sincronize (Pull): Antes de começar a trabalhar, sempre puxe as últimas alterações.
```
git pull origin main
```
Trabalhe e Faça Commits: Faça suas alterações. Quando terminar uma tarefa, salve seu progresso com um "commit".
```
git add .
git commit -m "Sua mensagem clara e curta aqui"
```
Envie (Push): Envie seus commits para o repositório principal, tornando-os disponíveis para todos.
```
git push origin main
```

🎲5. Entendendo a Godot (Nossa Engine)

A Filosofia: Nós e Cenas

A Godot é construída sobre um conceito simples e poderoso: tudo é uma cena, e toda cena é feita de nós. Pense nos nós como peças de Lego. Cada peça tem uma função específica:

Sprite2D: Uma peça para mostrar uma imagem.
AudioStreamPlayer: Uma peça para tocar um som.
CollisionShape2D: Uma peça (invisível) para definir a área de colisão de um objeto.
CharacterBody2D: Uma peça especial para objetos que serão controlados pelo jogador ou pela IA, com física embutida.

Uma cena é simplesmente um conjunto dessas peças de Lego que você agrupa para criar algo mais complexo. Por exemplo, a nossa cena player.tscn é um agrupamento de um CharacterBody2D, um AnimatedSprite2D (para as animações) e uma CollisionShape2D. Juntos, eles formam o nosso personagem jogável. Da mesma forma, um nível inteiro é uma cena que agrupa outras cenas (o player, os inimigos, as plataformas).

🧠6. A Arquitetura do Player (State Machine)

O movimento da nossa personagem é controlado por uma Máquina de Estados Finitos (State Machine). Pense nisso como o cérebro da borboleta: ela só pode estar em um "estado de espírito" de cada vez.

Por que isso é genial?

Isso mantém o código incrivelmente organizado. Cada estado (Parado, Andando, Pulando, Planando) tem seu próprio script com sua própria lógica. Se quisermos adicionar um novo comportamento, como "Nadar", não precisamos mexer no código de pulo; apenas criamos um novo script de estado. É um sistema à prova de futuro.

Como Funciona na Prática

O script principal player.gd é o "gerente". A cada frame, ele pergunta: "Qual é o nosso estado atual?". E então, ele executa o código daquele estado específico (ex: state_jump.gd`). Cada script de estado tem uma única responsabilidade: fazer a física daquele estado e verificar se é hora de mudar para outro (ex: se o personagem no estado `Pulando` toca o chão, ele transiciona para o estado `Parado`).


            Como Editar Parâmetros (Ex: Força do Pulo)
            
                Abra a cena do player: scenes/player.tscn.
                Selecione o nó raiz da cena (o nó Player).
                No painel Inspetor, você verá um grupo chamado "Movement Parameters". Ali, você
                    pode alterar valores como Jump Velocity, Move Speed e Gravity
                    sem tocar no código.

🖼️7. O Pipeline de Arte: Da Ideia ao Jogo

Este é o nosso workflow inicial para transformar uma criação artística em um elemento do jogo.

Criação e Digitalização: A ideia de um asset nasce no papel ou diretamente no Krita. Se for no papel, o desenho é escaneado ou fotografado em alta resolução para servir de base.
Exportação: O asset finalizado é exportado do Krita como um arquivo .png com fundo transparente. Respeite sempre a convenção de nomenclatura do Guia de Estilo.
Importação na Godot: Coloque o arquivo .png na pasta apropriada dentro de game/projeto-butterfly/assets/.
Implementação: Na engine, o asset é usado em um nó Sprite2D (para imagens estáticas) ou AnimatedSprite2D (para animações frame a frame), onde ele finalmente ganha vida.