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...

Caminhos de arquivos em projetos Godot

Esta página explica como os caminhos de arquivo funcionam dentro dos projetos Godot. Você aprenderá como acessar caminhos em seus projetos usando as notações res:// e user://, e onde o Godot armazena arquivos de projeto e editor em seus sistemas e nos sistemas de seus usuários.

Separadores de caminho

Para facilitar o suporte a várias plataformas, Godot usa separadores de caminho no estilo UNIX (barra /). Eles funcionam em todas as plataformas, incluindo Windows.

Em vez de escrever caminhos como C:\Projetos\Jogo, no Godot, você deve escrever C:/Projetos/Jogo.

Separadores de caminho no estilo do Windows (barra invertida \) também são suportados em alguns métodos relacionados a caminhos, mas precisam ser duplicados (\\), pois \ é normalmente usado como um escape para caracteres com um significado especial.

Isso possibilita trabalhar com caminhos retornados por outros aplicativos do Windows. Ainda recomendamos usar apenas barras (e não barra invertida) em seu próprio código para garantir que tudo funcione conforme o esperado.

Dica

A classe String oferece mais de uma dúzia de métodos para trabalhar com strings que representam caminhos de arquivos:

• String.filecasecmp_to()

• String.filenocasecmp_to()

• String.get_base_dir()

• String.get_basename()

• String.get_extension()

• String.get_file()

• String.is_absolute_path()

• String.is_relative_path()

• String.is_valid_filename()

• String.path_join()

• String.simplify_path()

• String.validate_filename()

Acessando arquivos na pasta do projeto (res://)

Godot considera que existe um projeto em qualquer pasta que contenha um arquivo de texto project.godot, mesmo que o arquivo esteja vazio. A pasta que contém este arquivo é a pasta raiz do seu projeto.

Você pode acessar qualquer arquivo relativo a ele escrevendo caminhos começando com res://, que significa recursos. Por exemplo, você pode acessar um arquivo de imagem character.png localizado na pasta raiz do projeto no código com o seguinte caminho: res://character.png.

Acessando dados persistentes dos usuários (user://)

Para armazenar arquivos de dados persistentes, como o salvamento do jogador ou as configurações, você deve usar user:// em vez de res:// como prefixo do seu caminho. Isso ocorre porque, quando o jogo está rodando, o sistema de arquivos do projeto provavelmente será apenas de leitura.

O prefixo user:// aponta para um diretório diferente no dispositivo do usuário. Ao contrário de res://, o diretório apontado por user:// é criado automaticamente e tem escrita garantida, mesmo em um projeto exportado.

A localização da pasta user:// depende do que está configurado nas Configurações do Projeto:

• Por padrão, a pasta user:// é criada dentro do caminho de dados do editor do Godot, na pasta app_userdata/[nome_do_projeto]. Esse é o padrão para que protótipos e projetos de teste fiquem autocontidos na pasta de dados do Godot.

• Se application/config/use_custom_user_dir estiver ativado nas Configurações do Projeto, a pasta user:// será criada ao lado do caminho de dados do editor do Godot, ou seja, no local padrão para dados de aplicativos.

  • Por padrão, o nome da pasta será deduzido do nome do projeto, mas pode ser customizado ainda mais com application/config/custom_user_dir_name. Esse caminho pode conter separadores de caminho, de modo que você pode usá-lo, por exemplo, para agrupar projetos de um determinado estúdio com uma estrutura Nome do Estudio/Nome do Jogo.

Em plataformas desktop, os caminhos reais dos diretórios para user:// são:

Tipo	Localização
Padrão	Windows: %APPDATA%\Godot\app_userdata\[project_name] macOS: ~/Library/Application Support/Godot/app_userdata/[project_name] Linux: ~/.local/share/godot/app_userdata/[project_name]
Diretório personalizado	Windows: %APPDATA%\[project_name] macOS: ~/Library/Application Support/[project_name] Linux: ~/.local/share/[project_name]
Diretório e nome personalizados	Windows: %APPDATA%\[custom_user_dir_name] macOS: ~/Library/Application Support/[usuario_personalizado_dir_nome] Linux: ~/.local/share/[custom_user_dir_name]

[nome_do_projeto] é baseado no nome do aplicativo definido nas Configurações do Projeto, mas você pode sobrescrevê-lo para cada plataforma usando tags de recursos.

Em plataformas móveis, esse caminho é exclusivo do projeto e não pode ser acessado por outros aplicativos por motivos de segurança.

Nas exportações HTML5, user:// se referirá a um sistema de arquivos virtual armazenado no dispositivo via IndexedDB. (A interação com o sistema de arquivos principal ainda pode ser realizada através do singleton JavaScriptBridge.)

Registro em arquivo

Ver também

A documentação sobre registro em arquivo foi movida para Log.

Convertendo caminhos para caminhos absolutos ou caminhos "locais"

Você pode usar ProjectSettings.globalize_path() para converter um caminho "local" como res://caminho/para/arquivo.txt para um caminho absoluto do SO. Por exemplo, ProjectSettings.globalize_path() pode ser usado para abrir caminhos "locais" no gerenciador de arquivos do SO usando OS.shell_open(), já que ele aceita apenas caminhos nativos do SO.

Para converter um caminho absoluto do SO para um caminho "local" começando com res:// ou user://, use ProjectSettings.localize_path(). Isso só funciona para caminhos absolutos que apontam para arquivos ou pastas na raiz do seu projeto ou nas pastas user://.

Caminhos de dados do editor

O editor usa caminhos diferentes para dados do editor, configurações do editor e cache, dependendo da plataforma. Por padrão, esses caminhos são:

Tipo	Localização
Dados do editor	Windows: %APPDATA%\Godot\ macOS: ~/Library/Application Support/Godot/ Linux: ~/.local/share/godot/
Opções do editor	Windows: %APPDATA%\Godot\ macOS: ~/Library/Application Support/Godot/ Linux: ~/.config/godot/
Cache	Windows: %TEMP%\Godot\ macOS: ~/Library/Caches/Godot/ Linux: ~/.cache/godot/

• Editor data contém modelos de exportação e dados específicos do projeto.

• Editor settings contém o arquivo de configuração principal do editor, bem como várias outras personalizações específicas do usuário (layouts do editor, perfis de recursos, modelos de script, etc.).

• Cache contém dados gerados pelo editor ou armazenados temporariamente. Ele pode ser removido com segurança quando o Godot for fechado.

O Godot está em conformidade com a Especificação XDG Base Directory em Linux/*BSD. Você pode substituir as variáveis de ambiente XDG_DATA_HOME, XDG_CONFIG_HOME e XDG_CACHE_HOME para alterar os caminhos de dados do editor e do projeto.

Nota

Se você usar Godot empacotado como um Flatpak, os caminhos de dados do editor estarão localizados em subpastas em ~/.var/app/ org.godotengine.Godot/.

Modo autocontido

If you create a file called ._sc_ or _sc_ in the same directory as the editor binary (or in MacOS/Contents/ for a macOS editor .app bundle), Godot will enable self-contained mode. This mode makes Godot write all editor data, settings, and cache to a directory named editor_data/ in the same directory as the editor binary. You can use it to create a portable installation of the editor.

A versão Steam do Godot usa o modo independente por padrão.

Nota

O modo independente ainda não é suportado em projetos exportados. Para ler e gravar arquivos relativos ao caminho executável, use OS.get_executable_path(). Observe que gravar arquivos no caminho executável só funciona se o executável for colocado em um local gravável (ou seja, não Arquivos de Programas ou outro diretório somente leitura para usuários regulares).