godot-characterbody-2d

CharacterBody2D の実装

初心者向けの move_and_slide チュートリアルではなく、熟練者向けの CharacterBody2D の操作感システムです。

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

• 標準的なプレイヤーコントローラーに RigidBody2D を絶対に使わないでください — RigidBody は物理シミュレーションを行うオブジェクト向けです。レスポンスが良く、操作感を重視したプレイヤーの移動には、必ず CharacterBody2D を使ってください。
• move_and_slide() の前に velocity に delta を絶対に乗算しないでください — move_and_slide() が内部で delta を処理します。手動で乗算すると、移動がフレームレートに依存するようになります。
• ゲームプレイ中の移動に global_position の更新を絶対に使わないでください — velocity と move_and_slide() を使ってください。位置を直接変更すると、衝突判定、床へのスナップ、片方向ルールが迂回されます。
• position.y を少しずらして、絶対に片方向床を「すり抜け」ないでください — 片方向衝突形状とレイヤー／マスクを使ってください（また、一時的なマスクの無効化や、エリアとの衝突パターンも使用できます）。godot-2d-physics を参照してください。
• move_and_slide() の直後に床／壁／天井の状態を絶対に無視しないでください — is_on_floor()、is_on_wall()、is_on_ceiling()、およびスライド衝突が、コヨーテタイム、壁ジャンプ、頭打ちの判定を担います。
• 高速で階段を上る際に、デフォルトの floor_snap_length に絶対に頼らないでください — デフォルトのスナップ距離は、高速で移動するキャラクターには短すぎます。レイキャストベースのカスタム階段処理を使ってください。
• is_on_floor() が true のときに、絶対に重力を適用しないでください — 下向きの力が一定にかかると微細な揺れが生じ、床へのスナップと干渉します。着地時に velocity.y をリセットしてください。
• 主な接地判定に Area2D を絶対に使わないでください — is_on_floor() やシェイプキャストを優先してください。Area はトリガー用であり、接地状態の判定用ではありません。
• 天井への頭打ちを絶対に見落とさないでください — is_on_ceiling() のときに velocity.y をリセットしてください。そうしないと、重力に負けるまでプレイヤーが天井に浮いたままになります。
• ピクセルアートで物理座標を絶対に丸めないでください — 物理演算では高精度を維持し、_process 内で スプライト の位置だけを丸めてください（subpixel_movement_rounding.gd）。
• 敵の大群に対して queue_free() を絶対に連発しないでください — 生成と破棄が頻繁な場合は、弾や敵をプールしてください（performance_character_pooling.gd）。

---

CharacterBody2D を使う場面

必要なもの	ボディ
操作感を重視したプレイヤー／NPC／敵の移動	CharacterBody2D
転がる瓦礫、ラグドール風の小道具、物理的に積み重なるオブジェクト	RigidBody2D
固定されたレベルのコライダー	StaticBody2D / TileMapLayer の物理

判定ツリー → 必須スクリプト

タスク	最初に行うこと	次に行うこと（任意）	読み込まないもの
プラットフォーマーの基盤（コヨーテタイム、バッファー、加速／摩擦）	expert_physics_2d.gd	—	インラインのチュートリアル用コントローラー
コヨーテタイム／バッファーのみを切り出す	frame_perfect_coyote_time.gd	—	SKILL 内の重複したコヨーテタイム処理
可変ジャンプ／小ジャンプ	variable_jump_height.gd	—	—
傾斜／階段	slope_stair_snapping.gd	godot-raycasting-queries	—
壁滑り／壁ジャンプ	wall_slide_jump_refined.gd または wall_jump_controller.gd	—	比較する場合を除き、両方
ダッシュ＋無敵時間	dash_state_controller.gd または dash_controller.gd	—	比較する場合を除き、両方
空中制御の調整	aerial_drift_acceleration.gd	—	—
天井への張り付き／衝突	ceiling_bonk_detection.gd	—	—
ノックバック／風の衝撃	impulse_response_handler.gd	—	—
ピクセルアートのビジュアル	subpixel_movement_rounding.gd	—	物理処理中に global_position を丸めること
多数の AI ボディ	performance_character_pooling.gd	—	—
片方向プラットフォーム	Tile／StaticBody の片方向設定＋レイヤー／マスク	godot-tilemap-mastery / godot-2d-physics	position.y += 1 によるすり抜けのハック
トップダウン／戦車型の移動	movement-recipes.md	—	インラインの8方向移動チュートリアル
ジャンプ軌道のデバッグ調整	game_feel_profiler.gd	—	—
アニメーションのルートモーション	root_motion_controller.gd	godot-2d-animation	—

推奨手順： まず expert_physics_2d.gd を読みます。ダッシュ／壁／ジャンプのスクリプトを追加するのは、そのコントローラーを導入してからにしてください。スクリプトがすでに処理している場合は、シーン内にコヨーテタイム／バッファー／加速のループを再度インラインで記述しないでください。

片方向プラットフォーム（正しいレシピ）

1. プレイヤーをテレポートさせるのではなく、プラットフォームのコライダー（CollisionShape2D の片方向設定／TileSet の物理片方向設定）に片方向設定を適用します。
2. プラットフォームとプレイヤーに明示的な衝突レイヤー／マスクを設定し、下＋ジャンプを押している間はプラットフォームのビットを一時的にクリアする（または「衝突する」を無効にする）ことで、すり抜けられるようにします。その後、次の物理フレームで元に戻します。
3. すり抜け処理は物理ティックで行います。position の微調整で move_and_slide を回避してはいけません。
4. タイルの片方向設定では、TileSet の物理レイヤーを CharacterBody のマスクに合わせます。godot-tilemap-mastery と godot-2d-physics を参照してください。

