Struct leafwing_input_manager::input_map::InputMap

pub struct InputMap<A: Actionlike> { /* private fields */ }

A Multi-Map that allows you to map actions to multiple UserInputss, whether they are Buttonlike, Axislike or DualAxislike.

When inserting a binding, the InputControlKind of the action variant must match that of the input type. Use InputMap::insert to insert buttonlike inputs, InputMap::insert_axis to insert axislike inputs, and InputMap::insert_dual_axis to insert dual-axislike inputs.

Many-to-One Mapping

You can associate multiple Buttonlikes (e.g., keyboard keys, mouse buttons, gamepad buttons) with a single action, simplifying handling complex input combinations for the same action. Duplicate associations are ignored.

One-to-Many Mapping

A single Buttonlike can be mapped to multiple actions simultaneously. This allows flexibility in defining alternative ways to trigger an action.

Clash Resolution

By default, the InputMap prioritizes larger Buttonlike combinations to trigger actions. This means if two actions share some inputs, and one action requires all the inputs of the other plus additional ones; only the larger combination will be registered.

This avoids unintended actions from being triggered by more specific input combinations. For example, pressing both S and Ctrl + S in your text editor app would only save your file (the larger combination), and not enter the letter s.

This behavior can be customized using the ClashStrategy resource.

Examples

use bevy::prelude::*;
use leafwing_input_manager::prelude::*;
use leafwing_input_manager::InputControlKind;

// Define your actions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash, Reflect)]
enum Action {
    Move,
    Run,
    Jump,
}

// Because our actions aren't all Buttonlike, we can't derive Actionlike.
impl Actionlike for Action {
    // Record what kind of inputs make sense for each action.
    fn input_control_kind(&self) -> InputControlKind {
        match self {
            Action::Move => InputControlKind::DualAxis,
            Action::Run | Action::Jump => InputControlKind::Button,
        }
    }
}

// Create an InputMap from an iterable,
// allowing for multiple input types per action.
let mut input_map = InputMap::new([
    // Multiple inputs can be bound to the same action.
    // Note that the type of your iterators must be homogeneous.
    (Action::Run, KeyCode::ShiftLeft),
    (Action::Run, KeyCode::ShiftRight),
    // Note that duplicate associations are ignored.
    (Action::Run, KeyCode::ShiftRight),
    (Action::Jump, KeyCode::Space),
])
// Associate actions with other input types.
.with_dual_axis(Action::Move, KeyboardVirtualDPad::WASD)
.with_dual_axis(Action::Move, GamepadStick::LEFT)
// Associate an action with multiple inputs at once.
.with_one_to_many(Action::Jump, [KeyCode::KeyJ, KeyCode::KeyU]);

// You can also use methods like a normal MultiMap.
input_map.insert(Action::Jump, KeyCode::KeyM);

// Remove all bindings to a specific action.
input_map.clear_action(&Action::Jump);

// Remove all bindings.
input_map.clear();

Implementations

impl<A: Actionlike> InputMap<A>

pub fn handle_clashes( &self, updated_actions: &mut UpdatedActions<A>, input_store: &CentralInputStore, clash_strategy: ClashStrategy, gamepad: Gamepad, )

Resolve clashing button-like inputs, removing action presses that have been overruled

The usize stored in pressed_actions corresponds to Actionlike::index

pub fn decomposed(&self, action: &A) -> Vec<BasicInputs>

Gets the decomposed BasicInputs for each binding mapped to the given action.

impl<A: Actionlike> InputMap<A>

pub fn new(bindings: impl IntoIterator<Item = (A, impl Buttonlike)>) -> Self

Creates an InputMap from an iterator over Buttonlike action-input bindings. Note that all elements within the iterator must be of the same type (homogeneous).

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn with(self, action: A, button: impl Buttonlike) -> Self

Associates an action with a specific Buttonlike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn with_axis(self, action: A, axis: impl Axislike) -> Self

Associates an action with a specific Axislike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn with_dual_axis(self, action: A, axis: impl DualAxislike) -> Self

Associates an action with a specific DualAxislike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn with_one_to_many( self, action: A, inputs: impl IntoIterator<Item = impl Buttonlike>, ) -> Self

Associates an action with multiple Buttonlike inputs provided by an iterator. Note that all elements within the iterator must be of the same type (homogeneous).

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn with_multiple( self, bindings: impl IntoIterator<Item = (A, impl Buttonlike)>, ) -> Self

Adds multiple action-input bindings provided by an iterator. Note that all elements within the iterator must be of the same type (homogeneous).

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

impl<A: Actionlike> InputMap<A>

pub fn insert(&mut self, action: A, button: impl Buttonlike) -> &mut Self

Inserts a binding between an action and a specific Buttonlike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn insert_axis(&mut self, action: A, axis: impl Axislike) -> &mut Self

