godot-camera-systems

絶対にしてはいけないこと

• 毎フレーム global_position = target.global_position を使用しないでください — 位置を瞬時に一致させると、動きがぎこちなくなります。lerp() または position_smoothing_enabled = true を使用してください。
• 恒久的なカメラ位置の設定に offset を使用しないでください — offset は揺れ、スウェイ、一時的な反動効果専用です。恒久的なフレーミングには position を使用してください。
• Camera2D の limit_smoothed = true を忘れないでください — 境界で視覚的に唐突に停止します。
• 同じビューポート内で複数の Camera2D ノードを同時に有効にしないでください — 最後に有効にしたカメラだけが優先されます。非アクティブなカメラは明示的に無効にしてください。
• コリジョンマスクなしで SpringArm3D を使用しないでください — 地形や壁を突き抜けます。ワールド／環境レイヤーに設定してください。
• position をランダム化して画面揺れを実装しないでください（またはシステム全体を offset の randf に頼らないでください） — フォローに重ねる専用の Trauma／Noise システムを使用してください（camera_shake_trauma_pro.gd）。
• 高速な物理ボディの子としてカメラを直接配置することを、デフォルトのリグにしないでください — 物理演算によるスタッターや親ノードの回転は、乗り物酔いを引き起こすことがあります。回転同期を無効にした RemoteTransform2D/3D／ファントムによる切り離しを推奨します（remote_transform_decoupling.gd、phantom_decoupling.gd）。
• 「上」ベクトルのフォールバックなしで、3D で look_at() を使用しないでください — 真上や真下のターゲットではカメラが反転します。ガード処理または Quaternion の計算を使用してください。
• ミニマップで SubViewport のデフォルト設定に頼らないでください — render_target_update_mode を UPDATE_WHEN_VISIBLE またはそれ以下の固定レートに設定してください。
• ズームに線形補間を使用しないでください — 指数的な lerp または Tween の TRANS_CUBIC を推奨します。

---

親子関係／切り離し（解決済み）

リグ	使用する状況	スクリプト
デフォルト： RemoteTransform／ファントム	プレイヤーが CharacterBody／高速で動く／回転する場合	remote_transform_decoupling.gd、phantom_decoupling.gd
プレイヤーの子としてのカメラ	低速なトップダウン／回転固定／プロトタイプのみ	明示的な注意事項：乗り物酔いや物理演算によるジッターが発生した場合は無効にしてください。位置の上書きによる揺れと決して併用しないでください
SpringArm3D + Camera3D	三人称視点での遮蔽対策	spring_lerp_camera_3d.gd — マスクが必須

利用可能なスクリプト

必須：該当する動作を実装する前にお読みください。プロジェクトのコードに randf を使用した揺れのサンプルを含めないでください。

• camera_shake_trauma_pro.gd — 画面の揺れ／インパクト演出には必須です。
• camera_shake_trauma.gd — 軽量版のトラウマ方式です。
• remote_transform_decoupling.gd — 物理ボディの追従にはデフォルトで必須です。
• phantom_decoupling.gd — 安定した追従を実現する別方式のファントムです。
• spring_lerp_camera_3d.gd — カスタムの3D追従スプリングを実装する前に必須です。
• deadzone_drag_margins.gd — プラットフォーマー向けのドラッグ／デッドゾーンです。
• camera_follow_2d.gd — 滑らかな2D追従用ヘルパーです。
• zoom_damping_controller.gd — 非線形ズームです。
• camera_state_machine.gd — 追従／固定／シネマティックの遷移です。
• cinematic_framing_logic.gd — 三分割法／リードルームです。
• minimap_viewport_manager.gd — SubViewportの更新モードです。
• split_screen_setup.gd — ローカルの複数カメラビューポートです。
• first_person_sway.gd — オフセットを使ったFPSの揺れ／スウェイです。
• juice_camera.gd — 演出用ヘルパーをまとめたものです。
• framing_box_camera_2d.gd — 複数ターゲットのAABBフレーミング＋ズーム調整です。
• occlusion_aware_camera_3d.gd — SpringArmでは不十分な場合のレイキャストによるオクルージョン処理です。
• trauma_debugger.gd — トラウマ減衰曲線を画面上に表示します（デバッグビルド用）。

エキスパート向けカメラアーキテクチャ

1. 複数ターゲットのフレーミング

ターゲットのAABBを計算 → カメラを中心に向けて線形補間 → 余白を確保できるようズーム／距離を調整します。演出用の揺れは offset のみに適用してください。必須：framing_box_camera_2d.gd。

2. オクルージョン（3D）

ワールド衝突マスクを設定した SpringArm3D を優先してください。カスタムリグでは、理想的なカメラ位置とターゲットの間で intersect_ray を使用します — occlusion_aware_camera_3d.gd（関連項目：godot-raycasting-queries）。

3. トラウマの監査

camera_shake_trauma_pro.gd の調整中に、トラウマの減衰をプロット（デバッグ描画）してください — trauma_debugger.gd を get_trauma() に接続します。生の randf オフセットデモで感触を検証しないでください。

