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, consultare DirAccess.
Resource load(path: String, type_hint: String = "", cache_mode: CacheMode = 1) 🔗
Loads a resource at the given path, caching the result for further access.
The registered ResourceFormatLoaders are queried sequentially to find the first one which can handle the file's extension, and then attempt loading. If loading fails, the remaining ResourceFormatLoaders are also attempted.
An optional type_hint can be used to further specify the Resource type that should be handled by the ResourceFormatLoader. Anything that inherits from Resource can be used as a type hint, for example Image.
The cache_mode property defines whether and how the cache should be used or updated when loading the resource.
Returns an empty resource if no ResourceFormatLoader could handle the file, and prints an error if no file is found at the specified path.
GDScript has a simplified @GDScript.load() built-in method which can be used in most situations, leaving the use of ResourceLoader for more advanced scenarios.
Note: If ProjectSettings.editor/export/convert_text_resources_to_binary is true, @GDScript.load() will not be able to read converted files in an exported project. If you rely on run-time loading of files present within the PCK, set ProjectSettings.editor/export/convert_text_resources_to_binary to false.
Note: Relative paths will be prefixed with "res://" before loading, to avoid unexpected results make sure your paths are absolute.
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.