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 中新增，可将项目的默认重力作为向量读取——非常方便

3. 基础 2D 平台游戏控制器

这是标准的横向卷轴平台游戏控制器。角色可以左右移动，并在地面上时跳跃。这也是你创建新的 CharacterBody2D 脚本时 Godot 生成的模板。

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

逐行解析

• 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 的浮点数。支持模拟输入。
• move_toward(velocity.x, 0, SPEED) — 在没有输入时平滑地减速到零。第三个参数是每次调用的最大变化量。
• move_and_slide() — 使用当前 velocity 移动物理体，处理碰撞，沿表面滑动，并自动更新 velocity。

4. 基础 2D 俯视角控制器

对于俯视角游戏（RPG、双摇杆射击等），你在没有重力的情况下向四个方向移动。代码比平台游戏更简单。

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() 从四个输入动作返回一个归一化的 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：使用 _process() 而非 _physics_process()

move_and_slide() 必须在 _physics_process() 中调用，它以固定速率运行（默认 60 Hz）。使用 _process() 会把物理与渲染帧率绑定，导致行为不一致。

错误 4：未设置 CollisionShape

没有 CollisionShape 子节点的 CharacterBody2D/CharacterBody3D 会穿过一切。如果缺少碰撞形状，Godot 会在编辑器中显示一个警告图标。

错误 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 搭建角色控制器