Godot 资源与数据

游戏数据的定义、编辑、加载与存档。默认：数据做成自定义 Resource 存 .tres，存档用 JSON 写到 user://。

范围

先查内置

做法

自定义 Resource

数据类继承 Resource，字段用 @export，实例存成 .tres。

class_name ItemData
extends Resource

@export var id: StringName
@export var title: String
@export_multiline var description: String
@export var icon: Texture2D
@export var price: int = 10
@export var price_curve: Curve
@export var tags: Array[StringName] = []

• 文件系统面板右键 New Resource 选 ItemData，存 .tres
• 撤销重做、拖拽引用、复制粘贴都是原生的
• 资源可互相引用：@export var drops: Array[ItemData]
• _init 的参数必须都有默认值
• Inspector 新建与 duplicate() 都无参构造，有必填参数时返回空壳
• 资源只放静态配置，当前血量等运行时状态放节点或 RefCounted
• 不需要 Inspector 编辑的内存数据包用 RefCounted 子类

数据库资源

整张表由一个资源持有，运行时按 id 建索引。

class_name ItemDb
extends Resource

@export var items: Array[ItemData] = []

var _by_id: Dictionary[StringName, ItemData] = {}

func get_item(id: StringName) -> ItemData:
	if _by_id.is_empty():
		for item in items:
			_by_id[item.id] = item
	return _by_id.get(id)

• 增删条目在 Inspector 里做，不扫目录
• 元素为 null 时 Inspector 不报错，用到时判空

JSON 与 Resource

• 表格与 Inspector 只能有一个源头
• 表格还在导出：JSON 为源，.tres 只生成不手改
• 改在 Inspector：.tres 为源，用工具脚本导出 JSON
• 类型错误在导入时暴露，运行时不再有解析代码

共享与复制

同一路径 load 多次得到同一对象，同一场景多次实例化共用其 sub_resource。

class_name StatBlock
extends Resource

@export var hp: int = 10
@export var speed: float = 120.0

extends CharacterBody2D

@export var base_stats: StatBlock

var stats: StatBlock

func _ready() -> void:
	stats = base_stats.duplicate()

• 每个敌人独立血量：_ready 里 duplicate()，或勾 resource_local_to_scene
• 运行时要改子资源数组里的项：duplicate(true) 或 duplicate_deep()
• local_to_scene 只复制数组，数组里的子资源仍共享
• 子资源自己也勾 resource_local_to_scene 才各得一份
• 数据表资源当只读，改了所有引用方都变
• 复制时做初始化：重写 Resource._setup_local_to_scene

加载方式

• load 按路径缓存，没有引用时释放，不另建字典缓存

异步加载

请求后每帧查状态，加载完再取结果。

extends Control

signal finished(resource: Resource)

@export var bar: ProgressBar

var _path: String = ""
var _progress: Array = []

func _ready() -> void:
	set_process(false)

func start(path: String) -> void:
	_path = path
	ResourceLoader.load_threaded_request(path)
	set_process(true)

func _process(_delta: float) -> void:
	var status := ResourceLoader.load_threaded_get_status(_path, _progress)
	match status:
		ResourceLoader.THREAD_LOAD_IN_PROGRESS:
			bar.value = float(_progress[0]) * 100.0
		ResourceLoader.THREAD_LOAD_LOADED:
			set_process(false)
			finished.emit(ResourceLoader.load_threaded_get(_path))
		_:
			set_process(false)
			push_error("加载失败 " + _path)

• load_threaded_get 在未加载完时阻塞，只在 THREAD_LOAD_LOADED 后调
• 进度按依赖估算，单个大文件可能从 0 直接到 1
• use_sub_threads = true 更快，可能拖慢主线程
• 加载完的场景交给 SceneTree.change_scene_to_packed

导出后的 res://

导入资源在包里只剩 .import 与 .godot/imported，.tres .tscn 默认转二进制只剩 .remap。

• list_directory 返回原文件名，子目录带 /，顺序不固定
• 导出前 list_directory("res://") 含 .godot/，要过滤
• .json 在 export_filter="all_resources" 时默认进包，4.7.2 实测
• .csv 默认导入成 Translation，原文件不进包

uid 引用

编辑器给每个资源分配 uid://，引用方同时存 uid 与路径，编辑器内移动文件引用不断。

• load("uid://...") 与 preload("uid://...") 可用
• @export_file 存 uid，@export_file_path 4.5+ 存裸路径
• 脚本的 .gd.uid 文件 4.4+ 要提交版本库
• 编辑器外移动文件后，让编辑器重扫并重存引用方
• 不手写 uid，字符集只有 a 到 y 与 0 到 8
• uid 与目标不符时打印 invalid UID 并退回路径

存档

存档文件在玩家手里，按不可信输入处理。

• 不 load() 玩家可写位置的 .tres .res .tscn
• 内嵌 GDScript 子资源的 .tres，load 时执行 _init，实测

陷阱

参考

• references/csharp.md：C# 项目先读，本文各节示例的 C# 写法，[GlobalClass] 资源
• references/builtin-data-resources.md：Curve Gradient CurveTexture Curve2D Animation 的取值与替换对照
• references/saving-data.md：存档位置、格式比较、版本迁移、原子写入、加密
• references/baking-data.md：JSON 转 .tres，大数据烘焙成 .res
• https://docs.godotengine.org/en/stable/tutorials/scripting/resources.html
• https://docs.godotengine.org/en/stable/tutorials/io/background_loading.html
• https://docs.godotengine.org/en/stable/tutorials/io/saving_games.html