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

Percorsi di file nei progetti di Godot

Questa pagina spiega come funzionano i percorsi dei file all'interno dei progetti Godot. Imparerai come accedere ai percorsi nei tuoi progetti utilizzando le notazioni res:// e user://, e dove Godot memorizza i file di progetto e dell'editor sui tuoi sistemi e su quelli dei tuoi utenti.

Separatori di percorso

Per facilitare il supporto di più piattaforme, Godot utilizza i separatori di percorso in stile UNIX (barra /). Questi funzionano su tutte le piattaforme, incluso Windows.

Anziché scrivere percorsi come C:\Projects\Game, in Godot si dovrebbe scrivere C:/Projects/Game.

Anche i separatori di percorso in stile Windows (barra rovesciata \) sono supportati in alcuni metodi riguardo i percorsi, ma devono essere raddoppiati (\\), poiché \ è normalmente utilizzato come escape per i caratteri con un significato speciale.

Ciò consente di lavorare con i percorsi restituiti da altre applicazioni Windows. Consigliamo comunque di utilizzare solo barre nel proprio codice per garantire che tutto funzioni come previsto.

Suggerimento

La classe String offre più di una dozzina di metodi per lavorare con stringhe che rappresentano percorsi di file:

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

Accesso ai file nella cartella del progetto (res://)

Godot considera che un progetto esista in qualsiasi cartella che contenga un file di testo project.godot, anche se il file è vuoto. La cartella che contiene questo file è la cartella radice del progetto.

È possibile accedere a qualsiasi file relativo ad esso scrivendo percorsi che iniziano con res://, che sta per risorse. Ad esempio, è possibile accedere a un file immagine character.png situato nella cartella principale del progetto tramite il seguente percorso: res://character.png.

Accesso ai dati persistenti degli utenti (user://)

Per archiviare file di dati persistenti, come i salvataggi o le impostazioni del giocatore, è consigliabile utilizzare user:// invece di res:// come prefisso del percorso. Questo perché quando il gioco è in esecuzione, il file system del progetto sarà probabilmente di sola lettura.

Il prefisso user:// punta a una cartella diversa sul dispositivo dell'utente. A differenza di res://, la cartella a cui punta user:// viene creata automaticamente e garantisce la scrittura, anche in un progetto esportato.

La posizione della cartella user:// dipende da quanto configurato nelle Impostazioni del progetto:

• Normalmente, la cartella user:// viene creata all'interno del percorso dati dell'editor di Godot nella cartella app_userdata/[nome_progetto]. Questa è l'impostazione predefinita, in modo che i prototipi e i progetti di prova rimangano indipendenti all'interno della cartella dati di Godot.

• Se application/config/use_custom_user_dir è abilitato nelle Impostazioni del progetto, la cartella user:// viene creata accanto al percorso dei dati dell'editor, ovvero nella posizione standard per i dati delle applicazioni.

  • Normalmente, il nome della cartella verrà dedotto dal nome del progetto, ma si può ulteriormente personalizzare con application/config/custom_user_dir_name. Questo percorso può contenere separatori di percorso, quindi è possibile utilizzarlo, ad esempio, per raggruppare i progetti di un determinato studio con una struttura Nome studio/Nome gioco.

Sulle piattaforme desktop, i percorsi effettivi delle cartelle per user:// sono:

Tipo	Posizione
Predefinito	Windows: %APPDATA%\Godot\app_userdata\[project_name] macOS: ~/Library/Application Support/Godot/app_userdata/[project_name] Linux: ~/.local/share/godot/app_userdata/[project_name]
Cartella personalizzata	Windows: %APPDATA%\[project_name] macOS: ~/Library/Application Support/[project_name] Linux: ~/.local/share/[project_name]
Cartella e nome personalizzati	Windows: %APPDATA%\[custom_user_dir_name] macOS: ~/Library/Application Support/[custom_user_dir_name] Linux: ~/.local/share/[custom_user_dir_name]

[project_name] si basa sul nome dell'applicazione definito nelle Impostazioni del progetto, ma è possibile sovrascriverlo in base alla piattaforma tramite tag di funzionalità.

Sulle piattaforme mobili, questo percorso è unico al progetto e non è accessibile ad altre applicazioni per motivi di sicurezza.

Nelle esportazioni HTML5, user:// farà riferimento a un file system virtuale memorizzato sul dispositivo tramite IndexedDB. (L'interazione con il file system principale si può comunque effettuare attraverso il singleton JavaScriptBridge.)

Logging su file

Vedi anche

La documentazione riguardo il logging su file è stata spostata in Logging.

Convertire i percorsi tra assoluti a "locali"

È possibile utilizzare ProjectSettings.globalize_path() per convertire un percorso "locale" come res://path/to/file.txt in un percorso assoluto del sistema operativo. Ad esempio, ProjectSettings.globalize_path() si può utilizzare per aprire percorsi "locali" nel gestore file del sistema operativo tramite OS.shell_open(), poiché accetta solo percorsi nativi del sistema operativo.

Per convertire un percorso assoluto del sistema operativo in un percorso "locale" che inizia con res:// o user://, usare ProjectSettings.localize_path(). Questo funziona solo per i percorsi assoluti che puntano a file o cartelle nella radice del progetto o nelle cartelle user://.

Percorsi dati dell'editor

L'editor utilizza percorsi diversi per i dati dell'editor, le impostazioni dell'editor e la cache, a seconda della piattaforma. Per impostazione predefinita, questi percorsi sono:

Tipo	Posizione
Dati dell'editor	Windows: %APPDATA%\Godot\ macOS: ~/Library/Application Support/Godot/ Linux: ~/.local/share/godot/
Impostazioni dell'editor	Windows: %APPDATA%\Godot\ macOS: ~/Library/Application Support/Godot/ Linux: ~/.config/godot/
Cache	Windows: %TEMP%\Godot\ macOS: ~/Library/Caches/Godot/ Linux: ~/.cache/godot/

• Dati dell'editor contiene modelli di esportazione e dati specifici del progetto.

• Impostazioni dell'editor contiene il file di configurazione delle impostazioni dell'editor principale, nonché varie altre personalizzazioni specifiche dell'utente (layout dell'editor, profili di funzionalità, modelli di script, ecc.).

• La cache contiene dati generati dall'editor o memorizzati temporaneamente. Si può rimuovere tranquillamente quando Godot è chiuso.

Godot è conforme alle specifiche XDG Base Directory su Linux/*BSD. È possibile sovrascrivere le variabili d'ambiente XDG_DATA_HOME, XDG_CONFIG_HOME e XDG_CACHE_HOME per modificare i percorsi dei dati dell'editor e del progetto.

Nota

Se si utilizza Godot impacchettato come Flatpak, i percorsi dei dati dell'editor saranno situati nelle sottocartelle in ~/.var/app/org.godotengine.Godot/.

Modalità autonoma

Se si crea un file chiamato ._sc_ o _sc_ nella stessa cartella dell'eseguibile dell'editor (o in MacOS/Contents/ per un pacchetto .app dell'editor per macOS), Godot abiliterà la modalità autonoma. Questa modalità fa sì che Godot scriva tutti i dati, le impostazioni e la cache dell'editor in una cartella chiamata editor_data/ nella stessa cartella dell'eseguibile dell'editor. È possibile utilizzarla per creare un'installazione portatile dell'editor.

La versione su Steam di Godot utilizza la modalità autonoma come predefinito.

Nota

La modalità autonoma non è ancora supportata nei progetti esportati. Per leggere e scrivere file relativi al percorso dell'eseguibile, utilizzare OS.get_executable_path(). Si noti che la scrittura di file nel percorso dell'eseguibile funziona solo se l'eseguibile si trova in una posizione scrivibile (ad esempio non in Programmi o un'altra cartella di sola lettura per gli utenti comuni).