Como Organizar um Projeto Godot: Estrutura de Pastas Que Escala

Todo projeto começa igual: meia dúzia de arquivos na raiz, player.tscn do lado de teste_final2.gd, e tudo funciona. Três meses depois são 300 arquivos, você gasta mais tempo procurando sprite do que fazendo jogo, e mover qualquer coisa de lugar é roleta russa. Organizar um projeto Godot não é capricho de programador arrumadinho: é infraestrutura. Esse guia mostra uma estrutura de pastas que escala, as convenções de nome que a própria documentação da Godot recomenda e as regras práticas pra bagunça não voltar.

Por que projeto desorganizado mata jogo

A desorganização cobra em três parcelas, e a última é a mais cara.

Primeiro, você para de achar as coisas. Cada "onde eu salvei aquele som de pulo?" custa dois minutos. Parece pouco, mas acontece dezenas de vezes por sessão, e cada interrupção dessas tira você do fluxo. O custo real não é o tempo de procurar, é o raciocínio que se perde no meio.

Segundo, mover arquivo quebra referência. Cenas (.tscn) e recursos (.tres) guardam os caminhos dos arquivos de que dependem, tipo res://sprites/slime.png. Se você arrasta esse PNG pra outra pasta pelo explorador do sistema, a Godot não fica sabendo, e na próxima vez que abrir o projeto vai te receber com aviso de dependências quebradas. Em projeto bagunçado, ninguém move nada por medo, e a bagunça se torna permanente.

Terceiro, o projeto morre no HD. É a soma das duas anteriores. Cada sessão começa com atrito, o atrito vira desânimo, o intervalo entre as sessões aumenta, e num certo ponto você nem lembra mais como o projeto funciona por dentro. Poucos jogos indie morrem por falta de talento; a maioria morre por atrito acumulado.

As duas filosofias de estrutura de pastas no Godot

Existem basicamente duas escolas pra estruturar o res://, e vale conhecer as duas antes de escolher.

Organização por tipo agrupa os arquivos pelo formato deles:

res://
├── scenes/
│   ├── player.tscn
│   ├── slime.tscn
│   └── main_menu.tscn
├── scripts/
│   ├── player.gd
│   ├── slime.gd
│   └── main_menu.gd
├── sprites/
│   ├── player.png
│   └── slime.png
└── audio/
    ├── jump.wav
    └── menu_theme.ogg

É a estrutura que quase todo iniciante cria por instinto, e ela até funciona em projeto pequeno. O problema aparece quando o jogo cresce: pra mexer no slime, você abre scenes/, depois scripts/, depois sprites/. Uma feature fica espalhada em quatro pastas, e cada pasta vira um saco com dezenas de arquivos de features diferentes misturados.

Organização por feature agrupa por parte do jogo:

res://
├── player/
│   ├── player.tscn
│   ├── player.gd
│   └── player.png
├── enemies/
│   ├── slime/
│   │   ├── slime.tscn
│   │   ├── slime.gd
│   │   └── slime.png
│   └── bat/
├── levels/
│   └── level_01/
├── ui/
│   └── main_menu/
│       ├── main_menu.tscn
│       ├── main_menu.gd
│       └── menu_theme.ogg
├── autoload/
└── shared/

Minha recomendação honesta: por feature, sem drama. O motivo é um princípio simples: tudo que muda junto fica junto. Quando você mexe no slime, a cena, o script e o sprite mudam juntos, então devem morar juntos. Quer apagar o slime do jogo? Apaga uma pasta e acabou, sem caçar arquivo órfão em scripts/ e sprites/. Quer levar o player pra um protótipo novo? Copia uma pasta. A estrutura por tipo responde "que formato esse arquivo tem", uma pergunta que você nunca faz. A por feature responde "de que parte do jogo isso é", a pergunta que você faz o tempo todo.

A exceção justa: em game jam ou protótipo de fim de semana com 20 arquivos, qualquer estrutura serve, e por tipo não atrapalha. Mas se o projeto tem ambição de virar jogo de verdade, comece por feature. Migrar depois custa muito mais caro.

As convenções de nome que a Godot recomenda de verdade

Isso não é opinião minha: está na documentação oficial de estilo da engine.

Arquivos e pastas em snake_case: tudo minúsculo, palavras separadas por underscore. player_controller.gd, main_menu.tscn, slime_idle.png. A razão é prática, não estética: Windows trata Player.tscn e player.tscn como o mesmo arquivo, Linux trata como dois arquivos diferentes. Um projeto com maiúsculas misturadas pode funcionar na sua máquina e quebrar na exportação ou na máquina de outra pessoa. Minúsculo em tudo elimina essa classe inteira de problema.

Nós e class_name em PascalCase: cada palavra com inicial maiúscula, seguindo as classes da própria engine (CharacterBody2D, AnimationPlayer). Ou seja, o arquivo player_controller.gd declara a classe PlayerController:

