/resource-pattern

name: resource-pattern
description: Use when creating data containers in Godot — custom Resources for configuration, items, stats, and editor integration

Resource Pattern in Godot 4.3+

Resources are Godot's built-in data containers. Use them for configuration, item definitions, character stats, and any data that lives outside the scene tree. All examples target Godot 4.3+ with no deprecated APIs.

> **Related skills:** **inventory-system** for Resource-based item definitions, **save-load** for Resource serialization, **component-system** for data-driven component configuration, **ability-system** for Resource-based ability definitions built on this pattern.

---

1. What Are Resources

A `Resource` is a reference-counted data object that:

• Is saved as a `.tres` (text) or `.res` (binary) file on disk
• Is editable directly in the Godot Inspector
• Is **loaded once and shared by default** — every node that loads the same path gets the same in-memory object
• Can be nested inside other Resources and PackedScenes
• Outlives a scene change only while something still references it (an autoload, a static var) — it is `RefCounted`, so the last reference going away frees it

Because Resources are shared by default, they are ideal for read-only data (item definitions, audio settings, ability blueprints). For per-instance mutable state, call `duplicate()` (or set `resource_local_to_scene`) — see section 8.

---

2. When to Use Resources

| Use Case | Example Resource | Alternative | |---|---|---| | Item definitions | `ItemData` with name, icon, value | Dictionary (loses type safety) | | Enemy configuration | `EnemyStats` with health, speed, damage | Exported vars on Node (not reusable) | | Character stats | `CharacterStats` with base values | Autoload (global state, hard to test) | | Ability definitions | `AbilityData` with cooldown, cost, effect | Hardcoded constants | | Level metadata | `LevelConfig` with music, time limit, goals | JSON (no editor integration) | | Audio / visual themes | `UIThemeData` with color palette, fonts | Theme resource (same idea, built-in) | | Dialogue trees | `DialogueLine` referencing next line | JSON (no type checking) |

Use a custom Resource any time you want **Inspector editing + typed data + sharing across scenes**.

---

3. Basic Custom Resource

GDScript

# item_data.gd
class_name ItemData
extends Resource

enum ItemType { WEAPON, ARMOUR, CONSUMABLE, QUEST }

@export var name:        String   = ""
@export var description: String   = ""
@export var icon:        Texture2D
@export var value:       int      = 0
@export var item_type:   ItemType = ItemType.CONSUMABLE

Create an instance in the editor: **right-click** the FileSystem panel → **New Resource** → choose `ItemData`. Fill in the Inspector fields and save as `res://data/items/health_potion.tres`.

Load it at runtime:

var potion: ItemData = load("res://data/items/health_potion.tres")
print(potion.name)        # "Health Potion"
print(potion.value)       # 50

C#

// ItemData.cs
using Godot;

[GlobalClass]
public partial class ItemData : Resource
{
    public enum ItemType { Weapon, Armour, Consumable, Quest }

    [Export] public string   Name        { get; set; } = "";
    [Export] public string   Description { get; set; } = "";
    [Export] public Texture2D Icon       { get; set; }
    [Export] public int      Value       { get; set; } = 0;
    [Export] public ItemType Type        { get; set; } = ItemType.Consumable;
}

> `[GlobalClass]` is required in C# so the editor recognizes the class and shows it in **New Resource**.

var potion = GD.Load<ItemData>("res://data/items/health_potion.tres");
GD.Print(potion.Name);   // "Health Potion"
GD.Print(potion.Value);  // 50

---

4. Editor Integration

Use `class_name` and `@icon` to make custom Resources first-class in the Inspector (add `@tool` only when setters must run in the editor) — they appear in the Resource picker, can be created via right-click "New Resource", show a custom icon. `@export_group` and `@export_subgroup` organize properties.

> See [references/editor-integration.md](references/editor-integration.md) for the full GDScript + C# pattern with `class_name`, `@icon`, `@export_group`.

---

5. Resource as Configuration

The strongest use case: data-driven game content. Loot tables, enemy stats, ability definitions, item catalogs all become custom Resources. Designers tweak `.tres` files in the Inspector; programmers wire the loader. Avoids JSON's loose schema and stringly-typed parsing.

> See [references/configuration-pattern.md](references/configuration-pattern.md) for a worked LootTable + DropEntry example (GDScript + C#).

---

6. Resource Collections

`@export var entries: Array[Entry] = []` exposes a typed array in the Inspector — drag and drop multiple Resource files. For startup-loaded sets, use `ResourcePreloader`. For asset-folder discovery at runtime, walk `DirAccess`.

> See [references/collections.md](references/collections.md) for typed-array exports (v1.6.0 C# parity preserved), `ResourcePreloader` setup, and the directory-walking loader pattern.

---

7. Resource vs Node

| Aspect | Resource | Node | |---|---|---| | Purpose | Data storage and configuration | Behavior, rendering, physics, input | | Scene tree | Not in the tree | Lives in the scene tree | | Lifecycle hooks | No tree callbacks (`_init`, `_setup_local_to_scene`) | `_ready`, `_process`, `_physics_process`, etc. | | Sharing | Shared by default (same path = same object) | Each instance is independent | | Serialization | Saved as `.tres` / `.res`, Inspector-editable | Saved inside `.tscn` | | Signals | Supported | Supported | | Use for | Item data, stats, config, ability blueprints | Player, enemy, UI widgets, cameras | | Avoid for | Anything needing per-frame updates or scene queries | Static data that never changes at runtime |

**Rule of thumb:** if it has no behavior