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

DirAccess

Hereda: RefCounted < Object

Proporciona métodos para gestionar directorios y su contenido.

Descripción

Esta clase se utiliza para gestionar directorios y su contenido, incluso fuera de la carpeta del proyecto.

DirAccess no puede instanciarse directamente. En su lugar, se crea mediante un método estático que recibe la ruta que se desea abrir.

La mayoría de los métodos tienen una alternativa estática que se puede usar sin crear un DirAccess. Los métodos estáticos solo admiten rutas absolutas (incluyendo res:// y user://).

# Estándar
var dir = DirAccess.open("user://levels")
dir.make_dir("world1")
# Estático
DirAccess.make_dir_absolute("user://levels/world1")

Nota: Acceder a directorios del proyecto ("res://") una vez exportado puede comportarse de manera inesperada, ya que algunos archivos se convierten a formatos específicos del motor y sus archivos fuente originales pueden no estar presentes en el paquete PCK esperado. Por este motivo, para acceder a recursos en un proyecto exportado, se recomienda usar ResourceLoader en lugar de FileAccess.

A continuación, un ejemplo de cómo iterar los archivos de un directorio:

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("Directorio encontrado: " + file_name)
            else:
                print("Archivo encontrado: " + file_name)
            file_name = dir.get_next()
    else:
        print("Ocurrió un error al intentar acceder a la ruta.")

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($"Directorio encontrado: {fileName}");
            }
            else
            {
                GD.Print($"Archivo encontrado: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("Ocurrió un error al intentar acceder a la ruta.");
    }
}

Tenga en cuenta que los nombres de archivo pueden cambiar o reasignarse después de la exportación. Si desea ver la lista real de archivos de recursos tal como aparece en el editor, usa ResourceLoader.list_directory().

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_label(idx: int) 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 es 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 es 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) 🔗

Cambia el directorio abierto actualmente al que se pasa como argumento. El argumento puede ser relativo al directorio actual (por ejemplo, newdir o ../newdir), o una ruta absoluta (por ejemplo, /tmp/newdir o res://somedir/newdir).

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

Nota: El nuevo directorio debe estar dentro del mismo ámbito; por ejemplo, si habías abierto un directorio dentro de res://, no puedes cambiarlo al directorio user://. Si necesitas abrir un directorio en otro ámbito de acceso, utiliza open() para crear una nueva instancia en su lugar.

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

Copia el archivo from al destino to. Ambos argumentos deben ser rutas a archivos, ya sean relativas o absolutas. Si el archivo de destino existe y no está protegido contra escritura, se sobrescribirá.

Si chmod_flags es distinto de -1, los permisos de Unix para la ruta de destino se establecerán al valor proporcionado, siempre que esté disponible en el sistema operativo actual.

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

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 🔗

Crea un directorio temporal. Este directorio se eliminará cuando el DirAccess devuelto sea liberado.

Si prefix no está vacío, se antepondrá al nombre del directorio, separado por un -.

Si keep es true, el directorio no se eliminará cuando el DirAccess devuelto sea liberado.

Devuelve null si no se pudo abrir el directorio. Puede utilizarse get_open_error() para comprobar el error que se produjo.

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) 🔗

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

Para un equivalente estático, utiliza FileAccess.file_exists().

Nota: Muchos tipos de recursos se importan (por ejemplo, texturas o archivos de sonido) y su asset original no se incluirá en el juego exportado, ya que solo se utiliza la versión importada. Consulta ResourceLoader.exists() para un enfoque alternativo que tenga en cuenta el remapeo de recursos.

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_label(idx: int) static 🔗

En Windows, devuelve la etiqueta de la unidad (partición) pasada como argumento.

En otras plataformas, o si la unidad solicitada no existe, devuelve una cadena vacía.

String get_drive_name(idx: int) static 🔗

On Windows, returns the name of the drive (partition) passed as an argument (e.g. C:).

On macOS, returns the path to the mounted volume passed as an argument.

On Linux, returns the path to the mounted volume or GTK 3 bookmark passed as an argument.

On Android (API level 30+), returns the path to the mounted volume as an argument.

On other platforms, or if the requested drive does not exist, returns an empty String.

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.