DirAccess

Proporciona métodos para gestionar directorios y su contenido.

Descripción

This class is used to manage directories and their content, even outside of the project folder.

DirAccess can't be instantiated directly. Instead it is created with a static method that takes a path for which it will be opened.

Most of the methods have a static alternative that can be used without creating a DirAccess. Static methods only support absolute paths (including res:// and user://).

# Standard
var dir = DirAccess.open("user://levels")
dir.make_dir("world1")
# Static
DirAccess.make_dir_absolute("user://levels/world1")

Note: Accessing project ("res://") directories once exported may behave unexpectedly as some files are converted to engine-specific formats and their original source files may not be present in the expected PCK package. Because of this, to access resources in an exported project, it is recommended to use ResourceLoader instead of FileAccess.

Here is an example on how to iterate through the files of a directory:

func dir_contents(path):
    var dir = DirAccess.open(path)
    if dir:
        dir.list_dir_begin()
        var file_name = dir.get_next()
        while file_name != "":
            if dir.current_is_dir():
                print("Found directory: " + file_name)
            else:
                print("Found file: " + file_name)
            file_name = dir.get_next()
    else:
        print("An error occurred when trying to access the path.")

public void DirContents(string path)
{
    using var dir = DirAccess.Open(path);
    if (dir != null)
    {
        dir.ListDirBegin();
        string fileName = dir.GetNext();
        while (fileName != "")
        {
            if (dir.CurrentIsDir())
            {
                GD.Print($"Found directory: {fileName}");
            }
            else
            {
                GD.Print($"Found file: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("An error occurred when trying to access the path.");
    }
}

Keep in mind that file names may change or be remapped after export. If you want to see the actual resource file list as it appears in the editor, use ResourceLoader.list_directory() instead.

Tutoriales

Sistema de archivos

Propiedades

bool	include_hidden
bool	include_navigational

Métodos

Error	change_dir(to_dir: String)
Error	copy(from: String, to: String, chmod_flags: int = -1)
Error	copy_absolute(from: String, to: String, chmod_flags: int = -1) static
Error	create_link(source: String, target: String)
DirAccess	create_temp(prefix: String = "", keep: bool = false) static
bool	current_is_dir() const
bool	dir_exists(path: String)
bool	dir_exists_absolute(path: String) static
bool	file_exists(path: String)
String	get_current_dir(include_drive: bool = true) const
int	get_current_drive()
PackedStringArray	get_directories()
PackedStringArray	get_directories_at(path: String) static
int	get_drive_count() static
String	get_drive_name(idx: int) static
PackedStringArray	get_files()
PackedStringArray	get_files_at(path: String) static
String	get_filesystem_type() const
String	get_next()
Error	get_open_error() static
int	get_space_left()
bool	is_bundle(path: String) const
bool	is_case_sensitive(path: String) const
bool	is_equivalent(path_a: String, path_b: String) const
bool	is_link(path: String)
Error	list_dir_begin()
void	list_dir_end()
Error	make_dir(path: String)
Error	make_dir_absolute(path: String) static
Error	make_dir_recursive(path: String)
Error	make_dir_recursive_absolute(path: String) static
DirAccess	open(path: String) static
String	read_link(path: String)
Error	remove(path: String)
Error	remove_absolute(path: String) static
Error	rename(from: String, to: String)
Error	rename_absolute(from: String, to: String) static

Descripciones de Propiedades

bool include_hidden 🔗

void set_include_hidden(value: bool)
bool get_include_hidden()

Si true, los archivos ocultos se incluyen al navegar por el directorio.

Afecta a list_dir_begin(), get_directories() y get_files().

bool include_navigational 🔗

void set_include_navigational(value: bool)
bool get_include_navigational()

Si true, . y .. se incluyen al navegar por el directorio.

Afecta a list_dir_begin() y get_directories().

Descripciones de Métodos

Error change_dir(to_dir: String) 🔗

Changes the currently opened directory to the one passed as an argument. The argument can be relative to the current directory (e.g. newdir or ../newdir), or an absolute path (e.g. /tmp/newdir or res://somedir/newdir).

Returns one of the Error code constants (@GlobalScope.OK on success).

Note: The new directory must be within the same scope, e.g. when you had opened a directory inside res://, you can't change it to user:// directory. If you need to open a directory in another access scope, use open() to create a new instance instead.

Error copy(from: String, to: String, chmod_flags: int = -1) 🔗

Copies the from file to the to destination. Both arguments should be paths to files, either relative or absolute. If the destination file exists and is not access-protected, it will be overwritten.

If chmod_flags is different than -1, the Unix permissions for the destination path will be set to the provided value, if available on the current operating system.

Returns one of the Error code constants (@GlobalScope.OK on success).

Error copy_absolute(from: String, to: String, chmod_flags: int = -1) static 🔗

Versión estática de copy(). Solo admite rutas absolutas.

Error create_link(source: String, target: String) 🔗

Crea un enlace simbólico entre archivos o carpetas.

Nota: En Windows, este método solo funciona si la aplicación se está ejecutando con privilegios elevados o el Modo Desarrollador está habilitado.

Nota: Este método está implementado en macOS, Linux y Windows.

DirAccess create_temp(prefix: String = "", keep: bool = false) static 🔗

Creates a temporary directory. This directory will be freed when the returned DirAccess is freed.

If prefix is not empty, it will be prefixed to the directory name, separated by a -.

If keep is true, the directory is not deleted when the returned DirAccess is freed.

Returns null if opening the directory failed. You can use get_open_error() to check the error that occurred.

bool current_is_dir() const 🔗

Devuelve si el objeto actual procesado con la última llamada a get_next() es un directorio. . y .. son considerados directorios.

bool dir_exists(path: String) 🔗

Devuelve si el directorio de destino existe. El argumento puede ser relativo al directorio actual, o una ruta absoluta.

Nota: El bool devuelto en el editor y después de la exportación cuando se usa en una ruta en el directorio res:// puede ser diferente. Algunos archivos se convierten a formatos específicos del motor cuando se exportan, lo que puede cambiar la estructura del directorio.

bool dir_exists_absolute(path: String) static 🔗

Versión estática de dir_exists(). Solo admite rutas absolutas.

Nota: El bool devuelto en el editor y después de la exportación cuando se usa en una ruta en el directorio res:// puede ser diferente. Algunos archivos se convierten a formatos específicos del motor cuando se exportan, lo que puede cambiar la estructura del directorio.

bool file_exists(path: String) 🔗

Returns whether the target file exists. The argument can be relative to the current directory, or an absolute path.

For a static equivalent, use FileAccess.file_exists().

Note: Many resources types are imported (e.g. textures or sound files), and their source asset will not be included in the exported game, as only the imported version is used. See ResourceLoader.exists() for an alternative approach that takes resource remapping into account.

String get_current_dir(include_drive: bool = true) const 🔗

Devuelve la ruta absoluta del directorio abierto actualmente (por ejemplo, res://folder o C:\tmp\folder).

int get_current_drive() 🔗

Devuelve el índice de la unidad del directorio abierto actualmente. Véase get_drive_name() para convertir el índice devuelto al nombre de la unidad.

PackedStringArray get_directories() 🔗

Devuelve un PackedStringArray que contiene los nombres de archivo del contenido del directorio, excluyendo los archivos. El array está ordenado alfabéticamente.

Afectado por include_hidden y include_navigational.

Nota: Los directorios devueltos en el editor y después de la exportación en el directorio res:// pueden diferir, ya que algunos archivos se convierten a formatos específicos del motor cuando se exportan.

PackedStringArray get_directories_at(path: String) static 🔗

Devuelve un PackedStringArray que contiene nombres de archivos del contenido del directorio, excluyendo archivos, en la path dada. El array se ordena alfabéticamente.

Usa get_directories() si quieres más control sobre lo que se incluye.

Nota: Los directorios devueltos en el editor y después de la exportación en el directorio res:// pueden diferir, ya que algunos archivos se convierten a formatos específicos del motor cuando se exportan.

int get_drive_count() static 🔗

En Windows, devuelve el número de unidades (particiones) montadas en el sistema de archivos actual.

En macOS y Android, devuelve el número de volúmenes montados.

En Linux, devuelve el número de volúmenes montados y los marcadores de GTK 3.

En otras plataformas, el método devuelve 0.

String get_drive_name(idx: int) static 🔗

En Windows, devuelve el nombre de la unidad (partición) pasada como argumento (p. ej. C:).

En macOS, devuelve la ruta al volumen montado pasado como argumento.

En Linux, devuelve la ruta al volumen montado o al marcador de GTK 3 pasado como argumento.

En Android (API nivel 30+), devuelve la ruta al volumen montado como argumento.

En otras plataformas, o si la unidad solicitada no existe, el método devuelve una String vacía.

PackedStringArray get_files() 🔗

Returns a PackedStringArray containing filenames of the directory contents, excluding directories. The array is sorted alphabetically.

Affected by include_hidden.

Note: When used on a res:// path in an exported project, only the files actually included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level .godot/ folder, only paths to *.gd and *.import files are returned (plus a few files such as project.godot or project.binary and the project icon). In an exported project, the list of returned files will also vary depending on whether ProjectSettings.editor/export/convert_text_resources_to_binary is true.

PackedStringArray get_files_at(path: String) static 🔗

Returns a PackedStringArray containing filenames of the directory contents, excluding directories, at the given path. The array is sorted alphabetically.

Use get_files() if you want more control of what gets included.

Note: When used on a res:// path in an exported project, only the files included in the PCK at the given folder level are returned. In practice, this means that since imported resources are stored in a top-level .godot/ folder, only paths to .gd and .import files are returned (plus a few other files, such as project.godot or project.binary and the project icon). In an exported project, the list of returned files will also vary depending on ProjectSettings.editor/export/convert_text_resources_to_binary.

String get_filesystem_type() const 🔗

Devuelve el nombre del tipo de sistema de archivos del disco del directorio actual. Los valores devueltos son cadenas de texto en mayúsculas como NTFS, FAT32, EXFAT, APFS, EXT4, BTRFS, y así sucesivamente.

Nota: Este método está implementado en macOS, Linux, Windows y para el sistema de archivos virtual PCK.

String get_next() 🔗

Devuelve el siguiente elemento (archivo o directorio) en el directorio actual.

Se devuelve el nombre del archivo o directorio (y no su ruta completa). Una vez que la secuencia se ha procesado completamente, el método devuelve una string vacía y cierra la secuencia automáticamente (es decir, list_dir_end() no sería obligatorio en tal caso).

Error get_open_error() static 🔗

Devuelve el resultado de la última llamada a open() en el hilo actual.

int get_space_left() 🔗

Devuelve el espacio disponible en el disco del directorio actual, en bytes. Devuelve 0 si el método específico de la plataforma para consultar el espacio disponible falla.

bool is_bundle(path: String) const 🔗

Devuelve true si el directorio es un paquete de macOS.

Nota: Este método está implementado en macOS.

bool is_case_sensitive(path: String) const 🔗

Devuelve true si el sistema de archivos o el directorio utilizan nombres de archivo que distinguen entre mayúsculas y minúsculas.

Nota: Este método está implementado en macOS, Linux (solo para sistemas de archivos EXT4 y F2FS) y Windows. En otras plataformas, siempre devuelve true.

bool is_equivalent(path_a: String, path_b: String) const 🔗

Devuelve true si las rutas path_a y path_b se resuelven en el mismo objeto del sistema de archivos. Devuelve false en caso contrario, incluso si los archivos son idénticos bit a bit (por ejemplo, copias idénticas del archivo que no son enlaces simbólicos).

bool is_link(path: String) 🔗

Devuelve true si el archivo o directorio es un enlace simbólico, una unión de directorio u otro punto de reanálisis.

Nota: Este método está implementado en macOS, Linux y Windows.

Error list_dir_begin() 🔗

Inicializa el flujo usado para listar todos los archivos y directorios usando la función get_next(), cerrando el flujo abierto actual si es necesario. Una vez que el flujo ha sido procesado, típicamente debería ser cerrado con list_dir_end().

Afectado por include_hidden y include_navigational.

Nota: El orden de los archivos y directorios devueltos por este método no es determinístico y puede variar entre sistemas operativos. Si quieres una lista de todos los archivos o carpetas ordenados alfabéticamente, usa get_files() o get_directories().

void list_dir_end() 🔗

Cierra el flujo actual abierto con list_dir_begin() (no importa si se ha procesado completamente con get_next() o no).

Error make_dir(path: String) 🔗

Crea un directorio. El argumento puede ser relativo al directorio actual o una ruta absoluta. El directorio de destino debe ubicarse en un directorio ya existente (para crear la ruta completa recursivamente, Véase make_dir_recursive()).

Devuelve una de las constantes de código Error (@GlobalScope.OK en caso de éxito).

Error make_dir_absolute(path: String) static 🔗

Versión estática de make_dir(). Solo admite rutas absolutas.

Error make_dir_recursive(path: String) 🔗

Crea un directorio de destino y todos los directorios intermedios necesarios en su ruta, llamando a make_dir() recursivamente. El argumento puede ser relativo al directorio actual, o una ruta absoluta.

Devuelve una de las constantes de código de Error (@GlobalScope.OK en caso de éxito).

Error make_dir_recursive_absolute(path: String) static 🔗

Versión estática de make_dir_recursive(). Solo admite rutas absolutas.

DirAccess open(path: String) static 🔗

Crea un nuevo objeto DirAccess y abre un directorio existente del sistema de archivos. El argumento path puede estar dentro del árbol del proyecto (res://folder), el directorio de usuario (user://folder) o una ruta absoluta del sistema de archivos de usuario (por ejemplo, /tmp/folder o C:\tmp\folder).

Devuelve null si falló la apertura del directorio. Puedes usar get_open_error() para verificar el error ocurrido.

String read_link(path: String) 🔗

Devuelve el destino del enlace simbólico.

Nota: Este método está implementado en macOS, Linux y Windows.

Error remove(path: String) 🔗

Elimina permanentemente el archivo de destino o un directorio vacío. El argumento puede ser relativo al directorio actual o una ruta absoluta. Si el directorio de destino no está vacío, la operación fallará.

Si no desea eliminar el archivo o directorio permanentemente, utiliza OS.move_to_trash().

Devuelve una de las constantes de código Error, (@GlobalScope.OK en caso de éxito).

Error remove_absolute(path: String) static 🔗

Versión estática de remove(). Solo admite rutas absolutas.

Error rename(from: String, to: String) 🔗

Renombra (mueve) el archivo o directorio from al destino to. Ambos argumentos deben ser rutas a archivos o directorios, ya sean relativas o absolutas. Si el archivo o directorio de destino existe y no está protegido contra el acceso, será sobrescrito.

Devuelve una de las constantes del código Error (@GlobalScope.OK en caso de éxito).

Error rename_absolute(from: String, to: String) static 🔗

Versión estática de rename(). Solo admite rutas absolutas.