Struct leafwing_input_manager::input_map::InputMap

pub struct InputMap<A: Actionlike> {
    pub map: HashMap<A, PetitSet<UserInput, 16>>,
    /* 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 one of [GamepadButtonType], [KeyCode] or [MouseButton].

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.

In addition, you can configure the per-mode cap for each InputMode using InputMap::new or InputMap::set_per_mode_cap. This can be useful if your UI can only display one or two possible keybindings for each input mode.

Example

use bevy::prelude::*;
use leafwing_input_manager::prelude::*;
use leafwing_input_manager::user_input::InputButton;
use strum::EnumIter;

// You can Run!
#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Hash, EnumIter)]
enum Action {
    Run,
    Hide,
}

let mut input_map: InputMap<Action> = InputMap::default();

// Basic insertion
input_map.insert(Action::Run, GamepadButtonType::South);
input_map.insert(Action::Run, MouseButton::Left);
input_map.insert(Action::Run, KeyCode::LShift);
input_map.insert_multiple(Action::Hide, [GamepadButtonType::LeftTrigger, GamepadButtonType::RightTrigger]);

// Combinations!
input_map.insert_chord(Action::Run, [KeyCode::LControl, KeyCode::R]);
input_map.insert_chord(Action::Hide, [InputButton::Keyboard(KeyCode::H),
                                      InputButton::Gamepad(GamepadButtonType::South),
                                      InputButton::Mouse(MouseButton::Middle)]);

// But you can't Hide :(
input_map.clear_action(Action::Hide, None);

Fields

map: HashMap<A, PetitSet<UserInput, 16>>

The raw [HashMap] of PetitSets used to store the input mapping

Implementations

impl<A: Actionlike> InputMap<A>

pub fn new(per_mode_cap: usize) -> Self

Creates a new empty InputMap

The per_mode_cap controls the maximum number of inputs of each InputMode that can be stored. If a value of 0 is supplied, no cap will be provided (although the global CAP must still be obeyed).

PANICS: 3 * per_mode_cap cannot exceed the global CAP, as we need space to store all mappings.

impl<A: Actionlike> InputMap<A>

pub fn pressed(
    &self,
    action: A,
    gamepad_input_stream: &Input<GamepadButton>,
    keyboard_input_stream: &Input<KeyCode>,
    mouse_input_stream: &Input<MouseButton>
) -> bool

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

pub fn any_pressed(
    &self,
    inputs: &PetitSet<UserInput, 16>,
    gamepad_input_stream: &Input<GamepadButton>,
    keyboard_input_stream: &Input<KeyCode>,
    mouse_input_stream: &Input<MouseButton>
) -> bool

Is at least one of the inputs pressed?

pub fn button_pressed(
    &self,
    button: InputButton,
    gamepad_input_stream: &Input<GamepadButton>,
    keyboard_input_stream: &Input<KeyCode>,
    mouse_input_stream: &Input<MouseButton>
) -> bool

Is the button pressed?

pub fn all_buttons_pressed(
    &self,
    buttons: &PetitSet<InputButton, 8>,
    gamepad_input_stream: &Input<GamepadButton>,
    keyboard_input_stream: &Input<KeyCode>,
    mouse_input_stream: &Input<MouseButton>
) -> bool

Are all of the buttons pressed?

impl<A: Actionlike> InputMap<A>

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

Returns the mapping between the action that uses the supplied input_mode

If input_mode is None, all inputs will be returned regardless of input mode.

For chords, an input will be returned if any of the contained buttons use that input mode.

If no matching bindings are found, an empty PetitSet will be returned.

A copy of the values are returned, rather than a reference to them. The order of these values is stable, in a first-in, first-out fashion. Use self.map.get or self.map.get_mut if you require a reference.

pub fn n_registered(&self, action: A, input_mode: Option<InputMode>) -> usize

Returns how many bindings are currently registered for the provided action with the provided InputMode

If None is provided, a total across all input modes will be provided.

A maximum of CAP bindings across all input modes can be stored for each action, and insert operations will silently fail if used when CAP bindings already exist.

impl<A: Actionlike> InputMap<A>

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

Insert a mapping between action and input

Existing mappings for that action will not be overwritten. If the set for this action is already full, this insertion will silently fail.

pub fn insert_multiple(
    &mut self,
    action: A,
    inputs: impl IntoIterator<Item = impl Into<UserInput>>
)

Insert a mapping between action and the provided inputs

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.

Existing mappings for that action will not be overwritten.

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

Insert a mapping between action and the simultaneous combination of buttons 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.

Existing mappings for that action will not be overwritten.

pub fn replace(
    &mut self,
    action: A,
    input: impl Into<UserInput>
) -> Option<PetitSet<UserInput, 16>>

Replaces any existing inputs for the action of the same InputMode with the provided input

Returns all previously registered inputs, if any

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

Replaces the input for the actionof the same InputMode at the same index with the provided input

If the input is a UserInput::Chord that combines multiple input modes or UserInput::Null, this method will silently fail. Returns the replaced input, if any.

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

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 clear_action(
    &mut self,
    action: A,
    input_mode: Option<InputMode>
) -> Option<PetitSet<UserInput, 16>>

Clears all inputs registered for the action that use the supplied input_mode

If input_mode is None, all inputs will be cleared regardless of input mode.

For chords, an input will be removed if any of the contained buttons use that input mode.

Returns all previously registered inputs, if any

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

Clears the input for the action with the specified InputMode at the provided index

Returns the removed input, if any

pub fn clear_input_mode(&mut self, input_mode: Option<InputMode>) -> InputMap<A>

Clears all inputs that use the supplied input_mode

If input_mode is None, all inputs will be cleared regardless of input mode.

For chords, an input will be removed if any of the contained buttons use that input mode.

Returns the subset of the action map that was removed

impl<A: Actionlike> InputMap<A>

pub fn per_mode_cap(&self) -> usize

Returns the per-InputMode cap on input bindings for every action

Each individual action can have at most this many bindings, making them easier to display and configure.

pub fn set_per_mode_cap(&mut self, per_mode_cap: usize) -> InputMap<A>

Sets the per-InputMode cap on input bindings for every action

Each individual action can have at most this many bindings, making them easier to display and configure. Any excess actions will be removed, and returned from this method.

Supplying a value of 0 removes any per-mode cap.

PANICS: 3 * per_mode_cap cannot exceed the global CAP, as we need space to store all mappings.

impl<A: Actionlike> InputMap<A>

pub fn assign_gamepad(&mut self, gamepad: Gamepad)

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

pub fn clear_gamepad(&mut self)

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

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

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

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<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> StructuralPartialEq for InputMap<A>