Table of Contents

Class ResourceLoader

A singleton for loading resource files.

Inheritance
ResourceLoader

Remarks

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

See Also

Operating System Testing Demo

Methods

add_resource_format_loader(ResourceFormatLoader, bool)

Registers a new ResourceFormatLoader. The ResourceLoader will use the ResourceFormatLoader as described in ResourceLoader.load.

This method is performed implicitly for ResourceFormatLoaders written in GDScript (see ResourceFormatLoader for more information).

void add_resource_format_loader(ResourceFormatLoader format_loader, bool at_front)

Parameters

format_loader ResourceFormatLoader
at_front bool

exists(String, 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).

bool exists(String path, String type_hint)

Parameters

path String
type_hint String

get_cached_ref(String)

Returns the cached resource reference for the given path.

Note: If the resource is not cached, the returned Resource will be invalid.

Resource get_cached_ref(String path)

Parameters

path String

get_dependencies(String)

Returns the dependencies for the resource at the given path.

Note: The dependencies are returned with slices separated by ::. You can use String.get_slice to get their components.

for dependency in ResourceLoader.get_dependencies(path):
    print(dependency.get_slice("::", 0)) # Prints the UID.
    print(dependency.get_slice("::", 2)) # Prints the path.


PackedStringArray get_dependencies(String path)

Parameters

path String

get_recognized_extensions_for_type(String)

Returns the list of recognized extensions for a resource type.

PackedStringArray get_recognized_extensions_for_type(String type)

Parameters

type String

get_resource_uid(String)

Returns the ID associated with a given resource path, or -1 when no such ID exists.

int get_resource_uid(String path)

Parameters

path String

has_cached(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 ResourceLoader.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.

bool has_cached(String path)

Parameters

path String

list_directory(String)

Lists a directory (as example: "res://assets/enemies"), returning all resources contained within. The resource files are the original file names as visible in the editor before exporting.

PackedStringArray list_directory(String directory_path)

Parameters

directory_path String

load(String, String, int)

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. See CacheMode for details.

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 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 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(String path, String type_hint, int cache_mode)

Parameters

path String
type_hint String
cache_mode int

load_threaded_get(String)

Returns the resource loaded by ResourceLoader.load_threaded_request.

If this is called before the loading thread is done (i.e. ResourceLoader.load_threaded_get_status is not ResourceLoader.THREAD_LOAD_LOADED), the calling thread will be blocked until the resource has finished loading. However, it's recommended to use ResourceLoader.load_threaded_get_status to known when the load has actually completed.

Resource load_threaded_get(String path)

Parameters

path String

load_threaded_get_status(String, Array)

Returns the status of a threaded loading operation started with ResourceLoader.load_threaded_request for the resource at path. See ThreadLoadStatus for possible return values.

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

int load_threaded_get_status(String path, Array progress)

Parameters

path String
progress Array

load_threaded_request(String, String, bool, int)

Loads the resource using threads. If use_sub_threads is true, multiple threads will be used to load the resource, which makes loading faster, but may affect the main thread (and thus cause game slowdowns).

The cache_mode property defines whether and how the cache should be used or updated when loading the resource. See CacheMode for details.

int load_threaded_request(String path, String type_hint, bool use_sub_threads, int cache_mode)

Parameters

path String
type_hint String
use_sub_threads bool
cache_mode int

remove_resource_format_loader(ResourceFormatLoader)

Unregisters the given ResourceFormatLoader.

void remove_resource_format_loader(ResourceFormatLoader format_loader)

Parameters

format_loader ResourceFormatLoader

set_abort_on_missing_resources(bool)

Changes the behavior on missing sub-resources. The default behavior is to abort loading.

void set_abort_on_missing_resources(bool abort)

Parameters

abort bool