godot-resources

Godot 资源（4.x）

将游戏数据建模为可复用、可在 Inspector 中编辑的 Resource 对象，而不是硬编码的值，并将其加载/保存为 .tres/.res 文件。目标版本为 Godot 4.7。

适用场景

• 需要将物品、属性、敌人配置、对话台词或关卡元数据表示为数据；在 Inspector 中编辑 .tres 文件；或加载/保存自定义资源时使用。

不适用场景： 节点/场景结构 → godot-nodes-scenes；保存玩家的运行时进度（与引擎无关的存档格式/槽位）→ save-systems；此模式的 C# 版本 → godot-csharp。

核心工作流

1. 继承 Resource，并添加 class_name 和 @export 字段。这样它会显示在“New Resource”对话框中，也可作为 @export 类型，并能在 Inspector 中编辑。
2. 将实例创建为 .tres 文件：在 FileSystem 面板中创建（文本格式，便于比较差异），或创建为 .res（二进制格式，更小/更快）。在 Inspector 中编辑字段，无需编写代码。
3. 从节点引用资源：使用 @export var data: ItemResource，或使用数组 @export var loot: Array[ItemResource]。
4. 在运行时加载：使用 preload（常量路径）或 load/ResourceLoader.load（可变路径）。对于大型资源，请使用线程加载。
5. 在运行时修改共享资源前先复制，否则所有使用该资源的节点也会随之改变（资源是共享引用）。
6. 使用 ResourceSaver.save 保存生成或编辑的资源。

模式

1. 自定义数据资源

# item.gd
extends Resource
class_name ItemResource

@export var id: StringName = &""
@export var display_name: String = "Item"
@export_multiline var description: String = ""
@export var icon: Texture2D
@export var max_stack: int = 99
@export var value: int = 0

在 FileSystem 面板中根据此类创建 sword.tres，并在 Inspector 中填写其内容。

2. 在节点中使用资源

extends Node
@export var starting_items: Array[ItemResource] = []   # drag .tres files in the Inspector

func _ready() -> void:
    for item in starting_items:
        print("Have: %s (x%d max)" % [item.display_name, item.max_stack])

3. 修改共享数据前先复制

func give_unique_copy(template: ItemResource) -> ItemResource:
    # true = deep copy sub-resources too; false = shallow (shares sub-resources).
    var copy: ItemResource = template.duplicate(true)
    copy.value += 5                # mutating the copy won't touch the template .tres
    return copy

4. 在运行时保存和加载资源

func save_config(cfg: Resource) -> void:
    ResourceSaver.save(cfg, "user://config.tres")   # user:// = writable app data dir

func load_config() -> Resource:
    if ResourceLoader.exists("user://config.tres"):
        return ResourceLoader.load("user://config.tres")
    return null

注意事项

• 资源按引用共享。 分配给多个节点的同一个 .tres 是同一个对象——修改它会影响所有节点（并会重新保存文件）。对于每个实例的状态，请调用 duplicate(true)。
• 从编辑器创建实例需要 class_name。 如果没有它，该类不会显示在“New Resource”对话框中，也不能作为 @export 类型。
• 导出的游戏中 res:// 是只读的。 将运行时数据写入 user://，不要写入 res://。只有在编辑器中才能使用 ResourceSaver.save 保存到 res://。
• 将节点存储在 Resource 中不会序列化它们。 Resource 用于保存数据，而非活动场景节点。应通过 PackedScene 引用场景，而不是节点实例。
• 循环资源引用（A 持有 B，B 又持有 A）可能无法正常保存/加载——请保持数据图无环，或使用 ID/查找方式。
• preload 与 load 的区别。 preload 需要常量路径，并会随脚本一起加载；load 在运行时接受可变路径。调用 load 前使用 ResourceLoader.exists()，以避免文件缺失时报错。
• 不要在 .tres 中存放机密——它们会以纯文本形式包含在导出内容中。

参考资料

• 有关线程/后台加载（load_threaded_request）、带自定义设置的 @tool 资源、自定义 ResourceFormatLoader/Saver、资源局部场景以及资源 UID，请阅读 references/resource-patterns.md。

相关技能

• godot-gdscript — 用于定义资源字段的 @export 注解。
• godot-nodes-scenes — 实例化场景与共享资源数据。
• save-systems — 持久化运行时进度（与静态数据分开）。
• unity-scriptableobjects — Unity 中对应的数据资源模式。