godot-resource-data-patterns

リソース設計で絶対にしてはいけないこと

• リソースのインスタンスを直接変更しないでください — .duplicate() を使わずに値（HP など）を変更すると、共有されている .tres がすべてのインスタンスに対して変更されます。
• リソースで型指定のない配列を使わないでください — @export var items: Array はロジックエラーの原因になります。型安全性を確保するため、必ず Array[ResourceClass] を使ってください。
• リソースに Node への参照を保存しないでください — 特定の SceneTree にのみ存在するオブジェクトはシリアライズできません。NodePath または UID を保存してください。
• リソースの getter/setter で負荷の高い計算を行わないでください — リソースはデータコンテナとして使ってください。ロジックは Node または専用の RefCounted クラスに任せてください。
• ResourceSaver.save() のエラーチェックを省略しないでください — 権限、ディスク容量、パスの問題などにより、保存に失敗することがあります。必ず戻り値を確認してください。
• 実行時に高頻度で変化するデータにリソースを使わないでください — 値が 1 秒間に 60 回変化する場合（速度など）、標準の変数のほうがリソースのプロパティより高速です。
• リソースの循環参照を許可しないでください — A.tres が B.tres を参照し、B.tres が A.tres を参照している場合、読み込み時にエンジンがクラッシュすることがあります。
• _init のデフォルト値を忘れないでください — new() 経由またはインスペクターで作成したリソースを編集できるよう、コンストラクターにデフォルト値を設定してください。
• 固有の状態が必要なエンティティ間でリソースを共有しないでください — コンポーネントには resource_local_to_scene = true または duplicate() を使ってください。
• 大規模なデータセットに .tres を使わないでください — 10,000 件の項目がある場合、個別のリソースファイルより JSON やカスタムバイナリ形式のほうが効率的なことがあります。

---

判断フロー：Resource、RefCounted、Node の使い分け

種類	使用する場面	ディスク／インスペクター
Resource	共有する定義、保存可能なデータ、@export による作成	.tres/.res、インスペクター ✅
RefCounted	一時的な実行時計算、永続化しないヘルパー	ディスクなし／インスペクター機能は限定的
Node	ツリー内で process/signals を持つシーンエンティティ	シーンファイル

Resource を使う対象： アイテム定義、ステータステンプレート、アビリティ、会話テーブル、敵の設定。 RefCounted を使う対象： ダメージ計算用の一時データ、短命なステートマシン、保存しないユーティリティ。

使用可能なスクリプト — シナリオに応じて必ず参照

シナリオ	必ず読むもの
ベース .tres を共有するインスタンスごとに変更可能なステータス（HP）	resource_local_to_scene.gd
Item → Weapon → StatusEffect のネストしたツリー／グラフ全体の保存	nested_resource_serialization.gd
多数のエンティティで 1 つの設定を共有する（フライウェイト）	resource_flyweight_caching.gd / flyweight_enemy_config.gd
カスタム @export データコンテナ	custom_data_resource.gd
シグナルを使ったリアクティブなステータス	character_stats_resource.gd
Resource の配列を使ったインベントリ	resource_based_inventory.gd
Resource ツリーをディスクに保存	resource_save_system.gd — Error を確認
プレイ前のプリロード／O(1) キャッシュ	resource_preloading_strategy.gd
実行時の Resource.new() による戦利品	dynamic_resource_generation.gd
検証／プール／ファクトリー	resource_validator.gd / resource_pool.gd / data_factory_resource.gd

専門的な注意点（重要）

CAUTION: duplicate(true) または resource_local_to_scene を使わずに、共有 .tres の実行時 HP／マナを変更すると、ディスク上のアセットが変更されます。つまり、**「1つにダメージを与えると、すべてにダメージが及ぶ」**バグが発生します。

• **.res と .tres：**本番環境ではバイナリの .res、デザインの差分確認には .tres を使います。入れ子のツリーは ResourceSaver で親と一緒に保存されます。
• **キャッシュ：**外部編集後に ResourceLoader.CACHE_MODE_REPLACE を使うと、古いキャッシュを回避できます。
• **シーンごとのローカル化／複製：**インスタンスごとのコンポーネントでは必須です — resource_local_to_scene.gd。
• **1万行以上：**個別の .tres ファイルは JSON／バイナリ形式に劣ります — 公式ドキュメントのバイナリシリアル化を参照してください。

