/godot-resources

name: godot-resources
description: >
  Design data-driven Godot 4.7 games with custom Resource classes: define typed
  data with class_name + @export, save/load .tres/.res files, instance and duplicate
  resources, and load on demand with ResourceLoader (incl. threaded loading). Use
  when modeling items/stats/configs as data in a Godot project, creating .tres
  resources, or working with custom Resource subclasses and ResourceLoader/ResourceSaver.

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