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
Hérite de : Object
Un singleton pour charger des fichiers de ressource.
Description
A singleton used to load resource files from the filesystem.
It uses the many ResourceFormatLoader classes registered in the engine (either built-in or from a plugin) to load files into memory and convert them to a format that can be used by the engine.
Note: You have to import the files into the engine first to load them using load(). If you want to load Images at run-time, you may use Image.load(). If you want to import audio files, you can use the snippet described in AudioStreamMP3.data.
Note: Non-resource files such as plain text files cannot be read using ResourceLoader. Use FileAccess for those files instead, and be aware that non-resource files are not exported by default (see notes in the FileAccess class description for instructions on exporting them).
Tutoriels
Méthodes
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) |
Énumérations
enum ThreadLoadStatus: 🔗
ThreadLoadStatus THREAD_LOAD_INVALID_RESOURCE = 0
La ressource est invalide, ou n'a pas été chargée avec load_threaded_request().
ThreadLoadStatus THREAD_LOAD_IN_PROGRESS = 1
La ressource est toujours en cours de chargement.
ThreadLoadStatus THREAD_LOAD_FAILED = 2
Une erreur s'est produite lors du chargement et il a échoué.
ThreadLoadStatus THREAD_LOAD_LOADED = 3
La ressource a été chargée avec succès et peut être consultée via load_threaded_get().
enum CacheMode: 🔗
CacheMode CACHE_MODE_IGNORE = 0
Ni la ressource principale (celle dont le chargement est demandé) ni ses sous-ressources ne sont récupérées depuis le cache ni y sont stockées. Les dépendances (ressources externes) sont chargées avec CACHE_MODE_REUSE.
CacheMode CACHE_MODE_REUSE = 1
La ressource principale (celle dont le chargement est demandé), ses sous-ressources et ses dépendances (ressources externes) sont récupérées depuis le cache si elles y sont présentes, plutôt que chargées. Celles qui ne sont pas en cache sont chargées puis stockées dans le cache. Ces mêmes règles s’appliquent récursivement à l’ensemble de l’arbre des dépendances (ressources externes).
CacheMode CACHE_MODE_REPLACE = 2
Comme CACHE_MODE_REUSE, mais le cache est vérifié pour la ressource principale (celle dont le chargement est demandé) ainsi que pour chacune de ses sous-ressources. Celles déjà présentes dans le cache, à condition que les types chargés et mis en cache correspondent, voient leurs données rafraîchies depuis le stockage dans les instances déjà existantes. Sinon, elles sont recréées en tant qu’objets entièrement nouveaux.
CacheMode CACHE_MODE_IGNORE_DEEP = 3
Comme CACHE_MODE_IGNORE, mais propagé de façon récursive dans l'arbre des dépendances (ressources externes).
CacheMode CACHE_MODE_REPLACE_DEEP = 4
Comme CACHE_MODE_REPLACE, mais propagé de façon récursive dans l'arbre des dépendances (ressources externes).
Descriptions des méthodes
void add_resource_format_loader(format_loader: ResourceFormatLoader, at_front: bool = false) 🔗
Registers a new ResourceFormatLoader. The ResourceLoader will use the ResourceFormatLoader as described in load().
This method is performed implicitly for ResourceFormatLoaders written in GDScript (see ResourceFormatLoader for more information).
bool exists(path: String, type_hint: String = "") 🔗
Returns whether a recognized resource exists for the given path.
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.
Note: If you use Resource.take_over_path(), this method will return true for the taken path even if the resource wasn't saved (i.e. exists only in resource cache).
Resource get_cached_ref(path: String) 🔗
Returns the cached resource reference for the given path.
Note: If the resource is not cached, the returned Resource will be invalid.
PackedStringArray get_dependencies(path: String) 🔗
Returns the dependencies for the resource at the given path.
Each dependency is a string that can be divided into sections by ::. There can be either one section or three sections, with the second section always being empty. When there is one section, it contains the file path. When there are three sections, the first section contains the UID and the third section contains the fallback path.
for dependency in ResourceLoader.get_dependencies(path):
if dependency.contains("::"):
print(dependency.get_slice("::", 0)) # Prints the UID.
print(dependency.get_slice("::", 2)) # Prints the fallback path.
else:
print(dependency) # Prints the path.
PackedStringArray get_recognized_extensions_for_type(type: String) 🔗
Renvoie la liste des extensions reconnues pour ce type de ressource.
int get_resource_uid(path: String) 🔗
Returns the ID associated with a given resource path, or -1 when no such ID exists.
bool has_cached(path: String) 🔗
Returns whether a cached resource is available for the given path.
Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the load() method will use the cached version. The cached resource can be overridden by using Resource.take_over_path() on a new resource for that same path.
PackedStringArray list_directory(directory_path: String) 🔗
Liste un répertoire, renvoyant toutes les ressources et les sous-répertoires contenus dedans. Les fichiers ressources ont leurs noms de fichiers originaux comme visibles dans l'éditeur avant l'export. Les répertoires ont "/" ajouté.
# Affiche ["extra_data/", "model.gltf", "model.tscn", "model_slime.png"]
print(ResourceLoader.list_directory("res://assets/enemies/slime"))
Note : L'ordre des fichiers et des répertoires renvoyés par cette méthode n'est pas déterministe, et peut varier entre les systèmes d'exploitation.
Note : Pour traverser normalement le système de fichiers, voir 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) 🔗
Renvoie la ressource chargée par load_threaded_request().
Si cela est appelé avant que le thread de chargement soit fini (c.-à-d. load_threaded_get_status() n'est pas THREAD_LOAD_LOADED), le thread d'appel sera bloqué jusqu'à ce que la ressource ait fini de charger. Cependant, il est recommandé d'utiliser load_threaded_get_status() pour savoir quand le chargement est réellement terminé.
ThreadLoadStatus load_threaded_get_status(path: String, progress: Array = []) 🔗
Returns the status of a threaded loading operation started with load_threaded_request() for the resource at path.
An array variable can optionally be passed via progress, and will return a one-element array containing the ratio of completion of the threaded loading (between 0.0 and 1.0).
Note: The recommended way of using this method is to call it during different frames (e.g., in Node._process(), instead of a loop).
Error load_threaded_request(path: String, type_hint: String = "", use_sub_threads: bool = false, cache_mode: CacheMode = 1) 🔗
Charge la ressource en utilisant des threads. Si use_sub_threads vaut true, plusieurs threads seront utilisés pour charger la ressource, ce qui rend le chargement plus rapide, mais peut affecter le thread principal (et donc causer des ralentissements de jeu).
Le paramètre cache_mode définit si et comment le cache devrait être utilisé ou mis à jour lors du chargement de la ressource.
void remove_resource_format_loader(format_loader: ResourceFormatLoader) 🔗
Désenregistre le ResourceFormatLoader donné.
void set_abort_on_missing_resources(abort: bool) 🔗
Change le comportement pour les sous-ressources manquantes. Le comportement par défaut est d'annuler le chargement.