Crate bevy_enhanced_input

source
Expand description

Dynamic and contextual input mappings inspired by Unreal Engine Enhanced Input for Bevy.

§What makes Enhanced Input… enhanced?

Instead of directly reacting to inputs from various sources (like keyboard, gamepad, etc.), you assign inputs to gameplay actions like Move or Jump, which are just unit structs markers. Actions are assigned to contexts, which are components that represent the current state of the player character, like OnFoot or InCar.

For example, if you have a player character that can be on foot or drive a car, you can swap the context to have the same keys perform different actions. On foot, pressing Space makes the character jump, while when driving, the same key acts as a brake.

§Core concepts

Entities can have any number of contexts, with evaluation order controlled by a defined priority. Actions can also consume inputs, allowing you to layer behaviors on top of each other.

Instead of reacting to raw input data like “Released” or “Pressed”, the crate provides modifiers and conditions.

Modifiers let you change the input before passing it to the action. We provide common modifiers, like DeadZone, Negate, etc., but you can add your own by implementing InputModifier.

Conditions define how an action activates. We also provide built-in conditions, such as Pressed, Released, Hold, etc. You can also add your game-specific conditions like CanJump by implementing InputCondition.

§Quick start

We provide a prelude module, which exports most of the typically used traits and types.

  1. Add EnhancedInputPlugin to your app.
  2. Define gameplay actions as unit structs and implement InputAction for them.
  3. Define context components and assign actions to them by implementing InputContext.
  4. Register contexts using ContextAppExt::add_input_context.
  5. Insert contexts to entities you want to control.
  6. Create observers to react on ActionEvent for each action.

For more details, see the documentation on relevant types. You can also find examples in the repository.

§Input and UI

Currently, Bevy does not have a focus management API. However, to prevent actions from being triggered while interacting with the UI, we implement temporary workarounds enabled by specific cargo features:

  • If the ui_priority feature is enabled, we check if any Interaction component is not Interaction::None and discard all mouse inputs.
  • If the egui_priority feature is enabled, we check if any egui context requires keyboard or mouse input and discard those inputs accordingly.

§Troubleshooting

If you face any issue, try to enable logging to see what is going on. To enable logging, you can temporarely set RUST_LOG environment variable to bevy_enhanced_input=debug (or bevy_enhanced_input=trace for more noisy output) like this:

RUST_LOG=bevy_enhanced_input=debug cargo run

The exact method depends on the OS shell.

Alternatively you can configure LogPlugin to make it permanent.

Modules§

Macros§

  • ignore_incompatible
    Simple helper to emit a warning if a dimension is not compatible with a modifier.

Structs§