詳細（必要に応じて読み込み）

パターン1～7の解説（ItemData、データベース、RefCounted による計算、ディレクトリスキャン、O(1) キャッシュ）— references/resource-patterns-deep.md。記憶に頼らず、nested_resource_serialization.gd を参考に入れ子の武器を実装してください。

参考資料

段階的開示：特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連する領域に処理を移す場合にのみ関連スキルを読み込んでください。スキル群全体を事前に読み込まないでください。

公式ドキュメント

• リソース — カスタムリソーススクリプト、.tres／.res、共有と duplicate() の使い分け、インスタンスごとの状態に使う resource_local_to_scene。
• データの選択 — インスペクターやシリアル化の要件に応じて、リソース、辞書、ConfigFile、通常のスクリプトのどれにデータを保存するかを判断する方法。
• Resource — ここで扱うすべてのデータコンテナパターンで使われる duplicate、emit_changed、resource_path、シーンごとのローカル化フラグ。
• ResourceLoader — フライウェイト共有やプリロードキャッシュを支える、キャッシュされた load とスレッド化リクエスト。
• ResourceSaver — カスタムリソースを user:// または res:// に保存し、返された Error を必ず確認します。
• RefCounted — ディスクへのシリアル化やインスペクターへのエクスポートを使わずに参照カウントが必要な場合の、軽量な実行時オブジェクト。
• ゲームの保存 — スロット単位の .tres 状態保存に ResourceSaver を組み合わせる、より幅広い保存方法。
• バックグラウンド読み込み — データベースや VFX パックの読み込みでメインスレッドが停止しないようにする、スレッド化された ResourceLoader のポーリング。
• GDScript のエクスポート — アイテムやクエストのリソースをインスペクターで安全に扱うための、型付き @export／Array[T]。
• バイナリシリアル化 API — 個別の .tres ファイルでは扱いきれない数千行のデータに適した、コンパクトな FileAccess パッキング。
• シーンの整理 — 共有リソースをシーンツリーの外に置く理由と、コンポーネントシーンでエクスポートされたデータを組み合わせる方法。

関連スキル

前提条件

• godot-project-foundations — 共有 .tres データベースを作成する前に必要な、プロジェクトのレイアウト、インポート、res:// の整理。
• godot-gdscript-mastery — カスタムリソーススクリプトに不可欠な class_name、型付き配列、セッター、@tool の規律。

関連項目

• godot-signal-architecture — リアクティブな UI やステータスを駆動する Resource changed／カスタムシグナルの所有権とファンアウトを扱います。
• godot-save-load-systems — ResourceSaver／ResourceLoader の保存フローを包む、スロットのバージョン管理、移行、安全なパスを扱います。
• godot-scene-management — 事前ロードされた Resource キャッシュを利用し、処理落ちを防ぐ Packed シーンとスレッド読み込みを扱います。
• godot-ability-system — アビリティ／バフの定義は Resource データです。このスキルでは、コンテナとシリアライズのパターンを扱います。
• godot-dialogue-system — 会話グラフとセリフテーブルはネストされた Resource であり、ここで扱う型付き配列や保存のパターンを再利用します。
• godot-performance-optimization — フライウェイト共有、RefCounted ペイロードのプーリング、大規模な場合にテキストの .tres より .res が適する状況を扱います。

下流／利用者

• godot-inventory-system — アイテムスタック、装備、バッグでは、ここで定義する ItemData／インベントリ Resource 配列を利用します。
• godot-procedural-generation — 実行時に Resource.new() を介して戦利品、クエスト、設定をインスタンス化するジェネレーターを扱います。
• godot-monte-carlo-balancer — .tres のステータスと経済テーブルが推奨される抽出元です。正規表現を大量に使う前にデータレイヤーを構築してください。

マスター

• godot-master — スキル横断での探索に使う、ライブラリルーター兼ミラー化されたモジュールエントリです。