Inserts a binding between an action and a specific Axislike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn insert_dual_axis( &mut self, action: A, dual_axis: impl DualAxislike, ) -> &mut Self

Inserts a binding between an action and a specific Axislike input. Multiple inputs can be bound to the same action.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn insert_one_to_many( &mut self, action: A, inputs: impl IntoIterator<Item = impl Buttonlike>, ) -> &mut Self

Inserts bindings between the same action and multiple Buttonlike inputs provided by an iterator. Note that all elements within the iterator must be of the same type (homogeneous).

To insert a chord, such as Control + A, use a ButtonlikeChord.

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn insert_multiple( &mut self, bindings: impl IntoIterator<Item = (A, impl Buttonlike)>, ) -> &mut Self

Inserts multiple action-input Buttonlike bindings provided by an iterator. Note that all elements within the iterator must be of the same type (homogeneous).

This method ensures idempotence, meaning that adding the same input for the same action multiple times will only result in a single binding being created.

pub fn merge(&mut self, other: &InputMap<A>) -> &mut Self

Merges the provided InputMap into this map, combining their bindings, avoiding duplicates.

If the associated gamepads do not match, the association will be removed.

impl<A: Actionlike> InputMap<A>

pub const fn gamepad(&self) -> Option<Gamepad>

Fetches the Gamepad associated with the entity controlled by this input map.

If this is None, input from any connected gamepad will be used.

pub fn with_gamepad(self, gamepad: Gamepad) -> Self

Assigns a particular Gamepad to the entity controlled by this input map.

Use this when an InputMap should exclusively accept input from a particular gamepad.

If this is not called, input from any connected gamepad will be used. The first matching non-zero input will be accepted, as determined by gamepad registration order.

Because of this robust fallback behavior, this method can typically be ignored when writing single-player games.

pub fn set_gamepad(&mut self, gamepad: Gamepad) -> &mut Self

Assigns a particular Gamepad to the entity controlled by this input map.

Use this when an InputMap should exclusively accept input from a particular gamepad.

If this is not called, input from any connected gamepad will be used. The first matching non-zero input will be accepted, as determined by gamepad registration order.

Because of this robust fallback behavior, this method can typically be ignored when writing single-player games.

pub fn clear_gamepad(&mut self) -> &mut Self

Clears any Gamepad associated with the entity controlled by this input map.

impl<A: Actionlike> InputMap<A>

pub fn pressed( &self, action: &A, input_store: &CentralInputStore, clash_strategy: ClashStrategy, ) -> bool

Checks if the action are currently pressed by any of the associated Buttonlikes.

Accounts for clashing inputs according to the ClashStrategy and remove conflicting actions.

pub fn process_actions( &self, gamepads: &Gamepads, input_store: &CentralInputStore, clash_strategy: ClashStrategy, ) -> UpdatedActions<A>

Determines the correct state for each action according to provided CentralInputStore.

This method uses the input bindings for each action to determine how to parse the input data, and generates corresponding ButtonData, AxisData and DualAxisData.

For Buttonlike actions, this accounts for clashing inputs according to the ClashStrategy and removes conflicting actions.

Buttonlike inputs will be pressed if any of the associated inputs are pressed. Axislike and DualAxislike inputs will be the sum of all associated inputs.

impl<A: Actionlike> InputMap<A>

pub fn iter_buttonlike( &self, ) -> impl Iterator<Item = (&A, &Vec<Box<dyn Buttonlike>>)>

Returns an iterator over all registered Buttonlike actions with their input bindings.

pub fn iter_axislike( &self, ) -> impl Iterator<Item = (&A, &Vec<Box<dyn Axislike>>)>

Returns an iterator over all registered Axislike actions with their input bindings.

pub fn iter_dual_axislike( &self, ) -> impl Iterator<Item = (&A, &Vec<Box<dyn DualAxislike>>)>

Returns an iterator over all registered DualAxislike actions with their input bindings.

pub fn buttonlike_bindings(&self) -> impl Iterator<Item = (&A, &dyn Buttonlike)>

Returns an iterator over all registered Buttonlike action-input bindings.

pub fn axislike_bindings(&self) -> impl Iterator<Item = (&A, &dyn Axislike)>

Returns an iterator over all registered Axislike action-input bindings.

pub fn dual_axislike_bindings( &self, ) -> impl Iterator<Item = (&A, &dyn DualAxislike)>

Returns an iterator over all registered DualAxislike action-input bindings.

pub fn buttonlike_actions(&self) -> impl Iterator<Item = &A>

Returns an iterator over all registered Buttonlike actions.

pub fn axislike_actions(&self) -> impl Iterator<Item = &A>

Returns an iterator over all registered Axislike actions.

pub fn dual_axislike_actions(&self) -> impl Iterator<Item = &A>

