Crate leafwing_input_manager 

About

A straightforward but robust input-action manager for Bevy.

Inputs from various input sources (keyboard, mouse and gamepad) are collected into a common ActionState on your player entity, which can be conveniently used in your game logic.

The mapping between inputs and actions is many-to-many, and easily configured and extended with the InputMap components on each player entity. A single action can be triggered by multiple inputs (or set directly by UI elements or gameplay logic), and a single input can result in multiple actions being triggered, which can be handled contextually.

Supported Bevy Versions

Bevy	leafwing-input-manager
0.17	0.18
0.16	0.17
0.15	0.16
0.14	0.14..0.15
0.13	0.13
0.12	0.11..0.12
0.11	0.10
0.10	0.9
0.9	0.7..0.8

Features

• Full keyboard, mouse and joystick support for button-like and axis inputs
• Dual axis support for analog inputs from gamepads and joysticks
  • Expressive and easy-to-use axis processing for deadzones, sensitivity and clamping
• Bind arbitrary button inputs into virtual D-Pads
• Effortlessly wire UI buttons to game state with one simple component!
  • When clicked, your button will press the appropriate action on the corresponding entity
• Store all your input mappings in a single InputMap component
  • No more bespoke Keybindings<KeyCode>, Keybindings<Gamepad> headaches
• Look up your current input state in a single ActionState component
  • That pesky maximum of 16 system parameters got you down? Say goodbye to that input handling mega-system
• Ergonomic insertion API that seamlessly blends multiple input types for you
  • Can’t decide between input_map.insert(Action::Jump, KeyCode::Space) and input_map.insert(Action::Jump, GamepadButton::South)? Have both!
• Full support for arbitrary button combinations: chord your heart out.
  • input_map.insert(Action::Console, ButtonlikeChord::new([KeyCode::ControlLeft, KeyCode::Shift, KeyCode::KeyC]))
• Sophisticated input disambiguation with the ClashStrategy enum: stop triggering individual buttons when you meant to press a chord!
• Create an arbitrary number of strongly typed disjoint action sets by adding multiple copies of this plugin: decouple your camera and player state
• Local multiplayer support: freely bind keys to distinct entities, rather than worrying about singular global state
• Networked multiplayer support: serializable structs, and a space-conscious ActionDiff representation to send on the wire
• Powerful and easy-to-use input mocking API for integration testing your Bevy applications
• Control which state this plugin is active in: stop wandering around while in a menu!
• Leafwing Studio’s trademark #![forbid(missing_docs)]

Limitations

• Gamepads must be manually assigned to each input map: read from the Gamepads resource and use InputMap::set_gamepad.

Getting started

1. Add leafwing-input-manager to your Cargo.toml.
2. Create an enum of the logical actions you want to represent, and derive the Actionlike trait for it.
3. Add the InputManagerPlugin to your App.
4. Add an InputMap<A: Actionlike> component to your player entity (or entities!).
5. Configure a mapping between your inputs and your actions by modifying the InputMap component on your player entity.
6. Read the ActionState component on your player entity to check the collected input state!

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

fn main() {
    App::new()
        .add_plugins(DefaultPlugins)
        // This plugin maps inputs to an input-type agnostic action-state
        // We need to provide it with an enum which stores the possible actions a player could take
        .add_plugins(InputManagerPlugin::<Action>::default())
        // The InputMap and ActionState components will be added to any entity with the Player component
        .add_systems(Startup, spawn_player)
        // Read the ActionState in your systems using queries!
        .add_systems(Update, jump)
        .run();
}

// This is the list of "things in the game I want to be able to do based on input"
#[derive(Actionlike, PartialEq, Eq, Hash, Clone, Copy, Debug, Reflect)]
enum Action {
    Run,
    Jump,
}

#[derive(Component)]
struct Player;

fn spawn_player(mut commands: Commands) {
    // Describes how to convert from player inputs into those actions
    let input_map = InputMap::new([(Action::Jump, KeyCode::Space)]);
    commands.spawn(input_map).insert(Player);
}

// Query for the `ActionState` component in your game logic systems!
fn jump(query: Query<&ActionState<Action>, With<Player>>) {
    let action_state = query.single();
    if let Ok(action_state) = action_state {
        // Each action has a button-like state of its own that you can check
        if action_state.just_pressed(&Action::Jump) {
            println!("I'm jumping!");
        }
    }
}

This snippet is the minimal.rs example from the examples folder: check there for more in-depth learning materials!

Crate Feature Flags

Please refer to the [features] section in the Cargo.toml for information about the available crate features.

Modules

action_diff

Serialization-friendly representation of changes to ActionState.

action_state

This module contains ActionState and its supporting methods and impls.

axislike

Tools for working with directional axis-like user inputs (game sticks, D-Pads and emulated equivalents)

buttonlike

Tools for working with button-like user inputs (mouse clicks, gamepad button, keyboard inputs and so on)

clashing_inputs

Handles clashing inputs into a InputMap in a configurable fashion.

common_conditions

Run conditions for actions.

input_map

This module contains InputMap and its supporting methods and impls.

input_processing

Processors for input values

plugin

Contains the main plugin exported by this crate.

prelude

Everything you need to get started

systems

The systems that power each InputManagerPlugin.

timing

Information about when an action was pressed or released.

typetag

Type tag registration for trait objects

user_input

Helpful abstractions over user inputs of all sorts.

Enums

InputControlKind

Classifies UserInputs and Actionlike actions based on their behavior (buttons, analog axes, etc.).

Traits

Actionlike

Allows a type to be used as a gameplay action in an input-agnostic fashion

Derive Macros

Actionlike