Struct leafwing_input_manager::action_state::ActionState

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

Stores the canonical input-method-agnostic representation of the inputs received

Can be used as either a resource or as a [Component] on entities that you wish to control directly from player input.

Example

use bevy::reflect::Reflect;
use leafwing_input_manager::prelude::*;
use bevy::utils::Instant;

#[derive(Actionlike, PartialEq, Eq, Clone, Copy, Debug, Reflect)]
enum Action {
    Left,
    Right,
    Jump,
}

let mut action_state = ActionState::<Action>::default();

// Typically, this is done automatically by the `InputManagerPlugin` from user inputs
// using the `ActionState::update` method
action_state.press(Action::Jump);

assert!(action_state.pressed(Action::Jump));
assert!(action_state.just_pressed(Action::Jump));
assert!(action_state.released(Action::Left));

// Resets just_pressed and just_released
let t0 = Instant::now();
let t1 = Instant::now();

 action_state.tick(t1, t0);
assert!(action_state.pressed(Action::Jump));
assert!(!action_state.just_pressed(Action::Jump));

action_state.release(Action::Jump);
assert!(!action_state.pressed(Action::Jump));
assert!(action_state.released(Action::Jump));
assert!(action_state.just_released(Action::Jump));

let t2 = Instant::now();
action_state.tick(t2, t1);
assert!(action_state.released(Action::Jump));
assert!(!action_state.just_released(Action::Jump));

Implementations

impl<A: Actionlike> ActionState<A>

pub fn update(&mut self, action_data: Vec<ActionData>)

Updates the ActionState based on a vector of ActionData, ordered by Actionlike::id.

The action_data is typically constructed from InputMap::which_pressed, which reads from the assorted Input resources.

pub fn tick(&mut self, current_instant: Instant, previous_instant: Instant)

Advances the time for all actions

The underlying Timing and ButtonState will be advanced according to the current_instant.

• if no [Instant] is set, the current_instant will be set as the initial time at which the button was pressed / released
• the Duration will advance to reflect elapsed time

Example

use bevy::prelude::Reflect;
use leafwing_input_manager::prelude::*;
use leafwing_input_manager::buttonlike::ButtonState;
use bevy::utils::Instant;

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

let mut action_state = ActionState::<Action>::default();

// Actions start released
assert!(action_state.released(Action::Jump));
assert!(!action_state.just_released(Action::Run));

// Ticking time moves causes buttons that were just released to no longer be just released
let t0 = Instant::now();
let t1 = Instant::now();

action_state.tick(t1, t0);
assert!(action_state.released(Action::Jump));
assert!(!action_state.just_released(Action::Jump));

action_state.press(Action::Jump);
assert!(action_state.just_pressed(Action::Jump));

// Ticking time moves causes buttons that were just pressed to no longer be just pressed
let t2 = Instant::now();

action_state.tick(t2, t1);
assert!(action_state.pressed(Action::Jump));
assert!(!action_state.just_pressed(Action::Jump));

pub fn action_data(&self, action: A) -> &ActionData

A reference to the ActionData of the corresponding action

Generally, it’ll be clearer to call pressed or so on directly on the ActionState. However, accessing the raw data directly allows you to examine detailed metadata holistically.

Example

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

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
enum Action {
    Run,
    Jump,
}
let mut action_state = ActionState::<Action>::default();
let run_data = action_state.action_data(Action::Run);

dbg!(run_data);

pub fn action_data_mut(&mut self, action: A) -> &mut ActionData

A mutable reference of the ActionData of the corresponding action

Generally, it’ll be clearer to call pressed or so on directly on the ActionState. However, accessing the raw data directly allows you to examine detailed metadata holistically.

Example

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

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
enum Action {
    Run,
    Jump,
}
let mut action_state = ActionState::<Action>::default();
let mut run_data = action_state.action_data_mut(Action::Run);
run_data.axis_pair = None;

dbg!(run_data);

pub fn value(&self, action: A) -> f32

Get the value associated with the corresponding action

Different kinds of bindings have different ways of calculating the value:

• Binary buttons will have a value of 0.0 when the button is not pressed, and a value of 1.0 when the button is pressed.
• Some axes, such as an analog stick, will have a value in the range -1.0..=1.0.
• Some axes, such as a variable trigger, will have a value in the range 0.0..=1.0.
• Some buttons will also return a value in the range 0.0..=1.0, such as analog gamepad triggers which may be tracked as buttons or axes. Examples of these include the Xbox LT/RT triggers and the Playstation L2/R2 triggers. See also the axis_inputs example in the repository.
• Dual axis inputs will return the magnitude of its DualAxisData and will be in the range 0.0..=1.0.
• Chord inputs will return the value of its first input.

If multiple inputs trigger the same game action at the same time, the value of each triggering input will be added together.

Warning

This value may not be bounded as you might expect. Consider clamping this to account for multiple triggering inputs, typically using the clamped_value method instead.

pub fn clamped_value(&self, action: A) -> f32

Get the value associated with the corresponding action, clamped to [-1.0, 1.0].

pub fn axis_pair(&self, action: A) -> Option<DualAxisData>

Get the DualAxisData from the binding that triggered the corresponding action.

Only certain events such as VirtualDPad and DualAxis provide an DualAxisData, and this will return None for other events.

