GDScript Resources Practice

Mental model: Resource = definition (immutable). Node = behavior. Runtime state = separate vars or component. When you compose multiple Resources to configure a game entity, you're applying the builder pattern—assembling a complex object step by step.

For a printable quick reference of Resource patterns, see the GDScript resources cheat sheet.

# upgrade_data.gd
extends Resource
class_name UpgradeData

@export var id: String = ""
@export var display_name: String = ""
@export var icon: Texture2D
@export var damage_bonus: float = 0.0
@export var cooldown_multiplier: float = 1.0

With class_name, this shows up in "New Resource" and can be exported:

# In player script
@export var upgrades: Array[UpgradeData] = []

See @export annotations for range constraints and Inspector organization.

Use preload() when the file is known at compile time. Use load() when the path is dynamic (mods, user content).

# Compile-time: faster, checked by editor
const FIRE_UPGRADE := preload("res://data/upgrades/fire.tres")

# Runtime: for dynamic paths
func load_upgrade(path: String) -> UpgradeData:
    return load(path) as UpgradeData

Note: preload() is resolved at parse time—the resource is already in memory when the script loads. load() fetches from disk at runtime.

Resources are great for config/save data. They serialize all @export properties automatically:

# Save
ResourceSaver.save(save_data, "user://savegame.tres")

# Load
var save_data := load("user://savegame.tres") as SaveGameData

For more complex save systems, see the GDQuest resource-based save tutorial.

Resources are shared by default. If two enemies reference the same stats Resource and one modifies it, both see the change:

# BUG: Editing enemy_a's stats affects enemy_b!
enemy_a.stats.hp -= 10

Fix 1: Treat Resources as Immutable (Recommended)

var current_hp: int

func _ready() -> void:
    current_hp = stats.max_hp  # Copy the value, don't modify the Resource

Fix 2: Duplicate at the Mutation Boundary

func _ready() -> void:
    stats = stats.duplicate() as EnemyStats

When to duplicate: At the exact moment you need unique state—not earlier. For inventories, that's when an item is added/equipped.

Setting resource_local_to_scene = true tells Godot to duplicate the Resource per scene instance. However:

• Only works for exported resources in the Inspector, not runtime-created ones
• Broken with Arrays/Dicts — if the Resource is inside an array, local_to_scene is ignored (GitHub Issue #71243, still open in 4.3)
• Can cause unexpected behavior with nested resources

When in doubt: duplicate() explicitly where you need unique state.

duplicate(true) is supposed to deep-copy subresources, but it doesn't work for subresources inside Arrays/Dictionaries. This is a confirmed bug with 100+ reactions, targeted for Godot 4.5.

# inventory.gd
extends Resource
@export var items: Array[ItemData] = []

# BUG: items inside the array are NOT duplicated
var copy := inventory.duplicate(true)  # items still share references!

Workarounds:

1. Keep nested subresources as direct properties, not inside arrays/dicts
2. Manually duplicate nested resources when creating copies:

func deep_copy_inventory(inv: Inventory) -> Inventory:
    var copy := inv.duplicate() as Inventory
    copy.items = []
    for item in inv.items:
        copy.items.append(item.duplicate() as ItemData)
    return copy

print(enemy_a.stats.get_instance_id())
print(enemy_b.stats.get_instance_id())
# Same ID = same object = shared state risk

# Check where a resource came from
print(stats.resource_path)  # Empty if created at runtime

If you're building editor tooling or want Inspector previews to update when a Resource changes, call emit_changed() from setters:

extends Resource
class_name EnemyStats

@export var max_hp: int = 100:
    set(value):
        max_hp = value
        emit_changed()  # Notifies editor and dependent objects

This is essential for custom resources that drive tool scripts or @tool editor plugins.