godot-game-loop-collection

絶対にしてはいけないこと（コレクションの落とし穴）

• 安定したコレクション ID を絶対に再利用したり、省略したりしないでください — ID が重複すると二重にカウントされたり、上書きされたりします。ID が欠けていると、達成率やセーブデータに問題が生じます。
• 同じ Area の重複を絶対に二重にカウントしないでください — 再進入時に body_entered が再度発火することがあります。「収集済み」チェックや監視のワンショット無効化で防いでください。
• コレクションの識別子として NodePath を絶対に永続化しないでください — シーンを移動するとパスが壊れます。get_path() ではなく ID（StringName / int）を保存してください。
• 最後のアイテムで進行不能にしないでください — コンパスやスポーンのロジックが「残り > 1」に依存していると、最後のアイテムが見つからなくなります。
• ハントの進行状況をシーン内のノードだけに絶対に保存しないでください — レベルを再読み込みすると進行状況が失われます。収集済みセットは collection_manager.gd とセーブデータで管理してください。
• ID を確定せずに、エフェクトのないコレクションアイテムを絶対に queue_free() しないでください — 先に ID を確定（シグナル送信）し、次に VFX を再生してから、解放してください。
• コレクションアイテムのコリジョンシェイプを絶対に不均等にスケーリングしないでください — 重なりの計算が壊れます。シェイプリソースを編集してください。
• スポーン位置をコードに絶対にハードコードしないでください — hidden_item_spawner.gd で Marker3D / デザイナー配置ポイントを使ってください。
• UI のシルエットをコレクション状態の情報源に絶対にしないでください — アーカイブ UI はマネージャーの状態を反映するものであり、正規の状態はマネージャーが管理します。
• ハント完了時に大規模なレベルを同期的に絶対に読み込まないでください — スレッド化された ResourceLoader を使ってください（参考資料を参照）。
• ワーカースレッドから SceneTree を絶対に操作しないでください — call_deferred のみを使用してください。

---

基本手順（必須）

1. collectible_item.gd — item_id（一意）+ collection_id（ハント）、ワンショットの Area 拾得処理
2. collection_manager.gd — register_item() + get_remaining_ids() による、収集済み ID セットの正規の管理
3. collection_compass.gd — マネージャーの残り ID に item_id が含まれている最寄りのノード
4. 収集済み ID を godot-save-load-systems で永続化する

任意：ランダム生成のハントには hidden_item_spawner.gd、高度なループ / MainLoop ヘルパーには collection_loop_patterns.gd を使用します。

利用可能なスクリプト（全一覧）

• collectible_item.gd — 拾得アクターとして必須。インスタンスごとに安定した item_id と、ハント用の collection_id をエクスポートします
• collection_manager.gd — 進行状況を管理する中核として必須。start_collection(id, item_ids) の後に register_item(id, item_id) を呼び出します
• collection_compass.gd — プレイヤーを誘導する場合に必須。collection_manager を接続し、get_remaining_ids() を照会します
• hidden_item_spawner.gd — デザイナー用マーカー / 確率スポーン（固定配置のみのハントでは読み込まないでください）
• collection_loop_patterns.gd — 高度なループパターン（シンプルな ID ハントでは読み込まないでください）

コレクションの高度なパターン

1. コレクションの永続化（保存 / 読み込み）

マネージャーの収集済み item_id セットを collection_id ごとにシリアライズします（get_collected_ids() / restore_collected_ids() 経由の PackedStringArray）。ノードパスは使用しないでください。再読み込み時は、マネージャーがセットを復元し、item_id がすでに取得済みのコレクションアイテムは自動的に無効化されます。

2. コレクションアーカイブ UI（シルエット）

アイコンをグリッド表示します。未収集のアイコンは modulate でシルエット表示し、マネージャーからその ID のシグナルが送られたら表示します。UI が収集状態を独自に決めることはありません。

