Struct leafwing_input_manager::input_map::InputMap

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

Maps from raw inputs to an input-method agnostic representation

Multiple inputs can be mapped to the same action, and each input can be mapped to multiple actions.

The provided input types must be able to be converted into a UserInput.

By default, if two actions are triggered by a combination of buttons, and one combination is a strict subset of the other, only the larger input is registered. For example, pressing both S and Ctrl + S in your text editor app would save your file, but not enter the letters s. Set the ClashStrategy resource to configure this behavior.

Example

use bevy::prelude::*;
use leafwing_input_manager::prelude::*;
use leafwing_input_manager::user_input::InputKind;

// You can Run!
// But you can't Hide :(
#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Hash, Reflect)]
enum Action {
    Run,
    Hide,
}

// Construction
let mut input_map = InputMap::new([
   // Note that the type of your iterators must be homogenous;
   // you can use `InputKind` or `UserInput` if needed
   // as unifying types
  (Action::Run, GamepadButtonType::South),
  (Action::Hide, GamepadButtonType::LeftTrigger),
  (Action::Hide, GamepadButtonType::RightTrigger),
]);

// Insertion
input_map.insert(Action::Run, MouseButton::Left)
.insert(Action::Run, KeyCode::ShiftLeft)
// Chords
.insert_modified(Action::Run, Modifier::Control, KeyCode::KeyR)
.insert_chord(Action::Run,
              [InputKind::PhysicalKey(KeyCode::KeyH),
               InputKind::GamepadButton(GamepadButtonType::South),
               InputKind::Mouse(MouseButton::Middle)],
           );

// Removal
input_map.clear_action(&Action::Hide);

Implementations

impl<A: Actionlike> InputMap<A>

