Index of every page on this site: llms.txt
All skills
Run it yourself

Godot 4.7 data-driven design with custom Resources: class_name and @export fields, .tres files, shared references vs duplicate_deep(), uids and threaded loading. Use for items, stats or enemy configs as data, or when editing one enemy changes every enemy or a .tres stops loading. Not for save slots (`save-systems`) or the C# version (`godot-csharp`).

Use this Skill: https://skilld.dev/gh/gamedev-skills/awesome-gamedev-agent-skills/godot-resources

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈92 tokens for metadata: the name and description. ≈1.8k when used: this file. ≈951 more on demand in 1 file.

Description uses 4.6% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈370 characters, or 4.6%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

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

  1. Subclass Resource with class_name and typed @export fields (Pattern 1). The class_name is what lets the editor offer it in "New Resource" and as an export type.
  2. 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.
  3. Reference resources from nodes with @export var data: ItemResource or @export var loot: Array[ItemResource], or load them by path in code.
  4. Load with preload (constant path) or load (variable path); use ResourceLoader.load_threaded_request for large scenes (see the reference).
  5. Duplicate before mutating a shared resource at runtime (Pattern 3); every node that loaded the same path holds the same object.
  6. Check before you finish.
    • After adding or moving .tres/.gd files, run the godot-nodes-scenes skill'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 = 0

2. 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 = 50

Leave 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 copy

4. 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. preload needs 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.md when 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-gdscript for the @export annotations that define resource fields.
  • godot-nodes-scenes for instancing scenes vs sharing resource data, and the checker.
  • save-systems for persisting runtime progress (separate from static data).
  • godot-gdscript-headless-testing to keep data tests in CI.
  • unity-scriptableobjects for the equivalent Unity pattern.

Version notes

Last verified: 2026-11-11 against Godot 4.7.2-stable (released 2026-08-18).

  • Resource.duplicate_deep() and DEEP_DUPLICATE_ALL exist since 4.5.
  • .uid sidecar files for scripts and shaders exist since 4.4; commit them.
  • The text format writes script_class in 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.

Source: SKILL.md on GitHub

No rule matched.

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts8d3 checks · Risk SAFE
  • Gen Agent Trust Hub9d

    This skill provides documentation and best practices for managing data resources in Godot 4.7. It includes code patterns for defining custom resources, handling shared references, and performing headless validation of project files using standard Godot CLI commands. No security issues were detected.

  • Socket8d

    No alerts

  • Snyk9d

    Risk: LOW · No issues

Signed by skilld at c6ca6c4. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub last week.

Activeupdated last week

README badge

README badge for gamedev-skills/awesome-gamedev-agent-skills/godot-resources