Godot 4のCharacterBody2D/3D 完全ガイド

1. はじめに

Godot 4ではキャラクター移動に大きな変更が加えられました。旧KinematicBody2DとKinematicBody3DノードはCharacterBody2DとCharacterBody3Dに改名され、move_and_slide() APIは完全に再設計されました。Godot 3からの移行でも、新規開始でも、このガイドで必要な情報を全てカバーします。

CharacterBody2DとCharacterBody3Dはコードで制御されるキャラクター用の物理ボディです。RigidBodyとは異なり、力に自動的に反応せず、移動はすべてスクリプトで制御します。そのため、プレイヤーキャラクター、NPC、そして正確で決定論的な動きが必要なすべてのものに最適です。

2. Godot 3からの変更点

Godot 3からGodot 4でのキャラクター移動における主要な変更点は以下の通りです：

• KinematicBody2D が CharacterBody2D に変更
• KinematicBody3D が CharacterBody3D に変更
• velocity は組み込みプロパティになりました — move_and_slide()に渡す必要はありません
• move_and_slide() は引数なしになりました — velocityプロパティから直接読み取ります
• move_and_slide_with_snap() は削除されました — 代わりにfloor_snap_lengthプロパティを使用
• is_on_floor()、is_on_wall()、is_on_ceiling() は従来通り動作します
• get_gravity() がGodot 4.4で追加され、プロジェクトのデフォルト重力をVectorとして取得できるようになりました

3. 基本的な2Dプラットフォーマーコントローラー

これは標準的な横スクロールプラットフォーマーコントローラーです。キャラクターは左右に移動し、地面にいるときにジャンプできます。これはGodotが新しいCharacterBody2Dスクリプトを作成する際に生成するテンプレートです。

extends CharacterBody2D

const SPEED = 300.0
const JUMP_VELOCITY = -400.0

func _physics_process(delta: float) -> void:
    # Apply gravity when not on floor
    if not is_on_floor():
        velocity += get_gravity() * delta

    # Jump when on floor and jump pressed
    if Input.is_action_just_pressed("ui_accept") and is_on_floor():
        velocity.y = JUMP_VELOCITY

    # Horizontal movement
    var direction := Input.get_axis("ui_left", "ui_right")
    if direction:
        velocity.x = direction * SPEED
    else:
        velocity.x = move_toward(velocity.x, 0, SPEED)

    move_and_slide()

1行ずつの解説

• extends CharacterBody2D — CharacterBody2Dを継承し、velocity、move_and_slide()、is_on_floor()等にアクセスできます。
• SPEED = 300.0 — 水平方向の移動速度（ピクセル/秒）。
• JUMP_VELOCITY = -400.0 — 2DではY軸が下向きなので負の値。負の値でキャラクターが上方向に移動します。
• get_gravity() * delta — 毎フレーム重力を適用します。get_gravity()は下向きのVector2（例：Vector2(0, 980)）を返します。deltaを掛けることでフレームレートに依存しなくなります。
• Input.get_axis("ui_left", "ui_right") — 押されている方向キーに応じて-1.0から1.0のfloatを返します。アナログ入力にも対応。
• move_toward(velocity.x, 0, SPEED) — 入力がないとき滑らかにゼロまで減速します。3番目の引数は1回の呼び出しでの最大変化量です。
• move_and_slide() — 現在のvelocityを使ってボディを移動し、衝突を処理し、面に沿ってスライドし、velocityを自動的に更新します。

4. 基本的な2Dトップダウンコントローラー

トップダウンゲーム（RPG、ツインスティックシューター等）では、重力なしで4方向に移動します。プラットフォーマーよりコードはシンプルです。

extends CharacterBody2D

const SPEED = 200.0

func _physics_process(delta: float) -> void:
    var input_direction := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    velocity = input_direction * SPEED
    move_and_slide()

仕組み

• Input.get_vector()は4つの入力アクションから正規化されたVector2を返します。斜め移動が正しく処理され、ベクトルの長さは常に1.0または0.0なので、斜め移動が縦横移動より速くなりません。
• トップダウンビューなので重力は適用されません。velocityを直接設定するため（慣性なし）、入力がないときキャラクターは即座に停止します。

加速と摩擦の追加

加速と減速でより滑らかな操作感にするには：

extends CharacterBody2D

const SPEED = 200.0
const ACCELERATION = 1200.0
const FRICTION = 1000.0

func _physics_process(delta: float) -> void:
    var input_direction := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")

    if input_direction != Vector2.ZERO:
        velocity = velocity.move_toward(input_direction * SPEED, ACCELERATION * delta)
    else:
        velocity = velocity.move_toward(Vector2.ZERO, FRICTION * delta)

    move_and_slide()

5. 3Dサードパーソンコントローラー