複数ターゲットのフレーミング、カスタムのオクルージョンリグ、2D／3D追従のレシピ、シネマティック遷移には必須：camera-expert-patterns.md。既定のスクリプトでリグをすでにカバーできる場合は、読み込まないでください。

参考資料

段階的な情報開示：特定のAPIを調査する場合に限り公式ドキュメントのリンクを開いてください。関連ドメインへ振り分ける場合に限り関連スキルを読み込んでください。関連資料全体を事前に読み込まないでください。

公式ドキュメント

• Camera2D — 2D の追従、デッドゾーン、レベル境界の基盤となる位置／ドラッグマージン、limit_*／limit_smoothed、position_smoothing_* について説明しています。
• Camera3D — 三人称視点、FPS、シネマティックな 3D リグで使用する投影、look_at、カレントカメラのルール、環境のオーバーライドについて説明しています。
• スプリングアームを使った三人称カメラ — Camera3D だけを親にするとジオメトリにめり込む理由と、SpringArm3D の長さや形状で視界を確保する方法について説明しています。
• SpringArm3D — 三人称視点での遮蔽物によるカメラの引き寄せを信頼できるものにするために必要な、衝突マスク、マージン、スプリングの長さに関する API について説明しています。
• ビューポートの使用 — 複数のカメラ、SubViewport の構成、分割画面／ミニマップのビューでワールドを共有する場合と分離する場合について説明しています。
• SubViewport — ミニマップやローカル協力プレイの GPU／オーディオコストを左右する render_target_update_mode とオーディオリスナーのフラグについて説明しています。
• RemoteTransform2D — カメラを物理ボディの子にせず、カメラの位置をプレイヤーの回転／スケールから分離する方法について説明しています。
• 補間 — カスタムカメラが機械的になったり、カクついたりしないようにする、Lerp／指数関数的な追従とズームの減衰計算について説明しています。
• 物理補間（概要） — 描画と物理の更新タイミングが一致しないと、CharacterBody の動きを追うカメラがカクつく理由について説明しています。
• FastNoiseLite — 生の randf による位置の乱れではなく、トラウマ／オフセットシェイクに使うコヒーレントノイズについて説明しています。
• PathFollow2D — カメラを Path2D に沿って Tween で動かす際に使う、進行度の比率に基づいたシネマティックなパスについて説明しています。
• マウスと入力座標 — FPS のピッチ／ヨーや戦術視点のズームをビューポート間で一貫させる、ホイールズームとマウス視点移動の座標空間について説明しています。

関連スキル

前提条件

• godot-project-foundations — ストレッチモード、デフォルトのビューポート、入力マップの設定によって、追従スクリプトの実行前に Camera2D の制限と SubViewport のサイズの挙動が決まります。
• godot-gdscript-mastery — 状態マシンやスプリング追従で使う、型付きノード、_physics_process と _process の使い分け、Tween／await のパターンについて説明しています。
• godot-input-handling — FPS の視点移動、ズームの減衰、カメラのオービット操作に使う、マウスのキャプチャ、視点軸、マウスホイールのイベントについて説明しています。

補完

• godot-tweening — Follow／Static／Cinematic 間のカメラ遷移には、急な切り替えや線形ズームではなく、Tween（ease／trans）を使用してください。
• godot-characterbody-2d — 先読みカメラとデッドゾーンカメラでは、対象を映すプラットフォーマーのボディから実際の速度／接地状態を取得する必要があります。
• godot-physics-3d — SpringArm の衝突レイヤーと CharacterBody3D の移動は、安定した三人称視点や FPS の揺れを制御する親ノードにおける 3D 版の要素です。
• godot-raycasting-queries — SpringArm を使用しないカスタムの遮蔽対応カメラでも、正しい intersect_ray のマスクと除外対象が必要です。
• godot-state-machine-advanced — camera_state_machine が単純な enum では対応できなくなった場合、Follow／Static／Cinematic（およびカットシーンの所有権）を形式化します。
• godot-signal-architecture — トラウマの追加、カットシーンへの引き継ぎ、複数ターゲットのフレーミングは、ゲームプレイ側からカメラの内部にアクセスしなくて済むよう、シグナル駆動にする必要があります。

下流／利用側

• godot-performance-optimization — 更新モードの調整後も SubViewport のミニマップ、分割画面、常時稼働するセカンダリカメラがフレーム時間の大部分を占める場合は、対応を進めます。
• godot-monte-carlo-balancer — 揺れの強さ、ズームの公平性、複数ターゲットのフレーミングをシミュレーションし、カメラ演出によってヒットボックスや対戦に関する情報が隠れないようにします。
• godot-adapt-single-to-multiplayer — ローカル協力プレイでプレイヤーごとのカメラとリスナーの所有権が必要な場合に、分割画面の SubViewport パターンを利用します。
• godot-debugging-profiling — カメラのジッターの原因（物理ティック、RemoteTransform、トラウマ）を監視ツールと可視化ツールで特定してから、追従計算を書き換えます。

マスター

• godot-master — ライブラリのルーター兼ミラー化されたモジュールのエントリーポイントです。横断的なカメラ関連の懸念事項をどのドメインスキルが担当するかを調べる際に開きます。