Returns an iterator over all registered DualAxislike actions.

pub fn get(&self, action: &A) -> Option<Vec<UserInputWrapper>>

Returns a reference to the UserInput inputs associated with the given action.

Warning

Unlike the other get methods, this method is forced to clone the inputs due to the lack of trait upcasting coercion.

As a result, no equivalent get_mut method is provided.

pub fn get_buttonlike(&self, action: &A) -> Option<&Vec<Box<dyn Buttonlike>>>

Returns a reference to the Buttonlike inputs associated with the given action.

pub fn get_buttonlike_mut( &mut self, action: &A, ) -> Option<&mut Vec<Box<dyn Buttonlike>>>

Returns a mutable reference to the Buttonlike inputs mapped to action

pub fn get_axislike(&self, action: &A) -> Option<&Vec<Box<dyn Axislike>>>

Returns a reference to the Axislike inputs associated with the given action.

pub fn get_axislike_mut( &mut self, action: &A, ) -> Option<&mut Vec<Box<dyn Axislike>>>

Returns a mutable reference to the Axislike inputs mapped to action

pub fn get_dual_axislike( &self, action: &A, ) -> Option<&Vec<Box<dyn DualAxislike>>>

Returns a reference to the DualAxislike inputs associated with the given action.

pub fn len(&self) -> usize

Count the total number of registered input bindings.

pub fn is_empty(&self) -> bool

Returns true if the map contains no action-input bindings.

pub fn clear(&mut self)

Clears the map, removing all action-input bindings.

impl<A: Actionlike> InputMap<A>

pub fn clear_action(&mut self, action: &A)

Clears all input bindings associated with the action.

pub fn remove_at(&mut self, action: &A, index: usize) -> Option<()>

Removes the input for the action at the provided index.

Returns Some(()) if the input was found and removed, or None if no matching input was found.

Note

The original input cannot be returned, as the trait object may differ based on the InputControlKind.

pub fn remove(&mut self, action: &A, input: impl Buttonlike) -> Option<usize>

Removes the input for the action if it exists

Returns Some with index if the input was found, or None if no matching input was found.

Trait Implementations

impl<A: Clone + Actionlike> Clone for InputMap<A>

fn clone(&self) -> InputMap<A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Actionlike> Component for InputMap<A>

where Self: Send + Sync + 'static,

