godot-inventory-system

シナリオ別トリガー（どのスクリプトを開くか）

シナリオ	開くファイル
スロット式バッグ（WoW 風のスタック）	inventory_data_resource.gd + item_slot_data.gd + inventory_ui_controller.gd
テトリス式グリッド（Diablo/RE 風の占有範囲）	grid_inventory_logic.gd / inventory_grid.gd
装備	Item リソース + RPG のステータス補完；drag_and_drop_slot.gd でドラッグ
戦利品テーブル	loot_table_resource.gd + item_pickup_node.gd
永続化	inventory_persistence.gd（ネストされた Resource ではなく、ID と数量を保存）
消耗品	consumable_item_logic.gd
DB 検索	item_database_loader.gd

必ず読むこと

1. inventory_item_resource.gd — アイテムの設計図
2. inventory_data_resource.gd — 2 パス方式のスタック処理と重量検証
3. inventory_ui_controller.gd — スロットコントロールを再利用するリアクティブ UI

インベントリシステムで絶対にしてはいけないこと

• アイテムに Node を絶対に使わないこと — Item extends Resource。
• スタック数や重量の事前チェックなしに絶対に追加しないこと — まず容量を検証してください。
• UI からインベントリ配列を黙って変更させないこと — 変更はデータ側が管理し、UI は通知を受け取ります。
• 数量に float を絶対に使わないこと — スタック数は int です。
• 一括処理でアイテムごとにシグナルを絶対に送信しないこと — ループ後に inventory_updated を 1 回だけ送信します。
• アイテム参照を絶対にハードコードしないこと — String/StringName の ID とデータベースを使用してください。
• 更新のたびにすべてのスロットを queue_free して作り直さないこと — スロットウィジェットを再利用してください（UI コントローラーを参照）。
• _process 内で新しい Resource を割り当てないこと。
• 共有アイテムの設計図を実行時に変更しないこと — スタック／スロットのインスタンスで duplicate(true) を使い、1 つの拾得アイテムがすべての .tres コピーを壊さないようにしてください。
• スロットのアイテムが null の場合に .icon にアクセスしないこと — UI を描画する前に is_instance_valid() で確認してください。

判断フロー

アイテムを追加する

1. 重量／容量に問題はありませんか？
2. 第 1 パス：部分的なスタックを埋める
3. 第 2 パス：空のスロット／グリッド上の占有範囲を確認する
4. あふれた数量を返し、UI シグナルは 1 回だけ送信する

UI

• inventory_updated に一度だけ接続する
• 既存のスロットノードを更新し、スロット数が増えたときだけ作成する

保存

• item_id / resource_path と amount のみをシリアライズする — inventory_persistence.gd

詳細レシピ（必要に応じて）

トピック	参照先／スクリプト
Resource によるアイテムモデル	core-architecture.md + inventory_item_resource.gd
2 パス方式のスタック追加	inventory-manager.md + inventory_data_resource.gd
テトリス式グリッドの占有範囲	elite-technical-patterns.md + grid_inventory_logic.gd
装備とクラフト	equipment-system.md / crafting-integration.md
リアクティブ UI と保存 ID	ui-integration.md + inventory_persistence.gd

参照

段階的開示：特定の API を調査するときに限り、公式ドキュメントのリンクを開いてください。関連スキルは、関連分野へ案内するときに読み込んでください。格子構造全体を事前に読み込まないでください。

公式ドキュメント

