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

Eredita: RefCounted < Object

Fornisce metodi per gestire le cartelle e il loro contenuto.

Descrizione

Questa classe serve per gestire le cartelle (directory) e il loro contenuto, anche al di fuori della cartella del progetto.

DirAccess non può essere istanziato direttamente. Invece viene creato con un metodo statico che accetta un percorso per il quale verrà aperto.

La maggior parte dei metodi ha un'alternativa statica che si può utilizzare senza creare un DirAccess. I metodi statici supportano solo percorsi assoluti (inclusi res:// e user://).

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

Nota: L'accesso alle cartelle del progetto ("res://") una volta esportate potrebbe comportarsi in modo imprevisto poiché alcuni file vengono convertiti in formati specifici del motore e i loro file sorgente originali potrebbero non essere presenti nel pacchetto PCK previsto. Per questo motivo, per accedere alle risorse in un progetto esportato, si consiglia di utilizzare ResourceLoader anziché FileAccess.

Ecco un esempio su come interare i file di una 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("Cartelle trovata: " + file_name)
            else:
                print("File trovato: " + file_name)
            file_name = dir.get_next()
    else:
        print("Si è verificato un errore cercando di accedere al percorso.")

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($"Cartella trovata: {fileName}");
            }
            else
            {
                GD.Print($"File trovato: {fileName}");
            }
            fileName = dir.GetNext();
        }
    }
    else
    {
        GD.Print("Si è verificato un errore cercando di accedere al percorso.");
    }
}

Tieni presente che i nomi dei file potrebbero cambiare o essere rimappati dopo l'esportazione. Se vuoi vedere l'elenco effettivo dei file di risorse così come appare nell'editor, usa invece ResourceLoader.list_directory().

Tutorial

Il File system

Proprietà

bool	include_hidden
bool	include_navigational

Metodi

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

Descrizioni delle proprietà

bool include_hidden 🔗

void set_include_hidden(value: bool)
bool get_include_hidden()

Se true, i file nascosti sono inclusi quando si naviga nella cartella.

Influisce su list_dir_begin(), get_directories(), e get_files().

bool include_navigational 🔗

void set_include_navigational(value: bool)
bool get_include_navigational()

Se true, . e .. sono inclusi durante la navigazione nella cartella.

Influisce su list_dir_begin() e get_directories().

Descrizioni dei metodi

Error change_dir(to_dir: String) 🔗

Cambia la directory attualmente aperta in quella passata come argomento. L'argomento può essere relativo alla directory attuale (ad esempio newdir o ../newdir), o un percorso assoluto (ad esempio /tmp/newdir o res://somedir/newdir).

Restituisce una delle costanti di Error (@GlobalScope.OK in caso di successo).

Nota: La nuova directory deve essere nella stessa ambito, ad esempio quando una directory è aperta all'interno di res://, non è possibile cambiarla in directory user://. Se è necessario aprire una directory in un altro ambito di accesso, usa open() per creare una nuova istanza.

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

Copia il file da from nella destinazione to. Entrambi gli argomenti devono essere percorsi a file, relativi o assoluti. Se il file di destinazione esiste e non è protetto da accesso, verrà sovrascritto.

Se chmod_flags è diverso da -1, i permessi Unix per il percorso di destinazione verranno impostati sul valore fornito, se disponibile sul sistema operativo corrente.

Restituisce una delle costanti di Error (@GlobalScope.OK in caso di successo).

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

Versione statica di copy(). Supporta solo i percorsi assoluti.

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

Crea un collegamento simbolico tra file o cartelle.

Nota: Su Windows, questo metodo funziona solo se l'applicazione è in esecuzione con privilegi elevati o se è abilitata la modalità sviluppatore.

Nota: Questo metodo è implementato su macOS, Linux, e Windows.

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

Crea una cartella temporanea. Questa cartella sarà liberata quando il DirAccess restituito viene liberato.

Se prefix non è vuoto, verrà prefissato al nome della cartella, separato da -.

Se keep è true, la cartella non viene eliminata quando il DirAccess restituito viene liberato.

Restituisce null se l'apertura della cartella non avviene con successo. È possibile usare get_open_error() per controllare l'errore che si è verificato.

bool current_is_dir() const 🔗

Restituisce se l'elemento attuale elaborato con l'ultima chiamata a get_next() è una cartella (. e .. sono considerate cartelle).

bool dir_exists(path: String) 🔗

Restituisce se la cartella di destinazione esiste. L'argomento può essere relativo alla cartella attuale o un percorso assoluto.

Nota: Il bool restituito nell'editor e dopo l'esportazione quando utilizzato su un percorso nella directory res:// potrebbe essere diverso. Alcuni file vengono convertiti in formati specifici del motore quando esportati, modificando potenzialmente la struttura della cartella.

