Up to date

This page is up to date for Godot 4.0. If you still find outdated information, please open an issue.

Resource

Inherits: RefCounted < Object

Inherited By: Animation, AnimationLibrary, AnimationNode, AnimationNodeStateMachinePlayback, AnimationNodeStateMachineTransition, AudioBusLayout, AudioEffect, AudioStream, BitMap, BoneMap, ButtonGroup, CameraAttributes, CryptoKey, Curve, Curve2D, Curve3D, EditorNode3DGizmoPlugin, EditorSettings, Environment, Font, GDExtension, GLTFAccessor, GLTFAnimation, GLTFBufferView, GLTFCamera, GLTFDocument, GLTFDocumentExtension, GLTFLight, GLTFMesh, GLTFNode, GLTFSkeleton, GLTFSkin, GLTFSpecGloss, GLTFState, GLTFTexture, GLTFTextureSampler, Gradient, Image, ImporterMesh, InputEvent, JSON, LabelSettings, LightmapGIData, Material, Mesh, MeshLibrary, MissingResource, MultiMesh, NavigationMesh, NavigationPolygon, Noise, Occluder3D, OccluderPolygon2D, OggPacketSequence, OpenXRAction, OpenXRActionMap, OpenXRActionSet, OpenXRInteractionProfile, OpenXRIPBinding, PackedDataContainer, PackedScene, PhysicsMaterial, PolygonPathFinder, RDShaderFile, RDShaderSPIRV, RichTextEffect, SceneReplicationConfig, Script, Shader, ShaderInclude, Shape2D, Shape3D, Shortcut, SkeletonModification2D, SkeletonModificationStack2D, SkeletonProfile, Skin, Sky, SpriteFrames, StyleBox, SyntaxHighlighter, Texture, Theme, TileMapPattern, TileSet, TileSetSource, Translation, VideoStream, VideoStreamPlayback, VisualShaderNode, VoxelGIData, World2D, World3D, X509Certificate

Base class for serializable objects.

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. Once loaded from disk, further attempts to load a resource by resource_path returns the same reference. 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.

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 linger on for a while before being removed.

Tutorials

• Resources

• When and how to avoid using nodes for everything

Properties

Methods

Signals

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.

setup_local_to_scene_requested ( )

Emitted when setup_local_to_scene is called, usually by a newly duplicated resource with resource_local_to_scene set to true. Custom behavior can be defined by connecting this signal.

Property Descriptions

bool resource_local_to_scene = false

• void set_local_to_scene ( bool value )

• bool is_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.

String resource_name = ""

• void set_name ( String value )

• String get_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.

String resource_path = ""

• void set_path ( String value )

• String get_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 take_over_path.

Method Descriptions

RID _get_rid ( ) virtual

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

Resource duplicate ( bool subresources=false ) 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 from the original resource. If subresources is true, a deep copy is returned; nested subresources will be duplicated and are not shared.

Subresource properties with the @GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE flag are always duplicated even with subresources set to false, and properties with the @GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE flag are never duplicated even with subresources set to true.

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

void emit_changed ( )

Emits the changed signal. This method is called automatically for 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()

Node get_local_scene ( ) 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.

RID get_rid ( ) 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.

void setup_local_to_scene ( )

Emits the setup_local_to_scene_requested signal. If resource_local_to_scene is set to true, this method is called from PackedScene.instantiate by the newly duplicated resource within the scene instance.

For most resources, this method performs no logic of its own. Custom behavior can be defined by connecting setup_local_to_scene_requested from a script, not by overriding this method.

Example: Assign a random value to health for every duplicated Resource from an instantiated scene, excluding the original.

extends Resource
var health = 0
func _init():
    setup_local_to_scene_requested.connect(randomize_health)
func randomize_health():
    health = randi_range(10, 40)

void take_over_path ( String path )

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.