Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Sistema de arquivos

Introdução

O sistema de arquivos gerencia como os assets são armazenados e como são acessados. Um sistema de arquivos bem projetado também permite que vários desenvolvedores editem os mesmos arquivos fonte e assets enquanto colaboram. O Godot guarda todos os assets como arquivos em seu sistema de arquivos.

Implementação

O sistema de arquivos armazena recursos no disco. Qualquer coisa, desde um roteiro até uma cena ou uma imagem PNG, é um recurso para o motor. Se um recurso contiver propriedades que fazem referência a outros recursos no disco, os caminhos para esses recursos também serão incluídos. Se um recurso tiver sub-recursos embutidos, ele será salvo em um único arquivo junto com todos os sub-recursos inclusos. Por exemplo, um recurso de fonte geralmente é empacotado junto com as texturas de fonte.

O sistema de arquivos do Godot evita o uso de arquivos de metadados. Gerenciadores de ativos e VCSs existentes são melhores do que qualquer coisa que possamos implementar, então o Godot faz o seu melhor para trabalhar em conjunto com Subversion, Git, Mercurial, etc.

Exemplo de conteúdo do sistema de arquivos:

/project.godot
/enemy/enemy.tscn
/enemy/enemy.gd
/enemy/enemysprite.png
/player/player.gd

project.godot

O arquivo project.godot é o arquivo de descrição do projeto e encontra-se sempre na raiz do projeto. Na verdade, sua localização define onde fica a raiz. Esse é o primeiro arquivo que o Godot procura ao abrir um projeto.

Este arquivo contém a configuração do projeto em texto simples, usando o formato win.ini. Até mesmo um project.godot vazio pode funcionar como uma definição básica de um projeto em branco.

Delimitador de caminho

Godot suporta apenas / como um delimitador de caminho. Isso é feito por razões de portabilidade. Todos os sistemas operacionais suportam isto, mesmo o Windows, então um caminho como c:\project\project.godot precisa ser digitado como c:/project/project.godot.

Caminho de recursos

Ao acessar recursos, usar o layout do sistema de arquivos do sistema operacional da máquina pode ser incômodo e não portátil. Para resolver este problema, o caminho especial res:// foi criado.

O caminho res:// sempre apontará para a raiz do projeto (onde project.godot está localizado, então res://project.godot é sempre válido).

Este sistema de arquivos é para leitura e escrita somente quando se executa o projeto localmente a partir do editor. Quando exportado ou quando executado em dispositivos diferentes (como em telefones ou consoles ou executando a partir de DVD), o sistema de arquivos se tornará somente leitura e a gravação não será mais permitida.

Caminho do usuário

Gravar em disco ainda é necessário para tarefas como salvar o estado do jogo ou baixar pacotes de conteúdo adicional. Para isso, o motor garante um caminho especial user:// que é sempre gravável. A resolução desse caminho é diferente dependendo do SO no qual ele está sendo executado. Resolução de caminhos locais é explicada com mais detalhes em Caminhos de arquivos em projetos Godot.

Sistema de arquivos da máquina

Alternativamente, os caminhos do sistema de arquivos da máquina também podem ser usados, mas isso não é recomendado para um produto a ser lançado, já que esses caminhos não têm garantia de funcionar em todas as plataformas. No entanto, o uso de caminhos do sistema de arquivos da máquina pode ser útil ao escrever ferramentas de desenvolvimento no Godot.

Desvantagens

Existem algumas desvantagens neste design de sistema de arquivos. O primeiro problema é que mover ativos (renomeá-los ou movê-los de um caminho para outro dentro do projeto) quebrará as referências existentes a esses ativos. Essas referências terão que ser redefinidas para apontar para o novo local do ativo.

Para evitar isso, faça todas as suas operações de mover, excluir e renomear dentro do Godot, na doca Sistema de Arquivos (FileSystem). Quando você exclui arquivos no Godot, ele solicitará uma caixa de diálogo de confirmação listando todos os arquivos selecionados e quaisquer cenas que dependam desses arquivos. Nunca mova ativos de fora do Godot, ou as dependências terão que ser corrigidas manualmente (o Godot detecta isso e ajuda você a corrigi-las de qualquer maneira, mas por que seguir o caminho difícil?).

A segunda é que, no Windows e no macOS, os nomes dos arquivos e dos caminhos não diferenciam letras maiúsculas de minúsculas. Se um desenvolvedor que trabalha em uma máquina com sistema de arquivos insensível a maiúsculas e minúsculas salvar um asset como meuarquivo.PNG, mas o referencia como meuarquivo.png, ele funcionará bem em sua plataforma, mas não em outras plataformas, como Linux, Android, etc. Isso também pode se aplicar aos binários exportados, que usam um pacote compactado para armazenar todos os arquivos.

Recomenda-se que sua equipe defina claramente uma convenção de nomenclatura para arquivos ao trabalhar com Godot. Uma convenção infalível é permitir apenas nomes de arquivos e caminhos em letras minúsculas.