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.

1. 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.

1. Reference resources from nodes via @export var data: ItemResource, or arrays

@export var loot: Array[ItemResource].

1. Load at runtime with preload (constant path) or load/ResourceLoader.load

(variable path). Use threaded loading for large assets.

1. Duplicate before mutating a shared resource at runtime, or every node using it

changes too (resources are shared references).

1. 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.