Attention: Here be dragons

This is the latest (unstable) version of this documentation, which may document features not available in or compatible with released stable versions of Godot.

Checking the stable version of the documentation...

Resource

继承： RefCounted < Object

派生： Animation, AnimationLibrary, AnimationNode, AnimationNodeStateMachinePlayback, AnimationNodeStateMachineTransition, AudioBusLayout, AudioEffect, AudioStream, BitMap, BoneMap, ButtonGroup, CameraAttributes, ColorPalette, Compositor, CompositorEffect, CryptoKey, Curve, Curve2D, Curve3D, EditorNode3DGizmoPlugin, EditorSettings, Environment, FoldableGroup, Font, GDExtension, GLTFAccessor, GLTFAnimation, GLTFBufferView, GLTFCamera, GLTFDocument, GLTFDocumentExtension, GLTFLight, GLTFMesh, GLTFNode, GLTFPhysicsBody, GLTFPhysicsShape, GLTFSkeleton, GLTFSkin, GLTFSpecGloss, GLTFState, GLTFTexture, GLTFTextureSampler, Gradient, Image, ImporterMesh, InputEvent, JointLimitation3D, JSON, LabelSettings, LightmapGIData, Material, Mesh, MeshLibrary, MissingResource, MultiMesh, NavigationMesh, NavigationMeshSourceGeometryData2D, NavigationMeshSourceGeometryData3D, NavigationPolygon, Noise, Occluder3D, OccluderPolygon2D, OggPacketSequence, OpenXRAction, OpenXRActionMap, OpenXRActionSet, OpenXRBindingModifier, OpenXRHapticBase, 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

可序列化对象的基类。

描述

资源是所有 Godot 特定资源类型的基类，主要作为数据容器。因为资源继承自 RefCounted，所以进行了引用计数，不再使用时会被释放。资源也可以嵌套到其他资源里、保存到磁盘上。PackedScene 也是一种资源，它是 Godot 项目中最常用的 Object 之一，独特的能力是可以将若干 Node 保存起来、随意进行实例化。

在 GDScript 中，可以根据 resource_path 从磁盘上加载资源，使用 @GDScript.load() 或 @GDScript.preload() 即可。

引擎会维护所有已加载资源的全局缓存，可以根据路径引用资源（见 ResourceLoader.has_cached()）。资源会在首次加载时缓存，所有引用释放后就会从缓存中移除。如果缓存中存在某个资源，那么后续使用其路径进行加载的时候返回的就是缓存中的引用。

注意：在 C# 中，资源不再被使用后并不会立即被释放。相反，垃圾回收将定期运行，并释放不再使用的资源。这意味着未使用的资源在被删除之前会在内存中保留一段时间。

教程

属性

bool	resource_local_to_scene	`false`
String	resource_name	`""`
String	resource_path	`""`
String	resource_scene_unique_id

方法

RID	_get_rid() virtual const
void	_reset_state() virtual
void	_set_path_cache(path: String) virtual const
void	_setup_local_to_scene() virtual
Error	copy_from_resource(resource: Resource)
Resource	duplicate(deep: bool = false) const
Resource	duplicate_deep(deep_subresources_mode: DeepDuplicateMode = 1) const
void	emit_changed()
String	generate_scene_unique_id() static
String	get_id_for_path(path: String) const
Node	get_local_scene() const
RID	get_rid() const
bool	is_built_in() const
void	reset_state()
void	set_id_for_path(path: String, id: String)
void	set_path_cache(path: String)
void	setup_local_to_scene()
void	take_over_path(path: String)

信号

changed() 🔗

当资源发生更改时发出信号，通常是当其属性之一被修改时。另见 emit_changed() 。

注意：自定义资源的属性不会自动发出此信号。如有必要，需要创建一个 setter 来触发。

setup_local_to_scene_requested() 🔗

已弃用： This signal is only emitted when the resource is created. Override _setup_local_to_scene() instead.

由新复制的 resource_local_to_scene 为 true 的资源发出。

枚举

enum DeepDuplicateMode: 🔗

