ResourceLoader

package
v0.0.0-...-535787f Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 16, 2025 License: MIT Imports: 25 Imported by: 0

Documentation

Overview

A singleton used to load resource files from the filesystem.

It uses the many graphics.gd/classdb/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 [graphics.gd/classdb/Image]s at run-time, you may use graphics.gd/classdb/Image.Instance.Load. If you want to import audio files, you can use the snippet described in graphics.gd/classdb/AudioStreamMP3.Instance.Data.

Note: Non-resource files such as plain text files cannot be read using graphics.gd/classdb/ResourceLoader. Use graphics.gd/classdb/FileAccess for those files instead, and be aware that non-resource files are not exported by default (see notes in the graphics.gd/classdb/FileAccess class description for instructions on exporting them).

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func AddResourceFormatLoader 

func AddResourceFormatLoader(format_loader ResourceFormatLoader.Instance, at_front bool)

Registers a new graphics.gd/classdb/ResourceFormatLoader. The ResourceLoader will use the ResourceFormatLoader as described in Load.

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

func AddResourceFormatLoaderOptions 

func AddResourceFormatLoaderOptions(format_loader ResourceFormatLoader.Instance, at_front bool)

Registers a new graphics.gd/classdb/ResourceFormatLoader. The ResourceLoader will use the ResourceFormatLoader as described in Load.

This method is performed implicitly for ResourceFormatLoaders written in GDScript (see graphics.gd/classdb/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, type_hint string) bool

Returns whether a recognized resource exists for the given 'path'.

An optional 'type_hint' can be used to further specify the graphics.gd/classdb/Resource type that should be handled by the graphics.gd/classdb/ResourceFormatLoader. Anything that inherits from graphics.gd/classdb/Resource can be used as a type hint, for example graphics.gd/classdb/Image.

Note: If you use graphics.gd/classdb/Resource.Instance.TakeOverPath, this method will return true for the taken path even if the resource wasn't saved (i.e. exists only in resource cache).

func ExistsOptions 

func ExistsOptions(path string, type_hint string) bool

Returns whether a recognized resource exists for the given 'path'.

An optional 'type_hint' can be used to further specify the graphics.gd/classdb/Resource type that should be handled by the graphics.gd/classdb/ResourceFormatLoader. Anything that inherits from graphics.gd/classdb/Resource can be used as a type hint, for example graphics.gd/classdb/Image.

Note: If you use graphics.gd/classdb/Resource.Instance.TakeOverPath, this method will return true for the taken path even if the resource wasn't saved (i.e. exists only in resource cache).

func GetCachedRef 

func GetCachedRef(path string) Resource.Instance

Returns the cached resource reference for the given 'path'.

Note: If the resource is not cached, the returned graphics.gd/classdb/Resource will be invalid.

func GetDependencies 

func GetDependencies(path string) []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.

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 -1 when no such ID exists.

func HasCached 

func HasCached(path string) bool

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 graphics.gd/classdb/Resource.Instance.TakeOverPath on a new resource for that same path.

func ListDirectory 

func ListDirectory(directory_path string) []string

Lists a directory, returning all resources and subdirectories contained within. The resource files have the original file names as visible in the editor before exporting. The directories have "/" appended.

Note: The order of files and directories returned by this method is not deterministic, and can vary between operating systems.

Note: To normally traverse the filesystem, see graphics.gd/classdb/DirAccess.

func Load 

func Load(path string, type_hint string) Resource.Instance

Loads a resource at the given 'path', caching the result for further access.

