Module user_input

Helpful abstractions over user inputs of all sorts.

This module simplifies user input handling in Bevy applications by providing abstractions and utilities for various input devices like gamepads, keyboards, and mice. It offers a unified interface for querying input values and states, reducing boilerplate code and making user interactions easier to manage.

The foundation of this module lies in the UserInput trait, used to define the behavior expected from a specific user input source.

Need something specific? You can also create your own inputs by implementing the trait for specific needs.

Feel free to suggest additions to the built-in inputs if you have a common use case!

Control Types

UserInputs use the method UserInput::kind returning an InputControlKind to classify the behavior of the input (buttons, analog axes, etc.).

• InputControlKind::Button: Represents a digital input with an on/off state (e.g., button press). These inputs typically provide two values, typically 0.0 (inactive) and 1.0 (fully active).

• InputControlKind::Axis: Represents an analog input (e.g., mouse wheel) with a continuous value typically ranging from -1.0 (fully left/down) to 1.0 (fully right/up). Non-zero values are considered active.

• InputControlKind::DualAxis: Represents a combination of two analog axes (e.g., thumb stick). These inputs provide separate X and Y values typically ranging from -1.0 to 1.0. Non-zero values are considered active.

Basic Inputs

UserInputs use the method UserInput::decompose returning a BasicInputs used for clashing detection, see clashing input check for details.

Built-in Inputs

Gamepad Inputs

• Check gamepad button presses using Bevy’s GamepadButtonType directly.
• Access physical sticks using GamepadStick, GamepadControlAxis, and GamepadControlDirection.

Keyboard Inputs

• Check physical keys presses using Bevy’s KeyCode directly.
• Use ModifierKey to check for either left or right modifier keys is pressed.

Mouse Inputs

• Check mouse buttons presses using Bevy’s MouseButton directly.
• Track mouse motion with MouseMove, MouseMoveAxis, and MouseMoveDirection.
• Capture mouse wheel events with MouseScroll, MouseScrollAxis, and MouseScrollDirection.

Complex Composition

• Combine multiple inputs into a virtual button using ButtonlikeChord.

  • Only active if all its inner inputs are active simultaneously.
  • Combine values from all inner single-axis inputs if available.
  • Retrieve values from the first encountered dual-axis input within the chord.

• Create a virtual axis control:

  • GamepadVirtualAxis from two GamepadButtonTypes.
  • KeyboardVirtualAxis from two KeyCodes.

• Create a virtual directional pad (D-pad) for dual-axis control:

  • GamepadVirtualDPad from four GamepadButtonTypes.
  • KeyboardVirtualDPad from four KeyCodes.

• Create a virtual directional pad (D-pad) for triple-axis control:

  • KeyboardVirtualDPad3D from six KeyCodes.

Re-exports

• pub use self::chord::*;
• pub use self::gamepad::*;
• pub use self::keyboard::*;
• pub use self::mouse::*;

Modules

• chord
  This module contains ButtonlikeChord and its impls.
• gamepad
  Gamepad inputs
• keyboard
  Keyboard inputs
• mouse
  Mouse inputs
• testing_utils
  Utilities for testing user input.
• updating
  Logic for updating user input based on the state of the world.

Enums

• UserInputWrapper
  A wrapper type to get around the lack of trait upcasting coercion.

Traits

• Axislike
  A trait used for axis-like user inputs, which provide a continuous value.
• Buttonlike
  A trait used for buttonlike user inputs, which can be pressed or released.
• DualAxislike
  A trait used for dual-axis-like user inputs, which provide separate X and Y values.
• RegisterUserInput
  A trait for registering inputs.
• TripleAxislike
  A trait used for triple-axis-like user inputs, which provide separate X, Y, and Z values.
• UserInput
  A trait for defining the behavior expected from different user input sources.