Bevy Enhanced Input

The AccumulateBy modifier allows an action to continuously add its input values together as long as a secondary 'trigger' action is in the TriggerState::Fired state.

Behavior:

• When the trigger action is Fired: The current action's input values are added to a running total (self.value).
• When the trigger action is inactive: The accumulation resets, and the action's value becomes equal to the current frame's input value.

This is useful for mechanics like movement acceleration, where holding a modifier key (like Shift) causes input (like WASD) to accumulate or scale over time.

use bevy::{ecs::spawn::SpawnWith, prelude::*};
use bevy_enhanced_input::prelude::*;

Actions::<TestContext>::spawn(SpawnWith(|context: &mut ActionSpawner<_>| {
    // 1. Define the trigger action (e.g., a modifier key)
    let accelerate = context
        .spawn((
            Action::<Accelerate>::new(),
            bindings![KeyCode::ShiftLeft, KeyCode::ShiftRight],
        ))
        .id();

    // 2. Define the primary action that accumulates values based on the trigger
    context.spawn((
        Action::<Movement>::new(),
        AccumulateBy::new(accelerate),
        Bindings::spawn(Cardinal::wasd_keys().with(DeadZone::default())),
    ));
}));

#[derive(Component)]
struct TestContext;

#[derive(InputAction)]
#[action_output(bool)]
struct Accelerate;

#[derive(InputAction)]
#[action_output(f32)]
struct Movement;

Bevy Enhanced Input uses three core abstractions to manage player input:

1. Actions: Represent high-level gameplay behaviors (e.g., "Jump", "Move") independent of specific keys. They are defined by implementing the InputAction trait and are stored as entities with the Action<A> component.
2. Bindings: Connect Actions to physical input sources (e.g., KeyCode::Space, MouseButton::Left). Bindings are entities with the Binding component associated with an action via the BindingOf relationship.
3. Contexts: Define the active input state (e.g., "On Foot", "In Vehicle"). Contexts are regular components registered as input contexts. They associate actions with specific entities and control when those actions are evaluated.

Workflow Summary:

• Register a component as a context using add_input_context.
• Define an InputAction struct.
• Spawn an entity with the context component and use the actions! macro to spawn Action entities and their Binding entities in one go.

use bevy::prelude::*;
use bevy_enhanced_input::prelude::*;

#[derive(Component)]
struct Player;

#[derive(InputAction)]
#[action_output(bool)]
struct Jump;

#[derive(InputAction)]
#[action_output(bool)]
struct Fire;

// In your App setup:
app.add_plugins(EnhancedInputPlugin)
    .add_input_context::<Player>()
    .finish();

// Spawning the player with actions and bindings:
app.world_mut().spawn((
    Player,
    actions!(Player[
        (
            Action::<Jump>::new(),
            bindings![KeyCode::Space, GamepadButton::South],
        ),
        (
            Action::<Fire>::new(),
            bindings![MouseButton::Left, GamepadButton::RightTrigger2],
        ),
    ])
));

The SwizzleAxis component is an input modifier used to reorder or swap the axes of an input value. This is particularly useful for mapping 1D inputs (like a single button or trigger) onto specific axes of a higher-dimensional action (like the Y axis of a 2D movement stick).

Behavioral Rules:

• It attempts to preserve the original dimension where possible.
• If an axis from the original input is promoted to a higher dimension, the ActionValue type will change (e.g., a Bool or Axis1D might become an Axis2D or Axis3D).
• Missing axes in the target configuration are replaced with zero.

Common Use Cases:

• Mapping a 1D input to the Y axis of a 2D action using SwizzleAxis::YXZ.
• Reordering 3D axes for specific coordinate system requirements.

use bevy::prelude::*;
use crate::prelude::*;

// Example of applying a swizzle (conceptual usage via component attachment)
// entity.insert(SwizzleAxis::YXZ);

The ActionMock component allows you to simulate input actions without physical device interaction. This is useful for automated testing, AI-driven inputs, cutscenes, or network-driven input.

When an action is mocked:

• Input reading, conditions, and modifiers are skipped.
• The action reports the provided TriggerState and ActionValue.
• State transition events (e.g., Start<A>, Fire<A>) are still triggered.
• Mocking takes effect during the next context evaluation.

Once the specified MockSpan expires, ActionMock::enabled is set to false, and the action resumes regular evaluation. The component is not automatically removed, allowing for reuse.

// Example: Spawn and move up for 2 seconds
world.spawn((
    Player,
    actions!(Player[
        (
            Action::<Movement>::new(),
            ActionMock::new(TriggerState::Fired, Vec2::Y, Duration::from_secs(2)),
            Bindings::spawn(Cardinal::wasd_keys()),
        ),
    ]),
));

Input conditions are components that implement the InputCondition trait. They define the logic for when an action is triggered (e.g., "hold for 1 second" or "tap").

Key Behaviors:

• Attachment: Conditions can be attached to both actions and bindings.
• Evaluation: They are evaluated during EnhancedInputSystems::Update after modifiers, in their insertion order. They update the TriggerState on the associated action entity.
• Default Behavior: If no conditions are attached to an action, it defaults to behaving like a Down condition with a zero actuation threshold (triggering on any non-zero input value).
• Custom Conditions: If you implement a custom condition, you must register it using InputConditionAppExt::add_input_condition.

use bevy::prelude::*;
use bevy_enhanced_input::prelude::*;

#[derive(InputAction)]
#[action_output(bool)]
struct Jump;

// Example of attaching a condition to an action
world.spawn(actions!((
    Action::<Jump>::new(),
    Hold::new(1.0),
    bindings![KeyCode::Space],
)));

The ActionEvents bitset tracks events caused by transitions in an action's TriggerState. During EnhancedInputSystems::Trigger, these bitflags are set based on the transition from the previous state to the new state. You can use ActionEvents as a component in systems or react to them via observers.

// ActionEvents bitflags
// START, ONGOING, FIRE, CANCEL, COMPLETE

You can mock an action by inserting an ActionMock component onto the specific action entity, or by using the convenience extension traits on EntityCommands or EntityWorldMut.

Using EntityCommands (Commands API)

Use mock, try_mock, mock_once, or try_mock_once on an entity to find the correct action within its Actions<C> container and apply the mock.

• mock: Emits a warning if the entity or action is not found.
• try_mock: Silences warnings if the entity or action is not found.
• mock_once: Mocks the action for a single update (shorthand for MockSpan::once()).
• try_mock_once: Silences warnings and mocks for a single update.

Using EntityWorldMut (Direct World Access)

Use mock, mock_once on EntityWorldMut for immediate application during system execution.

// Mock a 2 second long press using EntityCommands
fn mock_fire(mut commands: Commands, player: Single<Entity, With<Player>>) {
    commands
        .entity(player.into_inner())
        .mock::<Player, PrimaryFire>(TriggerState::Fired, true, Duration::from_secs(2));
}

// Mock a jump action for just the next frame
fn mock_jump(mut commands: Commands, jump: Single<Entity, With<Action<Jump>>>) {
    commands.entity(*jump).insert(ActionMock::once(TriggerState::Fired, true));
}