CharacterBody2D/3D in Godot 4 — Complete Guide Godot 4のCharacterBody2D/3D 完全ガイド

1. Introduction 1. はじめに

Godot 4 introduced major changes to character movement. The old KinematicBody2D and KinematicBody3D nodes were renamed to CharacterBody2D and CharacterBody3D, and the move_and_slide() API was completely redesigned. If you're migrating from Godot 3 or starting fresh, this guide covers everything you need to know.

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

CharacterBody2D and CharacterBody3D are physics bodies designed for characters controlled by code. Unlike RigidBody, they don't respond to forces automatically — you control their movement entirely through script. This makes them ideal for player characters, NPCs, and anything that needs precise, deterministic movement.

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

2. What Changed from Godot 3 2. Godot 3からの変更点

Here are the most important changes between Godot 3 and Godot 4 for character movement:

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

• KinematicBody2D is now CharacterBody2D KinematicBody2D が CharacterBody2D に変更
• KinematicBody3D is now CharacterBody3D KinematicBody3D が CharacterBody3D に変更
• velocity is now a built-in property — you no longer pass it to move_and_slide() velocity は組み込みプロパティになりました — move_and_slide()に渡す必要はありません
• move_and_slide() takes no arguments — it reads directly from the velocity property move_and_slide() は引数なしになりました — velocityプロパティから直接読み取ります
• move_and_slide_with_snap() is removed — use the floor_snap_length property instead move_and_slide_with_snap() は削除されました — 代わりにfloor_snap_lengthプロパティを使用
• is_on_floor(), is_on_wall(), is_on_ceiling() still work the same way is_on_floor()、is_on_wall()、is_on_ceiling() は従来通り動作します
• get_gravity() was added in Godot 4.4 to read the project's default gravity as a Vector — very convenient get_gravity() がGodot 4.4で追加され、プロジェクトのデフォルト重力をVectorとして取得できるようになりました

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

This is the standard side-scrolling platformer controller. The character can move left/right and jump when on the ground. This is the template Godot generates when you create a new CharacterBody2D script.

これは標準的な横スクロールプラットフォーマーコントローラーです。キャラクターは左右に移動し、地面にいるときにジャンプできます。これは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()

Line-by-line Breakdown

1行ずつの解説

• extends CharacterBody2D — The script inherits from CharacterBody2D, giving us access to velocity, move_and_slide(), is_on_floor(), etc. extends CharacterBody2D — CharacterBody2Dを継承し、velocity、move_and_slide()、is_on_floor()等にアクセスできます。
• SPEED = 300.0 — Horizontal movement speed in pixels per second. SPEED = 300.0 — 水平方向の移動速度（ピクセル/秒）。
• JUMP_VELOCITY = -400.0 — Negative because Y-axis points downward in 2D. A negative value moves the character upward. JUMP_VELOCITY = -400.0 — 2DではY軸が下向きなので負の値。負の値でキャラクターが上方向に移動します。
• get_gravity() * delta — Applies project gravity each frame. get_gravity() returns a Vector2 pointing downward (e.g., Vector2(0, 980)). Multiplying by delta makes it frame-rate independent. get_gravity() * delta — 毎フレーム重力を適用します。get_gravity()は下向きのVector2（例：Vector2(0, 980)）を返します。deltaを掛けることでフレームレートに依存しなくなります。
• Input.get_axis("ui_left", "ui_right") — Returns a float from -1.0 to 1.0 based on which direction key is pressed. Supports analog input. Input.get_axis("ui_left", "ui_right") — 押されている方向キーに応じて-1.0から1.0のfloatを返します。アナログ入力にも対応。
• move_toward(velocity.x, 0, SPEED) — Smoothly decelerates to zero when no input is pressed. The third argument is the maximum change per call. move_toward(velocity.x, 0, SPEED) — 入力がないとき滑らかにゼロまで減速します。3番目の引数は1回の呼び出しでの最大変化量です。
• move_and_slide() — Moves the body using the current velocity, handles collisions, slides along surfaces, and updates velocity automatically. move_and_slide() — 現在のvelocityを使ってボディを移動し、衝突を処理し、面に沿ってスライドし、velocityを自動的に更新します。

4. Basic 2D Top-Down Controller 4. 基本的な2Dトップダウンコントローラー

For top-down games (RPGs, twin-stick shooters, etc.), you move in all four directions without gravity. The code is simpler than a platformer.

トップダウンゲーム（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()

How It Works

仕組み

