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.3+.

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 display_name: String = "Item"
@export_multiline var description: String = ""
@export var icon: Texture2D
@export var max_stack: int = 99
@export var value: int = 0

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

2. Consume resources from a node

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. Duplicate before mutating shared data

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. Save and load a resource at runtime

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

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.