DeepDuplicateMode DEEP_DUPLICATE_NONE = 0

完全不会复制任何子资源（subresources）。即使在执行深度复制时，这也非常有用，因为它能让所有的数组和字典都被成功复制，但里面的元素依然指向原本的那些资源。

DeepDuplicateMode DEEP_DUPLICATE_INTERNAL = 1

仅复制不具备路径的子资源以及使用场景本地化路径的子资源。

DeepDuplicateMode DEEP_DUPLICATE_ALL = 2

复制所有子资源，即便使用的是非本地路径。换句话说，即便是单独保存的大型资源也会复制。

属性说明

bool resource_local_to_scene = false 🔗

void set_local_to_scene(value: bool)
bool is_local_to_scene()

如果为 true，则该资源会为使用它的所有场景的每个实例重复创建。在运行时，在某个场景中对该资源的修改不会影响其他实例（见 PackedScene.instantiate()）。

注意：运行时，在已创建副本的资源上修改该属性不会有效果。

String resource_name = "" 🔗

void set_name(value: String)
String get_name()

这个资源的可选名称。定义后会在“检查器”面板中显示这个值来代表该资源。对于内置脚本，该名称会在脚本编辑器中作为选项卡名称的一部分显示。

注意：某些资源格式不支持资源名称。仍然可以在编辑器中或通过代码设置名称，但重新加载资源时该名称将会丢失。例如，只有内置的脚本可以有资源名称，而存储在单独文件中的脚本则不能。

String resource_path = "" 🔗

void set_path(value: String)
String get_path()

该资源的唯一路径。如果已被保存到磁盘，该值将是其文件路径。如果该资源仅包含在某一个场景中，该值将是 PackedScene 的文件路径后加上一个唯一标识符。

注意：如果之前已经加载了具有相同路径的资源，手动设置该属性可能会失败。如果有必要，请使用 take_over_path()。

String resource_scene_unique_id 🔗

void set_scene_unique_id(value: String)
String get_scene_unique_id()

一个相对于该资源所属场景的唯一标识符。如果留空，当此资源被保存在一个 PackedScene（打包场景）中时，ID 将会被自动生成。如果该资源不属于任何场景，此属性默认为空。

注意： 当保存 PackedScene 时，如果同一场景中的多个资源使用了相同的 ID，只有场景层级中最早出现的那个资源会保留原 ID。其他重复的资源会被分配由 generate_scene_unique_id() 方法生成的新 ID。

注意： 设置此属性不会触发 changed（已更改）信号。

警告： 在设置时，该 ID 必须仅由字母、数字和下划线组成。否则设置将失败，并默认回退为一个随机生成的 ID。

方法说明

RID _get_rid() virtual const 🔗

可以覆盖此方法，从而在调用 get_rid() 时返回自定义 RID。

void _reset_state() virtual 🔗

如果资源在未导出的属性中存储状态，例如通过 Object._validate_property() 或 Object._get_property_list() 存储，则必须实现该方法进行状态的清空。

void _set_path_cache(path: String) virtual const 🔗

可以覆盖此方法，从而在对象的 set_path_cache() 被调用后执行额外的逻辑。

void _setup_local_to_scene() virtual 🔗

如果原始资源的 resource_local_to_scene 被设置为 true，则覆盖该方法可以自定义从 PackedScene.instantiate() 创建的新复制的资源。

示例：为实例化场景中的每个本地资源设置随机 damage 值：

extends Resource

var damage = 0

func _setup_local_to_scene():
    damage = randi_range(10, 40)

Error copy_from_resource(resource: Resource) 🔗

将数据从 resource 复制到此资源中。两个资源必须属于同一类别（class）。

Resource duplicate(deep: bool = false) const 🔗

制作该资源的副本，返回资源中，export 的属性以及 @GlobalScope.PROPERTY_USAGE_STORAGE 的属性都会从原始资源中复制。

如果 deep 为 false，则会返回浅拷贝：嵌套的 Array、Dictionary、Resource 属性不会发生复制，与原资源共享。

