Struct 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.

Disabling actions

Actions can be disabled in four different ways, with increasing granularity:

1. By disabling updates to all actions using a run condition on InputManagerSystem::Update.
2. By disabling updates to all actions of type A using a run condition on TickActionStateSystem::<A>.
3. By setting a specific action state to disabled using ActionState::disable.
4. By disabling a specific action using ActionState::disable_action.

More general mechanisms of disabling actions will cause specific mechanisms to be ignored. For example, if an entire action state is disabled, then enabling or disabling individual actions will have no effect.

Actions that are disabled will report as released (but not just released), and their values will be zero. Under the hood, their values are still updated to avoid surprising behavior when re-enabled, but they are not reported to the user using standard methods like ActionState::pressed. To check the underlying values, access their ActionData directly.

Example

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

#[derive(Actionlike, PartialEq, Eq, Hash, 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 all_action_data(&self) -> &HashMap<A, ActionData>

Returns a reference to the complete ActionData for all actions.

pub fn update(&mut self, updated_actions: UpdatedActions<A>)

Updates the ActionState based on the provided UpdatedActions.

The action_data is typically constructed from InputMap::process_actions, which reads from the assorted ButtonInput resources.

Actions that are disabled will still be updated: instead, their values will be read as released / zero. You can see their underlying values by checking their ActionData directly.

pub fn tick(&mut self, _current_instant: Instant, _previous_instant: Instant)

Advances the time for all actions, transitioning them from just_pressed to pressed, and just_released to released.

If the timing feature flag is enabled, the underlying timing and action data 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, Hash, 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 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 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) -> Option<&ActionData>

A reference to the ActionData corresponding to the action.

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

A mutable reference to the ActionData corresponding to the action.

To initialize the ActionData if it has not yet been triggered, use action_data_mut_or_default method.

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

A mutable reference to the ActionData corresponding to the action, initializing it if needed.

If the action has no data yet (because the action has not been triggered), this method will create and insert a default ActionData for you, avoiding potential errors from unwrapping None.

pub fn button_data(&self, action: &A) -> Option<&ButtonData>

A reference of the ButtonData corresponding to the 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.

Caution

To access the ButtonData regardless of whether the action has been triggered, use unwrap_or_default on the returned Option.

Returns