• Input.get_vector() returns a normalized Vector2 from four input actions. This handles diagonal movement correctly — the vector's length is always 1.0 or 0.0, so diagonal movement isn't faster than cardinal movement. Input.get_vector()は4つの入力アクションから正規化されたVector2を返します。斜め移動が正しく処理され、ベクトルの長さは常に1.0または0.0なので、斜め移動が縦横移動より速くなりません。
• No gravity is applied since this is a top-down view. The character stops immediately when no input is given because we set velocity directly (no inertia). トップダウンビューなので重力は適用されません。velocityを直接設定するため（慣性なし）、入力がないときキャラクターは即座に停止します。

Adding Acceleration and Friction

加速と摩擦の追加

For a smoother feel with acceleration and deceleration:

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

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 Third-Person Controller 5. 3Dサードパーソンコントローラー

The 3D version follows the same pattern. The main difference is working with Vector3 and using transform.basis to convert 2D input into 3D world-space movement.

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()

Key Differences from 2D

2Dとの主な違い

• Units: In 3D, 1 unit = 1 meter (convention). So SPEED = 5.0 means 5 meters per second — much smaller numbers than 2D pixel values. 単位: 3Dでは1単位 = 1メートル（慣例）。SPEED = 5.0は秒速5メートルを意味し、2Dのピクセル値よりずっと小さい数値です。
• Jump velocity is positive: In 3D, Y-axis points upward (unlike 2D), so JUMP_VELOCITY = 4.5 is positive. ジャンプ速度は正: 3DではY軸が上向き（2Dとは逆）なので、JUMP_VELOCITY = 4.5は正の値です。
• Direction transform: transform.basis * Vector3(input_dir.x, 0, input_dir.y) converts 2D input into a 3D direction relative to the character's facing. The input's Y maps to the Z axis (forward/backward in 3D). 方向変換: transform.basis * Vector3(input_dir.x, 0, input_dir.y)は2D入力をキャラクターの向きに対する3D方向に変換します。入力のYがZ軸（3Dの前後）にマッピングされます。
• Only X and Z are controlled: We set velocity.x and velocity.z separately, leaving velocity.y for gravity and jumping. XとZのみ制御: velocity.xとvelocity.zを個別に設定し、velocity.yは重力とジャンプ用に残します。

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

Both CharacterBody2D and CharacterBody3D share these important properties. Adjust them in the Inspector or via code.

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

7. Collision Detection After move_and_slide() 7. move_and_slide()後の衝突検出

After calling move_and_slide(), you can inspect the collisions that occurred. This is useful for reacting to specific collider types, playing sound effects on landing, or implementing wall-jump mechanics.

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

Useful KinematicCollision Methods

便利なKinematicCollisionメソッド

• get_collider() — The object that was hit.ヒットしたオブジェクト。
• get_normal() — The collision surface normal. Points away from the surface.衝突面の法線。面から離れる方向。
• get_position() — The point in world space where the collision occurred.衝突が発生したワールド空間上の点。
• get_travel() — How far the body traveled before colliding.衝突前にボディが移動した距離。
• get_remainder() — The remaining motion that was not applied.適用されなかった残りのモーション。
• get_collider_velocity() — Velocity of the collider (useful for moving platforms).コライダーの速度（移動プラットフォームに便利）。

8. Migration Cheat Sheet 8. 移行チートシート

Quick reference for converting Godot 3 code to Godot 4:

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

9. Common Mistakes 9. よくある間違い

Mistake 1: Passing arguments to move_and_slide()

間違い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()

Mistake 2: Forgetting to set velocity before move_and_slide()

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

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

Mistake 3: Using _process() instead of _physics_process()

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

move_and_slide() must be called in _physics_process(), which runs at a fixed rate (default 60 Hz). Using _process() ties physics to the rendering frame rate, causing inconsistent behavior.

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

Mistake 4: Not setting up CollisionShape

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

A CharacterBody2D/CharacterBody3D without a CollisionShape child will move through everything. Godot shows a warning icon in the editor if the collision shape is missing.

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

Mistake 5: Overwriting velocity.y with gravity every frame

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

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

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

Mistake 6: Applying gravity when on the floor

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

Always wrap gravity in if not is_on_floor(). Without this check, gravity keeps accumulating while on the floor. When the character walks off a ledge, it will plummet at an extreme speed instead of falling naturally.

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

10. Set Up Character Controllers with AI 10. AIでキャラクターコントローラーをセットアップ