如果 deep 为 true，则会返回深拷贝：嵌套的数组、字典和紧缩数组都会发生（递归）复制。内部的 Resource 只会在本地时进行复制，类似于对 duplicate_deep() 使用 DEEP_DUPLICATE_INTERNAL。

例外如下：

带有 @GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE 标志的子资源属性始终会被复制（是否递归取决于 deep）。
带有 @GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE 标志的子资源属性始终不会被复制。

注意：对于自定义资源，如果定义 Object._init() 时使用了必填的参数，则此方法会失败。

注意：复制时如果将 deep 设置为 true，则在复制过程中发现的每个资源，包括调用该方法的资源，都只会发生一次复制，在副本中可以对其存在多次引用。例如你复制的资源 A 里正好对资源 B 存在两个引用，那么新的资源 A' 就会引用新的资源 B' 两次。

Resource duplicate_deep(deep_subresources_mode: DeepDuplicateMode = 1) const 🔗

深度复制该资源，就像传递 true 时 duplicate() 一样，并对子资源的处理方式进行额外控制。

void emit_changed() 🔗

发出 changed 更改信号。某些内置资源会自动调用此方法。

注意：对于自定义资源，推荐在发生任何有意义的变化时都调用此方法，例如修改属性时。这样能够保证依赖于此资源的自定义 Object 能够正确更新其属性。

var damage:
    set(new_value):
        if damage != new_value:
            damage = new_value
            emit_changed()

String generate_scene_unique_id() static 🔗

根据当前日期、时间和随机值，为要包含在 PackedScene 中的资源生成唯一标识符。返回的字符串仅由字母（a 到 y）和数字（0 到 8）组成。另见 resource_scene_unique_id。

String get_id_for_path(path: String) const 🔗

根据场景唯一 ID 的内部缓存，返回位于 path 的场景中该资源的 ID。如果没有对应的条目则返回空字符串。适用于扩展 ResourceFormatLoader 和 ResourceFormatSaver 实现对版本控制系统友好的自定义资源格式时保持场景唯一 ID 一致。

注意：该方法仅在运行于编辑器上下文时实现。运行时返回空字符串。

Node get_local_scene() const 🔗

如果 resource_local_to_scene 为 true，并且该资源是从 PackedScene 实例中加载的，则返回使用该资源的场景的根 Node。否则返回 null。

RID get_rid() const 🔗

返回该资源的 RID（或者空的 RID）。许多资源（如 Texture2D、Mesh 等）是存储在服务器（DisplayServer、RenderingServer 等）中的资源的高级抽象，所以这个函数将返回原始的 RID。

bool is_built_in() const 🔗

如果资源是作为其他资源文件中的一部分保存到磁盘上的，则返回 true。

void reset_state() 🔗

清空资源中未导出的属性。另见 _reset_state()。适合在通过扩展 ResourceFormatLoader 和 ResourceFormatSaver 实现自定义资源格式时使用。

void set_id_for_path(path: String, id: String) 🔗

场景唯一 ID 的内部缓存，针对位于 path 的场景将该资源的 ID 设置为 id。如果 id 为空，则会清空 path 对应的缓存条目。适用于扩展 ResourceFormatLoader 和 ResourceFormatSaver 实现对版本控制系统友好的自定义资源格式时保持场景唯一 ID 一致。

注意：该方法仅在运行于编辑器上下文时实现。

void set_path_cache(path: String) 🔗

将资源的路径设置为 path，不涉及资源缓存。适用于扩展 ResourceFormatLoader 和 ResourceFormatSaver 实现自定义资源格式时处理 CacheMode 的值。

void setup_local_to_scene() 🔗

已弃用： This method should only be called internally.

调用 _setup_local_to_scene()。如果 resource_local_to_scene 为 true，则场景实例中新复制的资源会自动从 PackedScene.instantiate() 中调用该方法。

void take_over_path(path: String) 🔗

将 resource_path 设置为 path，可能会覆盖这个路径对应的已有缓存条目。后续尝试通过路径加载覆盖后的资源时，会返回这个资源。