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.

The maximum number of bindings (total) that can be stored for each action is 16. Insertions will silently fail if you have reached this cap.

By default, if two actions would be 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)]
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 unifiying types
  (GamepadButtonType::South, Action::Run),
  (GamepadButtonType::LeftTrigger, Action::Hide),
  (GamepadButtonType::RightTrigger, Action::Hide),
]);

// Insertion
input_map.insert(MouseButton::Left, Action::Run)
.insert(KeyCode::LShift, Action::Run)
// Chords
.insert_chord([KeyCode::LControl, KeyCode::R], Action::Run)
.insert_chord([InputKind::Keyboard(KeyCode::H),
               InputKind::GamepadButton(GamepadButtonType::South),
               InputKind::Mouse(MouseButton::Middle)],
           Action::Run)
.insert_chord([InputKind::Keyboard(KeyCode::H),
               InputKind::GamepadButton(GamepadButtonType::South),
               InputKind::Mouse(MouseButton::Middle)],
           Action::Hide);

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

Implementations

impl<A: Actionlike> InputMap<A>

pub fn handle_clashes(
    &self,
    action_data: &mut [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 = (impl Into<UserInput>, A)>
) -> 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;

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

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

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 orginal 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;

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

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

impl<A: Actionlike> InputMap<A>

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

Insert a mapping between input and action

Panics

Panics if the map is full and input is not a duplicate.

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

Insert a mapping between input and action at the provided index

If a matching input already existed in the set, it will be moved to the supplied index. Any input that was previously there will be moved to the matching input’s original index.

Panics

Panics if the map is full and input is not a duplicate.

pub fn insert_multiple(
    &mut self,
    input_action_pairs: impl IntoIterator<Item = (impl Into<UserInput>, A)>
) -> &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 that can be converted into a UserInput can be supplied.

Panics

Panics if the map is full and any of inputs is not a duplicate.

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

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

Any iterator that can be converted into a [Button] can be supplied, but will be converted into a PetitSet for storage and use. Chords can also be added with the insert method, if the UserInput::Chord variant is constructed explicitly.

Panics

Panics if the map is full and buttons is not a duplicate.

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
) -> Vec<ActionData>

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

Accounts for clashing inputs according to the ClashStrategy. The position in each vector corresponds to Actionlike::index().

impl<A: Actionlike> InputMap<A>

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

Returns an iterator over actions with their inputs

pub fn iter_inputs(&self) -> impl Iterator<Item = &PetitSet<UserInput, 16>>

Returns an iterator over all mapped inputs

pub fn get(&self, action: A) -> &PetitSet<UserInput, 16>

Returns the action mappings

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?

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) -> bool

Removes the input for the action at the provided index

Returns true if an element was 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

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: Actionlike> Deserialize<'de> for InputMap<A> where
    InputMap<A>: Default, 

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error> where
    __D: Deserializer<'de>, 

Deserialize this value from the given Serde deserializer.

impl<A: PartialEq + Actionlike> PartialEq<InputMap<A>> 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: &InputMap<A>) -> bool

This method tests for !=.

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

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

Serialize this value into the given Serde serializer.

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