Skip to content
Tutorials Center
My learning

Topics

Lesson 9 of 36 ยท Editor and Scenes

Godot Resources: Data, Loading and Custom Resources

Understand Resource objects in Godot 4: textures, scenes and data files, load versus preload, reference counting, sharing and duplicating, and writing your own custom Resource classes.

Nodes do things; resources are the data those nodes use. A texture, a sound, a font, a material, a scene file and even a script are all resources. Understanding how they are loaded, shared and saved prevents several confusing bugs, such as changing one enemy and watching all of them change. You will also learn to make your own resources to hold game data such as item stats.

Godot is not available here, so GDScript is read-only. The Python stand-ins model caching and sharing so you can see the effect.

Nodes versus resources

Node Resource
Lives in The scene tree Memory; saved as .tres/.res or an imported file
Has _process? Yes No
Examples Sprite2D, Timer Texture2D, AudioStream, PackedScene, Theme
Shared? Each node has one parent Many nodes can point to one resource

A Sprite2D is the thing in the world; its texture property refers to a Texture2D resource. Ten sprites can point to the same one without ten copies in memory.

All resources extend the class Resource, which is reference counted: when nothing refers to it any more, Godot frees it. You never call free() on a resource.

load and preload

GDSCRIPT
# Loaded when the script is compiled; path must be a constant
const ENEMY: PackedScene = preload("res://enemy/enemy.tscn")

func _ready() -> void:
    # Loaded when this line runs; path can be any string
    var tex: Texture2D = load("res://art/player.png")
    $Sprite2D.texture = tex
  • preload is faster at runtime (the work happens before the game starts) and gives type information to the editor, but the path must be a literal.
  • load is for paths known at runtime, such as "res://levels/level_%d.tscn" % n. It blocks until finished. Loading a big scene can cause a visible hitch.
  • For big or numerous resources, load in the background: ResourceLoader.load_threaded_request(path), poll with load_threaded_get_status(path), then load_threaded_get(path). This is used for loading screens.

Both return the same object if the resource is already in memory: Godot caches by path. Loading player.png twice gives you the identical Texture2D instance.

Sharing is the default: the duplicate trap

Because resources are shared, modifying one in place modifies it for everyone using it:

GDSCRIPT
# Two enemies share one material (set in the scene).
$Enemy1/Sprite2D.material.set_shader_parameter("flash", 1.0)
# Enemy2 flashes too!

To fix it, make a private copy:

GDSCRIPT
var mat := $Sprite2D.material.duplicate()
$Sprite2D.material = mat

In the Inspector, a resource property has a menu with Make Unique that does the same thing, and Local to Scene (a checkbox on the resource) makes Godot duplicate it automatically per instance. Remember this rule: editing a shared resource edits all users.

Saving and viewing resources

In the Inspector, a resource property such as Texture, Material or Shape can be created new (New CircleShape2D), loaded from a file, or saved with Save to a .tres file. A .tres file is plain text, readable in a diff. Built-in resources saved inside a scene are bundled into the .tscn ("sub resources"); saving them to their own file lets several scenes share them.

INI
[gd_resource type="CircleShape2D" format=3]

[resource]
radius = 16.0

Custom resources: your own data containers

You can define your own Resource types with a script. This is perfect for items, enemy stats, dialogue lines or settings, because designers can edit them in the Inspector without touching code.

GDSCRIPT
# item_data.gd
class_name ItemData
extends Resource

@export var display_name := "Item"
@export var price := 10
@export var icon: Texture2D
@export_multiline var description := ""

In the FileSystem dock choose New Resource..., search ItemData, and save it as sword.tres, then fill the fields in the Inspector. Use it:

GDSCRIPT
@export var item: ItemData

func _ready() -> void:
    print(item.display_name, " costs ", item.price)

Why not just use a dictionary? A custom resource gives you autocomplete, type checks, defaults, Inspector editing, drag-and-drop in exported variables and automatic saving. Resources can hold other resources and arrays of them, so an Inventory resource can hold Array[ItemData].

Do not load .tres or .res files from untrusted sources (for example downloaded mods or shared saves). A resource file can contain a script, which runs. Use JSON or a custom parser for data you do not trust.

ResourceSaver and save games

ResourceSaver.save(resource, "user://save.tres") writes a resource to disk, and load("user://save.tres") reads it back. Convenient for quick prototypes, but for real save files many developers prefer JSON or FileAccess for safety (see the warning above).

Stand-in: cache and sharing

This Python code is not Godot. It models the path cache and shows why editing a shared resource affects everyone, and what duplicate() fixes.

Python Stand-in (Python): cached loads and shared resources

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Common mistakes

  • Editing a shared resource and being surprised that all users change. Duplicate, or mark it Local to Scene.
  • Using preload with a variable path (an error).
  • Loading large resources in _process every frame. Load once and keep the reference.
  • Forgetting class_name on a custom resource, so it does not appear in "New Resource".
  • Opening untrusted .tres files.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which statement about load() and the same path is true?

    Godot caches resources by path, so repeated loads return the same instance.
  2. 2. Two sprites share one material resource. You change a shader parameter on one. What happens?

    Resources are shared by default. Use duplicate(), Make Unique or Local to Scene for a private copy.
  3. 3. What is a good use of a custom Resource?

    Custom resources are typed, editable data containers.
  4. 4. Why is loading untrusted .tres files risky?

    A resource file can embed a script, so untrusted data should use a plain format like JSON.

Summary

  • Resources are shared, reference-counted data objects; nodes are the active objects in the tree.
  • preload needs a constant path and runs at compile time; load is dynamic; threaded loading avoids hitches.
  • Resources are cached by path and shared: duplicate when you need a private copy.
  • Custom Resource classes with @export fields are an excellent way to store game data.
  • Never load resources from untrusted sources.

Next: GDScript Basics: Variables and Types