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...
ResourceLoader
Eredita: Object
Un singleton per caricare file di risorse.
Descrizione
Un singleton utilizzato per caricare i file di risorse dal file system.
Utilizza le numerose classi ResourceFormatLoader registrate nel motore (integrate o da un'estensione) per caricare i file in memoria e convertirli in un formato che il motore può utilizzare.
Nota: È necessario prima importare i file nel motore per caricarli tramite load(). Se si desidera caricare un Image in fase di esecuzione, è possibile usare Image.load(). Se si desidera importare file audio, è possibile usare lo snippet di codice descritto in AudioStreamMP3.data.
Nota: Non è possibile leggere i file non di risorse, come i file di testo semplice, attraverso ResourceLoader. Usa invece FileAccess per tali file e tieni presente che i file non di risorse non sono esportati come predefinito (vedi le note nella descrizione della classe FileAccess per istruzioni su come esportarli).
Tutorial
Metodi
void |
add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false) |
get_cached_ref(path: String) |
|
get_dependencies(path: String) |
|
get_resource_uid(path: String) |
|
has_cached(path: String) |
|
list_directory(directory_path: String) |
|
load(path: String, type_hint: String = "", cache_mode: CacheMode = 1) |
|
load_threaded_get(path: String) |
|
load_threaded_get_status(path: String, progress: Array = []) |
|
load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1) |
|
void |
remove_resource_format_loader(format_loader: ResourceFormatLoader) |
void |
set_abort_on_missing_resources(abort: bool) |
Enumerazioni
enum ThreadLoadStatus: 🔗
ThreadLoadStatus THREAD_LOAD_INVALID_RESOURCE = 0
La risorsa non è valida oppure non è stata caricata con load_threaded_request().
ThreadLoadStatus THREAD_LOAD_IN_PROGRESS = 1
La risorsa è ancora in fase di caricamento.
ThreadLoadStatus THREAD_LOAD_FAILED = 2
Si è verificato un errore durante il caricamento e non è riuscito.
ThreadLoadStatus THREAD_LOAD_LOADED = 3
La risorsa è stata caricata con successo ed è possibile accedervi tramite load_threaded_get().
enum CacheMode: 🔗
CacheMode CACHE_MODE_IGNORE = 0
Né la risorsa principale (quella di cui si richiede il caricamento) né alcuna delle sue sotto-risorse sono recuperate dalla cache né memorizzate in essa. Le dipendenze (ovvero le risorse esterne) sono caricate con CACHE_MODE_REUSE.
CacheMode CACHE_MODE_REUSE = 1
La risorsa principale (quella di cui si richiede il caricamento), le sue sotto-risorse e le sue dipendenze (risorse esterne) sono recuperate dalla cache se presenti, anziché caricate. Quelle non memorizzate nella cache sono caricate e quindi memorizzate nella cache. Le stesse regole sono propagate ricorsivamente lungo l'albero delle dipendenze (ovvero le risorse esterne).
CacheMode CACHE_MODE_REPLACE = 2
Come CACHE_MODE_REUSE, ma la cache è verificata per la risorsa principale (quella di cui si richiede il caricamento) e per ciascuna delle sue sotto-risorse. Quelle già nella cache, se i tipi caricati e memorizzati nella cache corrispondono, hanno i loro dati aggiornati dal disco nelle istanze già esistenti. Altrimenti, sono ricreate come oggetti completamente nuovi.
CacheMode CACHE_MODE_IGNORE_DEEP = 3
Simile a CACHE_MODE_IGNORE, ma propagato ricorsivamente lungo l'albero delle dipendenze (ovvero le risorse esterne).
CacheMode CACHE_MODE_REPLACE_DEEP = 4
Simile a CACHE_MODE_REPLACE, ma propagato ricorsivamente lungo l'albero delle dipendenze (ovvero le risorse esterne).
Descrizioni dei metodi
void add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false) 🔗
Registra un nuovo ResourceFormatLoader. Il ResourceLoader utilizzerà il ResourceFormatLoader come descritto in load().
Questo metodo viene effettuato implicitamente per i ResourceFormatLoader scritti in GDScript (vedi ResourceFormatLoader per maggiori informazioni).
bool exists(path: String, type_hint: String = "") 🔗
Restituisce se esiste una risorsa riconosciuta per il percorso path.
Un type_hint facoltativo può essere usato per specificare ulteriormente il tipo di Resource che deve essere gestito da ResourceFormatLoader. Tutto ciò che eredita da Resource può essere utilizzato come suggerimento per il tipo, ad esempio Image.
Nota: Se si utilizza Resource.take_over_path(), questo metodo restituirà true per il percorso preso anche se la risorsa non è stata salvata (ad esempio, esiste solo nella cache delle risorse).
Resource get_cached_ref(path: String) 🔗
Restituisce il riferimento alla risorsa memorizzata nella cache per il percorso path.
Nota: Se la risorsa non è memorizzata nella cache, la Resource restituita non sarà valida.
PackedStringArray get_dependencies(path: String) 🔗
Restituisce le dipendenze per la risorsa nel percorso path.
Ogni dipendenza è una stringa che si può dividere in sezioni tra ::. Può essere presente una o tre sezioni, con la seconda sezione sempre vuota. Quando è presente una sola sezione, contiene il percorso del file. Quando sono presenti tre sezioni, la prima sezione contiene l'UID e la terza sezione contiene il percorso di riserva.
for dependency in ResourceLoader.get_dependencies(path):
if dependency.contains("::"):
print(dependency.get_slice("::", 0)) # Stampa l'UID.
print(dependency.get_slice("::", 2)) # Stampa il percorso di riserva.
else:
print(dependency) # Stampa il percorso.
PackedStringArray get_recognized_extensions_for_type(type: String) 🔗
Restituisce la lista di estensioni riconosciute per un tipo di risorsa.
int get_resource_uid(path: String) 🔗
Restituisce l'ID associato a un determinato percorso di risorsa oppure -1 quando tale ID non esiste.
bool has_cached(path: String) 🔗
Restituisce se una risorsa memorizzata nella cache è disponibile per il percorso path.
Una volta che una risorsa è stata caricata dal motore, viene memorizzata nella cache per un accesso più rapido e le future chiamate al metodo load() utilizzeranno la versione memorizzata nella cache. È possibile sovrascrivere la risorsa memorizzata nella cache attraverso Resource.take_over_path() su una nuova risorsa per lo stesso percorso.
PackedStringArray list_directory(directory_path: String) 🔗
Elenca una cartella, restituendo tutte le risorse e le sottocartelle in essa contenute. I file di risorse hanno i nomi originali visibili nell'editor prima dell'esportazione. Alle cartelle è aggiunto "/".
# Stampa ["extra_data/", "model.gltf", "model.tscn", "model_slime.png"]
print(ResourceLoader.list_directory("res://assets/enemies/slime"))
Nota: L'ordine dei file e delle cartelle restituito da questo metodo non è deterministico e può variare a seconda del sistema operativo.
Nota: Per attraversare normalmente il file system, consulta DirAccess.
Resource load(path: String, type_hint: String = "", cache_mode: CacheMode = 1) 🔗
Carica una risorsa dal percorso path, memorizzando nella cache il risultato per accedervi in seguito.
I ResourceFormatLoader registrati vengono provati in sequenza per trovare il primo che può gestire l'estensione del file, da poi caricare. Se il caricamento fallisce, vengono provati anche i ResourceFormatLoader rimasti.
È possibile passare type_hint per specificare ulteriormente il tipo di Resource che deve essere gestito dal ResourceFormatLoader. Tutto ciò che eredita da Resource può essere utilizzato come suggerimento per il tipo, ad esempio Image.
cache_mode definisce se e come bisogna utilizzare o aggiornare la cache durante il caricamento della risorsa.
Restituisce una risorsa vuota se nessun ResourceFormatLoader è riuscito a gestire il file e stampa un errore se non viene trovato alcun file nel percorso specificato.
GDScript fornisce il metodo integrato semplificato @GDScript.load() che è sufficiente nella maggior parte delle situazioni, lasciando l'uso di ResourceLoader per motivi più avanzati.
Nota: Se ProjectSettings.editor/export/convert_text_resources_to_binary è true, @GDScript.load() non sarà in grado di leggere i file convertiti in un progetto esportato. Se in fase di esecuzione è necessario caricare i file presenti nel PCK, imposta ProjectSettings.editor/export/convert_text_resources_to_binary su false.
Nota: I percorsi relativi saranno preceduti da "res://" prima del caricamento, per evitare risultati imprevisti assicurati che i tuoi percorsi siano assoluti.
Resource load_threaded_get(path: String) 🔗
Restituisce la risorsa caricata da load_threaded_request().
Se viene chiamato prima che il thread di caricamento sia completato (ad esempio, load_threaded_get_status() non è THREAD_LOAD_LOADED), il thread chiamante verrà bloccato finché la risorsa non avrà finito di caricarsi. Tuttavia, si consiglia di usare load_threaded_get_status() per sapere quando il caricamento è stato effettivamente completato.
ThreadLoadStatus load_threaded_get_status(path: String, progress: Array = []) 🔗
Restituisce lo stato di un'operazione di caricamento su un thread, avviata con load_threaded_request(), per la risorsa nel percorso path.
Una variabile di tipo array può essere facoltativamente passata tramite progress e restituirà un array di un elemento contenente la percentuale di completamento del caricamento su un thread (tra 0.0 e 1.0).
Nota: Il modo consigliato per usare questo metodo è di chiamarlo durante frame diversi (ad esempio, in Node._process(), invece di un ciclo).
Error load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1) 🔗
Carica la risorsa usando i thread. Se use_sub_threads è true, saranno usati più thread per caricare la risorsa, il che velocizza il caricamento, ma potrebbe influenzare il thread principale (e quindi causare rallentamenti di gioco).
cache_mode definisce se e come bisogna utilizzare o aggiornare la cache durante il caricamento della risorsa.
void remove_resource_format_loader(format_loader: ResourceFormatLoader) 🔗
Annulla la registrazione del ResourceFormatLoader specificato.
void set_abort_on_missing_resources(abort: bool) 🔗
Cambia il comportamento per le sotto-risorse mancanti. Il comportamento predefinito è di annullare il caricamento.