Class ResourceLoader

Namespace

Godot

Assembly

GodotSharp.dll

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(string, string, CacheMode). If you want to load Images at run-time, you may use Load(string). If you want to import audio files, you can use the snippet described in Data.

public static class ResourceLoader

Inheritance

object

ResourceLoader

Inherited Members

object.GetType()

object.MemberwiseClone()

object.ToString()

object.Equals(object)

object.Equals(object, object)

object.ReferenceEquals(object, object)

object.GetHashCode()

Properties

Singleton

public static ResourceLoaderInstance Singleton { get; }

Property Value

ResourceLoaderInstance

Methods

AddResourceFormatLoader(ResourceFormatLoader, bool)

Registers a new ResourceFormatLoader. The ResourceLoader will use the ResourceFormatLoader as described in Load(string, string, CacheMode).

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

public static void AddResourceFormatLoader(ResourceFormatLoader formatLoader, bool atFront = false)

Parameters

formatLoader ResourceFormatLoader

atFront bool

Exists(string, string)

Returns whether a recognized resource exists for the given path.

An optional typeHint 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.

public static bool Exists(string path, string typeHint = "")

Parameters

path string

typeHint string

Returns

bool

GetDependencies(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 dep in ResourceLoader.get_dependencies(path):
      print(dep.get_slice("::", 0)) # Prints UID.
      print(dep.get_slice("::", 2)) # Prints path.

public static string[] GetDependencies(string path)

Parameters

path string

Returns

string[]

GetRecognizedExtensionsForType(string)

Returns the list of recognized extensions for a resource type.

public static string[] GetRecognizedExtensionsForType(string type)

Parameters

type string

Returns

string[]

GetResourceUid(string)

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

public static long GetResourceUid(string path)

Parameters

path string

Returns

long

HasCached(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(string, string, CacheMode) method will use the cached version. The cached resource can be overridden by using TakeOverPath(string) on a new resource for that same path.

public static bool HasCached(string path)

Parameters

path string

Returns

bool

Load(string, string, CacheMode)

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 typeHint 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 cacheMode property defines whether and how the cache should be used or updated when loading the resource. See ResourceLoader.CacheMode for details.

Returns an empty resource if no ResourceFormatLoader could handle the file.

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.

public static Resource Load(string path, string typeHint = "", ResourceLoader.CacheMode cacheMode = CacheMode.Reuse)

Parameters

path string

typeHint string

cacheMode ResourceLoader.CacheMode

Returns

Resource

LoadThreadedGet(string)

Returns the resource loaded by LoadThreadedRequest(string, string, bool, CacheMode).

If this is called before the loading thread is done (i.e. LoadThreadedGetStatus(string, Array) is not Loaded), the calling thread will be blocked until the resource has finished loading.

public static Resource LoadThreadedGet(string path)

Parameters

path string

Returns

Resource

LoadThreadedGetStatus(string, Array)

Returns the status of a threaded loading operation started with LoadThreadedRequest(string, string, bool, CacheMode) for the resource at path. See ResourceLoader.ThreadLoadStatus for possible return values.

An array variable can optionally be passed via progress, and will return a one-element array containing the percentage of completion of the threaded loading.

public static ResourceLoader.ThreadLoadStatus LoadThreadedGetStatus(string path, Array progress = null)

Parameters

path string

progress Array

Returns

ResourceLoader.ThreadLoadStatus

LoadThreadedRequest(string, string, bool, CacheMode)

Loads the resource using threads. If useSubThreads 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 cacheMode property defines whether and how the cache should be used or updated when loading the resource. See ResourceLoader.CacheMode for details.

public static Error LoadThreadedRequest(string path, string typeHint = "", bool useSubThreads = false, ResourceLoader.CacheMode cacheMode = CacheMode.Reuse)

Parameters

path string

typeHint string

useSubThreads bool

cacheMode ResourceLoader.CacheMode

Returns

Error

Load<T>(string, string, CacheMode)

Loads a resource at the given path, caching the result for further access. The registered ResourceFormatLoader instances 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 typeHint 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 cacheMode property defines whether and how the cache should be used or updated when loading the resource. See ResourceLoader.CacheMode for details. Returns an empty resource if no ResourceFormatLoader could handle the file.

public static T Load<T>(string path, string typeHint = null, ResourceLoader.CacheMode cacheMode = CacheMode.Reuse) where T : class

Parameters

path string

typeHint string

cacheMode ResourceLoader.CacheMode

Returns

T

Type Parameters

T

The type to cast to. Should be a descendant of Resource.

Exceptions

InvalidCastException

The loaded resource can't be casted to the given type T.

RemoveResourceFormatLoader(ResourceFormatLoader)

Unregisters the given ResourceFormatLoader.

public static void RemoveResourceFormatLoader(ResourceFormatLoader formatLoader)

Parameters

formatLoader ResourceFormatLoader

SetAbortOnMissingResources(bool)

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

public static void SetAbortOnMissingResources(bool abort)

Parameters

abort bool