How to use
- Copy the installation command and review the source package before installing it in your own agent environment.
- Check the source document for required tools, credentials and supported hosts.
- Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-resourcesBefore you start
- Installation does not include a model subscription, API allowance or permission to access your files.
- Repository stars and installation counts describe activity, not an independent quality or security test.
Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.
Godot Resources (4.x)
Model game data as Resource objects saved as .tres/.res, share them safely, and load them without hitches. Targets Godot 4.7 (see Version notes).
When to use
- Items, stats, enemy configs, dialogue lines or level metadata as data files; custom
Resource subclasses; ResourceLoader/ResourceSaver code.
When not to use:* scene structure → godot-nodes-scenes; the player's runtime progress, slots and migration → save-systems; C# → godot-csharp.
Core workflow
- Subclass `Resource` with
class_nameand typed@exportfields (Pattern 1). The
class_name is what lets the editor offer it in "New Resource" and as an export type.
- Create instances as text `.tres` files. You can write them directly (Pattern 2)
instead of clicking through the FileSystem dock and Inspector; use binary .res only for large generated data.
- Reference resources from nodes with
@export var data: ItemResourceor
@export var loot: Array[ItemResource], or load them by path in code.
- Load with
preload(constant path) orload(variable path); use
ResourceLoader.load_threaded_request for large scenes (see the reference).
- Duplicate before mutating a shared resource at runtime (Pattern 3); every node that
loaded the same path holds the same object.
- Check before you finish.
- After adding or moving
.tres/.gdfiles, run thegodot-nodes-scenesskill's
scripts/check_godot_project.py <project-dir> to catch broken ext_resource paths, uids and ids. Fix every ERROR.
- Prove the data loads and copies correctly with a headless test (Pattern 4):
godot --headless --path . --import once on a fresh checkout (so class_name types resolve), then godot --headless --path . --script res://tests/test_items.gd, and read the exit code. With no Godot binary (godot, godot4 or $GODOT_BIN), ask the user to run both lines and paste the output.
Patterns
1. A custom data resource
# res://items/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 = 02. The same item as a hand-written .tres
[gd_resource type="Resource" script_class="ItemResource" format=3]
[ext_resource type="Script" path="res://items/item.gd" id="1_item"]
[resource]
script = ExtResource("1_item")
id = &"sword"
display_name = "Sword"
max_stack = 1
value = 50Leave out the uid= attributes; Godot adds them the next time the file is saved. Fields left out keep the script defaults.
3. Duplicate before mutating shared data
func give_unique_copy(template: ItemResource) -> ItemResource:
# true = deep: copies nested arrays/dictionaries and *embedded* sub-resources, but
# sub-resources saved in their own .tres stay shared. Use
# template.duplicate_deep(Resource.DEEP_DUPLICATE_ALL) to copy those as well.
var copy: ItemResource = template.duplicate(true)
copy.value += 5 # mutating the copy won't touch the template .tres
return copy4. Headless check: the file loads as its class and copies are independent
# res://tests/test_items.gd
extends SceneTree
func _initialize() -> void:
var failed := 0
var sword := load("res://items/sword.tres") as ItemResource
if sword == null:
failed += 1
push_error("sword.tres did not load as ItemResource")
else:
var copy: ItemResource = sword.duplicate(true)
copy.value += 1
if copy.value == sword.value:
failed += 1
push_error("duplicate(true) shares state with the template")
print("Results: %d failed" % failed)
quit(1 if failed > 0 else 0)Gotchas
- Resources are shared by reference. Every
load()of one path returns the same cached
object, so mutating it changes every user (and re-saving writes the change into the file). Duplicate for per-instance state, or set resource_local_to_scene = true for a copy per scene instance.
- A deep copy still changes the original's sub-resource →
duplicate(true)only copies
sub-resources embedded in the file; one saved as its own .tres (e.g. a shared stats.tres inside goblin.tres) stays the same object. Use duplicate_deep(Resource.DEEP_DUPLICATE_ALL) when those must be copied too.
- `class_name` is required for editor and typed use. Without it the class is missing
from "New Resource" and cannot be an @export type.
- `class_name` "not declared" only in headless or CI runs → the global class cache in
.godot/ is missing on a fresh checkout. Run godot --headless --path . --import first.
- `res://` is read-only in exported games. Write runtime data to
user://.
ResourceSaver.save to res:// works only while running from the project folder.
- Moving a `.gd` or `.tres` outside the editor breaks `ext_resource` paths. Move the
.uid sidecar with scripts, then run the checker; a uid that still resolves keeps the link working.
- Nodes stored in a Resource don't serialize. Resources hold data; reference scenes as
PackedScene, not node instances.
- Cyclic references (A holds B holds A) can fail to save or load cleanly; keep data
graphs acyclic or link by id.
- `preload` vs `load`.
preloadneeds a constant path and loads with the script;
load takes a runtime path. Check ResourceLoader.exists() first for optional files.
- `.tres` files ship as readable text inside the export, so keep secrets out of them.
References
- Read
references/resource-patterns.mdwhen you need threaded loading with progress,
resource_local_to_scene, @tool resources, a custom ResourceFormatLoader/Saver for a new file type, uid handling, or a registry layout for many data files.
Related skills
godot-gdscriptfor the@exportannotations that define resource fields.godot-nodes-scenesfor instancing scenes vs sharing resource data, and the checker.save-systemsfor persisting runtime progress (separate from static data).godot-gdscript-headless-testingto keep data tests in CI.unity-scriptableobjectsfor the equivalent Unity pattern.
Version notes
Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).
Resource.duplicate_deep()andDEEP_DUPLICATE_ALLexist since 4.5..uidsidecar files for scripts and shaders exist since 4.4; commit them.- The text format writes
script_classin the[gd_resource]header; since 4.6 it no
longer writes or reads load_steps, so older files that carry it still load.
Sources: Resource @ 4.7.2-stable, resource_format_text.cpp @ 4.7.2-stable, Resources, File paths in Godot projects.