3D版も同じパターンに従います。主な違いはVector3を使用し、transform.basisで2D入力を3Dワールド空間の移動に変換する点です。

extends CharacterBody3D

const SPEED = 5.0
const JUMP_VELOCITY = 4.5

func _physics_process(delta: float) -> void:
    # Apply gravity
    if not is_on_floor():
        velocity += get_gravity() * delta

    # Jump
    if Input.is_action_just_pressed("ui_accept") and is_on_floor():
        velocity.y = JUMP_VELOCITY

    # Get input and convert to 3D direction
    var input_dir := Input.get_vector("ui_left", "ui_right", "ui_up", "ui_down")
    var direction := (transform.basis * Vector3(input_dir.x, 0, input_dir.y)).normalized()

    if direction:
        velocity.x = direction.x * SPEED
        velocity.z = direction.z * SPEED
    else:
        velocity.x = move_toward(velocity.x, 0, SPEED)
        velocity.z = move_toward(velocity.z, 0, SPEED)

    move_and_slide()

2Dとの主な違い

• 単位: 3Dでは1単位 = 1メートル（慣例）。SPEED = 5.0は秒速5メートルを意味し、2Dのピクセル値よりずっと小さい数値です。
• ジャンプ速度は正: 3DではY軸が上向き（2Dとは逆）なので、JUMP_VELOCITY = 4.5は正の値です。
• 方向変換: transform.basis * Vector3(input_dir.x, 0, input_dir.y)は2D入力をキャラクターの向きに対する3D方向に変換します。入力のYがZ軸（3Dの前後）にマッピングされます。
• XとZのみ制御: velocity.xとvelocity.zを個別に設定し、velocity.yは重力とジャンプ用に残します。

6. 主要プロパティリファレンス

CharacterBody2DとCharacterBody3Dの両方が共有する重要なプロパティです。インスペクタまたはコードで調整できます。

7. move_and_slide()後の衝突検出

move_and_slide()を呼んだ後、発生した衝突を検査できます。特定のコライダータイプへの反応、着地時のサウンドエフェクト再生、壁ジャンプの実装などに便利です。

func _physics_process(delta: float) -> void:
    # ... set velocity here ...
    move_and_slide()

    # Check all collisions from this frame
    for i in get_slide_collision_count():
        var collision := get_slide_collision(i)
        var collider := collision.get_collider()
        print("Collided with: ", collider.name)
        print("Normal: ", collision.get_normal())
        print("Position: ", collision.get_position())

    # Practical example: bounce off enemies
    for i in get_slide_collision_count():
        var collision := get_slide_collision(i)
        if collision.get_collider().is_in_group("enemies"):
            velocity = collision.get_normal() * 300
            break

便利なKinematicCollisionメソッド

• get_collider() — ヒットしたオブジェクト。
• get_normal() — 衝突面の法線。面から離れる方向。
• get_position() — 衝突が発生したワールド空間上の点。
• get_travel() — 衝突前にボディが移動した距離。
• get_remainder() — 適用されなかった残りのモーション。
• get_collider_velocity() — コライダーの速度（移動プラットフォームに便利）。

8. 移行チートシート

Godot 3からGodot 4への変換クイックリファレンス：

9. よくある間違い

間違い1: move_and_slide()に引数を渡す

# ERROR: move_and_slide() takes no arguments in Godot 4
velocity = move_and_slide(velocity, Vector2.UP)

# Set velocity, then call move_and_slide() with no arguments
velocity.x = direction * SPEED
move_and_slide()

間違い2: move_and_slide()の前にvelocityを設定し忘れる

func _physics_process(delta: float) -> void:
    move_and_slide()  # velocity is Vector2.ZERO — nothing happens

間違い3: _physics_process()の代わりに_process()を使用

move_and_slide()は固定レート（デフォルト60Hz）で実行される_physics_process()内で呼ぶ必要があります。_process()を使うと物理がレンダリングフレームレートに連動し、挙動が不安定になります。

間違い4: CollisionShapeを設定していない

CollisionShape子ノードのないCharacterBody2D/CharacterBody3Dはすべてを通り抜けます。衝突形状がない場合、エディタに警告アイコンが表示されます。

間違い5: 毎フレームvelocity.yを重力で上書きする

# This overwrites any jump velocity!
velocity.y = gravity * delta  # should be +=, not =

# Gravity accumulates over time
velocity += get_gravity() * delta

間違い6: 床の上にいるとき重力を適用する

重力は必ずif not is_on_floor()で囲んでください。このチェックがないと、床の上でも重力が蓄積し続けます。キャラクターが崖から歩いて落ちるとき、自然に落下する代わりに極端な速度で急降下します。

10. AIでキャラクターコントローラーをセットアップ