bevy-physics

Bevy 0.19 — 使用 Rapier 实现物理效果

何时使用此技能

• 添加 2D/3D 刚体、碰撞体、传感器、关节或角色移动。
• 在 bevy_rapier 和 Avian 等替代方案之间做出选择。
• 在物理步进前后安排输入/游戏逻辑系统，避免变换抖动。
• 读取碰撞消息，或执行射线、形状、点和重叠查询。
• 配置无头物理、插值、连续碰撞检测（CCD）、碰撞组或测试。

Bevy 核心不包含物理引擎。对于 Bevy 0.19，请使用 bevy_rapier2d/bevy_rapier3d 0.36，这是成熟的 Rapier 集成方案。当其 ECS 原生架构或模块化求解器是 选择它的具体原因时，可考虑 avian2d/avian3d 0.7。不要在同一批模拟实体上同时安装两个引擎。

Rapier 3D 固定步进的标准模式

[dependencies]
bevy = "0.19"
bevy_rapier3d = "0.36"

use bevy::prelude::*;
use bevy_rapier3d::prelude::*;

const PHYSICS_HZ: f64 = 60.0;
const PHYSICS_DT: f32 = 1.0 / PHYSICS_HZ as f32;

#[derive(Component)]
struct Player;

#[derive(SystemSet, Debug, Clone, Copy, PartialEq, Eq, Hash)]
enum GamePhysics {
    Drive,
    React,
}

fn main() {
    let mut app = App::new();
    app.add_plugins(DefaultPlugins)
        .insert_resource(Time::<Fixed>::from_hz(PHYSICS_HZ))
        .insert_resource(TimestepMode::Fixed {
            dt: PHYSICS_DT,
            substeps: 1,
        })
        .add_plugins((
            RapierPhysicsPlugin::<NoUserData>::default().in_fixed_schedule(),
            RapierDebugRenderPlugin::default(),
        ))
        .configure_sets(
            FixedUpdate,
            (
                GamePhysics::Drive.before(PhysicsSet::SyncBackend),
                GamePhysics::React.after(PhysicsSet::Writeback),
            ),
        )
        .add_systems(Startup, setup)
        .add_systems(FixedUpdate, drive_player.in_set(GamePhysics::Drive))
        .add_systems(FixedUpdate, react_to_collisions.in_set(GamePhysics::React));
    app.run();
}

fn setup(mut commands: Commands) {
    commands.spawn((
        Camera3d::default(),
        Transform::from_xyz(8.0, 6.0, 12.0).looking_at(Vec3::ZERO, Vec3::Y),
    ));

    // A collider without RigidBody is fixed. Cuboid arguments are half-extents.
    commands.spawn((
        Name::new("Ground"),
        Collider::cuboid(8.0, 0.25, 8.0),
        Transform::from_xyz(0.0, -0.25, 0.0),
    ));

    commands.spawn((
        Name::new("Player"),
        Player,
        RigidBody::Dynamic,
        Collider::ball(0.5),
        Velocity::linear(Vec3::new(1.5, 0.0, 0.0)),
        ActiveEvents::COLLISION_EVENTS,
        Transform::from_xyz(0.0, 4.0, 0.0),
    ));
}

fn drive_player(mut bodies: Query<&mut Velocity, With<Player>>) {
    for mut velocity in &mut bodies {
        velocity.linear.x = 1.5;
    }
}

fn react_to_collisions(mut events: MessageReader<CollisionEvent>) {
    for event in events.read() {
        if let CollisionEvent::Started(a, b, _) = event {
            let _pair = (*a, *b);
        }
    }
}

该插件通常在 PostUpdate 中以 TimestepMode::Variable 运行。此示例会特意将其移至 FixedUpdate，使 Rapier 的 dt 与 Bevy 的固定时钟匹配，在 PhysicsSet::SyncBackend 之前驱动刚体，并在 PhysicsSet::Writeback 之后响应。若有意采用与帧同步的模拟，请保留默认调度；并在同一调度中安排系统顺序。

选择相关深入指南

问题	阅读
Cargo 配置文件、默认步进与固定/插值步进、多物理世界	设置与调度
刚体类型、碰撞体形状、质量、单位、CCD、变换控制权	刚体与碰撞体
碰撞消息、传感器、组、射线/形状查询、钩子	事件、查询与筛选
运动学角色移动、控制器输出、关节	控制器与关节
回滚、确定性限制、无头测试、性能证据	确定性与测试

Bevy 0.19 / Rapier 0.36 注意事项

• Velocity 字段名是 linear 和 angular，而不是 linvel 和 angvel。
• CollisionEvent 和 ContactForceEvent 是消息。至少一个碰撞体必须启用相应的 ActiveEvents 标志。
• ReadRapierContext 是一个 SystemParam；调用 .single() 并处理其 Result。 RapierContext 不是全局资源，而且 Rapier 支持多个物理世界。
• 动态刚体拥有其模拟姿态。反复写入其 Transform 等同于传送，通常会导致抖动；应改为写入力、冲量或速度。
• 运动学刚体会沿着你指定的轨迹移动，自身不会避开障碍物。请使用场景查询或 KinematicCharacterController。
• Rapier 的默认 Cargo 特性会引入 Bevy 资产/渲染辅助功能。无头构建或使用外部渲染器时，请禁用默认特性，并启用正确的 dim2/dim3 特性。
• RapierDebugRenderPlugin 用于诊断可视化，不是渲染器，也不是发布版本的必需项。

另请参阅

• bevy-core-concepts — 固定调度与顺序。
• bevy-rendering — 渲染与物理的权属边界。
• bevy-cameras — 用于拾取和瞄准的相机射线。
• 第三人称轨道相机 — Rapier 球体投射阻挡检测与恢复滞回。
• bevy-input-actions — 固定步进的移动/瞄准指令。
• bevy-testing — 确定性应用步进与无头世界。
• bevy-a11y — 无障碍移动、计时与瞄准替代方案。
• bevy-voxel-pipeline — 体素世界的碰撞体代理。