Resource

package
v0.0.0-...-fe0704e Latest Latest
Warning

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

 Go to latest Published: Sep 19, 2025 License: MIT Imports: 25 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 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 ResourcePath using @GDScript.Load or @GDScript.Preload.

The engine keeps a global cache of all loaded resources, referenced by paths (see 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 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 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 DeepDuplicateMode 

type DeepDuplicateMode int //gd:Resource.DeepDuplicateMode

const (
	// No subresorces 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.
	DeepDuplicateNone DeepDuplicateMode = 0
	// Only subresources without a path or with a scene-local path will be duplicated.
	DeepDuplicateInternal DeepDuplicateMode = 1
	// 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.
	DeepDuplicateAll DeepDuplicateMode = 2
)

type Expanded 

type Expanded = MoreArgs

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 'deep' is false, a shallow copy is returned: nested slice, data structure, 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 DeepDuplicateInternal used with DuplicateDeep.

The following exceptions apply:

- Subresource properties with the [PropertyUsageAlwaysDuplicate] flag are always duplicated (recursively or not, depending on 'deep').

- Subresource properties with the [PropertyUsageNeverDuplicate] 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 (Instance) DuplicateDeep 

func (self Instance) DuplicateDeep() Instance

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

'deep_subresources_mode' must be one of the values from DeepDuplicateMode.

func (Instance) EmitChanged 

func (self Instance) EmitChanged()

Emits the 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 Objects depending on the resource are properly updated. 

package main

import "graphics.gd/classdb/Resource"

type SomeResource struct {
	Resource.Extension[SomeResource]

	damage int
}

func (r *SomeResource) SetDamage(newValue int) {
	if r.damage != newValue {
		r.damage = newValue
		r.AsResource().EmitChanged()
	}
}

func (Instance) GetIdForPath 

func (self Instance) GetIdForPath(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 (Instance) GetRid 

func (self Instance) GetRid() ID

Returns the Resource.ID 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 Resource.ID.

func (Instance) IsBuiltIn 

func (self Instance) IsBuiltIn() bool

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

func (Instance) MoreArgs 

func (self Instance) MoreArgs() MoreArgs

MoreArgs enables certain functions to be called with additional 'optional' arguments.

func (Instance) OnChanged 

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

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

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

func (Instance) OnSetupLocalToSceneRequested 

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

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

func (Instance) ResetState 

func (self Instance) ResetState()

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

func (Instance) ResourceLocalToScene 

func (self Instance) ResourceLocalToScene() bool

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.

func (Instance) ResourceName 

func (self Instance) ResourceName() 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.

func (Instance) ResourcePath 

func (self Instance) ResourcePath() 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 TakeOverPath.

func (Instance) ResourceSceneUniqueId 

func (self Instance) ResourceSceneUniqueId() string

A 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 GenerateSceneUniqueId.

Note: Setting this property does not emit the OnChanged 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.

func (Instance) SetIdForPath 

func (self Instance) SetIdForPath(path string, id string)

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 (*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. Useful for handling [ResourceFormatLoader.CacheMode] values when implementing a custom resource format by extending ResourceFormatLoader and ResourceFormatSaver.

func (Instance) SetResourceLocalToScene 

func (self Instance) SetResourceLocalToScene(value bool)

SetResourceLocalToScene sets the property returned by [IsLocalToScene].

func (Instance) SetResourceName 

func (self Instance) SetResourceName(value string)

SetResourceName sets the property returned by [GetName].

func (Instance) SetResourcePath 

func (self Instance) SetResourcePath(value string)

SetResourcePath sets the property returned by [GetPath].

func (Instance) SetResourceSceneUniqueId 

func (self Instance) SetResourceSceneUniqueId(value string)

SetResourceSceneUniqueId sets the property returned by [GetSceneUniqueId].

func (Instance) SetupLocalToScene 

func (self Instance) SetupLocalToScene()

Calls SetupLocalToScene. If ResourceLocalToScene is set to true, this method is automatically called from PackedScene.Instantiate by the newly duplicated resource within the scene instance.

func (Instance) TakeOverPath 

func (self Instance) TakeOverPath(path string)

Sets the 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 [PackedScene.Instantiate], if the original's [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)
	//
	//
	//
	// [PackedScene.Instantiate]: https://pkg.go.dev/graphics.gd/classdb/PackedScene#Instance.Instantiate
	// [ResourceLocalToScene]: https://pkg.go.dev/graphics.gd/classdb/Resource#Instance.ResourceLocalToScene
	SetupLocalToScene()
	// Override this method to return a custom [Resource.ID] when [GetRid] is called.
	//
	// [GetRid]: https://pkg.go.dev/graphics.gd/classdb/Resource#Instance.GetRid
	// [Resource.ID]: https://pkg.go.dev/graphics.gd/variant/Resource#ID
	GetRid() ID
	// For resources that store state in non-exported properties, such as via [Object.ValidateProperty] or [Object.GetPropertyList], this method must be implemented to clear them.
	//
	// [Object.GetPropertyList]: https://pkg.go.dev/graphics.gd/variant/Object#GetPropertyList
	// [Object.ValidateProperty]: https://pkg.go.dev/graphics.gd/variant/Object#ValidateProperty
	ResetState()
	// Override this method to execute additional logic after [SetPathCache] is called on this object.
	//
	// [SetPathCache]: https://pkg.go.dev/graphics.gd/classdb/Resource#Instance.SetPathCache
	SetPathCache(path string)
}

type MoreArgs 

type MoreArgs [1]gdclass.Resource

MoreArgs is a container for Instance functions with additional 'optional' arguments.

func (MoreArgs) Duplicate 

func (self MoreArgs) Duplicate(deep bool) Instance

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

If 'deep' is false, a shallow copy is returned: nested slice, data structure, 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 DeepDuplicateInternal used with DuplicateDeep.

The following exceptions apply:

- Subresource properties with the [PropertyUsageAlwaysDuplicate] flag are always duplicated (recursively or not, depending on 'deep').

- Subresource properties with the [PropertyUsageNeverDuplicate] 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 (MoreArgs) DuplicateDeep 

func (self MoreArgs) DuplicateDeep(deep_subresources_mode DeepDuplicateMode) Instance

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

'deep_subresources_mode' must be one of the values from DeepDuplicateMode.

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.