# player_controller.gd
class_name PlayerController
extends CharacterBody2D

@export var speed: float = 220.0
@export var jump_force: float = 480.0

E a regra que importa mais que qualquer outra: consistência vale mais que a convenção escolhida. Se o seu projeto já tem 200 arquivos em outro padrão, padronizar tudo de uma vez é receita de referência quebrada. Adote a convenção nos arquivos novos e renomeie os antigos aos poucos, sempre pelo editor.

Autoloads, recursos compartilhados e a pasta addons

Três casos não pertencem a nenhuma feature específica e merecem um lugar próprio.

Autoloads e singletons vão numa pasta autoload/ na raiz (ou globals/, os dois nomes são comuns na comunidade). São os scripts registrados nas configurações do projeto pra existirem durante o jogo inteiro: estado global, gerenciador de áudio, sistema de save. Ter todos num lugar só deixa explícito o que é global no seu projeto, e isso importa porque autoload demais é cheiro de arquitetura ruim. Se o tema é novo pra você, o guia de autoloads na Godot explica quando usar e quando evitar.

Recursos compartilhados vão em shared/ (ou common/): a fonte usada no jogo inteiro, a paleta de cores, shaders genéricos, sons de interface. A regra de bolso: se duas ou mais features usam, o arquivo sobe pra shared/. Se só uma usa, fica na pasta da feature.

A pasta addons/ é território da engine: é onde os plugins baixados da Asset Library são instalados. Não guarde os seus arquivos lá dentro. Misturar código seu com plugin de terceiro torna impossível atualizar ou remover o plugin depois sem medo de perder alguma coisa junto.

Mova arquivo sempre dentro do editor

Essa regra sozinha paga o artigo: renomeie e mova arquivos pelo FileSystem dock, dentro do editor da Godot, nunca pelo explorador do sistema.

Quando você arrasta um arquivo de uma pasta pra outra no FileSystem dock, a engine varre as cenas e os recursos que apontam pra ele e atualiza os caminhos. Mover slime.png de lugar atualiza a referência dentro de slime.tscn automaticamente. Fazendo o mesmo no Explorer do Windows, a Godot só descobre depois do fato, e aí é você quem conserta dependência quebrada na mão, arquivo por arquivo.

Um detalhe das versões recentes: a partir do Godot 4.4, scripts e shaders ganham um arquivo .uid do lado (player.gd.uid). É um identificador único que ajuda a engine a manter as referências mesmo quando caminhos mudam. Esses arquivos vão pro repositório junto com o código, e se algum dia você mover algo por fora do editor, mova o .uid junto.

O .gitignore essencial do Godot 4

Projeto de jogo sem controle de versão é projeto com prazo de validade, então assumo que o seu está no Git. O que muita gente erra é o que versionar. No Godot 4, a regra número um: a pasta .godot/ nunca vai pro repositório. Ela é cache gerado pela engine, com os assets importados e metadados do editor, e é recriada do zero em qualquer máquina que abrir o projeto. Versionar a .godot/ incha o repositório e gera conflito de merge em arquivo que nem é seu.

Um .gitignore mínimo e suficiente pra começar:

# cache gerado pela engine, recriado automaticamente
.godot/

# credenciais de exportação (senhas de keystore etc.)
export_credentials.cfg

# builds exportadas
build/

E um aviso sobre assets grandes: Git não foi feito pra binário pesado. Sprite e som pequenos tudo bem, mas vídeo, PSD gigante e áudio sem compressão degradam o repositório rápido. A solução padrão é o Git LFS, e o guia de controle de versão pra jogos com Git e LFS mostra a configuração completa pra Godot.

Checklist pra começar organizado

Pra fechar, o roteiro que eu sigo em todo projeto novo, na ordem:

• Criar o projeto e, antes de qualquer cena, o .gitignore com a .godot/ ignorada
• Fazer o primeiro commit só com a estrutura, pra ter um ponto de partida limpo
• Criar as pastas raiz: uma por feature inicial (player/, levels/, ui/), mais autoload/ e shared/
• Decidir a convenção de nomes (snake_case em arquivo e pasta, PascalCase em nó e class_name) e anotar num README curto
• Toda feature nova nasce como pasta própria, com cena, script e assets juntos
• Asset usado por duas ou mais features sobe pra shared/
• Renomear e mover sempre pelo FileSystem dock, nunca pelo explorador
• Revisar a estrutura a cada marco do projeto: pasta que virou saco de gatos é sinal de feature que merece subpastas

Nada disso exige ferramenta nova nem plugin: é decisão tomada cedo e mantida com disciplina. Estrutura de pastas é daquelas coisas que ninguém elogia quando está certa, mas que decide se o seu projeto sobrevive ao mês três. E se você está montando essa base agora e quer aprender a engine com método em vez de tutorial solto, veja o guia do melhor curso de Godot pra entender como o CursoGame.Dev estrutura esse caminho do zero ao jogo publicado.