const STORAGE_TYPE: StorageType = bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_component_hooks(_hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

impl<A: Debug + Actionlike> Debug for InputMap<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: Actionlike> Default for InputMap<A>

fn default() -> Self

Returns the “default value” for a type.

impl<'de, A> Deserialize<'de> for InputMap<A>

where A: Deserialize<'de> + Actionlike,

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<A: Actionlike, U: Buttonlike> From<HashMap<A, Vec<U>>> for InputMap<A>

fn from(raw_map: HashMap<A, Vec<U>>) -> Self

Converts a HashMap mapping actions to multiple Buttonlikes into an InputMap.

Examples

use bevy::prelude::*;
use bevy::utils::HashMap;
use leafwing_input_manager::prelude::*;

#[derive(Actionlike, Debug, Clone, Copy, PartialEq, Eq, Hash, Reflect)]
enum Action {
    Run,
    Jump,
}

// Create an InputMap from a HashMap mapping actions to their key bindings.
let mut map: HashMap<Action, Vec<KeyCode>> = HashMap::default();

// Bind the "run" action to either the left or right shift keys to trigger the action.
map.insert(
    Action::Run,
    vec![KeyCode::ShiftLeft, KeyCode::ShiftRight],
);

let input_map = InputMap::from(map);

impl<A: Actionlike, U: Buttonlike> FromIterator<(A, U)> for InputMap<A>

fn from_iter<T: IntoIterator<Item = (A, U)>>(iter: T) -> Self

Creates a value from an iterator.

impl<A> FromReflect for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<Box<dyn Buttonlike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn Axislike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn DualAxislike>>>: FromReflect + TypePath + RegisterForReflection, Option<Gamepad>: FromReflect + TypePath + RegisterForReflection,

fn from_reflect(reflect: &dyn Reflect) -> Option<Self>

Constructs a concrete instance of Self from a reflected value.

fn take_from_reflect( reflect: Box<dyn Reflect>, ) -> Result<Self, Box<dyn Reflect>>

Attempts to downcast the given value to Self using, constructing the value using from_reflect if that fails.

impl<A> GetTypeRegistration for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<Box<dyn Buttonlike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn Axislike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn DualAxislike>>>: FromReflect + TypePath + RegisterForReflection, Option<Gamepad>: FromReflect + TypePath + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

impl<A: PartialEq + Actionlike> PartialEq for InputMap<A>

fn eq(&self, other: &InputMap<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl<A> Reflect for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<Box<dyn Buttonlike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn Axislike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn DualAxislike>>>: FromReflect + TypePath + RegisterForReflection, Option<Gamepad>: FromReflect + TypePath + RegisterForReflection,

fn get_represented_type_info(&self) -> Option<&'static TypeInfo>

Returns the TypeInfo of the type represented by this value.

fn into_any(self: Box<Self>) -> Box<dyn Any>

Returns the value as a Box<dyn Any>.

fn as_any(&self) -> &dyn Any

Returns the value as a &dyn Any.

fn as_any_mut(&mut self) -> &mut dyn Any

Returns the value as a &mut dyn Any.

fn into_reflect(self: Box<Self>) -> Box<dyn Reflect>

Casts this type to a boxed reflected value.

fn as_reflect(&self) -> &dyn Reflect

Casts this type to a reflected value.

fn as_reflect_mut(&mut self) -> &mut dyn Reflect

Casts this type to a mutable reflected value.

fn clone_value(&self) -> Box<dyn Reflect>

Clones the value as a Reflect trait object.

fn set(&mut self, value: Box<dyn Reflect>) -> Result<(), Box<dyn Reflect>>

Performs a type-checked assignment of a reflected value to this value.

fn try_apply(&mut self, value: &dyn Reflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable enumeration of “kinds” of type.

fn reflect_mut(&mut self) -> ReflectMut<'_>

Returns a mutable enumeration of “kinds” of type.

fn reflect_owned(self: Box<Self>) -> ReflectOwned

Returns an owned enumeration of “kinds” of type.

fn reflect_partial_eq(&self, value: &dyn Reflect) -> Option<bool>

Returns a “partial equality” comparison result.

fn apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

fn reflect_hash(&self) -> Option<u64>

Returns a hash of the value (which includes the type).

fn debug(&self, f: &mut Formatter<'_>) -> Result<(), Error>

Debug formatter for the value.

fn serializable(&self) -> Option<Serializable<'_>>

Returns a serializable version of the value.

fn is_dynamic(&self) -> bool

Indicates whether or not this type is a dynamic type.

impl<A> Serialize for InputMap<A>

where A: Serialize + Actionlike,

fn serialize<__S>(&self, __serializer: __S) -> Result<__S::Ok, __S::Error>

where __S: Serializer,

Serialize this value into the given Serde serializer.

impl<A> Struct for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<Box<dyn Buttonlike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn Axislike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn DualAxislike>>>: FromReflect + TypePath + RegisterForReflection, Option<Gamepad>: FromReflect + TypePath + RegisterForReflection,

fn field(&self, name: &str) -> Option<&dyn Reflect>

Returns a reference to the value of the field named name as a &dyn Reflect.

fn field_mut(&mut self, name: &str) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field named name as a &mut dyn Reflect.

fn field_at(&self, index: usize) -> Option<&dyn Reflect>

Returns a reference to the value of the field with index index as a &dyn Reflect.

fn field_at_mut(&mut self, index: usize) -> Option<&mut dyn Reflect>

Returns a mutable reference to the value of the field with index index as a &mut dyn Reflect.

fn name_at(&self, index: usize) -> Option<&str>

Returns the name of the field with index index.

fn field_len(&self) -> usize

Returns the number of fields in the struct.

fn iter_fields(&self) -> FieldIter<'_>

Returns an iterator over the values of the reflectable fields for this struct.

fn clone_dynamic(&self) -> DynamicStruct

Clones the struct into a DynamicStruct.

impl<A> TypePath for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike,

fn type_path() -> &'static str

Returns the fully qualified path of the underlying type.

fn short_type_path() -> &'static str

Returns a short, pretty-print enabled path to the type.

fn type_ident() -> Option<&'static str>

Returns the name of the type, or None if it is anonymous.

fn crate_name() -> Option<&'static str>

Returns the name of the crate the type is in, or None if it is anonymous.

fn module_path() -> Option<&'static str>

Returns the path to the module the type is in, or None if it is anonymous.

impl<A> Typed for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<Box<dyn Buttonlike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn Axislike>>>: FromReflect + TypePath + RegisterForReflection, HashMap<A, Vec<Box<dyn DualAxislike>>>: FromReflect + TypePath + RegisterForReflection, Option<Gamepad>: FromReflect + TypePath + RegisterForReflection,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<A: Actionlike> VisitAssetDependencies for InputMap<A>

fn visit_dependencies(&self, visit: &mut impl FnMut(UntypedAssetId))

impl<A: Actionlike> Asset for InputMap<A>

impl<A: Eq + Actionlike> Eq for InputMap<A>

impl<A: Actionlike> Resource for InputMap<A>

where Self: Send + Sync + 'static,

impl<A: Actionlike> StructuralPartialEq for InputMap<A>