Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

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 的属性都会从原始资源中复制。

如果 subresourcesfalse,则返回的是浅拷贝;子资源中的嵌套资源不会被复制,仍然会被共享。如果 subresourcestrue,则返回的是深拷贝;会制作嵌套子资源的副本,不会进行共享。

带有 @GlobalScope.PROPERTY_USAGE_ALWAYS_DUPLICATE 标志的子资源属性始终会被复制,即便 subresourcesfalse。而带有 @GlobalScope.PROPERTY_USAGE_NEVER_DUPLICATE 标志的子资源属性始终不会被复制,即便 subresourcestrue

注意:对于自定义资源,如果定义 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_scenetrue,并且该资源是从 PackedScene 实例中加载的,则返回使用该资源的场景的根 Node。否则返回 null


RID get_rid ( ) const

返回该资源的 RID(或者空的 RID)。许多资源(如 Texture2DMesh 等)是存储在服务器(DisplayServerRenderingServer 等)中的资源的高级抽象,所以这个函数将返回原始的 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,可能会覆盖这个路径对应的已有缓存条目。后续尝试通过路径加载覆盖后的资源时,会返回这个资源。