Index · Object → RefCounted → ResourceFormatLoader

ResourceFormatLoader

Loads a specific resource type from a file.

Class Description

Godot loads resources in the editor or in exported games using ResourceFormatLoaders. They are queried automatically via the ResourceLoader singleton, or when a resource with internal dependencies is loaded. Each file type may load as a different resource type, so multiple ResourceFormatLoaders are registered in the engine.

Extending this class allows you to define your own loader. Be sure to respect the documented return types and values. You should give it a global class name with class_name for it to be registered. Like built-in ResourceFormatLoaders, it will be called automatically when loading resources of its handled type(s). You may also implement a ResourceFormatSaver.

Note: You can also extend EditorImportPlugin if the resource type you need exists but Godot is unable to load its format. Choosing one way over another depends on if the format is suitable or not for the final exported game. For example, it's better to import .png textures as .ctex (CompressedTexture2D) first, so they can be loaded with better efficiency on the graphics card.

Methods

func _exists(path: String) -> bool
func _get_classes_used(path: String) -> PackedStringArray
func _get_dependencies(path: String, add_types: bool) -> PackedStringArray

Should return the dependencies for the resource at the given path. Each dependency is a string composed of one to three sections separated by ::, with trailing empty sections omitted:

- The first section should contain the UID if the resource has one. Otherwise, it should contain the file path.

- The second section should contain the class name of the dependency if add_types is true. Otherwise, it should be empty.

- The third section should contain the fallback path if the resource has a UID. Otherwise, it should be empty.

func _get_dependencies(path, add_types):
	return [
		"uid://fqgvuwrkuixh::Script::res://script.gd",
		"uid://fqgvuwrkuixh::::res://script.gd",
		"res://script.gd::Script",
		"res://script.gd",
	]

Note: Custom resource types defined by scripts aren't known by the ClassDB, so "Resource" can be used for the class name.

func _get_recognized_extensions() -> PackedStringArray

Gets the list of extensions for files this loader is able to read.

func _get_resource_script_class(path: String) -> String

Returns the script class name associated with the Resource under the given path. If the resource has no script or the script isn't a named class, it should return "".

func _get_resource_type(path: String) -> String

Gets the class name of the resource associated with the given path. If the loader cannot handle it, it should return "".

Note: Custom resource types defined by scripts aren't known by the ClassDB, so you might just return "Resource" for them.

func _get_resource_uid(path: String) -> int

Should return the unique ID for the resource associated with the given path. If this method is not overridden, a .uid file is generated along with the resource file, containing the unique ID.

func _handles_type(type: StringName) -> bool

Tells which resource class this loader can load.

Note: Custom resource types defined by scripts aren't known by the ClassDB, so you might just handle "Resource" for them.

func _load(path: String, original_path: String, use_sub_threads: bool, cache_mode: int) -> Variant

Loads a resource when the engine finds this loader to be compatible. If the loaded resource is the result of an import, original_path will target the source file. Returns a Resource object on success, or an Error constant in case of failure.

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

func _recognize_path(path: String, type: StringName) -> bool

Tells whether or not this loader should load a resource from its resource path for a given type.

If it is not implemented, the default behavior returns whether the path's extension is within the ones provided by _get_recognized_extensions(), and if the type is within the ones provided by _get_resource_type().

func _rename_dependencies(path: String, renames: Dictionary) -> Error

If implemented, renames dependencies within the given resource and saves it. renames is a dictionary { String => String } mapping old dependency paths to new paths.

Returns OK on success, or an Error constant in case of failure.

Inherited from RefCounted (4)
func init_ref() -> bool
func reference() -> bool
func unreference() -> bool
Inherited from Object (62)
func _get(property: StringName) -> Variant
func _get_property_list() -> Dictionary[]
func _init() -> void
func _iter_get(iter: Variant) -> Variant
func _iter_init(iter: Array) -> bool
func _iter_next(iter: Array) -> bool
func _notification(what: int) -> void
func _set(property: StringName, value: Variant) -> bool
func _to_string() -> String
func _validate_property(property: Dictionary) -> void
func add_user_signal(signal: String, arguments: Array = []) -> void
func call(method: StringName) -> Variant
func callv(method: StringName, arg_array: Array) -> Variant
func cancel_free() -> void
func connect(signal: StringName, callable: Callable, flags: int = 0) -> Error
func disconnect(signal: StringName, callable: Callable) -> void
func emit_signal(signal: StringName) -> Error
func free() -> void
func get(property: StringName) -> Variant
func get_class() -> String
func get_incoming_connections() -> Dictionary[]
func get_indexed(property_path: NodePath) -> Variant
func get_meta(name: StringName, default: Variant = null) -> Variant
func get_meta_list() -> StringName[]
func get_method_list() -> Dictionary[]
func get_property_list() -> Dictionary[]
func get_signal_connection_list(signal: StringName) -> Dictionary[]
func get_signal_list() -> Dictionary[]
func has_meta(name: StringName) -> bool
func has_method(method: StringName) -> bool
func has_signal(signal: StringName) -> bool
func is_class(class: StringName) -> bool
func is_connected(signal: StringName, callable: Callable) -> bool
func notification(what: int, reversed: bool = false) -> void
func remove_meta(name: StringName) -> void
func remove_user_signal(signal: StringName) -> void
func set(property: StringName, value: Variant) -> void
func set_block_signals(enable: bool) -> void
func set_deferred(property: StringName, value: Variant) -> void
func set_indexed(property_path: NodePath, value: Variant) -> void
func set_message_translation(enable: bool) -> void
func set_meta(name: StringName, value: Variant) -> void
func set_script(script: Variant) -> void
func set_translation_domain(domain: StringName) -> void
func to_string() -> String
func tr(message: StringName, context: StringName = &"") -> String
func tr_n(message: StringName, plural_message: StringName, n: int, context: StringName = &"") -> String

Signals

Inherited from Object (2)

Enums & Constants

enum CacheMode
CACHE_MODE_IGNORE = 0

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

CACHE_MODE_REUSE = 1

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

CACHE_MODE_REPLACE = 2

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

CACHE_MODE_IGNORE_DEEP = 3

Like CACHE_MODE_IGNORE, but propagated recursively down the tree of dependencies (external resources).

CACHE_MODE_REPLACE_DEEP = 4

Like CACHE_MODE_REPLACE, but propagated recursively down the tree of dependencies (external resources).