godot-resources

Godot Resources (4.x)

Model game data as reusable, Inspector-editable Resource objects instead of hard-coded values, and load/save them as .tres/.res. Targets Godot 4.7.

When to use

• Use when representing items, stats, enemy configs, dialogue lines, or level metadata as data; authoring .tres files in the Inspector; or loading/saving custom resources.

When not to use: nodes/scene structure → godot-nodes-scenes; saving the player's runtime progress (engine-agnostic save format/slots) → save-systems; the C# variant of this pattern → godot-csharp.

Core workflow

1. Subclass Resource with class_name and @export fields. It now appears in the "New Resource" dialog and as an @export type, editable in the Inspector.
2. Create instances as .tres files in the FileSystem dock (text, diff-friendly) or .res (binary, smaller/faster). Edit their fields in the Inspector — no code needed.
3. Reference resources from nodes via @export var data: ItemResource, or arrays @export var loot: Array[ItemResource].
4. Load at runtime with preload (constant path) or load/ResourceLoader.load (variable path). Use threaded loading for large assets.
5. Duplicate before mutating a shared resource at runtime, or every node using it changes too (resources are shared references).
6. Save generated/edited resources with ResourceSaver.save.

Patterns

1. A custom data resource

# item.gd
extends Resource
class_name ItemResource
 
@export var id: StringName = &""
@export var

Create sword.tres from this class in the FileSystem dock and fill it in the Inspector.

2. Consume resources from a node

3. Duplicate before mutating shared data

4. Save and load a resource at runtime

Pitfalls

• Resources are shared by reference. A single .tres assigned to many nodes is the same object — mutating it changes all of them (and re-saving the file). Call duplicate(true) for per-instance state.
• class_name required to instance from the editor. Without it the class won't appear in the "New Resource" dialog or as an @export type.
• res:// is read-only in exported games. Write runtime data to user://, never res://. ResourceSaver.save to res:// only works in the editor.
• Storing nodes in a Resource doesn't serialize them. Resources hold data, not live scene nodes. Reference scenes via PackedScene, not node instances.
• Cyclic resource references (A holds B holds A) can fail to save/load cleanly — keep data graphs acyclic or use IDs/lookups.
• preload vs load. preload needs a constant path and loads with the script; load accepts a variable path at runtime. Use ResourceLoader.exists() before load to avoid errors on missing files.
• Don't put secrets in .tres — they ship in plain text inside the export.

References

• For threaded/background loading (load_threaded_request), @tool resources with custom setup, custom ResourceFormatLoader/Saver, resource-local-to-scene, and resource UIDs, read references/resource-patterns.md.

Related skills

• godot-gdscript — @export annotations used to define resource fields.
• godot-nodes-scenes — instancing scenes vs. sharing resource data.
• save-systems — persisting runtime progress (separate from static data).
• unity-scriptableobjects — the equivalent data-asset pattern in Unity.