Come usare
- Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
- Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
- Descrivi input e risultato desiderato; confronta l’output con le fonti.
npx skills add https://github.com/gamedev-skills/awesome-gamedev-agent-skills --skill godot-resourcesPrima di iniziare
- L’installazione non include abbonamenti, quote API o accesso ai file.
- Stelle e installazioni indicano attività, non un test indipendente di qualità o sicurezza.
Contenuto dal repository con titoli, esempi, codice, tabelle, link e immagini preservati.
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.