Table of Contents

Class Resource

Base class for serializable objects.

Inheritance
Resource
Derived

Remarks

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 @GDScript.load or @GDScript.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.

See Also

Resources
When and how to avoid using nodes for everything

Properties

resource_local_to_scene

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_local_to_scene : bool = false

Property Value

bool

Remarks

  • void set_local_to_scene(bool value)
  • bool is_local_to_scene

resource_name

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_name : String = ""

Property Value

String

Remarks

resource_path

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 Resource.take_over_path.

var resource_path : String = ""

Property Value

String

Remarks

resource_scene_unique_id

An unique identifier relative to the 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.

var resource_scene_unique_id : String

Property Value

String

Remarks

  • void set_scene_unique_id(String value)
  • String get_scene_unique_id

Methods

_get_rid

Qualifiers: virtualconst

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

RID _get_rid

_reset_state

Qualifiers: virtual

For resources that use a variable number of properties, either via Object._validate_property or _get_property_list, this method should be implemented to correctly clear the resource's state.

void _reset_state

_set_path_cache(String)

Qualifiers: virtualconst

Sets the resource's path to path without involving the resource cache.

void _set_path_cache(String path)

Parameters

path String

_setup_local_to_scene

Qualifiers: virtual

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)


void _setup_local_to_scene

duplicate(bool)

Qualifiers: const

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

If subresources is false, a shallow copy is returned; nested resources within subresources are not duplicated and are shared with the original resource (with one exception; see below). If subresources is true, a deep copy is returned; nested subresources will be duplicated and are not shared (with two exceptions; see below).

subresources is usually respected, with the following exceptions:

  • Subresource properties with the @GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE flag are always duplicated.

  • Subresource properties with the @GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE flag are never duplicated.

  • Subresources inside Array and Dictionary properties are never duplicated.

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

Resource duplicate(bool subresources)

Parameters

subresources bool

emit_changed

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


void emit_changed

generate_scene_unique_id

Qualifiers: static

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.

String generate_scene_unique_id

get_id_for_path(String)

Qualifiers: const

Returns the unique identifier for the resource with the given path from the resource cache. If the resource is not loaded and cached, an empty string is returned.

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

String get_id_for_path(String path)

Parameters

path String

get_local_scene

Qualifiers: const

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.

Node get_local_scene

get_rid

Qualifiers: const

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.

RID get_rid

is_built_in

Qualifiers: const

Returns true if the resource is built-in (from the engine) or false if it is user-defined.

bool is_built_in

reset_state

For resources that use a variable number of properties, either via Object._validate_property or _get_property_list, override _reset_state to correctly clear the resource's state.

void reset_state

set_id_for_path(String, String)

Sets the unique identifier to id for the resource with the given path in the resource cache. If the unique identifier is empty, the cache entry using path is removed if it exists.

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

void set_id_for_path(String path, String id)

Parameters

path String
id String

set_path_cache(String)

Sets the resource's path to path without involving the resource cache.

void set_path_cache(String path)

Parameters

path String

setup_local_to_scene

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.

void setup_local_to_scene

take_over_path(String)

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.

void take_over_path(String path)

Parameters

path String

Events

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 changed

setup_local_to_scene_requested

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

signal setup_local_to_scene_requested