スレッド化された読み込み、MainLoop ヘルパー、アーカイブ / セーブの詳細には、collection-loop-advanced.md が必須です。固定 ID のシンプルなアイテム探しでは読み込まないでください。

参考資料

段階的に参照してください。特定の API を調べる場合にのみ公式ドキュメントのリンクを開き、関連分野へ移る場合にのみ関連スキルを読み込んでください。知識体系全体を事前に読み込まないでください。

公式ドキュメント

• Area3D — 3Dの収集アイテム用body_entered取得判定エリアと、プレイヤーだけが収集を発動するようにするレイヤー／マスクの設定。
• Using Area2D — 同じ収集アイテムのループをArea2D／Sprite2DのレーダーUIに適用する際の、2Dの重なり判定のパターン。
• Groups — get_nodes_in_group／call_groupを使って収集アイテムを登録し、ハードコードされたノードパスを使わずにリセットを一斉通知します。
• Idle and physics processing — 衝突に伴う進行状況の更新を_physics_process／物理フレームで行い、コンパス／UIの処理を_processで間引きます。
• SceneTree — 収集状態の遷移で使用する、一時停止フラグ、グループ、physics_frame、current_sceneの所有権について説明します。
• Change scenes manually — ハントを終了して次のレベルを読み込む際の、遅延解放とインスタンス化による引き継ぎについて説明します。
• Background loading — 大規模な収集アイテムのあるレベルでメインスレッドが停止しないようにする、ResourceLoader.load_threaded_request／ステータスのポーリングについて説明します。
• Saving games — FileAccessを使用してuser://に収集済みIDと進行状況の辞書を保存します。
• Vector math — 最も近い収集アイテムの方向をコンパスで示すためのdirection_to／get_angle_toについて説明します。
• Marker3D — ハードコードされた座標の代わりに、隠しアイテム探しでデザイナーが配置するスポーンアンカーについて説明します。
• Using signals — 取得アイテムからマネージャーやUIへ、型付きのitem_collected／collection_updatedを接続する方法について説明します。
• MainLoop — 高度なcollection_loop_patternsで参照される、カスタムループの拡張インターフェースです（SceneTreeで対応できるため、必要になることはほとんどありません）。

関連スキル

前提条件

• godot-project-foundations — マネージャー、マーカー、収集アイテムのシーンを接続する前に、シーンツリー、@onready、リソースの基本を学びます。
• godot-gdscript-mastery — 収集マネージャーやループのパターン全体で使用する、型付きシグナル、match、await、遅延呼び出しについて学びます。
• godot-physics-3d — 取得判定を妨げるArea3D／CollisionShape3Dのレイヤー設定と、不均一スケールに関する落とし穴について学びます。

補完

• godot-signal-architecture — 多数の収集アイテムから 1 つのマネージャーに通知する際の、安全な動的接続とイベントバスのパターンです。
• godot-scene-management — ハント終了時のレベル遷移における、スレッド化されたシーン切り替えと所有権のルールです。
• godot-save-load-systems — セッションをまたいでどのアイテムを収集済みのままにするかを管理する、永続性のあるセーブスキーマです。
• godot-ui-containers — collection_updated を使ったシルエットのアーカイブグリッドと進捗 HUD のレイアウトです。
• godot-particles — ピックアップに応答性を持たせるため、queue_free の前に生成する気持ちよさを演出する VFX です。
• godot-audio-systems — 収集イベントに連動する、ワンショットのピックアップ SFX とバスのルーティングです。
• godot-monte-carlo-balancer — 完了時間の分布に基づいて spawn_chance、目標数、ハントの長さを調整します。

下流／利用側

• godot-quest-system — 収集の進捗を、報酬や分岐を伴うクエスト目標として扱います。
• godot-inventory-system — アイテムを消費せず保持する場合に、収集したピックアップをインベントリへの付与に変換します。
• godot-theme-easter — 同じ収集ループに重ねる、季節限定のエッグハント演出です。

マスター

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