Bevy 0.13中KinematicCharacterController.Translation无法移动物体问题

核心问题总结 #

1. Direction枚举缺失变体：代码中使用了Direction::Down和Direction::Up但枚举未定义，导致编译错误，无法正常执行移动逻辑。
2. 地面未设置静态刚体：地面仅添加了Collider，未设置RigidBody::Static，导致物理引擎无法识别其为碰撞体，无论哪种运动学刚体都无法与地面碰撞。
3. 位置型运动学刚体误用Velocity组件：RigidBody::KinematicPositionBased的运动由KinematicCharacterController控制，手动添加的Velocity组件会被Rapier忽略，且可能干扰控制器逻辑。
4. CharacterController位移设置不合理：固定设置y轴位移为-4.0会导致角色持续下坠，容易被地面卡住，应根据输入调整y轴（比如跳跃逻辑），否则保持y轴位移为0。

修正后的完整代码 #

use bevy::prelude::*;
use bevy_rapier2d::prelude::*;

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        .add_plugins(RapierPhysicsPlugin::<NoUserData>::pixels_per_meter(100.0))
        .add_plugins(RapierDebugRenderPlugin::default())
        .add_systems(Startup, setup_graphics)
        .add_systems(Startup, setup_physics)
        .add_systems(Update, player_movement)
        .run();
}

fn setup_graphics(mut commands: Commands) {
    commands.spawn(Camera2dBundle::default());
}

#[derive(Component)]
enum Direction {
    Left,
    Right,
    Up,
    Down,
    NoMovement,
}

#[derive(Component)]
struct Player;

fn setup_physics(mut commands: Commands) {
    // 地面：添加Static刚体，确保物理引擎识别为碰撞体
    commands
        .spawn(Collider::cuboid(500.0, 50.0))
        .insert(RigidBody::Static)
        .insert(TransformBundle::from(Transform::from_xyz(0.0, -100.0, 0.0)));

    // 玩家：使用位置型运动学刚体，移除多余的Velocity组件
    commands
        .spawn(RigidBody::KinematicPositionBased)
        .insert(Collider::ball(10.0))
        .insert(Direction::NoMovement)
        .insert(KinematicCharacterController {
            offset: CharacterLength::Absolute(0.1),
            snap_to_ground: Some(CharacterLength::Relative(0.2)),
            ..default()
        })
        .insert(Player);
}

fn player_movement(
    mut player_query: Query<(&mut KinematicCharacterController, &mut Direction), With<Player>>,
    time: Res<Time>,
    keys: Res<ButtonInput<KeyCode>>,
) {
    let (mut controller, mut direction) = player_query.single_mut();
    let speed = 300.0 * time.delta_seconds();
    let mut move_dir = Vec2::ZERO;

    // 直接根据按键更新移动方向，无需先修改Direction枚举（简化逻辑）
    if keys.pressed(KeyCode::KeyA) {
        move_dir.x -= speed;
    }
    if keys.pressed(KeyCode::KeyD) {
        move_dir.x += speed;
    }
    if keys.pressed(KeyCode::KeyW) {
        move_dir.y += speed;
    }
    if keys.pressed(KeyCode::KeyS) {
        move_dir.y -= speed;
    }

    // 设置控制器的位移增量
    controller.translation = Some(move_dir);

    // 可选：更新Direction枚举（如果需要其他系统使用）
    *direction = if move_dir == Vec2::ZERO {
        Direction::NoMovement
    } else if move_dir.x < 0 {
        Direction::Left
    } else if move_dir.x > 0 {
        Direction::Right
    } else if move_dir.y > 0 {
        Direction::Up
    } else {
        Direction::Down
    };
}

关键修改说明 #

1. 补全Direction枚举：添加Up和Down变体，解决编译错误。
2. 地面添加Static刚体：RigidBody::Static告诉Rapier这是一个固定的碰撞体，运动学刚体可以与其发生碰撞。
3. 移除玩家的Velocity组件：位置型运动学刚体的运动完全由KinematicCharacterController控制，Velocity组件在此场景下无用。
4. 简化移动逻辑：直接根据按键计算位移增量，避免先修改Direction再匹配的冗余步骤，同时让y轴位移随输入变化，而非固定下坠。
5. 添加Player标记组件：让查询更精准，避免误匹配其他实体。

关于基于速度的运动学刚体的补充说明 #

如果坚持使用RigidBody::KinematicVelocityBased，需要：

• 确保地面设置RigidBody::Static
• 直接修改Velocity组件的linvel，而非位移增量
• 该类型刚体不会被动态物体推动，但会与静态/动态物体发生碰撞，适合需要精确速度控制的场景

内容的提问来源于stack exchange，提问作者bilberry goat