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, 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，所以进行了引用计数，不再使用时会被释放。资源也可以嵌套到其他资源里、保存到磁盘上。一旦从磁盘加载，后续尝试使用 resource_path 加载资源时都会返回相同的引用。PackedScene 也是一种资源，它是 Godot 项目中最常用的 Object 之一，独特的能力是可以将若干 Node 保存起来、随意进行实例化。

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

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

教程

属性

bool

resource_local_to_scene

false

String

resource_name

""

String

resource_path

""

方法

RID

_get_rid ( ) virtual

void

_setup_local_to_scene ( ) virtual

Resource

duplicate ( bool subresources=false ) const

void

emit_changed ( )

Node

get_local_scene ( ) const

RID

get_rid ( ) const

void

setup_local_to_scene ( )

void

take_over_path ( String path )

信号

changed ( )

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

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

setup_local_to_scene_requested ( )

由新复制的资源发出，并将 resource_local_to_scene 设置为 true。

已弃用。该信号仅在创建资源时发出。改为覆盖 _setup_local_to_scene。

属性说明

bool resource_local_to_scene = false

  • void set_local_to_scene ( bool value )

  • bool is_local_to_scene ( )

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

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

String resource_name = ""

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

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

String resource_path = ""

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

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

方法说明

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 ( bool subresources=false ) const

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

如果 subresources 为 false，则返回的是浅拷贝；子资源中的嵌套资源不会被复制，仍然会被共享。如果 subresources 为 true，则返回的是深拷贝；会制作嵌套子资源的副本，不会进行共享。

带有 @GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE 标志的子资源属性始终会被复制，即便 subresources 为 false。而带有 @GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE 标志的子资源属性始终不会被复制，即便 subresources 为 true。

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

void emit_changed ( )

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

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

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

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 ( )

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

已弃用。该方法只能被内部调用。使用覆盖 _setup_local_to_scene 代替。

void take_over_path ( String path )

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