The registered [graphics.gd/classdb/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 'type_hint' can be used to further specify the graphics.gd/classdb/Resource type that should be handled by the graphics.gd/classdb/ResourceFormatLoader. Anything that inherits from graphics.gd/classdb/Resource can be used as a type hint, for example graphics.gd/classdb/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 graphics.gd/classdb/ResourceFormatLoader could handle the file, and prints an error if no file is found at the specified path.

GDScript has a simplified [graphics.gd/classdb/@GDScript.Instance.Load] built-in method which can be used in most situations, leaving the use of graphics.gd/classdb/ResourceLoader for more advanced scenarios.

Note: If graphics.gd/classdb/ProjectSettings "editor/export/convert_text_resources_to_binary" is true, [graphics.gd/classdb/@GDScript.Instance.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 graphics.gd/classdb/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.

func LoadOptions 

func LoadOptions(path string, type_hint string, cache_mode CacheMode) Resource.Instance

Loads a resource at the given 'path', caching the result for further access.

The registered [graphics.gd/classdb/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 'type_hint' can be used to further specify the graphics.gd/classdb/Resource type that should be handled by the graphics.gd/classdb/ResourceFormatLoader. Anything that inherits from graphics.gd/classdb/Resource can be used as a type hint, for example graphics.gd/classdb/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 graphics.gd/classdb/ResourceFormatLoader could handle the file, and prints an error if no file is found at the specified path.

GDScript has a simplified [graphics.gd/classdb/@GDScript.Instance.Load] built-in method which can be used in most situations, leaving the use of graphics.gd/classdb/ResourceLoader for more advanced scenarios.

Note: If graphics.gd/classdb/ProjectSettings "editor/export/convert_text_resources_to_binary" is true, [graphics.gd/classdb/@GDScript.Instance.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 graphics.gd/classdb/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.

func LoadThreadedGet 

func LoadThreadedGet(path string) Resource.Instance

Returns the resource loaded by LoadThreadedRequest.

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

func LoadThreadedRequest 

func LoadThreadedRequest(path string, type_hint string, use_sub_threads bool) error

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' parameter defines whether and how the cache should be used or updated when loading the resource.

func LoadThreadedRequestOptions 

func LoadThreadedRequestOptions(path string, type_hint string, use_sub_threads bool, cache_mode CacheMode) error

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' parameter defines whether and how the cache should be used or updated when loading the resource.

func RemoveResourceFormatLoader 

func RemoveResourceFormatLoader(format_loader ResourceFormatLoader.Instance)

Unregisters the given graphics.gd/classdb/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 int //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 [CacheModeReuse].
	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 [CacheModeReuse], 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 [CacheModeIgnore], but propagated recursively down the tree of dependencies (external resources).
	CacheModeIgnoreDeep CacheMode = 3
	// Like [CacheModeReplace], but propagated recursively down the tree of dependencies (external resources).
	CacheModeReplaceDeep CacheMode = 4
)

type Extension 

type Extension[T gdclass.Interface] struct{ gdclass.Extension[T, Instance] }

Extension can be embedded in a new struct to create an extension of this class. T should be the type that is embedding this Extension

func (*Extension[T]) AsObject 

func (self *Extension[T]) AsObject() [1]gd.Object

type ID 

type ID Object.ID

ID is a typed object ID (reference) to an instance of this class, use it to store references to objects with unknown lifetimes, as an ID will not panic on use if the underlying object has been destroyed.

func (ID) Instance 

func (id ID) Instance() (Instance, bool)

type Instance 

type Instance [1]gdclass.ResourceLoader

Instance of the class with convieniently typed arguments and results.

func (Instance) AsObject 

func (self Instance) AsObject() [1]gd.Object

func (Instance) ID 

func (self Instance) ID() ID

func (*Instance) SetObject 

func (self *Instance) SetObject(obj [1]gd.Object) bool

func (Instance) Virtual 

func (self Instance) Virtual(name string) reflect.Value

type ThreadLoadStatus 

type ThreadLoadStatus int //gd:ResourceLoader.ThreadLoadStatus

const (
	// The resource is invalid, or has not been loaded with [Instance.LoadThreadedRequest].
	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 [Instance.LoadThreadedGet].
	ThreadLoadLoaded ThreadLoadStatus = 3
)

func LoadThreadedGetStatus 

func LoadThreadedGetStatus(path string, progress []float32) ThreadLoadStatus

Returns the status of a threaded loading operation started with LoadThreadedRequest 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 graphics.gd/classdb/Node.Instance.Process, instead of a loop).

func LoadThreadedGetStatusOptions 

func LoadThreadedGetStatusOptions(path string, progress []float32) ThreadLoadStatus

Returns the status of a threaded loading operation started with LoadThreadedRequest 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 graphics.gd/classdb/Node.Instance.Process, instead of a loop).

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.