pub fn handle_clashes( &self, action_data: &mut HashMap<A, ActionData>, input_streams: &InputStreams<'_>, clash_strategy: ClashStrategy )

Resolve clashing inputs, removing action presses that have been overruled

The usize stored in pressed_actions corresponds to Actionlike::index

impl<A: Actionlike> InputMap<A>

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

Creates a new InputMap from an iterator of (user_input, action) pairs

To create an empty input map, use the Default::default method instead.

Example

use leafwing_input_manager::input_map::InputMap;
use leafwing_input_manager::Actionlike;
use bevy::input::keyboard::KeyCode;
use bevy::prelude::Reflect;

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

let input_map = InputMap::new([
    (Action::Run, KeyCode::ShiftLeft),
    (Action::Jump, KeyCode::Space),
]);

assert_eq!(input_map.len(), 2);

pub fn build(&mut self) -> Self

Constructs a new InputMap from a &mut InputMap, allowing you to insert or otherwise use it

This is helpful when constructing input maps using the “builder pattern”:

1. Create a new InputMap struct using InputMap::default or InputMap::new.
2. Add bindings and configure the struct using a chain of method calls directly on this struct.
3. Finish building your struct by calling .build(), receiving a concrete struct you can insert as a component.

Note that this is not the original input map, as we do not have ownership of the struct. Under the hood, this is just a more-readable call to .clone().

Example

use leafwing_input_manager::prelude::*;
use bevy::input::keyboard::KeyCode;
use bevy::prelude::Reflect;

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

let input_map: InputMap<Action> = InputMap::default()
  .insert(Action::Jump, KeyCode::Space).build();

impl<A: Actionlike> InputMap<A>

pub fn insert(&mut self, action: A, input: impl Into<UserInput>) -> &mut Self

Insert a mapping between input and action

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

Insert a mapping between many input’s and one action

pub fn insert_multiple( &mut self, input_action_pairs: impl IntoIterator<Item = (A, impl Into<UserInput>)> ) -> &mut Self

Insert a mapping between the provided input_action_pairs

This method creates multiple distinct bindings. If you want to require multiple buttons to be pressed at once, use insert_chord. Any iterator convertible into a UserInput can be supplied.

pub fn insert_chord( &mut self, action: A, buttons: impl IntoIterator<Item = impl Into<InputKind>> ) -> &mut Self

Insert a mapping between the simultaneous combination of buttons and the action provided

Any iterator convertible into a InputKind can be supplied, but will be converted into a HashSet for storage and use. Chords can also be added with the insert method if the UserInput::Chord variant is constructed explicitly.

When working with keyboard modifier keys, consider using the insert_modified method instead.

pub fn insert_modified( &mut self, action: A, modifier: Modifier, input: impl Into<InputKind> ) -> &mut Self

Inserts a mapping between the simultaneous combination of the Modifier plus the input and the action provided.

When working with keyboard modifiers, should be preferred over insert_chord.

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

Merges the provided InputMap into the InputMap this method was called on

This adds both of their bindings to the resulting InputMap. Like usual, any duplicate bindings are ignored.

If the associated gamepads do not match, the resulting associated gamepad will be set to None.

impl<A: Actionlike> InputMap<A>

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

Fetches the [Gamepad] associated with the entity controlled by this entity map

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

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

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

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_streams: &InputStreams<'_>, clash_strategy: ClashStrategy ) -> bool

Is at least one of the corresponding inputs for action found in the provided input streams?

Accounts for clashing inputs according to the ClashStrategy. If you need to inspect many inputs at once, prefer InputMap::which_pressed instead.

pub fn which_pressed( &self, input_streams: &InputStreams<'_>, clash_strategy: ClashStrategy ) -> HashMap<A, ActionData>

Returns the actions that are currently pressed, and the responsible UserInput for each action

Accounts for clashing inputs according to the ClashStrategy.

impl<A: Actionlike> InputMap<A>

pub fn iter(&self) -> impl Iterator<Item = (&A, &Vec<UserInput>)>

Returns an iterator over actions with their inputs

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

Returns a reference to the inputs mapped to action

pub fn get_mut(&mut self, action: &A) -> Option<&mut Vec<UserInput>>

Returns a mutable reference to the inputs mapped to action

pub fn len(&self) -> usize

How many input bindings are registered total?

pub fn is_empty(&self) -> bool

Are any input bindings registered at all?

pub fn clear(&mut self)

Clears the map, removing all action-inputs pairs.

Keeps the allocated memory for reuse.

impl<A: Actionlike> InputMap<A>

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

Clears all inputs registered for the action

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

Removes the input for the action at the provided index

Returns Some(input) if found.

pub fn remove( &mut self, action: &A, input: impl Into<UserInput> ) -> 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,

type Storage = TableStorage

A marker type indicating the storage type used for this component. This must be either [TableStorage] or [SparseStorage].

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> From<HashMap<A, Vec<UserInput>>> for InputMap<A>

fn from(map: HashMap<A, Vec<UserInput>>) -> Self

Create InputMap<A> from HashMap<A, Vec<UserInput>>

Example

use leafwing_input_manager::input_map::InputMap;
use leafwing_input_manager::user_input::UserInput;
use leafwing_input_manager::Actionlike;
use bevy::input::keyboard::KeyCode;
use bevy::reflect::Reflect;

use bevy::utils::HashMap;

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Hash, Reflect)]
enum Action {
    Run,
    Jump,
}
let mut map: HashMap<Action, Vec<UserInput>> = HashMap::default();
map.insert(
    Action::Run,
    vec![KeyCode::ShiftLeft.into(), KeyCode::ShiftRight.into()],
);
let input_map = InputMap::<Action>::from(map);

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

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

Create InputMap<A> from iterator with the item type (A, UserInput)

impl<A> FromReflect for InputMap<A>

where Self: Any + Send + Sync, A: TypePath + Actionlike, HashMap<A, Vec<UserInput>>: FromReflect + TypePath, Option<Gamepad>: FromReflect + TypePath,

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<UserInput>>: FromReflect + TypePath, Option<Gamepad>: FromReflect + TypePath,

fn get_type_registration() -> TypeRegistration

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

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

This method tests for self and other values to be equal, and is used by ==.

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

This method 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<UserInput>>: FromReflect + TypePath, Option<Gamepad>: FromReflect + TypePath,

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 apply(&mut self, value: &dyn Reflect)

Applies 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 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<UserInput>>: FromReflect + TypePath, Option<Gamepad>: FromReflect + TypePath,

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<UserInput>>: FromReflect + TypePath, Option<Gamepad>: FromReflect + TypePath,

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>