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, Compositor, CompositorEffect, CryptoKey, Curve, Curve2D, Curve3D, EditorNode3DGizmoPlugin, EditorSettings, Environment, Font, GDExtension, GLTFAccessor, GLTFAnimation, GLTFBufferView, GLTFCamera, GLTFDocument, GLTFDocumentExtension, GLTFLight, GLTFMesh, GLTFNode, GLTFPhysicsBody, GLTFPhysicsShape, GLTFSkeleton, GLTFSkin, GLTFSpecGloss, GLTFState, GLTFTexture, GLTFTextureSampler, Gradient, Image, ImporterMesh, InputEvent, JSON, LabelSettings, LightmapGIData, Material, Mesh, MeshLibrary, MissingResource, MultiMesh, NavigationMesh, NavigationMeshSourceGeometryData2D, NavigationMeshSourceGeometryData3D, 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

可序列化对象的基类。

描述

资源是所有 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

void

_setup_local_to_scene() virtual

Resource

duplicate(subresources: bool = false) const

void

emit_changed()

String

generate_scene_unique_id() static

Node

get_local_scene() const

RID

get_rid() const

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 的资源发出。

属性说明

bool resource_local_to_scene = false 🔗

  • void set_local_to_scene(value: bool)

  • bool is_local_to_scene()

如果为 true，那么在本地场景的各个实例中，该资源都会被唯一化。在运行时，在某个场景中对该资源的修改不会影响其他实例（见 PackedScene.instantiate）。

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

String resource_name = "" 🔗

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

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

String resource_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 🔗

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

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)

Resource duplicate(subresources: bool = 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 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:

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

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。

Node get_local_scene() const 🔗

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

RID get_rid() const 🔗

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

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，可能会覆盖这个路径对应的已有缓存条目。后续尝试通过路径加载覆盖后的资源时，会返回这个资源。