ResourceLoader

Documentation

Overview

Package ResourceLoader provides methods for working with ResourceLoader object instances.

Index

• func AddResourceFormatLoader(format_loader [1]gdclass.ResourceFormatLoader)
• func Advanced() class
• func Exists(path string) bool
• func GetDependencies(path string) []string
• func GetRecognizedExtensionsForType(atype string) []string
• func GetResourceUid(path string) int
• func HasCached(path string) bool
• func Load(path string) [1]gdclass.Resource
• func LoadThreadedGet(path string) [1]gdclass.Resource
• func LoadThreadedGetStatus(path string) gdclass.ResourceLoaderThreadLoadStatus
• func LoadThreadedRequest(path string) error
• func RemoveResourceFormatLoader(format_loader [1]gdclass.ResourceFormatLoader)
• func SetAbortOnMissingResources(abort bool)
• type CacheMode
• type ThreadLoadStatus

Functions

func AddResourceFormatLoader

func AddResourceFormatLoader(format_loader [1]gdclass.ResourceFormatLoader)

Registers a new [ResourceFormatLoader]. The ResourceLoader will use the ResourceFormatLoader as described in [method load]. This method is performed implicitly for ResourceFormatLoaders written in GDScript (see [ResourceFormatLoader] for more information).

func Advanced

func Advanced() class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

func Exists

func Exists(path string) bool

Returns whether a recognized resource exists for the given [param path]. An optional [param 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]. [b]Note:[/b] If you use [method Resource.take_over_path], this method will return [code]true[/code] for the taken path even if the resource wasn't saved (i.e. exists only in resource cache).

func GetDependencies

func GetDependencies(path string) []string

Returns the dependencies for the resource at the given [param path]. [b]Note:[/b] The dependencies are returned with slices separated by [code]::[/code]. You can use [method String.get_slice] to get their components. [codeblock] for dep in ResourceLoader.get_dependencies(path):

print(dep.get_slice("::", 0)) # Prints UID.
print(dep.get_slice("::", 2)) # Prints path.

[/codeblock]

func GetRecognizedExtensionsForType

func GetRecognizedExtensionsForType(atype string) []string

Returns the list of recognized extensions for a resource type.

func GetResourceUid

func GetResourceUid(path string) int

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

func HasCached

func HasCached(path string) bool

Returns whether a cached resource is available for the given [param path]. Once a resource has been loaded by the engine, it is cached in memory for faster access, and future calls to the [method load] method will use the cached version. The cached resource can be overridden by using [method Resource.take_over_path] on a new resource for that same path.

func Load

func Load(path string) [1]gdclass.Resource

Loads a resource at the given [param path], caching the result for further access. The registered [ResourceFormatLoader]s 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 [param 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 [param cache_mode] property defines whether and how the cache should be used or updated when loading the resource. See [enum 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 [method @GDScript.load] built-in method which can be used in most situations, leaving the use of [ResourceLoader] for more advanced scenarios. [b]Note:[/b] If [member ProjectSettings.editor/export/convert_text_resources_to_binary] is [code]true[/code], [method @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 [member ProjectSettings.editor/export/convert_text_resources_to_binary] to [code]false[/code]. [b]Note:[/b] Relative paths will be prefixed with [code]"res://"[/code] before loading, to avoid unexpected results make sure your paths are absolute.

func LoadThreadedGet

func LoadThreadedGet(path string) [1]gdclass.Resource

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

func LoadThreadedGetStatus

func LoadThreadedGetStatus(path string) gdclass.ResourceLoaderThreadLoadStatus

Returns the status of a threaded loading operation started with [method load_threaded_request] for the resource at [param path]. See [enum ThreadLoadStatus] for possible return values. An array variable can optionally be passed via [param progress], and will return a one-element array containing the percentage of completion of the threaded loading. [b]Note:[/b] The recommended way of using this method is to call it during different frames (e.g., in [method Node._process], instead of a loop).

func LoadThreadedRequest

func LoadThreadedRequest(path string) error

Loads the resource using threads. If [param use_sub_threads] is [code]true[/code], 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 [param cache_mode] property defines whether and how the cache should be used or updated when loading the resource. See [enum CacheMode] for details.

func RemoveResourceFormatLoader

func RemoveResourceFormatLoader(format_loader [1]gdclass.ResourceFormatLoader)

Unregisters the given [ResourceFormatLoader].

func SetAbortOnMissingResources

func SetAbortOnMissingResources(abort bool)

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

Types

type CacheMode

type CacheMode = gdclass.ResourceLoaderCacheMode //gd:ResourceLoader.CacheMode

const (
	/*Neither the main resource (the one requested to be loaded) nor any of its subresources are retrieved from cache nor stored into it. Dependencies (external resources) are loaded with [constant CACHE_MODE_REUSE].*/
	CacheModeIgnore CacheMode = 0
	/*The main resource (the one requested to be loaded), its subresources, and its dependencies (external resources) are retrieved from cache if present, instead of loaded. Those not cached are loaded and then stored into the cache. The same rules are propagated recursively down the tree of dependencies (external resources).*/
	CacheModeReuse CacheMode = 1
	/*Like [constant CACHE_MODE_REUSE], but the cache is checked for the main resource (the one requested to be loaded) as well as for each of its subresources. Those already in the cache, as long as the loaded and cached types match, have their data refreshed from storage into the already existing instances. Otherwise, they are recreated as completely new objects.*/
	CacheModeReplace CacheMode = 2
	/*Like [constant CACHE_MODE_IGNORE], but propagated recursively down the tree of dependencies (external resources).*/
	CacheModeIgnoreDeep CacheMode = 3
	/*Like [constant CACHE_MODE_REPLACE], but propagated recursively down the tree of dependencies (external resources).*/
	CacheModeReplaceDeep CacheMode = 4
)

type ThreadLoadStatus

type ThreadLoadStatus = gdclass.ResourceLoaderThreadLoadStatus //gd:ResourceLoader.ThreadLoadStatus

const (
	/*The resource is invalid, or has not been loaded with [method load_threaded_request].*/
	ThreadLoadInvalidResource ThreadLoadStatus = 0
	/*The resource is still being loaded.*/
	ThreadLoadInProgress ThreadLoadStatus = 1
	/*Some error occurred during loading and it failed.*/
	ThreadLoadFailed ThreadLoadStatus = 2
	/*The resource was loaded successfully and can be accessed via [method load_threaded_get].*/
	ThreadLoadLoaded ThreadLoadStatus = 3
)