Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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.

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://)

To store persistent data files, like the player's save or settings, you want to use user:// instead of res:// as your path's prefix. This is because when the game is running, the project's file system will likely be read-only.

The user:// prefix points to a different directory on the user's device. Unlike res://, the directory pointed at by user:// is created automatically and guaranteed to be writable to, even in an exported project.

The location of the user:// folder depends on what is configured in the Project Settings:

  • By default, the user:// folder is created within Godot's editor data path in the app_userdata/[project_name] folder. This is the default so that prototypes and test projects stay self-contained within Godot's data folder.

  • If application/config/use_custom_user_dir is enabled in the Project Settings, the user:// folder is created next to Godot's editor data path, i.e. in the standard location for applications data.

    • By default, the folder name will be inferred from the project name, but it can be further customized with application/config/custom_user_dir_name. This path can contain path separators, so you can use it e.g. to group projects of a given studio with a Studio Name/Game Name structure.

On desktop platforms, the actual directory paths for user:// are:

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]

[project_name] is based on the application name defined in the Project Settings, but you can override it on a per-platform basis using feature tags.

On mobile platforms, this path is unique to the project and is not accessible by other applications for security reasons.

On HTML5 exports, user:// will refer to a virtual filesystem stored on the device via IndexedDB. (Interaction with the main filesystem can still be performed through the JavaScriptBridge singleton.)

Converting paths to absolute paths or "local" paths

You can use ProjectSettings.globalize_path() to convert a "local" path like res://path/to/file.txt to an absolute OS path. For example, ProjectSettings.globalize_path() can be used to open "local" paths in the OS file manager using OS.shell_open() since it only accepts native OS paths.

To convert an absolute OS path to a "local" path starting with res:// or user://, use ProjectSettings.localize_path(). This only works for absolute paths that point to files or folders in your project's root or user:// folders.

Caminhos de dados do editor

The editor uses different paths for editor data, editor settings, and cache, depending on the platform. By default, these paths are:

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.

Godot está em conformidade com a Especificação de Diretório Base XDG em todas as plataformas. Você pode substituir as variáveis de ambiente seguindo a especificação para alterar o editor e os caminhos de dados 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

Se você criar um arquivo chamado ._sc_ ou _sc_ no mesmo diretório que o binário do editor (ou em MacOS/Contents/ para um pacote do editor do macOS .app), Godot irá habilitar self-contained mode. Este modo faz Godot escrever todos os dados do editor, configurações e cache para um diretório chamado ``editor_data/` no mesmo diretório que o editor binário. Você pode usá-lo para criar uma instalação portátil do 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).