Godot Resources (4.x)
Model game data as Resource objects saved as .tres/.res, share them safely, and
load them without hitches. Targets Godot 4.7 (see Version notes).
When to use
- Items, stats, enemy configs, dialogue lines or level metadata as data files; custom
Resourcesubclasses;ResourceLoader/ResourceSavercode.
When not to use: scene structure → godot-nodes-scenes; the player's runtime
progress, slots and migration → save-systems; C# → godot-csharp.
Core workflow
- Subclass
Resourcewithclass_nameand typed@exportfields (Pattern 1). Theclass_nameis what lets the editor offer it in "New Resource" and as an export type. - Create instances as text
.tresfiles. You can write them directly (Pattern 2) instead of clicking through the FileSystem dock and Inspector; use binary.resonly for large generated data. - Reference resources from nodes with
@export var data: ItemResourceor@export var loot: Array[ItemResource], or load them by path in code. - Load with
preload(constant path) orload(variable path); useResourceLoader.load_threaded_requestfor large scenes (see the reference). - Duplicate before mutating a shared resource at runtime (Pattern 3); every node that loaded the same path holds the same object.
- Check before you finish.
- After adding or moving
.tres/.gdfiles, run thegodot-nodes-scenesskill'sscripts/check_godot_project.py <project-dir>to catch brokenext_resourcepaths, uids and ids. Fix everyERROR. - Prove the data loads and copies correctly with a headless test (Pattern 4):
godot --headless --path . --importonce on a fresh checkout (soclass_nametypes resolve), thengodot --headless --path . --script res://tests/test_items.gd, and read the exit code. With no Godot binary (godot,godot4or$GODOT_BIN), ask the user to run both lines and paste the output.
- After adding or moving
Patterns
1. A custom data resource
# res://items/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 = 02. The same item as a hand-written .tres
[gd_resource type="Resource" script_class="ItemResource" format=3]
[ext_resource type="Script" path="res://items/item.gd" id="1_item"]
[resource]
script = ExtResource("1_item")
id = &"sword"
display_name = "Sword"
max_stack = 1
value = 50Leave out the uid= attributes; Godot adds them the next time the file is saved. Fields
left out keep the script defaults.
3. Duplicate before mutating shared data
func give_unique_copy(template: ItemResource) -> ItemResource:
# true = deep: copies nested arrays/dictionaries and *embedded* sub-resources, but
# sub-resources saved in their own .tres stay shared. Use
# template.duplicate_deep(Resource.DEEP_DUPLICATE_ALL) to copy those as well.
var copy: ItemResource = template.duplicate(true)
copy.value += 5 # mutating the copy won't touch the template .tres
return copy4. Headless check: the file loads as its class and copies are independent
# res://tests/test_items.gd
extends SceneTree
func _initialize() -> void:
var failed := 0
var sword := load("res://items/sword.tres") as ItemResource
if sword == null:
failed += 1
push_error("sword.tres did not load as ItemResource")
else:
var copy: ItemResource = sword.duplicate(true)
copy.value += 1
if copy.value == sword.value:
failed += 1
push_error("duplicate(true) shares state with the template")
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)Gotchas
- Resources are shared by reference. Every
load()of one path returns the same cached object, so mutating it changes every user (and re-saving writes the change into the file). Duplicate for per-instance state, or setresource_local_to_scene = truefor a copy per scene instance. - A deep copy still changes the original's sub-resource →
duplicate(true)only copies sub-resources embedded in the file; one saved as its own.tres(e.g. a sharedstats.tresinsidegoblin.tres) stays the same object. Useduplicate_deep(Resource.DEEP_DUPLICATE_ALL)when those must be copied too. class_nameis required for editor and typed use. Without it the class is missing from "New Resource" and cannot be an@exporttype.class_name"not declared" only in headless or CI runs → the global class cache in.godot/is missing on a fresh checkout. Rungodot --headless --path . --importfirst.res://is read-only in exported games. Write runtime data touser://.ResourceSaver.savetores://works only while running from the project folder.- Moving a
.gdor.tresoutside the editor breaksext_resourcepaths. Move the.uidsidecar with scripts, then run the checker; a uid that still resolves keeps the link working. - Nodes stored in a Resource don't serialize. Resources hold data; reference scenes as
PackedScene, not node instances. - Cyclic references (A holds B holds A) can fail to save or load cleanly; keep data graphs acyclic or link by id.
preloadvsload.preloadneeds a constant path and loads with the script;loadtakes a runtime path. CheckResourceLoader.exists()first for optional files..tresfiles ship as readable text inside the export, so keep secrets out of them.
References
- Read
references/resource-patterns.mdwhen you need threaded loading with progress,resource_local_to_scene,@toolresources, a customResourceFormatLoader/Saverfor a new file type, uid handling, or a registry layout for many data files.
Related skills
godot-gdscriptfor the@exportannotations that define resource fields.godot-nodes-scenesfor instancing scenes vs sharing resource data, and the checker.save-systemsfor persisting runtime progress (separate from static data).godot-gdscript-headless-testingto keep data tests in CI.unity-scriptableobjectsfor the equivalent Unity pattern.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
Resource.duplicate_deep()andDEEP_DUPLICATE_ALLexist since 4.5..uidsidecar files for scripts and shaders exist since 4.4; commit them.- The text format writes
script_classin the[gd_resource]header; since 4.6 it no longer writes or readsload_steps, so older files that carry it still load.
Sources: Resource @ 4.7.2-stable, resource_format_text.cpp @ 4.7.2-stable, Resources, File paths in Godot projects.