bevy-physics

Bevy 0.19 — Rapier による物理演算

このスキルを使う場面

• 2D／3D の剛体、コライダー、センサー、ジョイント、またはキャラクターの移動を追加する場合。
• bevy_rapier と Avian などの代替手段を比較して選ぶ場合。
• 物理ステップの前後に入力／ゲームプレイシステムを配置し、Transform のちらつきを防ぐ場合。
• 衝突メッセージを読み取る場合や、レイ、形状、点、重なりのクエリを実行する場合。
• ヘッドレス物理演算、補間、CCD、衝突グループ、またはテストを設定する場合。

Bevy コアには物理エンジンが含まれていません。Bevy 0.19 では、成熟した Rapier 統合として bevy_rapier2d／bevy_rapier3d 0.36 を使用してください。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);
        }
    }
}

プラグインは通常、TimestepMode::Variable を使用して PostUpdate で実行されます。この例では意図的に実行先を FixedUpdate に変更し、Rapier の dt を Bevy の固定クロックに合わせ、PhysicsSet::SyncBackend より前にボディを動かし、 PhysicsSet::Writeback の後に反応します。フレームに連動するシミュレーションを意図している場合は、デフォルトのスケジュールを維持し、 その同じスケジュール内でシステムの実行順序を指定してください。

該当する詳細ガイドを選ぶ

問題	参照先
Cargo プロファイル、デフォルト／固定／補間ステップ、複数のワールド	セットアップとスケジューリング
ボディタイプ、コライダー形状、質量、単位、CCD、Transform の制御元	ボディとコライダー
衝突メッセージ、センサー、グループ、レイ／形状クエリ、フック	イベント、クエリ、フィルタリング
キネマティックなキャラクター移動、コントローラー出力、ジョイント	コントローラーとジョイント
ロールバック、決定性の制限、ヘッドレステスト、パフォーマンスの根拠	決定性とテスト

Bevy 0.19／Rapier 0.36 の注意点

• Velocity のフィールド名は linvel や angvel ではなく、linear と angular です。
• CollisionEvent と ContactForceEvent はメッセージです。対応する ActiveEvents フラグを有効にするコライダーが少なくとも 1 つ必要です。
• 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 — ボクセルワールド用のコライダープロキシ。