熟練者向けキャラクター設計

1. 壁への張り付き（可変摩擦）

落下中に is_on_wall() を監視し、二値の壁滑りフラグを使う代わりに、摩擦係数（任意でタイルのカスタムデータから取得）を velocity.y に適用します。独自の張り付き処理を作るより、wall_slide_jump_refined.gd を優先してください。

2. アニメーション駆動の移動（ルートモーション）

AnimationTree.get_root_motion_position() を取得し、2D に変換して、velocity = motion / delta を設定し、その後 move_and_slide() を呼び出します。作成済みのクリップに合わせて足元を固定できます。godot-2d-animation と組み合わせてください。

3. ゲームフィールプロファイラー（ジャンプの軌道）

_draw() で過去の位置と現在の速度をデバッグ描画し、expert_physics_2d.gd のエクスポート値を調整しながら、頂点、コヨーテタイム、入力バッファの時間枠を視覚化します — game_feel_profiler.gd。

必須：トップダウン／戦車型のレシピ、動くプラットフォーム、スライド衝突への応答、落とし穴の一覧には、movement-recipes.md を参照してください。expert_physics_2d.gd がプラットフォーマーの対象範囲をすでにカバーしている場合は、読み込まないでください。

リファレンス

段階的な情報開示：特定の API を調べる場合にのみ公式ドキュメントへのリンクを開いてください。 関連スキルは作業を関連領域へ引き継ぐ場合に読み込み、スキル全体を事前に読み込まないでください。

公式ドキュメント

• CharacterBody2D の使用 — move_and_slide と床・壁・天井の動作に関する標準的な仕様です。ゲームプレイ中の移動に position を設定しないでください。
• CharacterBody2D — velocity、スナップ、is_on_floor／壁／天井の判定、スライド衝突のアクセサーに関する API です。
• 物理演算の概要 — CharacterBody と RigidBody／StaticBody の違い、およびレイヤー／マスクがすべての接触を制御する仕組みについて説明しています。
• 衝突形状（2D） — カプセル／ボックスのサイズ設定と、CollisionShape2D ノードのスケーリングによって法線や床の検出が壊れる理由について説明しています。
• 2D の移動 — ジューシーさのシステムに進む前に、トップダウン型とプラットフォーマーの基本で入力軸を速度に反映する方法を説明しています。
• キネマティックキャラクター（2D） — 階段や斜面のカスタム処理にも今なお参考となる、従来のスライド／衝突ループのパターンです。
• 物理演算の問題のトラブルシューティング — CharacterBody の操作感の不具合で発生する、一方向プラットフォーム、すり抜け、ジッターの診断方法を説明しています。
• レイキャスティング — is_on_floor() だけでは対応できない階段のスナップ、足場の端の確認、地面のプローブに使うダイレクトスペースレイについて説明しています。
• KinematicCollision2D — get_slide_collision から取得できる、壁ジャンプや天井への衝突に使うスライドごとの法線と残り移動量について説明しています。
• 物理補間の概要 — ジャンプ／コヨーテタイムのロジックを物理ティック上に保ちながら、高リフレッシュレートでも滑らかな表示を実現します。
• InputEvent — ジャンプの入力バッファやコヨーテタイムの時間枠が依存する、アクションの押下直後のタイミングについて説明しています。

関連スキル

前提条件

• godot-project-foundations — コヨーテタイムやジャンプの操作感を調整する前に、デフォルトの重力、物理演算のティックレート、2D レイヤー名を設定しておく必要があります。
• godot-gdscript-mastery — 型付きの_physics_process、タイマー、move_towardの適切な使用が、ここで扱うすべての移動スクリプトの基礎となります。
• godot-2d-physics — CharacterBody の動作を支える衝突レイヤー／マスクのマトリックス、片方向シェイプ、クエリの適切な管理を扱います。
• godot-input-handling — 物理演算ステップでアクションをサンプリングし、ジャンプバッファー／コヨーテタイムのウィンドウをフレーム単位で安定させます。

補完

• godot-raycasting-queries — is_on_*ヘルパーでは対応できない段差スナップ、壁張り付きの検出、足場の端を検出するレイを扱います。
• godot-tilemap-mastery — プラットフォーム用の片方向タイルとタイルの物理レイヤーは、CharacterBody のマスクと一致させる必要があります。
• godot-2d-animation — move_and_slideと競合することなく、床上／空中／ダッシュの状態に応じて歩行・ジャンプ・落下のアニメーションクリップを再生します。
• godot-state-machine-advanced — ダッシュ、壁滑り、空中状態は、巨大な_physics_processの分岐よりも拡張しやすく整理できます。
• godot-camera-systems — 追従／先読みカメラは、CharacterBody の速度や着地時のスナップと密接に連携します。
• godot-signal-architecture — 着地／ダッシュ／壁ジャンプのイベントを適切に管理し、UI／VFX のリスナーからイベントが大量に発生しないようにします。

下流／利用先

• godot-genre-platformer — ジャンルレベルのプラットフォーマーの操作感は、このスキルのコヨーテタイム、バッファー、斜面、片方向足場を活用します。
• godot-genre-metroidvania — 能力によって解放される移動（壁ジャンプ、ダッシュ）は、ここで定義するコントローラーを基盤とします。
• godot-combat-system — ノックバックやヒットストップは、同じvelocityとスライドループを通じて力積を適用します。
• godot-monte-carlo-balancer — コヨーテフレーム、ジャンプの高さ、ダッシュのクールダウン、空中加速はバランス調整のパラメーターです。推測するのではなく、シミュレーションしましょう。

マスター

• godot-master — ライブラリのルーターであり、関連する各ドメインと並ぶ CharacterBody2D の対応するエントリーポイントです。