leafwing_input_manager/
lib.rs

1#![forbid(missing_docs)]
2#![warn(clippy::doc_markdown)]
3#![doc = include_str!("../README.md")]
4
5use bevy::reflect::{FromReflect, Reflect, TypePath, Typed};
6use serde::{Deserialize, Serialize};
7use std::fmt::Debug;
8use std::hash::Hash;
9
10pub mod action_diff;
11pub mod action_state;
12pub mod axislike;
13pub mod buttonlike;
14pub mod clashing_inputs;
15pub mod common_conditions;
16pub mod input_map;
17pub mod input_processing;
18pub mod plugin;
19pub mod systems;
20
21#[cfg(feature = "timing")]
22pub mod timing;
23pub mod typetag;
24pub mod user_input;
25
26// Importing the derive macro
27pub use leafwing_input_manager_macros::Actionlike;
28
29/// Everything you need to get started
30pub mod prelude {
31    pub use crate::InputControlKind;
32
33    pub use crate::action_state::ActionState;
34    pub use crate::clashing_inputs::ClashStrategy;
35    pub use crate::input_map::InputMap;
36    pub use crate::input_processing::*;
37    pub use crate::user_input::*;
38
39    pub use crate::plugin::InputManagerPlugin;
40    pub use crate::Actionlike;
41    pub use leafwing_input_manager_macros::serde_typetag;
42}
43
44/// Allows a type to be used as a gameplay action in an input-agnostic fashion
45///
46/// Actions are modelled as "virtual buttons" (or axes), cleanly abstracting over messy, customizable inputs
47/// in a way that can be easily consumed by your game logic.
48///
49/// This trait should be implemented on the `A` type that you want to pass into [`InputManagerPlugin`](crate::plugin::InputManagerPlugin).
50///
51/// Generally, these types will be very small (often data-less) enums.
52/// As a result, the APIs in this crate accept actions by value, rather than reference.
53/// While `Copy` is not a required trait bound,
54/// users are strongly encouraged to derive `Copy` on these enums whenever possible to improve ergonomics.
55///
56/// # Examples
57///
58/// ```rust
59/// use bevy::prelude::Reflect;
60/// use leafwing_input_manager::Actionlike;
61///
62/// #[derive(Actionlike, Debug, PartialEq, Eq, Clone, Copy, Hash, Reflect)]
63/// enum PlayerAction {
64///    // Movement
65///    Up,
66///    Down,
67///    Left,
68///    Right,
69///    // Abilities
70///    Ability1,
71///    Ability2,
72///    Ability3,
73///    Ability4,
74///    Ultimate,
75/// }
76/// ```
77///
78/// # Customizing variant behavior
79///
80/// By default, the derive macro for this trait assumes that all actions are buttonlike.
81///
82/// You can customize this behavior by using the `#[actionlike]` attribute,
83/// either on the entire enum or on individual variants.
84///
85/// See the document of [`InputControlKind`] for available options.
86///
87/// ```rust
88/// use bevy::prelude::*;
89/// use leafwing_input_manager::prelude::*;
90///
91/// #[derive(Actionlike, Debug, PartialEq, Eq, Clone, Copy, Hash, Reflect)]
92/// #[actionlike(Axis)] // This attribute applies to all variants in the enum
93/// enum CameraAction {
94///    Zoom,  // This action is controlled by axes
95///    #[actionlike(DualAxis)]
96///    Move,  // This action is controlled by dual axes since we have overridden the default option
97///    #[actionlike(Button)]
98///    TakePhoto, // This action is controlled by buttons since we have overridden the default option
99/// }
100/// ```
101pub trait Actionlike:
102    Debug + Eq + Hash + Send + Sync + Clone + Reflect + Typed + TypePath + FromReflect + 'static
103{
104    /// Returns the kind of input control this action represents: buttonlike, axislike, or dual-axislike.
105    fn input_control_kind(&self) -> InputControlKind;
106}
107
108/// Classifies [`UserInput`](crate::user_input::UserInput)s and [`Actionlike`] actions based on their behavior (buttons, analog axes, etc.).
109#[derive(Debug, Clone, Copy, PartialEq, Reflect, Serialize, Deserialize)]
110#[must_use]
111pub enum InputControlKind {
112    /// A single input with binary state (active or inactive), typically a button press (on or off).
113    ///
114    /// Corresponds to [`Buttonlike`](crate::user_input::Buttonlike)  inputs.
115    Button,
116
117    /// A single analog or digital input, often used for range controls like a thumb stick on a gamepad or mouse wheel,
118    /// providing a value within a min-max range.
119    ///
120    /// Corresponds to [`Axislike`](crate::user_input::Axislike) inputs.
121    Axis,
122
123    /// A combination of two axis-like inputs, often used for directional controls like a D-pad on a gamepad,
124    /// providing separate values for the X and Y axes.
125    ///
126    /// Corresponds to [`DualAxislike`](crate::user_input::DualAxislike) inputs.
127    DualAxis,
128
129    /// A combination of three axis-like inputs, providing separate values for the X, Y and Z axes.
130    ///
131    /// Corresponds to [`TripleAxislike`](crate::user_input::TripleAxislike) inputs.
132    TripleAxis,
133}
leafwing_input_manager/lib.rs

leafwing_input_manager/
lib.rs
