Index · Object → RefCounted → Resource

Resource

Base class for serializable objects.

Inherited by (105): AnimationAnimationLibraryAnimationNodeAnimationNodeStateMachinePlaybackAnimationNodeStateMachineTransitionAudioBusLayoutAudioEffectAudioStreamBitMapBoneMapButtonGroupCameraAttributesColorPaletteCompositorCompositorEffectCryptoKeyCurveCurve2DCurve3DEditorNode3DGizmoPlugin (+85 more)
Class Description

Resource is the base class for all Godot-specific resource types, serving primarily as data containers. Since they inherit from RefCounted, resources are reference-counted and freed when no longer in use. They can also be nested within other resources, and saved on disk. PackedScene, one of the most common Objects in a Godot project, is also a resource, uniquely capable of storing and instantiating the Nodes it contains as many times as desired.

In GDScript, resources can loaded from disk by their resource_path using load() or preload().

The engine keeps a global cache of all loaded resources, referenced by paths (see ResourceLoader.has_cached()). A resource will be cached when loaded for the first time and removed from cache once all references are released. When a resource is cached, subsequent loads using its path will return the cached reference.

Note: In C#, resources will not be freed instantly after they are no longer in use. Instead, garbage collection will run periodically and will free resources that are no longer in use. This means that unused resources will remain in memory for a while before being removed.

Properties

var resource_local_to_scene: bool = false

If true, the resource is duplicated for each instance of all scenes using it. At run-time, the resource can be modified in one scene without affecting other instances (see PackedScene.instantiate()).

Note: Changing this property at run-time has no effect on already created duplicate resources.

var resource_name: String = ""

An optional name for this resource. When defined, its value is displayed to represent the resource in the Inspector dock. For built-in scripts, the name is displayed as part of the tab name in the script editor.

Note: Some resource formats do not support resource names. You can still set the name in the editor or via code, but it will be lost when the resource is reloaded. For example, only built-in scripts can have a resource name, while scripts stored in separate files cannot.

var resource_path: String = ""

The unique path to this resource. If it has been saved to disk, the value will be its filepath. If the resource is exclusively contained within a scene, the value will be the PackedScene's filepath, followed by a unique identifier.

Note: Setting this property manually may fail if a resource with the same path has already been previously loaded. If necessary, use take_over_path().

var resource_scene_unique_id: String

A unique identifier relative to this resource's scene. If left empty, the ID is automatically generated when this resource is saved inside a PackedScene. If the resource is not inside a scene, this property is empty by default.

Note: When the PackedScene is saved, if multiple resources in the same scene use the same ID, only the earliest resource in the scene hierarchy keeps the original ID. The other resources are assigned new IDs from generate_scene_unique_id().

Note: Setting this property does not emit the changed signal.

Warning: When setting, the ID must only consist of letters, numbers, and underscores. Otherwise, it will fail and default to a randomly generated ID.

Methods

func _get_rid() -> RID

Override this method to return a custom RID when get_rid() is called.

func _reset_state() -> void

For resources that store state in non-exported properties, such as via Object._validate_property() or Object._get_property_list(), this method must be implemented to clear them.

func _set_path_cache(path: String) -> void

Override this method to execute additional logic after set_path_cache() is called on this object.

func _setup_local_to_scene() -> void

Override this method to customize the newly duplicated resource created from PackedScene.instantiate(), if the original's resource_local_to_scene is set to true.

Example: Set a random damage value to every local resource from an instantiated scene:

extends Resource

var damage = 0

func _setup_local_to_scene():
	damage = randi_range(10, 40)
func copy_from_resource(resource: Resource) -> Error

Copies the data from resource into this resource. Both resources must share the same class.

func duplicate(deep: bool = false) -> Resource

Duplicates this resource, returning a new resource with its exported or PROPERTY_USAGE_STORAGE properties copied from the original.

If deep is false, a shallow copy is returned: nested Array, Dictionary, and Resource properties are not duplicated and are shared with the original resource.

If deep is true, a deep copy is returned: all nested arrays, dictionaries, and packed arrays are also duplicated (recursively). Any Resource found inside will only be duplicated if it's local, like DEEP_DUPLICATE_INTERNAL used with duplicate_deep().

The following exceptions apply:

- Subresource properties with the PROPERTY_USAGE_ALWAYS_DUPLICATE flag are always duplicated (recursively or not, depending on deep).

- Subresource properties with the PROPERTY_USAGE_NEVER_DUPLICATE flag are never duplicated.

Note: For custom resources, this method will fail if Object._init() has been defined with required parameters.

Note: When duplicating with deep set to true, each resource found, including the one on which this method is called, will be only duplicated once and referenced as many times as needed in the duplicate. For instance, if you are duplicating resource A that happens to have resource B referenced twice, you'll get a new resource A' referencing a new resource B' twice.

func duplicate_deep(deep_subresources_mode: Resource.DeepDuplicateMode = 1) -> Resource

Duplicates this resource, deeply, like duplicate() when passing true, with extra control over how subresources are handled.

func emit_changed() -> void

Emits the changed signal. This method is called automatically for some built-in resources.

Note: For custom resources, it's recommended to call this method whenever a meaningful change occurs, such as a modified property. This ensures that custom Objects depending on the resource are properly updated.

var damage:
	set(new_value):
		if damage != new_value:
			damage = new_value
			emit_changed()
func generate_scene_unique_id() -> String

Generates a unique identifier for a resource to be contained inside a PackedScene, based on the current date, time, and a random value. The returned string is only composed of letters (a to y) and numbers (0 to 8). See also resource_scene_unique_id.

func get_id_for_path(path: String) -> String

From the internal cache for scene-unique IDs, returns the ID of this resource for the scene at path. If there is no entry, an empty string is returned. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending ResourceFormatLoader and ResourceFormatSaver.

Note: This method is only implemented when running in an editor context. At runtime, it returns an empty string.

func get_local_scene() -> Node

If resource_local_to_scene is set to true and the resource has been loaded from a PackedScene instantiation, returns the root Node of the scene where this resource is used. Otherwise, returns null.

func get_rid() -> RID

Returns the RID of this resource (or an empty RID). Many resources (such as Texture2D, Mesh, and so on) are high-level abstractions of resources stored in a specialized server (DisplayServer, RenderingServer, etc.), so this function will return the original RID.

func is_built_in() -> bool

Returns true if the resource is saved on disk as a part of another resource's file.

func reset_state() -> void

Makes the resource clear its non-exported properties. See also _reset_state(). Useful when implementing a custom resource format by extending ResourceFormatLoader and ResourceFormatSaver.

func set_id_for_path(path: String, id: String) -> void

In the internal cache for scene-unique IDs, sets the ID of this resource to id for the scene at path. If id is empty, the cache entry for path is cleared. Useful to keep scene-unique IDs the same when implementing a VCS-friendly custom resource format by extending ResourceFormatLoader and ResourceFormatSaver.

Note: This method is only implemented when running in an editor context.

func set_path_cache(path: String) -> void

Sets the resource's path to path without involving the resource cache. Useful for handling ResourceFormatLoader.CacheMode values when implementing a custom resource format by extending ResourceFormatLoader and ResourceFormatSaver.

func setup_local_to_scene() -> void

Calls _setup_local_to_scene(). If resource_local_to_scene is set to true, this method is automatically called from PackedScene.instantiate() by the newly duplicated resource within the scene instance.

func take_over_path(path: String) -> void

Sets the resource_path to path, potentially overriding an existing cache entry for this path. Further attempts to load an overridden resource by path will instead return this resource.

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

signal changed()

Emitted when the resource changes, usually when one of its properties is modified. See also emit_changed().

Note: This signal is not emitted automatically for properties of custom resources. If necessary, a setter needs to be created to emit the signal.

signal setup_local_to_scene_requested()

Emitted by a newly duplicated resource with resource_local_to_scene set to true.

Inherited from Object (2)

Enums & Constants

enum DeepDuplicateMode
DEEP_DUPLICATE_NONE = 0

No subresources at all are duplicated. This is useful even in a deep duplication to have all the arrays and dictionaries duplicated but still pointing to the original resources.

DEEP_DUPLICATE_INTERNAL = 1

Only subresources without a path or with a scene-local path will be duplicated.

DEEP_DUPLICATE_ALL = 2

Every subresource found will be duplicated, even if it has a non-local path. In other words, even potentially big resources stored separately will be duplicated.