bevy-input-actions

Bevy 0.19 — 入力アクション

このスキルを使う場面

• ゲームプレイで、デバイスに依存せず、保存や再割り当てが可能なアクションとプロンプトが必要な場合。
• コントローラーの接続・並び順が動的に変わる場合や、複数のプレイヤーやデバイスで入力を共有する場合。
• マウスのキャプチャ、フォーカス喪失、Steam Deck、またはアダプティブなハードウェアに対して、単一のポリシーが必要な場合。
• フレーム単位のエッジやモーションを、決定的な FixedUpdate シミュレーションに反映する場合。

ゲームプレイでは生のキー入力を直接使わず、ハードコードされたコントローラーエンティティにも依存しません。 Bevy のフレーム入力を一度アクション状態に変換し、その状態をプレゼンテーションと固定シミュレーションの両方に渡します。

基本パターン

Bevy は InputSystems 内の PreUpdate で生の入力を更新します。ButtonInput、Gamepad、入力メッセージ、蓄積されたマウスモーションが現在のフレームを反映するよう、そのセットの後にトランスレーターを実行します。

use bevy::{input::InputSystems, prelude::*};

fn install_input(app: &mut App) {
    app.init_resource::<ActionBuffer>().add_systems(
        PreUpdate,
        translate_physical_input.after(InputSystems),
    );
}

#[derive(Resource, Default)]
struct ActionBuffer;

fn translate_physical_input(mut _actions: ResMut<ActionBuffer>) {}

keyboard / mouse / touch / Gamepad entities / Steam Input
                     |
                     v
        physical bindings + device calibration
                     |
                     v
       active action set/context + conflict policy
                     |
                     v
       frame action state + ordered transition queue
              |                         |
        Update/UI consumers      fixed-tick bridge

gameplay.jump、menu.confirm、camera.look のような、シリアライズ可能な安定したアクション ID を使います。バインド、ラベル、プロンプト、セーブデータ、分析では、これらの ID を参照します。Rust の enum 判別値やカタログの順序は、永続化の契約ではありません。

デバイスごとのストリーム内で正確な順序が重要なエッジについては、基になるキーボード、マウス、またはゲームパッドのメッセージを順序付きキューに変換します。単一の just_pressed 真偽値では、複数の状態遷移やその順序を表せません。押下状態やフィルタリング済みの軸は、最新値として保存できます。

Bevy 0.19 ではゲームパッドはエンティティです

fn inspect_gamepads(gamepads: Query<(Entity, &Gamepad)>) {
    for (entity, gamepad) in &gamepads {
        let move_x = gamepad.get(GamepadAxis::LeftStickX).unwrap_or(0.0);
        let jump_started = gamepad.just_pressed(GamepadButton::South);
        let _sample = (entity, move_x, jump_started);
    }
}

接続状態の変化には GamepadConnectionEvent を使い、接続、ボタン、軸の変化の相対的な順序が重要な場合は GamepadEvent を使います。アクティブなプレイヤーの割り当ては、バインドとは別に保存します。ECS の Entity は有効なデバイスハンドルであり、安定したデバイス ID やセーブファイルのキーではありません。

各デバイスのフィルタリングは、そのデバイスの GamepadSettings コンポーネントで設定します。内側のデッドゾーン、任意の外側キャリブレーション、レスポンスカーブ、最後のクランプを一度だけ適用します。ゲームプレイコードで、別の隠れたデッドゾーンを適用しないでください。

注意点：フレーム入力は固定ティック入力ではありません

生の入力はフレーム単位ですが、固定シミュレーションはそのフレーム内で 0 回、1 回、または複数回実行されることがあります。そのため、次の点に注意してください。

• 順序付きの押下・解放遷移は、固定ティックが消費するまで保持します。
• 相対モーションは、同じティックまで蓄積します。
• 遷移と相対モーションは、最初に実行可能なティックで一度だけ取り出します。
• 押下状態のボタンと絶対軸は、すべての固定ティックにコピーします。
• FixedUpdate の各反復で just_pressed や AccumulatedMouseMotion を個別に読み直さないでください。

ロールバックやネットワークシミュレーションでは、ブリッジの出力をシミュレーションティックに紐づけた明示的なコマンドフレームに変換し、リプレイ用に保持します。

マウスのキャプチャとフォーカス

ゲームプレイが視点入力を受け付けるときは、プライマリウィンドウの CursorOptions を通じてキャプチャし、カーソルを非表示にして CursorGrabMode::Locked を要求します。フォーカスを失ったら、ゲームプレイ入力を一時停止するかニュートラル状態にし、キャプチャを解除して、必要なアクションの解放を合成し、相対モーションをクリアします。意図的なユーザー操作があった場合にのみ再取得します。フォーカスが戻っただけでポインターを閉じ込めないでください。

フォーカスを失うと、キーボードの状態は Bevy によって解放されますが、ゲームパッドの状態はウィンドウのフォーカスとは無関係です。アクションレイヤーでは、操作状態が固着したり、予期しないゲームプレイアクションが発生したりしないよう、単一のポリシーが必要です。

関連する詳細ガイドを選ぶ

問題	参照先
安定したアクション、バインドの文法、コンテキスト、再割り当て、競合	アクションと再割り当て
デバイスの割り当て、ホットプラグ、デッドゾーン、Steam Deck、アダプティブなハードウェア	ゲームパッドとプラットフォーム
エッジキュー、マウスの蓄積、固定ティックの 0 回・複数回実行、ロールバック	固定ステップのバッファリング

レビューチェックリスト

• メニューやアクセシビリティ経由の操作を含む、すべてのゲームプレイ操作を名前付きアクションに割り当てられます。重要な操作には、同時押しや長押しに代わる方法が用意されています。
• プロンプトではキーを指定せず、現在有効な割り当てとデバイスのグリフが表示されます。
• コントローラーを1台切断しても、そのプレイヤーが別のコントローラーに気付かないうちに移行することはありません。
• 2つの固定ティックの間に行われた押下と解放は、順序どおりに1回だけ処理されます。
• ティックが発生しないフレームでマウスの動きが失われたり、追いつき処理のティックで増幅されたりすることはありません。
• フォーカスを失っても、アクションが押されたままになったり、ポインターのキャプチャが解除されなくなったりすることはありません。
• Steam Deckとアダプティブコントローラーのテストには、実機と保存済みの再割り当て設定を使用します。

関連項目

• bevy-a11y — アクションのアクセシビリティとコントローラーの受け入れ基準。
• bevy-core-concepts — PreUpdate、Update、FixedUpdate。
• bevy-testing — 固定ステップ入力の決定論的なテスト。
• Bevy ゲームパッドモジュール