• Some(ButtonData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn button_data_mut(&mut self, action: &A) -> Option<&mut ButtonData>

A mutable reference of the ButtonData corresponding to the 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.

Caution

To access the ButtonData regardless of whether the action has been triggered, use unwrap_or_default on the returned Option.

To insert a default ButtonData if it doesn’t exist, use button_data_mut_or_default method.

Returns

• Some(ButtonData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn button_data_mut_or_default(&mut self, action: &A) -> &mut ButtonData

A mutable reference of the ButtonData corresponding to the action, initializing it if needed.

If the action has no data yet (because the action has not been triggered), this method will create and insert a default ButtonData for you, avoiding potential errors from unwrapping None.

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.

pub fn axis_data(&self, action: &A) -> Option<&AxisData>

A reference of the AxisData corresponding to the action.

Caution

To access the AxisData regardless of whether the action has been triggered, use unwrap_or_default on the returned Option.

Returns

• Some(AxisData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn axis_data_mut(&mut self, action: &A) -> Option<&mut AxisData>

A mutable reference of the AxisData corresponding to the action.

Caution

To insert a default AxisData if it doesn’t exist, use axis_data_mut_or_default method.

Returns

• Some(AxisData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn axis_data_mut_or_default(&mut self, action: &A) -> &mut AxisData

A mutable reference of the AxisData corresponding to the action, initializing it if needed..

If the action has no data yet (because the action has not been triggered), this method will create and insert a default AxisData for you, avoiding potential errors from unwrapping None.

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.

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

A reference of the DualAxisData corresponding to the action.

Caution

To access the DualAxisData regardless of whether the action has been triggered, use unwrap_or_default on the returned Option.

Returns

• Some(DualAxisData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

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

A mutable reference of the DualAxisData corresponding to the action.

Caution

To insert a default DualAxisData if it doesn’t exist, use dual_axis_data_mut_or_default method.

Returns

• Some(DualAxisData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn dual_axis_data_mut_or_default(&mut self, action: &A) -> &mut DualAxisData

A mutable reference of the DualAxisData corresponding to the action initializing it if needed.

If the action has no data yet (because the action has not been triggered), this method will create and insert a default DualAxisData for you, avoiding potential errors from unwrapping None.

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.

pub fn triple_axis_data(&self, action: &A) -> Option<&TripleAxisData>

A reference of the TripleAxisData corresponding to the action.

Caution

To access the TripleAxisData regardless of whether the action has been triggered, use unwrap_or_default on the returned Option.

Returns

• Some(TripleAxisData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn triple_axis_data_mut( &mut self, action: &A, ) -> Option<&mut TripleAxisData>

A mutable reference of the TripleAxisData corresponding to the action.

Caution

To insert a default TripleAxisData if it doesn’t exist, use triple_axis_data_mut_or_default method.

Returns

• Some(ButtonData) if it exists.
• None if the action has never been triggered (pressed, clicked, etc.).

pub fn triple_axis_data_mut_or_default( &mut self, action: &A, ) -> &mut TripleAxisData

A mutable reference of the TripleAxisData corresponding to the action initializing it if needed.

If the action has no data yet (because the action has not been triggered), this method will create and insert a default TripleAxisData for you, avoiding potential errors from unwrapping None.

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.

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

Get the value associated with the corresponding action if present.

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/Rtriggers and the Playstation L2/R2 triggers. See also the axis_inputs example in the repository.
• Dual axis inputs will return the magnitude of its Vec2 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.

Warnings

This value will be 0. if the action has never been pressed or released.

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 set_value(&mut self, action: &A, value: f32)

Sets the value of the action to the provided value.

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

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

Warning

This value will be 0. by default, even if the action is not an axislike action.

pub fn axis_pair(&self, action: &A) -> Vec2

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

Only events that represent dual-axis control provide a Vec2, and this will return None for other events.

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

This value will be Vec2::ZERO by default, even if the action is not a dual-axislike action.

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 set_axis_pair(&mut self, action: &A, pair: Vec2)

Sets the Vec2 of the action to the provided pair.

pub fn clamped_axis_pair(&self, action: &A) -> Vec2

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

Warning

This value will be Vec2::ZERO by default, even if the action is not a dual-axislike action.

pub fn axis_triple(&self, action: &A) -> Vec3

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

Only events that represent triple-axis control provide a Vec3, and this will return None for other events.

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

Warning

This value will be Vec3::ZERO by default, even if the action is not a triple-axislike action.

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

pub fn set_axis_triple(&mut self, action: &A, triple: Vec3)

Sets the Vec2 of the action to the provided pair.

pub fn clamped_axis_triple(&self, action: &A) -> Vec3

Get the Vec3 associated with the corresponding action, clamped to the cube of values bounded by -1 and 1 on all axes.

Warning

This value will be Vec3::ZERO by default, even if the action is not a dual-axislike action.

pub fn set_button_data(&mut self, action: A, data: ButtonData)

Manually sets the ButtonData 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 ButtonData between action states.

Example

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

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

#[derive(Actionlike, Clone, Copy, PartialEq, Eq, Hash, 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.button_data(&AbilitySlot::Slot1);

// And transfer it to the actual ability that we care about
// without losing timing information
if let Some(state) = slot_1_state {
   action_state.set_button_data(Action::Run, 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 reset(&mut self, action: &A)

Resets an action to its default state.

Buttons will be released, and axes will be set to 0.

pub fn reset_all(&mut self)

Releases all Buttonlike actions, sets all Axislike actions to 0, sets all DualAxislike actions to Vec2::ZERO, and sets all TripleAxislike actions to Vec3::ZERO.

pub fn disabled(&self) -> bool

Is the entire ActionState currently disabled?

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

Is this action currently disabled?

pub fn disable(&mut self)

Disables the entire ActionState.

All values will be reset to their default state.

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

Disables the action.

The action’s value will be reset to its default state.

pub fn disable_all_actions(&mut self)

Disables all actions

pub fn enable(&mut self)

Enables the entire ActionState

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

Enables the action

pub fn enable_all_actions(&mut self)

Enables all actions

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

Is this action currently pressed?

Warning

This value will be false by default, even if the action is not a buttonlike action.

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

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

Warning

This value will be false by default, even if the action is not a buttonlike action.

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

Is this action currently released?

This is always the logical negation of pressed

Warning

This value will be true by default, even if the action is not a buttonlike action.

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

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

Warning

This value will be false by default, even if the action is not a buttonlike action.

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 our actions are assigned a timing and duration that corresponds exactly to the start of a frame, rather than relying on idiosyncratic timing.

This will also be None if the action was never pressed or released.

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

The Duration for which the action has been held or released

This will be Duration::ZERO if the action was never pressed 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.

This will be Duration::ZERO if the action was never pressed or released.

pub fn apply_diff(&mut self, action_diff: &ActionDiff<A>)

Applies an ActionDiff (usually received over the network) to the ActionState.

This lets you reconstruct an ActionState from a stream of ActionDiffs

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

Returns an owned list of the Actionlike keys in this ActionState.

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,

const STORAGE_TYPE: StorageType = bevy::ecs::component::StorageType::Table

A constant indicating the storage type used for this component.

fn register_component_hooks(_hooks: &mut ComponentHooks)

Called when registering this component, allowing mutable access to its ComponentHooks.

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() -> Self

Returns the “default value” for a type.

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

where A: Deserialize<'de> + Actionlike,

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 Self: Any + Send + Sync, A: TypePath + Actionlike, bool: FromReflect + TypePath + RegisterForReflection, HashMap<A, ActionData>: FromReflect + TypePath + RegisterForReflection,

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 Self: Any + Send + Sync, A: TypePath + Actionlike, bool: FromReflect + TypePath + RegisterForReflection, HashMap<A, ActionData>: FromReflect + TypePath + RegisterForReflection,

fn get_type_registration() -> TypeRegistration

Returns the default TypeRegistration for this type.

fn register_type_dependencies(registry: &mut TypeRegistry)

Registers other types needed by this type.

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

fn eq(&self, other: &ActionState<A>) -> bool

Tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

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 Self: Any + Send + Sync, A: TypePath + Actionlike, bool: FromReflect + TypePath + RegisterForReflection, HashMap<A, ActionData>: FromReflect + TypePath + RegisterForReflection,

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 try_apply(&mut self, value: &dyn Reflect) -> Result<(), ApplyError>

Tries to apply a reflected value to this value.

fn reflect_kind(&self) -> ReflectKind

Returns a zero-sized enumeration of “kinds” of type.

fn reflect_ref(&self) -> ReflectRef<'_>

Returns an immutable 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 apply(&mut self, value: &(dyn Reflect + 'static))

Applies a reflected value to this value.

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

where A: Serialize + Actionlike,

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 Self: Any + Send + Sync, A: TypePath + Actionlike, bool: FromReflect + TypePath + RegisterForReflection, HashMap<A, ActionData>: FromReflect + TypePath + RegisterForReflection,

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 Self: 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 Self: Any + Send + Sync, A: TypePath + Actionlike, bool: FromReflect + TypePath + RegisterForReflection, HashMap<A, ActionData>: FromReflect + TypePath + RegisterForReflection,

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>