Resource

package
v0.0.0-...-503a9e4 Latest Latest
Warning

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

 Go to latest Published: Sep 14, 2025 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

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

In GDScript, resources can loaded from disk by their Instance.ResourcePath using [graphics.gd/classdb/@GDScript.Instance.Load] or [graphics.gd/classdb/@GDScript.Instance.Preload].

The engine keeps a global cache of all loaded resources, referenced by paths (see graphics.gd/classdb/ResourceLoader.HasCached). 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.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func Duplicate 

func Duplicate[T Any](res T) T

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

func GenerateSceneUniqueId 

func GenerateSceneUniqueId() string

Generates a unique identifier for a resource to be contained inside a graphics.gd/classdb/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 Instance.ResourceSceneUniqueId.

func Load 

func Load[T Any, P string | Path.ToResource](path_to_resource P) T

Load behaves like the builtin "load" function in GDScript. It can also be used to preload a resource if called before startup.

Types

type Advanced 

type Advanced = class

Advanced exposes a 1:1 low-level instance of the class, undocumented, for those who know what they are doing.

type Any 

type Any interface {
	gd.IsClass
	AsResource() Instance
}

type Expanded 

type Expanded [1]gdclass.Resource

func (Expanded) Duplicate 

func (self Expanded) Duplicate(subresources bool) Instance

Duplicates this resource, returning a new resource with its exported or [PropertyUsageStorage] 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 [PropertyUsageAlwaysDuplicate] flag are always duplicated.

- Subresource properties with the [PropertyUsageNeverDuplicate] flag are never duplicated.

- Subresources inside slice and data structure properties are never duplicated.

Note: For custom resources, this method will fail if graphics.gd/classdb/Object.Instance.Init has been defined with required parameters.

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]See Interface for methods that can be overridden by T.

func (*Extension[T]) AsObject 

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

func (*Extension[T]) AsRefCounted 

func (self *Extension[T]) AsRefCounted() [1]gd.RefCounted

func (*Extension[T]) AsResource 

func (self *Extension[T]) AsResource() Instance

type ID 

type ID = gd.RID

ID that uniquely identifies a resource.

func AllocateID 

func AllocateID() ID

New allocates a unique ID which can be used by the implementation to construct an RID. This is used mainly from native extensions to implement servers.

func Int64 

func Int64(id int64) ID

Int64 returns a resource ID from the given int64.

type Implementation 

type Implementation = implementation

Implementation implements Interface with empty methods.

type Instance 

type Instance [1]gdclass.Resource

Instance of the class with convieniently typed arguments and results. 

var Nil Instance

Nil is a nil/null instance of the class. Equivalent to the zero value.

func New 

func New() Instance

func (Instance) AsObject 

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

func (Instance) AsRefCounted 

func (self Instance) AsRefCounted() [1]gd.RefCounted

func (Instance) AsResource 

func (self Instance) AsResource() Instance

func (Instance) Duplicate 

func (self Instance) Duplicate() Instance

Duplicates this resource, returning a new resource with its exported or [PropertyUsageStorage] 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 [PropertyUsageAlwaysDuplicate] flag are always duplicated.

- Subresource properties with the [PropertyUsageNeverDuplicate] flag are never duplicated.

- Subresources inside slice and data structure properties are never duplicated.

Note: For custom resources, this method will fail if graphics.gd/classdb/Object.Instance.Init has been defined with required parameters.

func (Instance) EmitChanged 

func (self Instance) EmitChanged()

Emits the Instance.OnChanged 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 [graphics.gd/classdb/Object]s depending on the resource are properly updated.

func (Instance) GetIdForPath 

func (self Instance) GetIdForPath(path string) string

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.

func (Instance) GetRid 

func (self Instance) GetRid() ID

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

func (Instance) IsBuiltIn 

func (self Instance) IsBuiltIn() bool

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

func (Instance) OnChanged 

func (self Instance) OnChanged(cb func(), flags ...Signal.Flags)

func (Instance) OnSetupLocalToSceneRequested 

func (self Instance) OnSetupLocalToSceneRequested(cb func(), flags ...Signal.Flags)

func (Instance) ResetState 

func (self Instance) ResetState()

For resources that use a variable number of properties, either via graphics.gd/classdb/Object.Instance.ValidateProperty or graphics.gd/classdb/Object.Instance.GetPropertyList, override [Interface.ResetState] to correctly clear the resource's state.

func (Instance) ResourceLocalToScene 

func (self Instance) ResourceLocalToScene() bool

func (Instance) ResourceName 

func (self Instance) ResourceName() string

func (Instance) ResourcePath 

func (self Instance) ResourcePath() string

func (Instance) ResourceSceneUniqueId 

func (self Instance) ResourceSceneUniqueId() string

func (Instance) SetIdForPath 

func (self Instance) SetIdForPath(path string, id 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.

func (*Instance) SetObject 

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

func (Instance) SetPathCache 

func (self Instance) SetPathCache(path string)

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

func (Instance) SetResourceLocalToScene 

func (self Instance) SetResourceLocalToScene(value bool)

func (Instance) SetResourceName 

func (self Instance) SetResourceName(value string)

func (Instance) SetResourcePath 

func (self Instance) SetResourcePath(value string)

func (Instance) SetResourceSceneUniqueId 

func (self Instance) SetResourceSceneUniqueId(value string)

func (Instance) SetupLocalToScene 

func (self Instance) SetupLocalToScene()

Calls [Interface.SetupLocalToScene]. If Instance.ResourceLocalToScene is set to true, this method is automatically called from graphics.gd/classdb/PackedScene.Instance.Instantiate by the newly duplicated resource within the scene instance.

func (Instance) TakeOverPath 

func (self Instance) TakeOverPath(path string)

Sets the Instance.ResourcePath 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.

func (Instance) Virtual 

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

type Interface 

type Interface interface {
	// Override this method to customize the newly duplicated resource created from [graphics.gd/classdb/PackedScene.Instance.Instantiate], if the original's [Instance.ResourceLocalToScene] 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)
	//
	//
	SetupLocalToScene()
	// Override this method to return a custom [Resource.ID] when [Instance.GetRid] is called.
	GetRid() ID
	// For resources that use a variable number of properties, either via [graphics.gd/classdb/Object.Instance.ValidateProperty] or [graphics.gd/classdb/Object.Instance.GetPropertyList], this method should be implemented to correctly clear the resource's state.
	ResetState()
	// Sets the resource's path to 'path' without involving the resource cache.
	SetPathCache(path string)
}

type UID 

type UID int

UID uniquely identifies a resource that has been imported into the graphics directory. Remains valid even if the resource is relocated or renamed.

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.