Chord inputs will return the DualAxisData of it’s first input.

If multiple inputs with an axis pair trigger the same game action at the same time, the value of each axis pair will be added together.

Warning

These values may not be bounded as you might expect. Consider clamping this to account for multiple triggering inputs, typically using the clamped_axis_pair method instead.

pub fn clamped_axis_pair(&self, action: A) -> Option<DualAxisData>

Get the DualAxisData associated with the corresponding action, clamped to [-1.0, 1.0].

pub fn set_action_data(&mut self, action: A, data: ActionData)

Manually sets the ActionData of the corresponding action

You should almost always use more direct methods, as they are simpler and less error-prone.

However, this method can be useful for testing, or when transferring ActionData between action states.

Example

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

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
enum AbilitySlot {
    Slot1,
    Slot2,
}

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

let mut ability_slot_state = ActionState::<AbilitySlot>::default();
let mut action_state = ActionState::<Action>::default();

// Extract the state from the ability slot
let slot_1_state = ability_slot_state.action_data(AbilitySlot::Slot1);

// And transfer it to the actual ability that we care about
// without losing timing information
action_state.set_action_data(Action::Run, slot_1_state.clone());

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

Press the action

No initial instant or reasons why the button was pressed will be recorded Instead, this is set through ActionState::tick()

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

Release the action

No initial instant will be recorded Instead, this is set through ActionState::tick()

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

Consumes the action

The action will be released, and will not be able to be pressed again until it would have otherwise been released by ActionState::release, ActionState::release_all or ActionState::update.

No initial instant will be recorded Instead, this is set through ActionState::tick()

Example

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

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Debug, Reflect)]
enum Action {
    Eat,
    Sleep,
}

let mut action_state = ActionState::<Action>::default();

action_state.press(Action::Eat);
assert!(action_state.pressed(Action::Eat));

// Consuming actions releases them
action_state.consume(Action::Eat);
assert!(action_state.released(Action::Eat));

// Doesn't work, as the action was consumed
action_state.press(Action::Eat);
assert!(action_state.released(Action::Eat));

// Releasing consumed actions allows them to be pressed again
action_state.release(Action::Eat);
action_state.press(Action::Eat);
assert!(action_state.pressed(Action::Eat));

pub fn consume_all(&mut self)

Consumes all actions

pub fn release_all(&mut self)

Releases all actions

pub fn pressed(&self, action: A) -> bool

Is this action currently pressed?

pub fn just_pressed(&self, action: A) -> bool

Was this action pressed since the last time tick was called?

pub fn released(&self, action: A) -> bool

Is this action currently released?

This is always the logical negation of pressed

pub fn just_released(&self, action: A) -> bool

Was this action released since the last time tick was called?

pub fn get_pressed(&self) -> Vec<A>

Which actions are currently pressed?

pub fn get_just_pressed(&self) -> Vec<A>

Which actions were just pressed?

pub fn get_released(&self) -> Vec<A>

Which actions are currently released?

pub fn get_just_released(&self) -> Vec<A>

Which actions were just released?

pub fn instant_started(&self, action: A) -> Option<Instant>

The [Instant] that the action was last pressed or released

If the action was pressed or released since the last time ActionState::tick was called the value will be None. This ensures that all of our actions are assigned a timing and duration that corresponds exactly to the start of a frame, rather than relying on idiosyncratic timing.

pub fn current_duration(&self, action: A) -> Duration

The Duration for which the action has been held or released

pub fn previous_duration(&self, action: A) -> Duration

The Duration for which the action was last held or released

This is a snapshot of the ActionState::current_duration state at the time the action was last pressed or released.

Trait Implementations

impl<A: Clone + Actionlike> Clone for ActionState<A>

fn clone(&self) -> ActionState<A>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<A: Actionlike> Component for ActionState<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 ActionState<A>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<A: Actionlike> Default for ActionState<A>

fn default() -> ActionState<A>

Returns the “default value” for a type.

impl<'de, A: Actionlike> Deserialize<'de> for ActionState<A>

fn deserialize<__D>(__deserializer: __D) -> Result<Self, __D::Error>

where __D: Deserializer<'de>,

Deserialize this value from the given Serde deserializer.

impl<A> FromReflect for ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: Any + Send + Sync + Default, A: TypePath + Actionlike,

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 ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: Any + Send + Sync, A: TypePath + Actionlike,

fn get_type_registration() -> TypeRegistration

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

fn eq(&self, other: &ActionState<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 ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: Any + Send + Sync, A: TypePath + Actionlike,

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_ref(&self) -> ReflectRef<'_>

Returns an 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 type_name(&self) -> &str

👎Deprecated since 0.12.0: view the method documentation to find alternatives to this method.

Returns the type path of the underlying type.

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: Actionlike> Serialize for ActionState<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> Struct for ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: Any + Send + Sync, A: TypePath + Actionlike,

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 ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: 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 ActionState<A>

where Vec<ActionData>: FromReflect, PhantomData<A>: Any + Send + Sync, A: TypePath + Actionlike,

fn type_info() -> &'static TypeInfo

Returns the compile-time info for the underlying type.

impl<A: Actionlike> Resource for ActionState<A>

where Self: Send + Sync + 'static,

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