godot-resources

SKILL.md

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

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.

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.

Reference resources from nodes via @export var data: ItemResource, or arrays
@export var loot: Array[ItemResource].

Load at runtime with preload (constant path) or load/ResourceLoader.load
(variable path). Use threaded loading for large assets.

Duplicate before mutating a shared resource at runtime, or every node using it
changes too (resources are shared references).

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.