godot-resource-data-patterns

NEVER Do in Resource Design

• NEVER modify resource instances directly — Without .duplicate(), changing a value (like HP) modifies the shared .tres for everyone.
• NEVER use untyped arrays in Resources — @export var items: Array allows logic errors. Always use Array[ResourceClass] for type safety.
• NEVER store Node references in Resources — Objects that only exist in a specific SceneTree cannot be serialized. Store NodePath or UID.
• NEVER perform heavy calculations in Resource getters/setters — Resources should be data containers. Offload logic to Nodes or specialized RefCounted classes.
• NEVER skip ResourceSaver.save() error checks — Saving can fail due to permissions, disk space, or path issues. Always check the return code.
• NEVER use Resources for high-frequency runtime data — If a value changes 60 times a second (like velocity), a standard variable is faster than a Resource property.
• NEVER allow circular Resource references — If A.tres references B.tres and B.tres references A.tres, the engine may crash on load.
• NEVER forget the _init defaults — Resources created via new() or in the Inspector need default values in their constructor to be editable.
• NEVER share a Resource between entities if they need unique state — Use resource_local_to_scene = true or duplicate() for components.
• NEVER use .tres for massive datasets — If you have 10,000 items, a JSON or custom binary format might be more efficient than individualized Resource files.

---

Decision Tree: Resource vs RefCounted vs Node

| Type | Use when | Disk / Inspector |

|------|----------|------------------|

| Resource | Shared definitions, saveable data, @export authoring | .tres/.res, Inspector ✅ |

| RefCounted | Temporary runtime calcs, non-persistent helpers | No disk / weak Inspector |

| Node | Scene entities with process/signals in the tree | Scene files |

Use Resources for: item defs, stats templates, abilities, dialogue tables, enemy configs.

Use RefCounted for: damage calc scratchpads, ephemeral state machines, non-saved utilities.

Available Scripts — MANDATORY by Scenario

| Scenario | MANDATORY read |

|----------|----------------|

| Per-instance mutable stats (HP) sharing a base .tres | [resource_local_to_scene.gd](scripts/resource_local_to_scene.gd) |

| Nested Item → Weapon → StatusEffect trees / save whole graph | [nested_resource_serialization.gd](scripts/nested_resource_serialization.gd) |

| Many entities sharing one config (flyweight) | [resource_flyweight_caching.gd](scripts/resource_flyweight_caching.gd) / [flyweight_enemy_config.gd](scripts/flyweight_enemy_config.gd) |

| Custom @export data containers | [custom_data_resource.gd](scripts/custom_data_resource.gd) |

| Reactive stats with signals | [character_stats_resource.gd](scripts/character_stats_resource.gd) |

| Inventory arrays of Resources | [resource_based_inventory.gd](scripts/resource_based_inventory.gd) |

| Save Resource trees to disk | [resource_save_system.gd](scripts/resource_save_system.gd) — check Error |

| Preload / O(1) cache before play | [resource_preloading_strategy.gd](scripts/resource_preloading_strategy.gd) |

| Runtime Resource.new() loot | [dynamic_resource_generation.gd](scripts/dynamic_resource_generation.gd) |

| Validate / pool / factory | [resource_validator.gd](scripts/resource_validator.gd) / [resource_pool.gd](scripts/resource_pool.gd) / [data_factory_resource.gd](scripts/data_factory_resource.gd) |

Expert WHY (critical)

> CAUTION: Runtime HP/mana on a shared .tres without duplicate(true) or resource_local_to_scene mutates the asset on disk — the "damaging one damages all" bug.

• .res vs .tres: binary .res in production; .tres for design diffs; nested trees save with parent via ResourceSaver.
• Cache: ResourceLoader.CACHE_MODE_REPLACE after external edits bypass stale cache.
• Local-to-scene / duplicate: mandatory for per-instance components — [resource_local_to_scene.gd](scripts/resource_local_to_scene.gd).
• 10k+ rows: individualized .tres files lose to JSON/binary — see Official Docs binary serialization.

Deep dive (load on demand)

Pattern 1–7 walkthroughs (ItemData, databases, RefCounted calcs, directory scan, O(1) cache) — [references/resource-patterns-deep.md](references/resource-patterns-deep.md). Implement nested weapons from [nested_resource_serialization.gd](scripts/nested_resource_serialization.gd), not memory.

Reference

> Progressive disclosure: open Official Documentation links only when researching a specific API; load Related Skills when routing to a peer domain — do not preload the whole lattice.

Official Documentation

• Resources — Custom Resource scripts, .tres/.res, sharing vs duplicate(), and resource_local_to_scene for per-instance state.
• Data preferences — When to store data in Resources vs dictionaries, ConfigFile, or plain scripts for inspector and serialization needs.
• Resource — duplicate, emit_changed, resource_path, and local-to-scene flags used by every data container pattern here.
• ResourceLoader — Cached load / threaded requests that power flyweight sharing and preload caches.
• ResourceSaver — Persist custom Resources to user:// or res:// and always check the returned Error.
• RefCounted — Lightweight runtime objects when you need refcounting without disk serialization or Inspector exports.
• Saving games — Broader save strategies that pair with ResourceSaver for slot-based .tres state.
• Background loading — Threaded ResourceLoader polling so databases and VFX packs do not hitch the main thread.
• GDScript exports — Typed @export / Array[T] so item and quest Resources stay Inspector-safe.
• Binary serialization API — Compact FileAccess packing when thousands of rows outgrow individualized .tres files.
• Scene organization — Why shared Resources live outside scene trees and how component scenes compose exported data.

Related Skills

Prerequisites

• godot-project-foundations — Project layout, import, and res:// hygiene before authoring shared .tres databases.
• godot-gdscript-mastery — class_name, typed arrays, setters, and @tool discipline every custom Resource script depends on.

Complements

• godot-signal-architecture — Ownership and fan-out for Resource changed / custom signals that drive reactive UI and stats.
• godot-save-load-systems — Slot versioning, migration, and secure paths that wrap ResourceSaver/ResourceLoader save flows.
• godot-scene-management — Packed scenes and threaded loads that consume preloaded Resource caches without hitch spikes.
• godot-ability-system — Ability/buff definitions are Resource data; this skill owns the container and serialization patterns.
• godot-dialogue-system — Dialogue graphs and line tables are nested Resources that reuse typed-array and save patterns here.
• godot-performance-optimization — Flyweight sharing, pooling RefCounted payloads, and when .res beats text .tres at scale.

Downstream / consumers

• godot-inventory-system — Item stacks, equipment, and bags consume ItemData / inventory Resource arrays defined here.
• godot-procedural-generation — Generators that instantiate loot, quests, and configs via Resource.new() at runtime.
• godot-monte-carlo-balancer — .tres stats and economy tables are the preferred extract source — build the data layer before regex farms.

Master

• godot-master — Library router and mirrored module entry for cross-skill discovery.