gamedev-skills/awesome-gamedev-agent-skills

godot-resources

Godot 4.7 data-driven design with custom Resources: classname and @export fields, .tres files, shared references vs duplicatedeep(), uids and threaded loading.

Vedi sorgente

Come usare

  1. Copia il comando e controlla il pacchetto prima di installarlo nel tuo ambiente agente.
  2. Controlla strumenti, credenziali e ambienti richiesti nel documento originale.
  3. 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-resources

Prima 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.
Documento Skill originale

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

  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.

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

  1. Reference resources from nodes with @export var data: ItemResource or

@export var loot: Array[ItemResource], or load them by path in code.

  1. Load with preload (constant path) or load (variable path); use

ResourceLoader.load_threaded_request for large scenes (see the reference).

  1. Duplicate before mutating a shared resource at runtime (Pattern 3); every node that

loaded the same path holds the same object.

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

gdscript
# 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

ini
[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

gdscript
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

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

dallo stesso repository

Altri Skills

Tutti gli Skills
gamedev-skills
Community

game-ui-ux

Engine-neutral design rules for game HUDs and menus: anchors and containers, scaling, safe areas, gamepad focus, HUDs driven by events instead of polling, and accessibility minimums. Use for menus, health bars or inventory screens that break on ultrawide or phones. Pair with godot-ui-control or roblox-ui. Not for button juice (game-feel) or rebinding (input-systems).

Installazioni / 24h
433
GitHub Stars
10K
Aggiornato
12 nov
gamedev-skills
Community

game-feel

Adds engine-neutral juice to a working mechanic: trauma-based screen shake, hit-stop, eased tweens, squash and stretch, and knockback. Use when the game feels flat, weightless or not punchy, or hits and jumps should feel satisfying. Not for coyote time (platformer), input buffering (input-systems), camera follow (camera-systems) or HUD layout (game-ui-ux).

Installazioni / 24h
431
GitHub Stars
10K
Aggiornato
12 nov
gamedev-skills
Community

create-game-assets

Plans, generates or sources, and validates consistent game art: style guides, sprites, pixel art, tilesets, icons and textures, with QA and licence records. Use when making or AI-generating game art, fixing fake transparency, or checking Steam AI disclosure. Not for engine import (godot-tilemap, godot-animation, unity-tilemap-2d), UI layout (game-ui-ux) or sound (audio-design).

Installazioni / 24h
365
GitHub Stars
10K
Aggiornato
12 nov
gamedev-skills
Community

performance-optimization

Finds and fixes game frame-rate problems by measurement in Godot, Unity, Unreal or Roblox: CPU- vs GPU-bound, then the biggest fix (draw calls, pooling, GC spikes). Use for low FPS, stutter, a first-use hitch, or requests to optimize or profile. Not for build size (unity-build-size), physics jitter (physics-tuning) or network lag (roblox-networking, godot-multiplayer).

Installazioni / 24h
360
GitHub Stars
10K
Aggiornato
12 nov