bool dir_exists_absolute(path: String) static 🔗

Versione statica di dir_exists(). Supporta solo percorsi assoluti.

Nota: Il bool restituito nell'editor e dopo l'esportazione quando utilizzato su un percorso nella directory res:// potrebbe essere diverso. Alcuni file vengono convertiti in formati specifici del motore quando esportati, modificando potenzialmente la struttura della cartella.

bool file_exists(path: String) 🔗

Restituisce se il file di destinazione esiste. L'argomento può essere relativo alla cartella attuale oppure un percorso assoluto.

Per un equivalente statico, usa FileAccess.file_exists().

Nota: Molti tipi di risorse sono importati (ad esempio texture o file audio) e la loro risorsa sorgente non sarà inclusa nel gioco esportato, poiché solo la versione importata è utilizzata. Vedi ResourceLoader.exists() per un approccio alternativo che tenga conto della rimappatura delle risorse.

String get_current_dir(include_drive: bool = true) const 🔗

Restituisce il percorso assoluto alla cartella attualmente aperta (ad esempio res://folder o C:\tmp\folder).

int get_current_drive() 🔗

Restituisce l'indice dell'unità della cartella attualmente aperta. Vedi get_drive_name() per convertire l'indice restituito nel nome dell'unità.

PackedStringArray get_directories() 🔗

Restituisce un PackedStringArray contenente i nomi dei file del contenuto della cartella, esclusi i file. L'array è ordinato alfabeticamente.

Influenzato da include_hidden e include_navigational.

Nota: Le cartelle restituite nell'editor e dopo l'esportazione nella cartella res:// potrebbero essere diversi poiché alcuni file vengono convertiti in formati specifici del motore durante l'esportazione.

PackedStringArray get_directories_at(path: String) static 🔗

Restituisce un PackedStringArray contenente i nomi dei file del contenuto della cartella, esclusi i file, nel percorso path specificato. L'array è ordinato alfabeticamente.

Usa get_directories() se si desidera più controllo su cosa viene incluso.

Nota: Le cartelle restituite nell'editor e dopo l'esportazione nella cartella res:// potrebbero essere diversi poiché alcuni file vengono convertiti in formati specifici del motore durante l'esportazione.

int get_drive_count() static 🔗

Su Windows, restituisce il numero di unità (partizioni) montate sul file system attuale.

Su macOS e Android, restituisce il numero di volumi montati.

Su Linux, restituisce il numero di volumi montati e segnalibri GTK 3.

Su altre piattaforme, il metodo restituisce 0.

String get_drive_label(idx: int) static 🔗

On Windows, returns the label of the drive (partition) passed as an argument.

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

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

Restituisce un PackedStringArray contenente i nomi file del contenuto della cartella, escluse le cartelle. L'array è ordinato alfabeticamente.

Influenzato da include_hidden.

Nota: Quando utilizzato su un percorso res:// in un progetto esportato, sono restituiti solo i file effettivamente inclusi nel PCK al livello di cartella specificato. In pratica, ciò significa che poiché le risorse importate sono archiviate in una cartella di livello superiore .godot/, sono restituiti solo i percorsi ai file *.gd e *.import (oltre ad alcuni file come project.godot o project.binary e l'icona del progetto). In un progetto esportato, l'elenco dei file restituiti varierà anche a seconda che ProjectSettings.editor/export/convert_text_resources_to_binary sia true.

PackedStringArray get_files_at(path: String) static 🔗

Restituisce un PackedStringArray contenente i nomi file del contenuto della cartella, escluse le cartelle, al percorso path specificato. L'array è ordinato alfabeticamente.

Usa get_files() se si desidera più controllo su cosa viene incluso.

Nota: Quando utilizzato su un percorso res:// in un progetto esportato, sono restituiti solo i file effettivamente inclusi nel PCK al livello di cartella specificato. In pratica, ciò significa che poiché le risorse importate sono archiviate in una cartella di livello superiore .godot/, sono restituiti solo i percorsi ai file *.gd e *.import (oltre a qualche altro file come project.godot o project.binary e l'icona del progetto). In un progetto esportato, l'elenco dei file restituiti varierà anche a seconda di ProjectSettings.editor/export/convert_text_resources_to_binary.

String get_filesystem_type() const 🔗

Restituisce il nome del tipo di file system del disco della cartella attuale. I valori restituiti sono stringhe maiuscole come NTFS, FAT32, EXFAT, APFS, EXT4, BTRFS e così via.

Nota: Questo metodo è implementato su macOS, Linux, Windows e per il file system virtuale dei PCK.

String get_next() 🔗

Restituisce l'elemento successivo (file o cartella) nella cartella attuale.

Viene restituito il nome del file o della cartella (e non il suo percorso completo). Una volta che il flusso è stato elaborato completamente, il metodo restituisce una String vuota e chiude automaticamente il flusso (ad esempio, list_dir_end() non sarebbe obbligatorio in tal caso).

Error get_open_error() static 🔗

Restituisce il risultato dell'ultima chiamata a open() nel thread attuale.

int get_space_left() 🔗

Restituisce lo spazio disponibile sul disco della cartella attuale, in byte. Restituisce 0 se il metodo specifico della piattaforma per interrogare lo spazio disponibile fallisce.

bool is_bundle(path: String) const 🔗

Restituisce true se la cartella è un pacchetto macOS.

Nota: Questo metodo è implementato solo su macOS.

bool is_case_sensitive(path: String) const 🔗

Restituisce true se il file system o la cartella utilizzano nomi di file sensibili alle maiuscole e minuscole.

Nota: Questo metodo è implementato su macOS, Linux (solo per i file system EXT4 e F2FS) e Windows. Su altre piattaforme, restituisce sempre true.

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

Restituisce true se i percorsi path_a e path_b risolvono nello stesso oggetto del file system. Restituisce false altrimenti, anche se i file sono identici bit per bit (ad esempio, copie identiche del file che non sono collegamenti simbolici).

bool is_link(path: String) 🔗

Restituisce true se il file o la cartella è un collegamento simbolico, una giunzione di directory o un altro reparse point.

Nota: Questo metodo è implementato su macOS, Linux, e Windows.

Error list_dir_begin() 🔗

Inizializza il flusso usato per elencare tutti i file e le cartelle attraverso la funzione get_next(), chiudendo il flusso attualmente aperto se necessario. Una volta elaborato, il flusso dovrebbe essere solitamente chiuso con list_dir_end().

Influenzato da include_hidden e include_navigational.

Nota: L'ordine dei file e delle cartelle restituito da questo metodo non è deterministico e può variare tra i sistemi operativi. Se desideri un elenco di tutti i file o cartelle in ordine alfabetico, utilizza get_files() o get_directories().

void list_dir_end() 🔗

Chiude il flusso aperto attuale con list_dir_begin() (non importa se è stato completamente elaborato con get_next()).

Error make_dir(path: String) 🔗

Crea una cartella. L'argomento può essere relativo alla cartella attuale o un percorso assoluto. La cartella di destinazione dovrebbe essere posizionata in una cartella già esistente (per creare il percorso completo in modo ricorsivo, vedi make_dir_recursive()).

Restituisce una delle costanti di codice Error (@GlobalScope.OK in caso di successo).

Error make_dir_absolute(path: String) static 🔗

Versione statica di make_dir(). Supporta solo i percorsi assoluti.

Error make_dir_recursive(path: String) 🔗

Crea una cartella di destinazione e tutte le cartelle intermedie necessarie nel suo percorso, chiamando make_dir() ricorsivamente. L'argomento può essere relativo alla cartella attuale o un percorso assoluto.

Restituisce una delle costanti di codice Error (@GlobalScope.OK in caso di successo).

Error make_dir_recursive_absolute(path: String) static 🔗

Versione statica di make_dir_recursive(). Supporta solo i percorsi assoluti.

DirAccess open(path: String) static 🔗

Crea un nuovo oggetto DirAccess e apre una cartella esistente del file system. Il percorso path può essere all'interno dell'albero del progetto (res://folder), della cartella utente (user://folder) o di un percorso assoluto del file system dell'utente (ad esempio /tmp/folder o C:\tmp\folder).

Restituisce null se l'apertura della cartella non avviene con successo. È possibile usare get_open_error() per controllare l'errore che si è verificato.

String read_link(path: String) 🔗

Restituisce la destinazione del collegamento simbolico.

Nota: Questo metodo è implementato su macOS, Linux e Windows.

Error remove(path: String) 🔗

Elimina definitivamente il file di destinazione o una cartella vuota. L'argomento può essere relativo alla cartella attuale o un percorso assoluto. Se la cartella di destinazione non è vuota, l'operazione fallirà.

Se non vuoi eliminare definitivamente il file o la cartella, usa invece OS.move_to_trash().

Restituisce una delle costanti di codice Error (@GlobalScope.OK in caso di successo).

Error remove_absolute(path: String) static 🔗

Versione statica di remove(). Supporta solo i percorsi assoluti.

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

Rinomina (sposta) il file o la cartella from nella destinazione to. Entrambi gli argomenti devono essere percorsi a file o cartelle, relativi o assoluti. Se il file o la cartella di destinazione esiste e non è protetto da accesso, verrà sovrascritto.

Restituisce una delle costanti di codice Error (@GlobalScope.OK in caso di successo).

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

Versione statica di rename(). Supporta solo i percorsi assoluti.