• リソース — アイテム、スロット、インベントリには、スタックを軽量で共有可能な .tres データベースとして維持できるよう、ノードではなく Resource データを使用してください。
• リソース — 実行時のスタック／スロットインスタンスには duplicate(true) を使用し、数量を変更しても共有アイテムの設計データが破損しないようにしてください。
• GDScript のエクスポート — @export ／ @export_group を使用すると、アイテムのリソースで ID、アイコン、max_stack、重量、戦利品の重みをインスペクターから設定できます。
• シグナルの使用 — inventory_changed ／スロットのシグナルを発行して UI にデータを反映してください。スロットウィジェットから配列を通知なしに変更しないでください。
• シーンの構成 — 「シグナルは上へ、呼び出しは下へ」を維持してください。UI はシグナルを受け取り、インベントリのリソース／マネージャーが追加、削除、スタックのロジックを管理します。
• GUI コンテナー — カスタムのテトリス型配置を実装する前に、GridContainer ／コンテナーのサイズ設定をスロットグリッドの基本として使用してください。
• Control — 標準の _get_drag_data ／ _can_drop_data ／ _drop_data と set_drag_preview を使用すると、独自の入力処理を用意せずにインベントリのドラッグ＆スワップを実装できます。
• カスタム GUI コントロール — アイコン／数量を描画し、ドラッグ＆ドロップに対応するスロット Control を構築するためのパターンです。
• ゲームの保存 — スロット ID と数量（再帰的なリソース全体ではありません）を、プレイヤーのほかのセーブデータと一緒に保存してください。
• ResourceLoader — テクスチャをセーブデータに毎回埋め込むのではなく、ロード時に resource_path ／ID からアイテムの設計データを解決してください。
• JSON — FileAccess のセーブファイルでは、簡潔なインベントリ辞書（path／id ＋ amount）を使用して、入れ子になったリソースの構造が肥大化しないようにしてください。
• 乱数生成 — 重み付き戦利品の抽選や宝箱の中身には、UI コードのあちこちで場当たり的に randf() を使うのではなく、シード付き RNG のパターンが必要です。

関連スキル

前提条件

• godot-resource-data-patterns — インベントリはリソースを優先して構成します（アイテム、スロット、戦利品テーブル）。ノードベースのアイテムツリーを独自に考案する前に、コンポジション／シリアライズのパターンを学んでください。
• godot-signal-architecture — バッチ処理に対応した inventory_updated ／スロットのシグナルを使うと、アイテムごとの過剰な通知や不要な接続を発生させずに、リアクティブな UI を同期できます。
• godot-gdscript-mastery — 型付きリソース、Array／Dictionary によるスロットマップ、int によるスタック数の計算には、GDScript の確かな知識が必要です。
• godot-ui-containers — スロットグリッド、装備パネル、画面サイズに応じたインベントリウィンドウは、ドラッグ＆ドロップの仕上げに入る前に、コンテナーのレイアウトを基礎として構築してください。

補完

• godot-save-load-systems — インベントリの永続化では、プロジェクトのセーブスキーマを通じてデータを往復できる必要があります（ID と個数を使用し、移行に対応）。
• godot-rpg-stats — 装備ボーナス、所持重量、消耗品の効果には、一貫したステータス／修正値レイヤーが必要です。
• godot-economy-system — ショップ、売買、レア度に応じた重み付けを行う戦利品テーブルでは、同じアイテムリソースとスタックルールを使用します。
• godot-ability-system — 消耗品の巻物、スキルブック、アビリティを付与する装備は、インベントリからの付与を AbilityManager への登録につなげます。
• godot-combat-system — インベントリから装備した武器／防具は、ダメージ処理と命中処理のパイプラインに反映されます。DamageData はアイテムのメタデータと分離してください。
• godot-ui-theming — レア度の色、スロットのスタイル、ドラッグ時のプレビューは、スロットスクリプトにハードコードせず、Theme リソースに配置してください。

下流／利用側

• godot-monte-carlo-balancer — スタックサイズ、重量、ドロップ率、ショップ価格をデータ駆動にした後、モンテカルロシミュレーションで経済や戦利品の範囲を検証し、カーブをリリースする前に確認します。
• godot-genre-action-rpg — アクション RPG のバッグ、装備画面、戦利品ループは、このスキルを戦闘、ステータス、クエストと組み合わせて構成します。
• godot-genre-survival — 重量制限、消耗品、希少な戦利品は、サバイバルゲームのインベントリにおける中核的な制約です。
• godot-quest-system — 収集クエストでは has_item で所持品を確認し、同じインベントリの追加／削除 API を通じて報酬を付与します。

マスター

• godot-master — ライブラリのルーターであり、ミラー化されたモジュールのエントリです。関連スキルの検索や、ドメインスキルの編集後に共有スクリプトのミラーを同期する際に使用します。