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 GamepadButton 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.

Virtual Axial Controls

• VirtualAxis: Create a virtual axis control from two buttons.

• VirtualDPad: Create a virtual dual-axis control from four buttons.

• VirtualDPad3D: Create a virtual triple-axis control from six buttons.

Chords

• ButtonlikeChord: A combined input that groups multiple Buttonlikes together, allowing you to define complex input combinations like hotkeys, shortcuts, and macros.

• AxislikeChord: A combined input that groups a Buttonlike and an Axislike together, allowing you to only read the dual axis data when the button is pressed.

• DualAxislikeChord: A combined input that groups a Buttonlike and a DualAxislike together, allowing you to only read the dual axis data when the button is pressed.

• TripleAxislikeChord: A combined input that groups a Buttonlike and a TripleAxislike together, allowing you to only read the dual axis data when the button is pressed.

Re-exports

pub use self::chord::*;

pub use self::gamepad::*;

pub use self::keyboard::*;

pub use self::mouse::*;

pub use self::virtual_axial::*;

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.

virtual_axial

This module contains VirtualAxis, VirtualDPad, and VirtualDPad3D.

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 with a value for how much they are pressed.

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.